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
 
@@ -177,8 +178,8 @@ controller:
         networking.gke.io/load-balancer-type: "Internal"
         # For earlier versions
         # cloud.google.com/load-balancer-type: "Internal"
-        
-        # Any other annotation can be declared here. 
+
+        # Any other annotation can be declared here.
 ```
 
 Example for Azure:

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:
@@ -44,4 +46,4 @@ spec:
           service:
             name: http-svc
             port:
-              number: 80
+              number: 80

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:
@@ -15,4 +16,4 @@ spec:
           service:
             name: http-svc
             port:
-              number: 80
+              number: 80

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>
@@ -23,4 +24,4 @@ spec:
           service:
             name: docker-registry
             port:
-              number: 5000
+              number: 5000

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:
@@ -18,4 +19,4 @@ spec:
           service:
             name: docker-registry
             port:
-              number: 5000
+              number: 5000

docs/examples/grpc/README.md

@@ -16,7 +16,7 @@ This example demonstrates how to route traffic to a gRPC service through the ngi
   ```
   $ kubectl get po -A -o wide | grep go-grpc-greeter-server
   ```
-- If you have a gRPC app deployed in your cluster, then skip further notes in this Step 1, and continue from Step 2 below. 
+- If you have a gRPC app deployed in your cluster, then skip further notes in this Step 1, and continue from Step 2 below.
 
 - As an example gRPC application, we can use this app <https://github.com/grpc/grpc-go/blob/91e0aeb192456225adf27966d04ada4cf8599915/examples/features/reflection/server/main.go> .
 
@@ -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

@@ -1,8 +1,12 @@
 # Ingress examples
 
-This directory contains a catalog of examples on how to run, configure and scale Ingress.  
+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
@@ -14,7 +18,7 @@ Customization | [Configuration snippets](customization/configuration-snippets/RE
 Customization | [Custom configuration](customization/custom-configuration/README.md) | TODO | TODO
 Customization | [Custom DH parameters for perfect forward secrecy](customization/ssl-dh-param/README.md) | TODO | TODO
 Customization | [Custom errors](customization/custom-errors/README.md) | serve custom error pages from the default backend | Intermediate
-Customization | [Custom headers](customization/custom-headers/README.md) | set custom headers before sending traffic to backends  | Advanced
+Customization | [Custom headers](customization/custom-headers/README.md) | set custom headers before sending traffic to backends | Advanced
 Customization | [External authentication with response header propagation](customization/external-auth-headers/README.md) | TODO | TODO
 Customization | [Sysctl tuning](customization/sysctl/README.md) | TODO | TODO
 Features | [Rewrite](rewrite/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:
@@ -32,7 +33,7 @@ spec:
             # This assumes http-svc exists and routes to healthy endpoints
             service:
               name: http-svc
-              port: 
+              port:
                 number: 80
 ```
 

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:
@@ -67,7 +65,7 @@ spec:
         backend:
           service:
             name: myservicea
-            port: 
+            port:
               number: 80
   ingressClassName: nginx
 ---
@@ -85,7 +83,7 @@ spec:
         backend:
           service:
             name: myserviceb
-            port: 
+            port:
               number: 80
   ingressClassName: nginx
 ```

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: