Merge pull request #2464 from valohai/doc-fixes

Documentation fixes & improvements

docs/deploy/upgrade.md

@@ -0,0 +1,50 @@
+# Upgrading
+
+!!! important
+    No matter the method you use for upgrading, *if you use template overrides,
+    make sure your templates are compatible with the new version of ingress-nginx*.
+
+## Without Helm
+
+To upgrade your ingress-nginx installation, it should be enough to change the version of the image
+in the controller Deployment.
+
+I.e. if your deployment resource looks like (partial example):
+
+```yaml
+kind: Deployment
+metadata:
+  name: nginx-ingress-controller
+  namespace: ingress-nginx
+spec:
+  replicas: 1
+  selector: ...
+  template:
+    metadata: ...
+    spec:
+      containers:
+        - name: nginx-ingress-controller
+          image: quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.9.0
+          args: ...
+```
+
+simply change the `0.9.0` tag to the version you wish to upgrade to.
+The easiest way to do this is e.g. (do note you may need to change the name parameter according to your installation):
+
+```
+kubectl set image deployment/nginx-ingress-controller \
+  nginx-ingress-controller=nginx:quay.io/kubernetes-ingress-controller/nginx-ingress-controller:0.14.0
+```
+
+For interactive editing, use `kubectl edit deployment nginx-ingress-controller`.
+
+
+## With Helm
+
+If you installed ingress-nginx using the Helm command in the deployment docs so its name is `ngx-ingress`,
+you should be able to upgrade using
+
+```shell
+helm upgrade --reuse-values ngx-ingress stable/nginx-ingress
+```
+

docs/examples/customization/custom-vts-metrics-prometheus/README.md

@@ -1,4 +1,4 @@
-# Deploying the Nginx Ingress controller
+# Custom VTS metrics with Prometheus
 
 This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to enable [nginx vts module](https://github.com/vozlt/nginx-module-vts
 ) to export metrics in prometheus format. 

docs/examples/customization/ssl-dh-param/README.md

@@ -1,4 +1,4 @@
-# Deploying the Nginx Ingress controller
+# 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

docs/examples/index.md

@@ -0,0 +1,26 @@
+# Ingress examples
+
+This directory contains a catalog of examples on how to run, configure and scale Ingress.  
+Please review the [prerequisites](PREREQUISITES.md) before trying them.
+
+Category | Name | Description | Complexity Level
+---------| ---- | ----------- | ----------------
+Apps | [Docker Registry](docker-registry/README.md) | TODO | TODO
+Auth | [Basic authentication](auth/basic/README.md) | password protect your website | Intermediate
+Auth | [Client certificate authentication](auth/client-certs/README.md) | secure your website with client certificate authentication | Intermediate
+Auth | [External authentication plugin](auth/external-auth/README.md) | defer to an external authentication service | Intermediate
+Auth | [OAuth external auth](auth/oauth-external-auth/README.md) | TODO | TODO
+Customization | [Configuration snippets](customization/configuration-snippets/README.md) | customize nginx location configuration using annotations | Advanced
+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) | TODO | TODO
+Customization | [Custom headers](customization/custom-headers/README.md) | set custom headers before sending traffic to backends  | Advanced
+Customization | [Custom upstream check](customization/custom-upstream-check/README.md) | TODO | TODO
+Customization | [Custom VTS metrics with Prometheus](customization/custom-vts-metrics-prometheus/README.md) | TODO | TODO
+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
+Features | [Session stickiness](affinity/cookie/README.md) | route requests consistently to the same endpoint | Advanced
+Scaling | [Static IP](static-ip/README.md) | a single ingress gets a single static IP |  Intermediate
+TLS | [Multi TLS certificate termination](multi-tls/README.md) | TODO | TODO
+TLS | [TLS termination](tls-termination/README.md) | TODO | TODO

docs/user-guide/default-backend.md

