Fix Ingress resources in docs (#7579)

* fix Ingress resources in docs

Signed-off-by: Gerald Pape <gerald@giantswarm.io>

* move to ingressClassName

* fix more Ingress resource examples

* empty commit

Signed-off-by: Gerald Pape <gerald@giantswarm.io>

* make NOTES.txt aware of version + add notice about ingress version to examples main page

* add link to legacy documentation

Signed-off-by: Gerald Pape <gerald@giantswarm.io>

.github/ISSUE_TEMPLATE/bug_report.md

@@ -105,7 +105,10 @@ echo "
   kind: Ingress
   metadata:
     name: foo-bar
+    annotations:
+      kubernetes.io/ingress.class: nginx
   spec:
+    ingressClassName: nginx # omit this if you're on controller version below 1.0.0
     rules:
     - host: foo.bar
       http:

charts/ingress-nginx/README.md

@@ -2,13 +2,14 @@
 
 [ingress-nginx](https://github.com/kubernetes/ingress-nginx) Ingress controller for Kubernetes using NGINX as a reverse proxy and load balancer
 
-To use, add the `kubernetes.io/ingress.class: nginx` annotation to your Ingress resources.
+To use, add `ingressClassName: nginx` spec field or the `kubernetes.io/ingress.class: nginx` annotation to your Ingress resources.
 
 This chart bootstraps an ingress-nginx deployment on a [Kubernetes](http://kubernetes.io) cluster using the [Helm](https://helm.sh) package manager.
 
 ## Prerequisites
 
-- Kubernetes v1.16+
+- Chart version 3.x.x: Kubernetes v1.16+
+- Chart version 4.x.x and above: Kubernetes v1.19+
 
 ## Get Repo Info
 

charts/ingress-nginx/templates/NOTES.txt

@@ -29,23 +29,30 @@ Get the application URL by running these commands:
 
 An example Ingress that makes use of the controller:
 
+{{- $isV1 := semverCompare ">=1" .Chart.AppVersion}}
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: example
     namespace: foo
+    {{- if eq $isV1 false }}
+    annotations:
+      kubernetes.io/ingress.class: {{ .Values.controller.ingressClass }}
+    {{- end }}
   spec:
-    ingressClassName: example-class
+    {{- if $isV1 }}
+    ingressClassName: {{ .Values.controller.ingressClassResource.name }}
+    {{- end }}
     rules:
       - host: www.example.com
         http:
           paths:
-            - path: /
-              pathType: Prefix
-              backend:
+            - backend:
                 service:
                   name: exampleService
-                  port: 80
+                  port:
+                    number: 80
+              path: /
     # This section is only required if TLS is to be enabled for the Ingress
     tls:
       - hosts:

docs/examples/affinity/cookie/ingress-samesite.yaml

@@ -11,6 +11,7 @@ metadata:
     nginx.ingress.kubernetes.io/session-cookie-samesite: "None"
     nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none: "true" # omits SameSite=None for older browsers which reject cookies with SameSite=None
 spec:
+  ingressClassName: nginx
   rules:
   - host: stickyingress-samesite-none.example.com
     http:
@@ -34,6 +35,7 @@ metadata:
     nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
     nginx.ingress.kubernetes.io/session-cookie-samesite: "Strict"
 spec:
+  ingressClassName: nginx
   rules:
   - host: stickyingress-samesite-strict.example.com
     http:

docs/examples/affinity/cookie/ingress.yaml

@@ -9,6 +9,7 @@ metadata:
     nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
 
 spec:
+  ingressClassName: nginx
   rules:
   - host: stickyingress.example.com
     http:

docs/examples/auth/basic/README.md

@@ -42,6 +42,7 @@ metadata:
     # message to display with an appropriate context why the authentication is required
     nginx.ingress.kubernetes.io/auth-realm: 'Authentication Required - foo'
 spec:
+  ingressClassName: nginx
   rules:
   - host: foo.bar.com
     http:

docs/examples/auth/client-certs/ingress.yaml

@@ -15,6 +15,7 @@ metadata:
   name: nginx-test
   namespace: default
 spec:
+  ingressClassName: nginx
   rules:
   - host: mydomain.com
     http:

docs/examples/auth/external-auth/ingress.yaml

@@ -5,6 +5,7 @@ metadata:
     nginx.ingress.kubernetes.io/auth-url: "https://httpbin.org/basic-auth/user/passwd"
   name: external-auth
 spec:
+  ingressClassName: nginx
   rules:
   - host: external-auth-01.sample.com
     http:

docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml

@@ -7,6 +7,7 @@ metadata:
   name: external-auth-oauth2
   namespace: kube-system
 spec:
+  ingressClassName: nginx
   rules:
   - host: __INGRESS_HOST__
     http:
@@ -26,6 +27,7 @@ metadata:
   name: oauth2-proxy
   namespace: kube-system
 spec:
+  ingressClassName: nginx
   rules:
   - host: __INGRESS_HOST__
     http:

docs/examples/chashsubset/deployment.yaml

@@ -64,6 +64,7 @@ metadata:
   name: nginxhello-ingress
   namespace: default
 spec:
+  ingressClassName: nginx
   rules:
   - host: foo.bar.com
     http:
@@ -75,4 +76,3 @@ spec:
               name: nginxhello
               port:
                 number: 80
-

docs/examples/customization/configuration-snippets/ingress.yaml

@@ -6,6 +6,7 @@ metadata:
     nginx.ingress.kubernetes.io/configuration-snippet: |
       more_set_headers "Request-Id: $req_id";
 spec:
+  ingressClassName: nginx
   rules:
   - host: custom.configuration.com
     http:

docs/examples/customization/external-auth-headers/deploy/echo-service.yaml

@@ -52,6 +52,7 @@ metadata:
     nginx.ingress.kubernetes.io/auth-response-headers: UserID, UserRole
   namespace: default
 spec:
+  ingressClassName: nginx
   rules:
   - host: public-demo-echo-service.kube.local
     http:
@@ -73,6 +74,7 @@ metadata:
     nginx.ingress.kubernetes.io/auth-response-headers: UserID, UserRole
   namespace: default
 spec:
+  ingressClassName: nginx
   rules:
   - host: secure-demo-echo-service.kube.local
     http:

docs/examples/docker-registry/ingress-with-tls.yaml

@@ -9,6 +9,7 @@ metadata:
   name: docker-registry
   namespace: docker-registry
 spec:
+  ingressClassName: nginx
   tls:
   - hosts:
     - registry.<your domain>

docs/examples/docker-registry/ingress-without-tls.yaml

@@ -8,6 +8,7 @@ metadata:
   name: docker-registry
   namespace: docker-registry
 spec:
+  ingressClassName: nginx
   rules:
   - host: registry.<your domain>
     http:

docs/examples/grpc/README.md

@@ -94,12 +94,12 @@ This example demonstrates how to route traffic to a gRPC service through the ngi
   kind: Ingress
   metadata:
     annotations:
-      kubernetes.io/ingress.class: "nginx"
       nginx.ingress.kubernetes.io/ssl-redirect: "true"
       nginx.ingress.kubernetes.io/backend-protocol: "GRPC"
     name: fortune-ingress
     namespace: default
   spec:
+    ingressClassName: nginx
     rules:
     - host: grpctest.dev.mydomain.com
       http:

docs/examples/index.md

@@ -3,6 +3,10 @@
 This directory contains a catalog of examples on how to run, configure and scale Ingress.
 Please review the [prerequisites](PREREQUISITES.md) before trying them.
 
+The examples on these pages include the `spec.ingressClassName` field which replaces the deprecated `kubernetes.io/ingress.class: nginx` annotation. Users of ingress-nginx < 1.0.0 (Helm chart < 4.0.0) should use the [legacy documentation](https://github.com/kubernetes/ingress-nginx/tree/legacy/docs/examples).
+
+For more information, check out the [Migration to apiVersion networking.k8s.io/v1](../#faq-migration-to-apiversion-networkingk8siov1) guide.
+
 Category | Name | Description | Complexity Level
 ---------| ---- | ----------- | ----------------
 Apps | [Docker Registry](docker-registry/README.md) | TODO | TODO

docs/examples/multi-tls/multi-tls.yaml

@@ -98,6 +98,7 @@ metadata:
   name: foo-tls
   namespace: default
 spec:
+  ingressClassName: nginx
   tls:
   - hosts:
     - foo.bar.com

docs/examples/rewrite/README.md

@@ -42,6 +42,7 @@ metadata:
   name: rewrite
   namespace: default
 spec:
+  ingressClassName: nginx
   rules:
   - host: rewrite.bar.com
     http:
@@ -77,6 +78,7 @@ metadata:
   name: approot
   namespace: default
 spec:
+  ingressClassName: nginx
   rules:
   - host: approot.bar.com
     http:

docs/examples/static-ip/nginx-ingress.yaml

@@ -3,6 +3,7 @@ kind: Ingress
 metadata:
   name: ingress-nginx
 spec:
+  ingressClassName: nginx
   tls:
   # This assumes tls-secret exists.
   - secretName: tls-secret

docs/examples/tls-termination/README.md

@@ -22,6 +22,7 @@ spec:
       # This assumes tls-secret exists and the SSL
       # certificate contains a CN for foo.bar.com
       secretName: tls-secret
+  ingressClassName: nginx
   rules:
     - host: foo.bar.com
       http:

docs/examples/tls-termination/ingress.yaml

@@ -3,6 +3,7 @@ kind: Ingress
 metadata:
   name: nginx-test
 spec:
+  ingressClassName: nginx
   tls:
     - hosts:
       - foo.bar.com

docs/user-guide/basic-usage.md

@@ -13,10 +13,8 @@ apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   name: ingress-myservicea
-  annotations:
-    # use the shared ingress-nginx
-    kubernetes.io/ingress.class: "nginx"
 spec:
+  ingressClassName: nginx
   rules:
   - host: myservicea.foo.org
     http:

docs/user-guide/fcgi-services.md

@@ -64,12 +64,12 @@ apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
   annotations:
-    kubernetes.io/ingress.class: "nginx"
     nginx.ingress.kubernetes.io/backend-protocol: "FCGI"
     nginx.ingress.kubernetes.io/fastcgi-index: "index.php"
     nginx.ingress.kubernetes.io/fastcgi-params-configmap: "example-cm"
   name: example-app
 spec:
+  ingressClassName: nginx
   rules:
   - host: app.example.com
     http:

docs/user-guide/ingress-path-matching.md

@@ -22,6 +22,7 @@ metadata:
   annotations:
     nginx.ingress.kubernetes.io/use-regex: "true"
 spec:
+  ingressClassName: nginx
   rules:
   - host: test.com
     http:
@@ -59,6 +60,7 @@ kind: Ingress
 metadata:
   name: test-ingress-1
 spec:
+  ingressClassName: nginx
   rules:
   - host: test.com
     http:
@@ -87,6 +89,7 @@ metadata:
   annotations:
     nginx.ingress.kubernetes.io/rewrite-target: /$1
 spec:
+  ingressClassName: nginx
   rules:
   - host: test.com
     http:
@@ -144,6 +147,7 @@ metadata:
   annotations:
     nginx.ingress.kubernetes.io/use-regex: "true"
 spec:
+  ingressClassName: nginx
   rules:
   - host: test.com
     http:

docs/user-guide/third-party-addons/opentracing.md

@@ -185,6 +185,7 @@ In the Zipkin interface we can see the details:
       metadata:
         name: echo-ingress
       spec:
+        ingressClassName: nginx
         rules:
         - host: example.com
           http: