Minor documentation cleanup (#7826)

* clarify link * Add section headers * console blocks * grpc example json was not valid * multi-tls update text The preceding point 1 related to https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/ingress.yaml and the deployments referenced in https://github.com/kubernetes-retired/contrib/blob/4f2cb51ef82b4dddb625f6053ad132c1faf07aa1/ingress/controllers/nginx/examples/README.md They are not relevant to the current instructions. * add whitespace around parens * grammar setup would be a proper noun, but it is not the intended concept, which is a state * grammar * is-only * via * Use bullets for choices * ingress-controller nginx is a distinct brand. generally this repo talks about ingress-controller, although it is quite inconsistent about how... * drop stray paren * OAuth is a brand and needs an article here also GitHub is a brand * Indent text under numbered lists * use e.g. * Document that customer header config maps changes do not trigger updates This should be removed if #5238 is fixed. * article * period * infinitive verb + period * clarify that the gRPC server is responsible for listening for TCP traffic and not some other part of the backend application * avoid using ; and reword * whitespace * brand: gRPC * only-does is the right form `for` adds nothing here * spelling: GitHub * punctuation `;` is generally not the right punctuation... * drop stray `to` * sentence * backticks * fix link * Improve readability of compare/vs * Renumber list * punctuation * Favor Ingress-NGINX and Ingress NGINX * Simplify custom header restart text * Undo typo damage Co-authored-by: Josh Soref <[email protected]>
kubernetes · Jan 17, 2022 · 1614027 · 1614027
1 parent 784f9c5
commit 1614027
Show file tree

Hide file tree

Showing 27 changed files with 215 additions and 176 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# NGINX Ingress Controller
+# Ingress NGINX Controller
 
 [![Go Report Card](https://goreportcard.com/badge/github.com/kubernetes/ingress-nginx)](https://goreportcard.com/report/github.com/kubernetes/ingress-nginx)
 [![GitHub license](https://img.shields.io/github/license/kubernetes/ingress-nginx.svg)](https://github.com/kubernetes/ingress-nginx/blob/main/LICENSE)
@@ -28,7 +28,7 @@ For detailed changes on the `ingress-nginx` helm chart, please check the followi
 
 ### Support Versions table 
 
-| Ingress-nginx version | k8s supported version        | Alpine Version | Nginx Version |
+| Ingress-NGINX version | k8s supported version        | Alpine Version | Nginx Version |
 |-----------------------|------------------------------|----------------|---------------|
 | v1.1.1                | 1.23, 1.22, 1.21, 1.20, 1.19 | 3.14.2         |  1.19.9†      |
 | v1.1.0                | 1.22, 1.21, 1.20, 1.19       | 3.14.2         |  1.19.9†      |

diff --git a/docs/e2e-tests.md b/docs/e2e-tests.md
@@ -1,6 +1,6 @@
 
 
-# e2e test suite for [NGINX Ingress Controller](https://github.com/kubernetes/ingress-nginx/tree/main/)
+# e2e test suite for [Ingress NGINX Controller](https://github.com/kubernetes/ingress-nginx/tree/main/)
 
 
 

diff --git a/docs/examples/affinity/cookie/README.md b/docs/examples/affinity/cookie/README.md
@@ -14,13 +14,13 @@ Session affinity can be configured using the following annotations:
 |nginx.ingress.kubernetes.io/session-cookie-name|Name of the cookie that will be created|string (defaults to `INGRESSCOOKIE`)|
 |nginx.ingress.kubernetes.io/session-cookie-secure|Set the cookie as secure regardless the protocol of the incoming request|`"true"` or `"false"`|
 |nginx.ingress.kubernetes.io/session-cookie-path|Path that will be set on the cookie (required if your [Ingress paths][ingress-paths] use regular expressions)|string (defaults to the currently [matched path][ingress-paths])|
-|nginx.ingress.kubernetes.io/session-cookie-samesite|SameSite attribute to apply to the cookie|Browser accepted values are `None`, `Lax`, and `Strict`|
+|nginx.ingress.kubernetes.io/session-cookie-samesite|`SameSite` attribute to apply to the cookie|Browser accepted values are `None`, `Lax`, and `Strict`|
 |nginx.ingress.kubernetes.io/session-cookie-conditional-samesite-none|Will omit `SameSite=None` attribute for older browsers which reject the more-recently defined `SameSite=None` value|`"true"` or `"false"`
 |nginx.ingress.kubernetes.io/session-cookie-max-age|Time until the cookie expires, corresponds to the `Max-Age` cookie directive|number of seconds|
 |nginx.ingress.kubernetes.io/session-cookie-expires|Legacy version of the previous annotation for compatibility with older browsers, generates an `Expires` cookie directive by adding the seconds to the current date|number of seconds|
 |nginx.ingress.kubernetes.io/session-cookie-change-on-failure|When set to `false` nginx ingress will send request to upstream pointed by sticky cookie even if previous attempt failed. When set to `true` and previous attempt failed, sticky cookie will be changed to point to another upstream.|`true` or `false` (defaults to `false`)|
 
-You can create the [example Ingress](ingress.yaml) to test this:
+You can create the [session affinity example Ingress](ingress.yaml) to test this:
 
 ```console
 kubectl create -f ingress.yaml
@@ -66,13 +66,15 @@ Accept-Ranges: bytes
 ```
 
 In the example above, you can see that the response contains a `Set-Cookie` header with the settings we have defined.
-This cookie is created by NGINX, it contains a randomly generated key corresponding to the upstream used for that request (selected using [consistent hashing][consistent-hashing]) and has an `Expires` directive.
-If the user changes this cookie, NGINX creates a new one and redirects the user to another upstream.
+This cookie is created by the NGINX Ingress Controller, it contains a randomly generated key corresponding to the upstream used for that request (selected using [consistent hashing][consistent-hashing]) and has an `Expires` directive.
+If a client sends a cookie that doesn't correspond to an upstream, NGINX selects an upstream and creates a corresponding cookie.
 
 If the backend pool grows NGINX will keep sending the requests through the same server of the first request, even if it's overloaded.
 
 When the backend server is removed, the requests are re-routed to another upstream server. This does not require the cookie to be updated because the key's [consistent hash][consistent-hashing] will change.
 
+## Caveats
+
 When you have a Service pointing to more than one Ingress, with only one containing affinity configuration, the first created Ingress will be used.
 This means that you can face the situation that you've configured session affinity on one Ingress and it doesn't work because the Service is pointing to another Ingress that doesn't configure this.
 

diff --git a/docs/examples/auth/basic/README.md b/docs/examples/auth/basic/README.md
@@ -3,6 +3,8 @@
 This example shows how to add authentication in a Ingress rule using a secret that contains a file generated with `htpasswd`.
 It's important the file generated is named `auth` (actually - that the secret has a key `data.auth`), otherwise the ingress-controller returns a 503.
 
+## Create htpasswd file
+
 ```console
 $ htpasswd -c auth foo
 New password: <bar>
@@ -11,11 +13,15 @@ Re-type new password:
 Adding password for user foo
 ```
 
+## Convert htpasswd into a secret
+
 ```console
 $ kubectl create secret generic basic-auth --from-file=auth
 secret "basic-auth" created
 ```
 
+## Examine secret
+
 ```console
 $ kubectl get secret basic-auth -o yaml
 apiVersion: v1
@@ -28,8 +34,10 @@ metadata:
 type: Opaque
 ```
 
+## Using kubectl, create an ingress tied to the basic-auth secret
+
 ```console
-echo "
+$ echo "
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
@@ -57,6 +65,8 @@ spec:
 " | kubectl create -f -
 ```
 
+## Use curl to confirm authorization is required by the ingress
+
 ```
 $ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com'
 *   Trying 10.2.29.4...
@@ -84,6 +94,8 @@ $ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com'
 * Connection #0 to host 10.2.29.4 left intact
 ```
 
+## Use curl with the correct credentials to connect to the ingress
+
 ```
 $ curl -v http://10.2.29.4/ -H 'Host: foo.bar.com' -u 'foo:bar'
 *   Trying 10.2.29.4...

diff --git a/docs/examples/auth/client-certs/README.md b/docs/examples/auth/client-certs/README.md
@@ -1,11 +1,12 @@
 # Client Certificate Authentication
 
 It is possible to enable Client-Certificate Authentication by adding additional annotations to your Ingress Resource.
-Before getting started you must have the following Certificates Setup:
 
-1. CA certificate and Key(Intermediate Certs need to be in CA)
-2. Server Certificate(Signed by CA) and Key (CN should be equal the hostname you will use)
-3. Client Certificate(Signed by CA) and Key
+Before getting started you must have the following Certificates configured:
+
+1. CA certificate and Key (Intermediate Certs need to be in CA)
+2. Server Certificate (Signed by CA) and Key (CN should be equal the hostname you will use)
+3. Client Certificate (Signed by CA) and Key
 
 For more details on the generation process, checkout the Prerequisite [docs](../../PREREQUISITES.md#client-certificate-authentication).
 
@@ -15,36 +16,36 @@ You can have as many certificates as you want. If they're in the binary DER form
 openssl x509 -in certificate.der -inform der -out certificate.crt -outform pem
 ```
 
-Then, you can concatenate them all in only one file, named 'ca.crt' as the following:
+Then, you can concatenate them all into one file, named 'ca.crt' with the following:
 
 ```bash
 cat certificate1.crt certificate2.crt certificate3.crt >> ca.crt
 ```
 
-**Note:** Make sure that the Key Size is greater than 1024 and Hashing Algorithm(Digest) is something better than md5
+**Note:** Make sure that the Key Size is greater than 1024 and Hashing Algorithm (Digest) is something better than md5
 for each certificate generated. Otherwise you will receive an error.
 
 ## Creating Certificate Secrets
 
 There are many different ways of configuring your secrets to enable Client-Certificate
 Authentication to work properly.
 
-1. You can create a secret containing just the CA certificate and another
+*   You can create a secret containing just the CA certificate and another
     Secret containing the Server Certificate which is Signed by the CA.
 
     ```bash
     kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt
     kubectl create secret generic tls-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key
     ```
 
-2. You can create a secret containing CA certificate along with the Server
-    Certificate, that can be used for both TLS and Client Auth.
+*   You can create a secret containing CA certificate along with the Server
+    Certificate that can be used for both TLS and Client Auth.
 
     ```bash
     kubectl create secret generic ca-secret --from-file=tls.crt=server.crt --from-file=tls.key=server.key --from-file=ca.crt=ca.crt
     ```
 
-3. If you want to also enable Certificate Revocation List verification you can 
+*  If you want to also enable Certificate Revocation List verification you can
    create the secret also containing the CRL file in PEM format:
    ```bash
    kubectl create secret generic ca-secret --from-file=ca.crt=ca.crt --from-file=ca.crl=ca.crl

diff --git a/docs/examples/auth/external-auth/README.md b/docs/examples/auth/external-auth/README.md
@@ -1,6 +1,6 @@
 # External Basic Authentication
 
-### Example 1:
+### Example 1
 
 Use an external service (Basic Auth) located in `https://httpbin.org`
 
@@ -44,7 +44,7 @@ status:
 $
 ```
 
-Test 1: no username/password (expect code 401)
+## Test 1: no username/password (expect code 401)
 
 ```console
 $ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com'
@@ -74,7 +74,8 @@ $ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com'
 * Connection #0 to host 172.17.4.99 left intact
 ```
 
-Test 2: valid username/password (expect code 200)
+## Test 2: valid username/password (expect code 200)
+
 ```
 $ curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:passwd'
 * Rebuilt URL to: http://172.17.4.99/
@@ -121,7 +122,8 @@ BODY:
 -no body in request-
 ```
 
-Test 3: invalid username/password (expect code 401)
+## Test 3: invalid username/password (expect code 401)
+
 ```
 curl -k http://172.17.4.99 -v -H 'Host: external-auth-01.sample.com' -u 'user:user'
 * Rebuilt URL to: http://172.17.4.99/

diff --git a/docs/examples/auth/oauth-external-auth/README.md b/docs/examples/auth/oauth-external-auth/README.md
@@ -6,7 +6,7 @@ The `auth-url` and `auth-signin` annotations allow you to use an external
 authentication provider to protect your Ingress resources.
 
 !!! Important
-    This annotation requires `ingress-nginx-controller v0.9.0` or greater.)
+    This annotation requires `ingress-nginx-controller v0.9.0` or greater.
 
 ### Key Detail
 
@@ -32,45 +32,47 @@ metadata:
 ### Example: OAuth2 Proxy + Kubernetes-Dashboard
 
 This example will show you how to deploy [`oauth2_proxy`](https://github.com/pusher/oauth2_proxy)
-into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using github as oAuth2 provider
+into a Kubernetes cluster and use it to protect the Kubernetes Dashboard using GitHub as the OAuth2 provider.
 
 #### Prepare
 
 1. Install the kubernetes dashboard
 
-```console
-kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml
-```
+    ```console
+    kubectl create -f https://raw.githubusercontent.com/kubernetes/kops/master/addons/kubernetes-dashboard/v1.10.1.yaml
+    ```
 
-2. Create a [custom Github OAuth application](https://github.com/settings/applications/new)
+2. Create a [custom GitHub OAuth application](https://github.com/settings/applications/new)
 
-![Register OAuth2 Application](images/register-oauth-app.png)
+    ![Register OAuth2 Application](images/register-oauth-app.png)
 
-- Homepage URL is the FQDN in the Ingress rule, like `https://foo.bar.com`
-- Authorization callback URL is the same as the base FQDN plus `/oauth2/callback`, like `https://foo.bar.com/oauth2/callback`
+    - Homepage URL is the FQDN in the Ingress rule, like `https://foo.bar.com`
+    - Authorization callback URL is the same as the base FQDN plus `/oauth2/callback`, like `https://foo.bar.com/oauth2/callback`
 
-![Register OAuth2 Application](images/register-oauth-app-2.png)
+    ![Register OAuth2 Application](images/register-oauth-app-2.png)
 
 3. Configure oauth2_proxy values in the file [`oauth2-proxy.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/auth/oauth-external-auth/oauth2-proxy.yaml) with the values:
 
-- OAUTH2_PROXY_CLIENT_ID with the github `<Client ID>`
-- OAUTH2_PROXY_CLIENT_SECRET with the github `<Client Secret>`
-- OAUTH2_PROXY_COOKIE_SECRET with value of `python -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode("ascii"))'`
+    - OAUTH2_PROXY_CLIENT_ID with the github `<Client ID>`
+    - OAUTH2_PROXY_CLIENT_SECRET with the github `<Client Secret>`
+    - OAUTH2_PROXY_COOKIE_SECRET with value of `python -c 'import os,base64; print(base64.b64encode(os.urandom(16)).decode("ascii"))'`
 
 4. Customize the contents of the file [`dashboard-ingress.yaml`](https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/docs/examples/auth/oauth-external-auth/dashboard-ingress.yaml):
 
-Replace `__INGRESS_HOST__` with a valid FQDN and `__INGRESS_SECRET__` with a Secret with a valid SSL certificate.
+    Replace `__INGRESS_HOST__` with a valid FQDN and `__INGRESS_SECRET__` with a Secret with a valid SSL certificate.
 
 5. Deploy the oauth2 proxy and the ingress rules running:
 
-```console
-$ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
-```
+    ```console
+    $ kubectl create -f oauth2-proxy.yaml,dashboard-ingress.yaml
+    ```
+
+### Test
 
-Test the oauth integration accessing the configured URL, like `https://foo.bar.com`
+Test the oauth integration accessing the configured URL, e.g. `https://foo.bar.com`
 
 ![Register OAuth2 Application](images/github-auth.png)
 
-![Github authentication](images/oauth-login.png)
+![GitHub authentication](images/oauth-login.png)
 
 ![Kubernetes dashboard](images/dashboard.png)
diff --git a/docs/examples/customization/configuration-snippets/README.md b/docs/examples/customization/configuration-snippets/README.md
@@ -2,13 +2,16 @@
 
 ## Ingress
 
-The Ingress in [this example](ingress.yaml) adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at [this example](../custom-headers/README.md).
+The Ingress in [this example](ingress.yaml) adds a custom header to Nginx configuration that only applies to that specific Ingress. If you want to add headers that apply globally to all Ingresses, please have a look at [an example of specifying customer headers](../custom-headers/README.md).
 
 ```console
-$ kubectl apply -f ingress.yaml
+kubectl apply -f ingress.yaml
 ```
 
 ## Test
 
 Check if the contents of the annotation are present in the nginx.conf file using:
-`kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf`
+
+```console
+kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf
+```
diff --git a/docs/examples/customization/custom-headers/README.md b/docs/examples/customization/custom-headers/README.md
@@ -1,5 +1,15 @@
 # Custom Headers
 
+## Caveats
+
+Changes to the custom header config maps do not force a reload of the ingress-nginx-controllers.
+
+### Workaround
+
+To work around this limitation, perform a rolling restart of the deployment.
+
+## Example
+
 This example demonstrates configuration of the nginx ingress controller via
 a ConfigMap to pass a custom list of headers to the upstream
 server.
@@ -29,4 +39,4 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main
 ## Test
 
 Check the contents of the ConfigMaps are present in the nginx.conf file using:
-`kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf`
+`kubectl exec ingress-nginx-controller-873061567-4n3k2 -n ingress-nginx -- cat /etc/nginx/nginx.conf`
diff --git a/docs/examples/customization/external-auth-headers/README.md b/docs/examples/customization/external-auth-headers/README.md
@@ -1,7 +1,7 @@
 # External authentication, authentication service response headers propagation
 
 This example demonstrates propagation of selected authentication service response headers
-to backend service.
+to a backend service.
 
 Sample configuration includes:
 
@@ -37,7 +37,7 @@ public-demo-echo-service   public-demo-echo-service.kube.local             80
 secure-demo-echo-service   secure-demo-echo-service.kube.local             80        1m
 ```
 
-Test 1: public service with no auth header
+## Test 1: public service with no auth header
 
 ```console
 $ curl -H 'Host: public-demo-echo-service.kube.local' -v 192.168.99.100
@@ -60,7 +60,7 @@ $ curl -H 'Host: public-demo-echo-service.kube.local' -v 192.168.99.100
 UserID: , UserRole:
 ```
 
-Test 2: secure service with no auth header
+## Test 2: secure service with no auth header
 
 ```console
 $ curl -H 'Host: secure-demo-echo-service.kube.local' -v 192.168.99.100
@@ -89,7 +89,7 @@ $ curl -H 'Host: secure-demo-echo-service.kube.local' -v 192.168.99.100
 * Connection #0 to host 192.168.99.100 left intact
 ```
 
-Test 3: public service with valid auth header
+## Test 3: public service with valid auth header
 
 ```console
 $ curl -H 'Host: public-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100
@@ -113,7 +113,7 @@ $ curl -H 'Host: public-demo-echo-service.kube.local' -H 'User:internal' -v 192.
 UserID: 1443635317331776148, UserRole: admin
 ```
 
-Test 4: secure service with valid auth header
+## Test 4: secure service with valid auth header
 
 ```console
 $ curl -H 'Host: secure-demo-echo-service.kube.local' -H 'User:internal' -v 192.168.99.100

diff --git a/docs/examples/customization/ssl-dh-param/README.md b/docs/examples/customization/ssl-dh-param/README.md
@@ -1,7 +1,7 @@
 # Custom DH parameters for perfect forward secrecy
 
 This example aims to demonstrate the deployment of an nginx ingress controller and
-use a ConfigMap to configure custom Diffie-Hellman parameters file to help with
+use a ConfigMap to configure a custom Diffie-Hellman parameters file to help with
 "Perfect Forward Secrecy".
 
 ## Custom configuration
@@ -27,7 +27,7 @@ $ kubectl create -f configmap.yaml
 ## Custom DH parameters secret
 
 ```console
-$> openssl dhparam 4096 2> /dev/null | base64
+$ openssl dhparam 4096 2> /dev/null | base64
 LS0tLS1CRUdJTiBESCBQQVJBTUVURVJ...
 ```
 
@@ -52,4 +52,6 @@ $ kubectl create -f ssl-dh-param.yaml
 ## Test
 
 Check the contents of the configmap is present in the nginx.conf file using:
-`kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf`
+```console
+$ kubectl exec ingress-nginx-controller-873061567-4n3k2 -n kube-system -- cat /etc/nginx/nginx.conf
+```