@@ -0,0 +1,17 @@
+# Default backend
+
+The default backend is a service which handles all URL paths and hosts the nginx controller doesn't understand
+(i.e., all the requests that are not mapped with an Ingress).
+
+Basically a default backend exposes two URLs:
+
+- `/healthz` that returns 200
+- `/` that returns 404
+
+!!! example
+    The sub-directory [`/images/404-server`](https://github.com/kubernetes/ingress-nginx/tree/master/images/404-server)
+    provides a service which satisfies the requirements for a default backend.
+
+!!! example
+    The sub-directory [`/images/custom-error-pages`](https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages)
+    provides an additional service for the purpose of customizing the error pages served via the default backend.

docs/user-guide/miscellaneous.md

@@ -1,21 +1,5 @@
 # Miscellaneous
 
-## Conventions
-
-Anytime we reference a tls secret, we mean (x509, pem encoded, RSA 2048, etc). You can generate such a certificate with:
-`openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout ${KEY_FILE} -out ${CERT_FILE} -subj "/CN=${HOST}/O=${HOST}"`
-and create the secret via `kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE}`
-
-## Requirements
-
-The default backend is a service which handles all url paths and hosts the nginx controller doesn't understand (i.e., all the requests that are not mapped with an Ingress).
-Basically a default backend exposes two URLs:
-
-- `/healthz` that returns 200
-- `/` that returns 404
-
-The sub-directory [`/images/404-server`](https://github.com/kubernetes/ingress-nginx/tree/master/images/404-server) provides a service which satisfies the requirements for a default backend.  The sub-directory [`/images/custom-error-pages`](https://github.com/kubernetes/ingress-nginx/tree/master/images/custom-error-pages) provides an additional service for the purpose of customizing the error pages served via the default backend.
-
 ## Source IP address
 
 By default NGINX uses the content of the header `X-Forwarded-For` as the source of truth to get information about the client IP address. This works without issues in L7 **if we configure the setting `proxy-real-ip-cidr`** with the correct information of the IP/network address of trusted external load balancer.

docs/user-guide/multiple-ingress.md

@@ -1,30 +1,10 @@
-# Multiple ingress controllers
+# Multiple Ingress controllers
 
-## Running multiple ingress controllers
+If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress such as GKE,
+you need to specify the annotation `kubernetes.io/ingress.class: "nginx"` in all ingresses that you would like the ingress-nginx controller to claim.
 
-If you're running multiple ingress controllers, or running on a cloud provider that natively handles ingress, you need to specify the annotation `kubernetes.io/ingress.class: "nginx"` in all ingresses that you would like this controller to claim.
 
-This mechanism also provides users the ability to run _multiple_ NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).  When utilizing this functionality the option `--ingress-class` should be changed to a value unique for the cluster within the definition of the replication controller. Here is a partial example:
-
-```
-spec:
-  template:
-     spec:
-       containers:
-         - name: nginx-ingress-internal-controller
-           args:
-             - /nginx-ingress-controller
-             - '--default-backend-service=ingress/nginx-ingress-default-backend'
-             - '--election-id=ingress-controller-leader-internal'
-             - '--ingress-class=nginx-internal'
-             - '--configmap=ingress/nginx-ingress-internal-controller'
-```
-
-
-## Annotation ingress.class
-
-If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the `ingress.class` 
-annotation, eg creating an Ingress with an annotation like
+For instance,
 
 ```yaml
 metadata:
@@ -44,11 +24,32 @@ metadata:
 
 will target the nginx controller, forcing the GCE controller to ignore it.
 
-__Note__: Deploying multiple ingress controller and not specifying the annotation will result in both controllers fighting to satisfy the Ingress.
+To reiterate, setting the annotation to any value which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.
+If you are only running a single NGINX ingress controller, this can be achieved by setting the annotation to any value except "nginx" or an empty string.
 
-## Disabling NGINX ingress controller
+Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
 
-Setting the annotation `kubernetes.io/ingress.class` to any other value  which does not match a valid ingress class will force the NGINX Ingress controller to ignore your Ingress.  If you are only running a single NGINX ingress controller, this can be achieved by setting this to any value except "nginx" or an empty string.
+!!! important
+    Deploying multiple Ingress controllers and not specifying a class annotation will
+    result in both or all controllers fighting to satisfy the Ingress, and all of them
+    updating the Ingress status field in confusing ways.
 
-Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller.
+## Multiple ingress-nginx controllers
 
+This mechanism also provides users the ability to run _multiple_ NGINX ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic).
+To do this, the option `--ingress-class` must be changed to a value unique for the cluster within the definition of the replication controller.
+Here is a partial example:
+
+```yaml
+spec:
+  template:
+     spec:
+       containers:
+         - name: nginx-ingress-internal-controller
+           args:
+             - /nginx-ingress-controller
+             - '--default-backend-service=ingress/nginx-ingress-default-backend'
+             - '--election-id=ingress-controller-leader-internal'
+             - '--ingress-class=nginx-internal'
+             - '--configmap=ingress/nginx-ingress-internal-controller'
+```