From 017e1ecde30c0d283f55a59a74f4c4f9ff64f00e Mon Sep 17 00:00:00 2001 From: Gerald Pape Date: Tue, 9 Nov 2021 16:43:49 +0100 Subject: [PATCH] Fix Ingress resources in docs (#7579) * fix Ingress resources in docs Signed-off-by: Gerald Pape * move to ingressClassName * fix more Ingress resource examples * empty commit Signed-off-by: Gerald Pape * 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 --- .github/ISSUE_TEMPLATE/bug_report.md | 3 +++ charts/ingress-nginx/README.md | 9 +++++---- charts/ingress-nginx/templates/NOTES.txt | 17 ++++++++++++----- .../affinity/cookie/ingress-samesite.yaml | 4 +++- docs/examples/affinity/cookie/ingress.yaml | 1 + docs/examples/auth/basic/README.md | 1 + docs/examples/auth/client-certs/ingress.yaml | 1 + docs/examples/auth/external-auth/ingress.yaml | 3 ++- .../oauth-external-auth/dashboard-ingress.yaml | 2 ++ docs/examples/chashsubset/deployment.yaml | 2 +- .../configuration-snippets/ingress.yaml | 1 + .../deploy/echo-service.yaml | 2 ++ .../docker-registry/ingress-with-tls.yaml | 3 ++- .../docker-registry/ingress-without-tls.yaml | 3 ++- docs/examples/grpc/README.md | 4 ++-- docs/examples/index.md | 8 ++++++-- docs/examples/multi-tls/multi-tls.yaml | 1 + docs/examples/rewrite/README.md | 2 ++ docs/examples/static-ip/nginx-ingress.yaml | 1 + docs/examples/tls-termination/README.md | 3 ++- docs/examples/tls-termination/ingress.yaml | 1 + docs/user-guide/basic-usage.md | 8 +++----- docs/user-guide/fcgi-services.md | 2 +- docs/user-guide/ingress-path-matching.md | 4 ++++ .../third-party-addons/opentracing.md | 1 + 25 files changed, 62 insertions(+), 25 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 66fba1fbf..f266d0f29 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.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: diff --git a/charts/ingress-nginx/README.md b/charts/ingress-nginx/README.md index fecbbcde2..5e5c8b235 100644 --- a/charts/ingress-nginx/README.md +++ b/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: diff --git a/charts/ingress-nginx/templates/NOTES.txt b/charts/ingress-nginx/templates/NOTES.txt index 2dbf14f21..c10ab03ed 100644 --- a/charts/ingress-nginx/templates/NOTES.txt +++ b/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: diff --git a/docs/examples/affinity/cookie/ingress-samesite.yaml b/docs/examples/affinity/cookie/ingress-samesite.yaml index d03a25e39..2f7022ef7 100644 --- a/docs/examples/affinity/cookie/ingress-samesite.yaml +++ b/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 \ No newline at end of file + number: 80 diff --git a/docs/examples/affinity/cookie/ingress.yaml b/docs/examples/affinity/cookie/ingress.yaml index d3053021e..4ca9fbc09 100644 --- a/docs/examples/affinity/cookie/ingress.yaml +++ b/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: diff --git a/docs/examples/auth/basic/README.md b/docs/examples/auth/basic/README.md index d3d255afb..ffd8495f3 100644 --- a/docs/examples/auth/basic/README.md +++ b/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: diff --git a/docs/examples/auth/client-certs/ingress.yaml b/docs/examples/auth/client-certs/ingress.yaml index 90ff87514..0cd56fcbf 100644 --- a/docs/examples/auth/client-certs/ingress.yaml +++ b/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: diff --git a/docs/examples/auth/external-auth/ingress.yaml b/docs/examples/auth/external-auth/ingress.yaml index df80cbb25..1aa2f36e9 100644 --- a/docs/examples/auth/external-auth/ingress.yaml +++ b/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 \ No newline at end of file + number: 80 diff --git a/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml b/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml index 4c0a2d373..198a165f4 100644 --- a/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml +++ b/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: diff --git a/docs/examples/chashsubset/deployment.yaml b/docs/examples/chashsubset/deployment.yaml index 867cd01c0..0ac13fcce 100644 --- a/docs/examples/chashsubset/deployment.yaml +++ b/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 - diff --git a/docs/examples/customization/configuration-snippets/ingress.yaml b/docs/examples/customization/configuration-snippets/ingress.yaml index aaf31f0bb..1f0c4f24a 100644 --- a/docs/examples/customization/configuration-snippets/ingress.yaml +++ b/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: diff --git a/docs/examples/customization/external-auth-headers/deploy/echo-service.yaml b/docs/examples/customization/external-auth-headers/deploy/echo-service.yaml index 3a80ae834..9881ac8d0 100644 --- a/docs/examples/customization/external-auth-headers/deploy/echo-service.yaml +++ b/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: diff --git a/docs/examples/docker-registry/ingress-with-tls.yaml b/docs/examples/docker-registry/ingress-with-tls.yaml index bef35c50b..1bdd9ed7a 100644 --- a/docs/examples/docker-registry/ingress-with-tls.yaml +++ b/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. @@ -23,4 +24,4 @@ spec: service: name: docker-registry port: - number: 5000 \ No newline at end of file + number: 5000 diff --git a/docs/examples/docker-registry/ingress-without-tls.yaml b/docs/examples/docker-registry/ingress-without-tls.yaml index f64cbb295..d0ffc8baf 100644 --- a/docs/examples/docker-registry/ingress-without-tls.yaml +++ b/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. http: @@ -18,4 +19,4 @@ spec: service: name: docker-registry port: - number: 5000 + number: 5000 \ No newline at end of file diff --git a/docs/examples/grpc/README.md b/docs/examples/grpc/README.md index a20c8c7dd..a738450a9 100644 --- a/docs/examples/grpc/README.md +++ b/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 . @@ -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: diff --git a/docs/examples/index.md b/docs/examples/index.md index 04f42ea60..8a5fd5f51 100644 --- a/docs/examples/index.md +++ b/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 diff --git a/docs/examples/multi-tls/multi-tls.yaml b/docs/examples/multi-tls/multi-tls.yaml index aa2cf54d6..3612ab6d7 100644 --- a/docs/examples/multi-tls/multi-tls.yaml +++ b/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 diff --git a/docs/examples/rewrite/README.md b/docs/examples/rewrite/README.md index 3c48b100f..fbe9f30c7 100644 --- a/docs/examples/rewrite/README.md +++ b/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: diff --git a/docs/examples/static-ip/nginx-ingress.yaml b/docs/examples/static-ip/nginx-ingress.yaml index 740f46e89..5c8a3c920 100644 --- a/docs/examples/static-ip/nginx-ingress.yaml +++ b/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 diff --git a/docs/examples/tls-termination/README.md b/docs/examples/tls-termination/README.md index 2df767e26..f4fe2e81d 100644 --- a/docs/examples/tls-termination/README.md +++ b/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 ``` diff --git a/docs/examples/tls-termination/ingress.yaml b/docs/examples/tls-termination/ingress.yaml index debaa45b2..890247fd3 100644 --- a/docs/examples/tls-termination/ingress.yaml +++ b/docs/examples/tls-termination/ingress.yaml @@ -3,6 +3,7 @@ kind: Ingress metadata: name: nginx-test spec: + ingressClassName: nginx tls: - hosts: - foo.bar.com diff --git a/docs/user-guide/basic-usage.md b/docs/user-guide/basic-usage.md index 64c81148b..cbb7004c7 100644 --- a/docs/user-guide/basic-usage.md +++ b/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 ``` diff --git a/docs/user-guide/fcgi-services.md b/docs/user-guide/fcgi-services.md index 03afc89d1..becb4819f 100644 --- a/docs/user-guide/fcgi-services.md +++ b/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: diff --git a/docs/user-guide/ingress-path-matching.md b/docs/user-guide/ingress-path-matching.md index e5e0d9a50..321ddfa8e 100644 --- a/docs/user-guide/ingress-path-matching.md +++ b/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: diff --git a/docs/user-guide/third-party-addons/opentracing.md b/docs/user-guide/third-party-addons/opentracing.md index e27f32f6b..27c64e300 100644 --- a/docs/user-guide/third-party-addons/opentracing.md +++ b/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: