update ingress documentation to prefer ingressclass (#16386)

* update ingress documentation to prefer ingressclass

Signed-off-by: tjons <tylerschade99@gmail.com>

* gen

Signed-off-by: tjons <tylerschade99@gmail.com>

* Apply suggestions from code review

Attempt to fix test

* fix issue in test

Signed-off-by: tjons <tylerschade99@gmail.com>

---------

Signed-off-by: tjons <tylerschade99@gmail.com>
Co-authored-by: Craig Box <craig.box@gmail.com>

content/en/docs/tasks/traffic-management/ingress/kubernetes-ingress/index.md

@@ -24,17 +24,23 @@ A [Kubernetes Ingress Resources](https://kubernetes.io/docs/concepts/services-ne
 
 Let's see how you can configure a `Ingress` on port 80 for HTTP traffic.
 
-1.  Create an `Ingress` resource:
+1.  Create an `Ingress` resource and an `IngressClass`:
 
     {{< text bash >}}
     $ kubectl apply -f - <<EOF
     apiVersion: networking.k8s.io/v1
+    kind: IngressClass
+    metadata:
+      name: istio
+    spec:
+      controller: istio.io/ingress-controller
+    ---
+    apiVersion: networking.k8s.io/v1
     kind: Ingress
     metadata:
-      annotations:
-        kubernetes.io/ingress.class: istio
       name: ingress
     spec:
+      ingressClassName: istio
       rules:
       - host: httpbin.example.com
         http:
@@ -49,7 +55,9 @@ Let's see how you can configure a `Ingress` on port 80 for HTTP traffic.
     EOF
     {{< /text >}}
 
-    The `kubernetes.io/ingress.class` annotation is required to tell the Istio gateway controller that it should handle this `Ingress`, otherwise it will be ignored.
+    The `IngressClass` resource identifies the Istio gateway controller to Kubernetes, and the `ingressClassName: istio` value instructs Kubernetes that the Istio gateway controller should handle the following `Ingress`.
+
+    Older versions of the Ingress API used the `kubernetes.io/ingress.class` annotation, and while it still works, [it has been deprecated in Kubernetes](https://kubernetes.io/docs/concepts/services-networking/ingress/#deprecated-annotation) for some time.
 
 1.  Access the _httpbin_ service using _curl_:
 
@@ -86,42 +94,12 @@ By default, Istio will treat paths as exact matches, unless they end in `/*` or
 
 In Kubernetes 1.18, a new field, `pathType`, was added. This allows explicitly declaring a path as `Exact` or `Prefix`.
 
-### Specifying `IngressClass`
-
-In Kubernetes 1.18, a new resource, `IngressClass`, was added, replacing the `kubernetes.io/ingress.class` annotation on the `Ingress` resource. If you are using this resource, you will need to set the `controller` field to `istio.io/ingress-controller`. For example:
-
-{{< text yaml >}}
-apiVersion: networking.k8s.io/v1
-kind: IngressClass
-metadata:
-  name: istio
-spec:
-  controller: istio.io/ingress-controller
----
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: ingress
-spec:
-  ingressClassName: istio
-  rules:
-  - host: httpbin.example.com
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: httpbin
-            port:
-              number: 8000
-{{< /text >}}
-
 ## Cleanup
 
-Delete the `Ingress` configuration, and shutdown the [httpbin]({{< github_tree >}}/samples/httpbin) service:
+Delete the `IngressClass` and `Ingress` configurations, and shutdown the [httpbin]({{< github_tree >}}/samples/httpbin) service:
 
 {{< text bash >}}
 $ kubectl delete ingress ingress
+$ kubectl delete ingressclass istio
 $ kubectl delete --ignore-not-found=true -f @samples/httpbin/httpbin.yaml@
 {{< /text >}}

content/en/docs/tasks/traffic-management/ingress/kubernetes-ingress/snips.sh

@@ -23,12 +23,18 @@
 snip_configuring_ingress_using_an_ingress_resource_1() {
 kubectl apply -f - <<EOF
 apiVersion: networking.k8s.io/v1
+kind: IngressClass
+metadata:
+  name: istio
+spec:
+  controller: istio.io/ingress-controller
+---
+apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
-  annotations:
-    kubernetes.io/ingress.class: istio
   name: ingress
 spec:
+  ingressClassName: istio
   rules:
   - host: httpbin.example.com
     http:
@@ -64,34 +70,8 @@ HTTP/1.1 404 Not Found
 ...
 ENDSNIP
 
-! IFS=$'\n' read -r -d '' snip_specifying_ingressclass_1 <<\ENDSNIP
-apiVersion: networking.k8s.io/v1
-kind: IngressClass
-metadata:
-  name: istio
-spec:
-  controller: istio.io/ingress-controller
----
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: ingress
-spec:
-  ingressClassName: istio
-  rules:
-  - host: httpbin.example.com
-    http:
-      paths:
-      - path: /
-        pathType: Prefix
-        backend:
-          service:
-            name: httpbin
-            port:
-              number: 8000
-ENDSNIP
-
 snip_cleanup_1() {
 kubectl delete ingress ingress
+kubectl delete ingressclass istio
 kubectl delete --ignore-not-found=true -f samples/httpbin/httpbin.yaml
 }

content/en/docs/tasks/traffic-management/ingress/kubernetes-ingress/test.sh

@@ -40,14 +40,6 @@ _verify_elided snip_configuring_ingress_using_an_ingress_resource_2 "$snip_confi
 # Access other URL
 _verify_elided snip_configuring_ingress_using_an_ingress_resource_3 "$snip_configuring_ingress_using_an_ingress_resource_3_out"
 
-# Test IngressClass and pathType
-kubectl apply -f - <<< "$snip_specifying_ingressclass_1"
-
-get_headers() {
-curl -s -H "Foo: bar" -HHost:httpbin.example.com "http://$INGRESS_HOST:$INGRESS_PORT/headers" | jq '.headers["Foo"][0]'
-}
-_verify_contains get_headers '"bar"'
-
 # @cleanup
 snip_cleanup_1
 kubectl label namespace default istio-injection-