More clearly recommend Gateway API

Updates docs to more clearly recommend Gateway API and remove any
implementation-specific references from the main Ingress docs.

Author: robscott

content/en/docs/concepts/services-networking/ingress-controllers.md

@@ -3,27 +3,52 @@ title: Ingress Controllers
 description: >-
   In order for an [Ingress](/docs/concepts/services-networking/ingress/) to work in your cluster,
   there must be an _ingress controller_ running.
-  You need to select at least one ingress controller and make sure it is set up in your cluster.  
+  You need to select at least one ingress controller and make sure it is set up in your cluster.
   This page lists common ingress controllers that you can deploy.
 content_type: concept
 weight: 50
 ---
 
-<!-- overview -->
+{{< warning >}}
+The Ingress API has been frozen.
+{{< /warning >}}
+
+<!-- body -->
 
-In order for the Ingress resource to work, the cluster must have an ingress controller running. 
+<!-- overview -->
 
-Unlike other types of controllers which run as part of the `kube-controller-manager` binary, Ingress controllers 
-are not started automatically with a cluster. Use this page to choose the ingress controller implementation 
-that best fits your cluster.
+## Consider using Gateway API
+[Gateway API](/docs/concepts/services-networking/gateway/) is GA and includes
+many more features (and controllers). The following table highlights some of the
+differences between the APIs:
+
+| | Ingress | Gateway API |
+| - | - | - |
+| GA | ✅ Yes | ✅ Yes |
+| Basic HTTP path matching | ✅ Yes | ✅ Yes |
+| Traffic Splitting | ❌ No | ✅ Yes |
+| More Protocols (gRPC, TLS) | ❌ No | ✅ Yes |
+| More Matchers (Headers, Query Params, Methods) | ❌ No | ✅ Yes |
+| Redirects | ❌ No | ✅ Yes |
+| Rewrites | ❌ No | ✅ Yes |
+| TLS Validation | ❌ No | ✅ Yes |
+| Cross-Namespace References | ❌ No | ✅ Yes |
+| AI Extensions | ❌ No | ✅ [Yes](https://gateway-api-inference-extension.sigs.k8s.io/) |
+| Service Mesh Support | ❌ No | ✅ Yes |
+| More Features in Development | ❌ No | ✅ Yes |
+| Conformance Tests | 🟡 Some | ✅ Thorough |
+| # of Implementations | ✅ [33](/docs/concepts/services-networking/ingress-controllers) | ✅ [34](https://gateway-api.sigs.k8s.io/implementations/) |
+
+
+## Ingress Controllers
 
 Kubernetes as a project supports and maintains [AWS](https://github.com/kubernetes-sigs/aws-load-balancer-controller#readme), [GCE](https://git.k8s.io/ingress-gce/README.md#readme), and
   [nginx](https://git.k8s.io/ingress-nginx/README.md#readme) ingress controllers.
 
 
 <!-- body -->
 
-## Additional controllers
+## Additional Controllers
 
 {{% thirdparty-content %}}
 

content/en/docs/concepts/services-networking/ingress.md

@@ -1,6 +1,7 @@
 ---
 reviewers:
-- bprashanth
+- robscott
+- rikatz
 title: Ingress
 api_metadata:
 - apiVersion: "networking.k8s.io/v1"
@@ -20,12 +21,35 @@ weight: 30
 {{< feature-state for_k8s_version="v1.19" state="stable" >}}
 {{< glossary_definition term_id="ingress" length="all" >}}
 
-{{< note >}}
-Ingress is frozen. New features are being added to the [Gateway API](/docs/concepts/services-networking/gateway/).
-{{< /note >}}
+{{< warning >}}
+The Ingress API has been frozen.
+{{< /warning >}}
 
 <!-- body -->
 
+## Consider using Gateway API
+[Gateway API](/docs/concepts/services-networking/gateway/) is GA and includes
+many more features. The following table highlights some of the differences
+between the APIs:
+
+| | Ingress | Gateway API |
+| - | - | - |
+| GA | ✅ Yes | ✅ Yes |
+| Basic HTTP path matching | ✅ Yes | ✅ Yes |
+| Traffic Splitting | ❌ No | ✅ Yes |
+| More Protocols (gRPC, TLS) | ❌ No | ✅ Yes |
+| More Matchers (Headers, Query Params, Methods) | ❌ No | ✅ Yes |
+| Redirects | ❌ No | ✅ Yes |
+| Rewrites | ❌ No | ✅ Yes |
+| TLS Validation | ❌ No | ✅ Yes |
+| Cross-Namespace References | ❌ No | ✅ Yes |
+| AI Extensions | ❌ No | ✅ [Yes](https://gateway-api-inference-extension.sigs.k8s.io/) |
+| Service Mesh Support | ❌ No | ✅ Yes |
+| More Features in Development | ❌ No | ✅ Yes |
+| Conformance Tests | 🟡 Some | ✅ Thorough |
+| # of Implementations | ✅ [30](/docs/concepts/services-networking/ingress-controllers) | ✅ [34](https://gateway-api.sigs.k8s.io/implementations/) |
+
+
 ## Terminology
 
 For clarity, this guide defines the following terms:
@@ -68,7 +92,6 @@ uses a service of type [Service.Type=NodePort](/docs/concepts/services-networkin
 You must have an [Ingress controller](/docs/concepts/services-networking/ingress-controllers)
 to satisfy an Ingress. Only creating an Ingress resource has no effect.
 
-You may need to deploy an Ingress controller such as [ingress-nginx](https://kubernetes.github.io/ingress-nginx/deploy/).
 You can choose from a number of [Ingress controllers](/docs/concepts/services-networking/ingress-controllers).
 
 Ideally, all Ingress controllers should fit the reference specification. In reality, the various Ingress
@@ -91,10 +114,6 @@ For general information about working with config files, see
 [deploying applications](/docs/tasks/run-application/run-stateless-application-deployment/),
 [configuring containers](/docs/tasks/configure-pod-container/configure-pod-configmap/),
 [managing resources](/docs/concepts/workloads/management/).
-Ingress frequently uses annotations to configure some options depending on the Ingress controller, an example of which
-is the [rewrite-target annotation](https://github.com/kubernetes/ingress-nginx/blob/main/docs/examples/rewrite/README.md).
-Different [Ingress controllers](/docs/concepts/services-networking/ingress-controllers) support different annotations.
-Review the documentation for your choice of Ingress controller to learn which annotations are supported.
 
 The [Ingress spec](/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec)
 has all the information needed to configure a load balancer or proxy server. Most importantly, it
@@ -104,12 +123,6 @@ for directing HTTP(S) traffic.
 If the `ingressClassName` is omitted, a [default Ingress class](#default-ingress-class)
 should be defined.
 
-There are some ingress controllers, that work without the definition of a
-default `IngressClass`. For example, the Ingress-NGINX controller can be
-configured with a [flag](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/#what-is-the-flag-watch-ingress-without-class)
-`--watch-ingress-without-class`. It is [recommended](https://kubernetes.github.io/ingress-nginx/user-guide/k8s-122-migration/#i-have-only-one-ingress-controller-in-my-cluster-what-should-i-do) though, to specify the
-default `IngressClass` as shown [below](#default-ingress-class).
-
 ### Ingress rules
 
 Each HTTP rule contains the following information:
@@ -298,7 +311,7 @@ spec:
 
 {{% /tab %}}
 {{% tab name="Namespaced" %}}
-{{< feature-state for_k8s_version="v1.23" state="stable" >}}
+{{< feature-state for_k8s_version="v1.23" state="deprecated" >}}
 
 If you set the `.spec.parameters` field and set
 `.spec.parameters.scope` to `Namespace`, then the IngressClass refers
@@ -376,10 +389,8 @@ IngressClass is marked as default in your cluster.
 {{< /caution >}}
 
 There are some ingress controllers, that work without the definition of a
-default `IngressClass`. For example, the Ingress-NGINX controller can be
-configured with a [flag](https://kubernetes.github.io/ingress-nginx/#what-is-the-flag-watch-ingress-without-class)
-`--watch-ingress-without-class`. It is [recommended](https://kubernetes.github.io/ingress-nginx/#i-have-only-one-instance-of-the-ingresss-nginx-controller-in-my-cluster-what-should-i-do)  though, to specify the
-default `IngressClass`:
+default `IngressClass`. It is recommended though, to specify the default
+`IngressClass`:
 
 {{% code_sample file="service/networking/default-ingressclass.yaml" %}}
 
@@ -520,11 +531,9 @@ section.
 {{% code_sample file="service/networking/tls-example-ingress.yaml" %}}
 
 {{< note >}}
-There is a gap between TLS features supported by various Ingress
-controllers. Please refer to documentation on
-[nginx](https://kubernetes.github.io/ingress-nginx/user-guide/tls/),
-[GCE](https://git.k8s.io/ingress-gce/README.md#frontend-https), or any other
-platform specific Ingress controller to understand how TLS works in your environment.
+There is a gap between TLS features supported by various Ingress controllers.
+Please refer to documentation for the Ingress controller you've chosen to
+understand how TLS works in your environment.
 {{< /note >}}
 
 ### Load balancing {#load-balancing}
@@ -540,9 +549,7 @@ It's also worth noting that even though health checks are not exposed directly
 through the Ingress, there exist parallel concepts in Kubernetes such as
 [readiness probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
 that allow you to achieve the same end result. Please review the controller
-specific documentation to see how they handle health checks (for example:
-[nginx](https://git.k8s.io/ingress-nginx/README.md), or
-[GCE](https://git.k8s.io/ingress-gce/README.md#health-checks)).
+specific documentation to see how they handle health checks.
 
 ## Updating an Ingress
 
@@ -562,8 +569,6 @@ Rules:
   ----         ----  --------
   foo.bar.com
                /foo   service1:80 (10.8.0.90:80)
-Annotations:
-  nginx.ingress.kubernetes.io/rewrite-target:  /
 Events:
   Type     Reason  Age                From                     Message
   ----     ------  ----               ----                     -------
@@ -624,8 +629,6 @@ Rules:
                /foo   service1:80 (10.8.0.90:80)
   bar.baz.com
                /foo   service2:80 (10.8.0.91:80)
-Annotations:
-  nginx.ingress.kubernetes.io/rewrite-target:  /
 Events:
   Type     Reason  Age                From                     Message
   ----     ------  ----               ----                     -------

content/en/examples/service/networking/minimal-ingress.yaml

@@ -2,8 +2,6 @@ apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: minimal-ingress
-  annotations:
-    nginx.ingress.kubernetes.io/rewrite-target: /
 spec:
   ingressClassName: nginx-example
   rules: