From 0aa9d2e89ff5f95b01abb4840a4e064e9ce33dd4 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 12:36:16 +0300 Subject: [PATCH 01/10] Move all documentation under docs/ --- README.md | 156 +-------------- deploy/README.md | 322 +----------------------------- docs/deploy.md | 321 +++++++++++++++++++++++++++++ docs/development.md | 2 +- docs/examples/rewrite/README.md | 4 +- docs/examples/static-ip/README.md | 6 +- docs/index.md | 154 ++++++++++++++ {deploy => docs}/rbac.md | 0 8 files changed, 485 insertions(+), 480 deletions(-) create mode 100644 docs/deploy.md create mode 100644 docs/index.md rename {deploy => docs}/rbac.md (100%) diff --git a/README.md b/README.md index fcdc595797..dc50277117 100644 --- a/README.md +++ b/README.md @@ -22,158 +22,6 @@ The Ingress resource embodies this idea, and an Ingress controller is meant to h An Ingress Controller is a daemon, deployed as a Kubernetes Pod, that watches the apiserver's `/ingresses` endpoint for updates to the [Ingress resource](https://kubernetes.io/docs/concepts/services-networking/ingress/). Its job is to satisfy requests for Ingresses. -## Contents +## Documentation -- [Conventions](#conventions) -- [Requirements](#requirements) -- [Deployment](deploy/README.md) -- [Command line arguments](docs/user-guide/cli-arguments.md) -- [Contribute](CONTRIBUTING.md) -- [TLS](docs/user-guide/tls.md) -- [Annotation ingress.class](#annotation-ingressclass) -- [Customizing NGINX](#customizing-nginx) - - [Custom NGINX configuration](docs/user-guide/configmap.md) - - [Annotations](docs/user-guide/annotations.md) -- [Source IP address](#source-ip-address) -- [Exposing TCP and UDP Services](docs/user-guide/exposing-tcp-udp-services.md) -- [Proxy Protocol](#proxy-protocol) -- [ModSecurity Web Application Firewall](docs/user-guide/modsecurity.md) -- [OpenTracing](docs/user-guide/opentracing.md) -- [VTS and Prometheus metrics](docs/examples/customization/custom-vts-metrics-prometheus/README.md) -- [Custom errors](docs/user-guide/custom-errors.md) -- [NGINX status page](docs/user-guide/nginx-status-page.md) -- [Running multiple ingress controllers](#running-multiple-ingress-controllers) -- [Disabling NGINX ingress controller](#disabling-nginx-ingress-controller) -- [Retries in non-idempotent methods](#retries-in-non-idempotent-methods) -- [Log format](docs/user-guide/log-format.md) -- [Websockets](#websockets) -- [Optimizing TLS Time To First Byte (TTTFB)](#optimizing-tls-time-to-first-byte-tttfb) -- [Debug & Troubleshooting](docs/troubleshooting.md) -- [Limitations](#limitations) -- [Why endpoints and not services?](#why-endpoints-and-not-services) -- [External Articles](docs/user-guide/external-articles.md) - -## 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. - -## 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 - -```yaml -metadata: - name: foo - annotations: - kubernetes.io/ingress.class: "gce" -``` - -will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like - -```yaml -metadata: - name: foo - annotations: - kubernetes.io/ingress.class: "nginx" -``` - -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. - -### Customizing NGINX - -There are three ways to customize NGINX: - -1. [ConfigMap](docs/user-guide/configmap.md): using a Configmap to set global configurations in NGINX. -2. [Annotations](docs/user-guide/annotations.md): use this if you want a specific configuration for a particular Ingress rule. -3. [Custom template](docs/user-guide/custom-template.md): when more specific settings are required, like [open_file_cache](http://nginx.org/en/docs/http/ngx_http_core_module.html#open_file_cache), adjust [listen](http://nginx.org/en/docs/http/ngx_http_core_module.html#listen) options as `rcvbuf` or when is not possible to change the configuration through the ConfigMap. - -## 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. - -If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. - -Another option is to enable proxy protocol using `use-proxy-protocol: "true"`. - -In this mode NGINX does not use the content of the header to get the source IP address of the connection. - -## Proxy Protocol - -If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the [Proxy Protocol](http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt) for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself. - -Amongst others [ELBs in AWS](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/enable-proxy-protocol.html) and [HAProxy](http://www.haproxy.org/) support Proxy Protocol. - -### Running multiple ingress controllers - -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' -``` - -Not specifying the annotation will lead to multiple ingress controllers claiming the same ingress. Specifying a value which does not match the class of any existing ingress controllers will result in all ingress controllers ignoring the ingress. - -The use of multiple ingress controllers in a single cluster is supported in Kubernetes versions >= 1.3. - -### Websockets - -Support for websockets is provided by NGINX out of the box. No special configuration required. - -The only requirement to avoid the close of connections is the increase of the values of `proxy-read-timeout` and `proxy-send-timeout`. - -The default value of this settings is `60 seconds`. - -A more adequate value to support websockets is a value higher than one hour (`3600`). - -**Important:** If the NGINX ingress controller is exposed with a service `type=LoadBalancer` make sure the protocol between the loadbalancer and NGINX is TCP. - -### Optimizing TLS Time To First Byte (TTTFB) - -NGINX provides the configuration option [ssl_buffer_size](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) to allow the optimization of the TLS record size. - -This improves the [TLS Time To First Byte](https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/) (TTTFB). -The default value in the Ingress controller is `4k` (NGINX default is `16k`). - -### Retries in non-idempotent methods - -Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error. -The previous behavior can be restored using `retry-non-idempotent=true` in the configuration ConfigMap. - -### Disabling NGINX ingress 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. - -Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller. - -### Limitations - -- Ingress rules for TLS require the definition of the field `host` - -### Why endpoints and not services - -The NGINX ingress controller does not use [Services](http://kubernetes.io/docs/user-guide/services) to route traffic to the pods. Instead it uses the Endpoints API in order to bypass [kube-proxy](http://kubernetes.io/docs/admin/kube-proxy/) to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT. +See [docs/index.md](docs/index.md) for detailed documentation. diff --git a/deploy/README.md b/deploy/README.md index 01c97bdfdd..8048daa46c 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,321 +1,3 @@ -# Installation Guide +# Deployment documentation moved! -## Contents - -- [Mandatory commands](#mandatory-commands) -- [Install without RBAC roles](#install-without-rbac-roles) -- [Install with RBAC roles](#install-with-rbac-roles) -- [Custom Provider](#custom-provider) - - [Docker for Mac](#docker-for-mac) - - [minikube](#minikube) - - [AWS](#aws) - - [GCE - GKE](#gce---gke) - - [Azure](#azure) - - [Baremetal](#baremetal) -- [Using Helm](#using-helm) -- [Verify installation](#verify-installation) -- [Detect installed version](#detect-installed-version) -- [Deploying the config-map](#deploying-the-config-map) - -## Generic Deployment - -The following resources are required for a generic deployment. - -### Mandatory commands - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \ - | kubectl apply -f - - -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \ - | kubectl apply -f - - -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \ - | kubectl apply -f - - -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \ - | kubectl apply -f - - -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \ - | kubectl apply -f - -``` - -### Install without RBAC roles - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \ - | kubectl apply -f - -``` - -### Install with RBAC roles - -Please check the [RBAC](rbac.md) document. - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \ - | kubectl apply -f - - -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \ - | kubectl apply -f - -``` - -## Custom Service Provider Deployment - -There are cloud provider specific yaml files. - -### Docker for Mac - -Kubernetes is available for Docker for Mac's Edge channel. Switch to the [Edge -channel][edge] and [enable Kubernetes][enable]. - -[edge]: https://docs.docker.com/docker-for-mac/install/ -[enable]: https://docs.docker.com/docker-for-mac/#kubernetes - -Patch the nginx ingress controller deployment to add the flag `--publish-service` - -```console -kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ - --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" -``` - -Create a service - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/docker-for-mac/service.yaml \ - | kubectl apply -f - -``` - -### minikube - -For standard usage: - -```console -minikube addons enable ingress -``` - -For development: - -1. Disable the ingress addon: - -```console -$ minikube addons disable ingress -``` - -2. Use the [docker daemon](https://github.com/kubernetes/minikube/blob/master/docs/reusing_the_docker_daemon.md) -3. [Build the image](../docs/development.md) -4. Perform [Mandatory commands](#mandatory-commands) -5. Install the `nginx-ingress-controller` deployment [without RBAC roles](#install-without-rbac-roles) or [with RBAC roles](#install-with-rbac-roles) -6. Edit the `nginx-ingress-controller` deployment to use your custom image. Local images can be seen by performing `docker images`. - -```console -$ kubectl edit deployment nginx-ingress-controller -n ingress-nginx -``` - -edit the following section: - -```yaml -image: : -imagePullPolicy: IfNotPresent -name: nginx-ingress-controller -``` - -7. Confirm the `nginx-ingress-controller` deployment exists: - -```console -$ kubectl get pods -n ingress-nginx -NAME READY STATUS RESTARTS AGE -default-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s -nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s -``` - -### AWS - -In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of `Type=LoadBalancer`. -Since Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB) -Please check the [elastic load balancing AWS details page](https://aws.amazon.com/es/elasticloadbalancing/details/) - -#### Elastic Load Balancer - ELB - -This setup requires to choose in which layer (L4 or L7) we want to configure the ELB: - -- [Layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_Layer): use TCP as the listener protocol for ports 80 and 443. -- [Layer 7](https://en.wikipedia.org/wiki/OSI_model#Layer_7:_Application_Layer): use HTTP as the listener protocol for port 80 and terminate TLS in the ELB - -Patch the nginx ingress controller deployment to add the flag `--publish-service` - -```console -kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ - --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" -``` - -For L4: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml -``` - -For L7: - -Change line of the file `provider/aws/service-l7.yaml` replacing the dummy id with a valid one `"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"` -Then execute: - -```console -kubectl apply -f provider/aws/service-l7.yaml -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml -``` - -This example creates an ELB with just two listeners, one in port 80 and another in port 443 - -![Listeners](../docs/images/elb-l7-listener.png) - -If the ingress controller uses RBAC run: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml -``` - -If not run: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml -``` - -#### Network Load Balancer (NLB) - -This type of load balancer is supported since v1.10.0 as an ALPHA feature. - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml -``` - -If the ingress controller uses RBAC run: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml -``` - -If not run: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml -``` - -### GCE - GKE - -Patch the nginx ingress controller deployment to add the flag `--publish-service` - -```console -kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ - --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" -``` - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \ - | kubectl apply -f - -``` - -If the ingress controller uses RBAC run: - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml | kubectl apply -f - -``` - -If not run: - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml | kubectl apply -f - -``` - -**Important Note:** proxy protocol is not supported in GCE/GKE - -### Azure - -Patch the nginx ingress controller deployment to add the flag `--publish-service` - -```console -kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ - --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" -``` - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \ - | kubectl apply -f - -``` - -If the ingress controller uses RBAC run: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml -``` - -If not run: - -```console -kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml -``` - -**Important Note:** proxy protocol is not supported in GCE/GKE - -### Baremetal - -Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport): - -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \ - | kubectl apply -f - -``` - -## Using Helm - -NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository. -To install the chart with the release name `my-nginx`: - -```console -helm install stable/nginx-ingress --name my-nginx -``` - -If the kubernetes cluster has RBAC enabled, then run: - -```console -helm install stable/nginx-ingress --name my-nginx --set rbac.create=true -``` - -## Verify installation - -To check if the ingress controller pods have started, run the following command: - -```console -kubectl get pods --all-namespaces -l app=ingress-nginx --watch -``` - -Once the operator pods are running, you can cancel the above command by typing `Ctrl+C`. -Now, you are ready to create your first ingress. - -## Detect installed version - -To detect which version of the ingress controller is running, exec into the pod and run `nginx-ingress-controller version` command. - -```console -POD_NAMESPACE=ingress-nginx -POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=ingress-nginx -o jsonpath={.items[0].metadata.name}) -kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version -``` - -## Deploying the config-map - -A config map can be used to configure system components for the nginx-controller. In order to begin using a config-map -make sure it has been created and is being used in the deployment. - -It is created as seen in the [Mandatory Commands](#mandatory-commands) section above. -```console -curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \ - | kubectl apply -f - -``` - -and is setup to be used in the deployment [without-rbac](without-rbac.yaml) or [with-rbac](with-rbac.yaml) with the following line: -```yaml -- --configmap=$(POD_NAMESPACE)/nginx-configuration -``` - -For information on using the config-map, see its [user-guide](../docs/user-guide/configmap.md). +See (/docs/deploy.md)[../docs/deploy.md]. \ No newline at end of file diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000000..284f990eb0 --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,321 @@ +# Installation Guide + +## Contents + +- [Mandatory commands](#mandatory-commands) +- [Install without RBAC roles](#install-without-rbac-roles) +- [Install with RBAC roles](#install-with-rbac-roles) +- [Custom Provider](#custom-provider) + - [Docker for Mac](#docker-for-mac) + - [minikube](#minikube) + - [AWS](#aws) + - [GCE - GKE](#gce---gke) + - [Azure](#azure) + - [Baremetal](#baremetal) +- [Using Helm](#using-helm) +- [Verify installation](#verify-installation) +- [Detect installed version](#detect-installed-version) +- [Deploying the config-map](#deploying-the-config-map) + +## Generic Deployment + +The following resources are required for a generic deployment. + +### Mandatory commands + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \ + | kubectl apply -f - +``` + +### Install without RBAC roles + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \ + | kubectl apply -f - +``` + +### Install with RBAC roles + +Please check the [RBAC](rbac.md) document. + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \ + | kubectl apply -f - + +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \ + | kubectl apply -f - +``` + +## Custom Service Provider Deployment + +There are cloud provider specific yaml files. + +### Docker for Mac + +Kubernetes is available for Docker for Mac's Edge channel. Switch to the [Edge +channel][edge] and [enable Kubernetes][enable]. + +[edge]: https://docs.docker.com/docker-for-mac/install/ +[enable]: https://docs.docker.com/docker-for-mac/#kubernetes + +Patch the nginx ingress controller deployment to add the flag `--publish-service` + +```console +kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +``` + +Create a service + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/docker-for-mac/service.yaml \ + | kubectl apply -f - +``` + +### minikube + +For standard usage: + +```console +minikube addons enable ingress +``` + +For development: + +1. Disable the ingress addon: + +```console +$ minikube addons disable ingress +``` + +2. Use the [docker daemon](https://github.com/kubernetes/minikube/blob/master/docs/reusing_the_docker_daemon.md) +3. [Build the image](./development.md) +4. Perform [Mandatory commands](#mandatory-commands) +5. Install the `nginx-ingress-controller` deployment [without RBAC roles](#install-without-rbac-roles) or [with RBAC roles](#install-with-rbac-roles) +6. Edit the `nginx-ingress-controller` deployment to use your custom image. Local images can be seen by performing `docker images`. + +```console +$ kubectl edit deployment nginx-ingress-controller -n ingress-nginx +``` + +edit the following section: + +```yaml +image: : +imagePullPolicy: IfNotPresent +name: nginx-ingress-controller +``` + +7. Confirm the `nginx-ingress-controller` deployment exists: + +```console +$ kubectl get pods -n ingress-nginx +NAME READY STATUS RESTARTS AGE +default-http-backend-66b447d9cf-rrlf9 1/1 Running 0 12s +nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s +``` + +### AWS + +In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of `Type=LoadBalancer`. +Since Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB) +Please check the [elastic load balancing AWS details page](https://aws.amazon.com/es/elasticloadbalancing/details/) + +#### Elastic Load Balancer - ELB + +This setup requires to choose in which layer (L4 or L7) we want to configure the ELB: + +- [Layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_Layer): use TCP as the listener protocol for ports 80 and 443. +- [Layer 7](https://en.wikipedia.org/wiki/OSI_model#Layer_7:_Application_Layer): use HTTP as the listener protocol for port 80 and terminate TLS in the ELB + +Patch the nginx ingress controller deployment to add the flag `--publish-service` + +```console +kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +``` + +For L4: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml +``` + +For L7: + +Change line of the file `provider/aws/service-l7.yaml` replacing the dummy id with a valid one `"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"` +Then execute: + +```console +kubectl apply -f provider/aws/service-l7.yaml +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml +``` + +This example creates an ELB with just two listeners, one in port 80 and another in port 443 + +![Listeners](../docs/images/elb-l7-listener.png) + +If the ingress controller uses RBAC run: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml +``` + +If not run: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml +``` + +#### Network Load Balancer (NLB) + +This type of load balancer is supported since v1.10.0 as an ALPHA feature. + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-nlb.yaml +``` + +If the ingress controller uses RBAC run: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml +``` + +If not run: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml +``` + +### GCE - GKE + +Patch the nginx ingress controller deployment to add the flag `--publish-service` + +```console +kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +``` + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \ + | kubectl apply -f - +``` + +If the ingress controller uses RBAC run: + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml | kubectl apply -f - +``` + +If not run: + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml | kubectl apply -f - +``` + +**Important Note:** proxy protocol is not supported in GCE/GKE + +### Azure + +Patch the nginx ingress controller deployment to add the flag `--publish-service` + +```console +kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \ + --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)" +``` + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \ + | kubectl apply -f - +``` + +If the ingress controller uses RBAC run: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml +``` + +If not run: + +```console +kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml +``` + +**Important Note:** proxy protocol is not supported in GCE/GKE + +### Baremetal + +Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport): + +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \ + | kubectl apply -f - +``` + +## Using Helm + +NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [stable/nginx](https://github.com/kubernetes/charts/tree/master/stable/nginx-ingress) from the official charts repository. +To install the chart with the release name `my-nginx`: + +```console +helm install stable/nginx-ingress --name my-nginx +``` + +If the kubernetes cluster has RBAC enabled, then run: + +```console +helm install stable/nginx-ingress --name my-nginx --set rbac.create=true +``` + +## Verify installation + +To check if the ingress controller pods have started, run the following command: + +```console +kubectl get pods --all-namespaces -l app=ingress-nginx --watch +``` + +Once the operator pods are running, you can cancel the above command by typing `Ctrl+C`. +Now, you are ready to create your first ingress. + +## Detect installed version + +To detect which version of the ingress controller is running, exec into the pod and run `nginx-ingress-controller version` command. + +```console +POD_NAMESPACE=ingress-nginx +POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app=ingress-nginx -o jsonpath={.items[0].metadata.name}) +kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version +``` + +## Deploying the config-map + +A config map can be used to configure system components for the nginx-controller. In order to begin using a config-map +make sure it has been created and is being used in the deployment. + +It is created as seen in the [Mandatory Commands](#mandatory-commands) section above. +```console +curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \ + | kubectl apply -f - +``` + +and is setup to be used in the deployment [without-rbac](../deploy/without-rbac.yaml) or [with-rbac](../deploy/with-rbac.yaml) with the following line: +```yaml +- --configmap=$(POD_NAMESPACE)/nginx-configuration +``` + +For information on using the config-map, see its [user-guide](./user-guide/configmap.md). diff --git a/docs/development.md b/docs/development.md index c351e39539..a9a7e4debe 100644 --- a/docs/development.md +++ b/docs/development.md @@ -107,7 +107,7 @@ $ TAG= REGISTRY=$USER/ingress-controller make docker-push ## Deploying There are several ways to deploy the ingress controller onto a cluster. -Please check the [deployment guide](../deploy/README.md) +Please check the [deployment guide](./deploy.md) ## Testing diff --git a/docs/examples/rewrite/README.md b/docs/examples/rewrite/README.md index f67cd90d58..3ce607992b 100644 --- a/docs/examples/rewrite/README.md +++ b/docs/examples/rewrite/README.md @@ -5,8 +5,8 @@ This example demonstrates how to use the Rewrite annotations ## Prerequisites You will need to make sure your Ingress targets exactly one Ingress -controller by specifying the [ingress.class annotation](/README.md#annotation-ingressclass), -and that you have an ingress controller [running](/deploy/README.md) in your cluster. +controller by specifying the [ingress.class annotation](../../index.md#annotation-ingressclass), +and that you have an ingress controller [running](../../deploy.md) in your cluster. ## Deployment diff --git a/docs/examples/static-ip/README.md b/docs/examples/static-ip/README.md index 130a2f88e4..348997fc46 100644 --- a/docs/examples/static-ip/README.md +++ b/docs/examples/static-ip/README.md @@ -4,10 +4,10 @@ This example demonstrates how to assign a static-ip to an Ingress on through the ## Prerequisites -You need a [TLS cert](/docs/examples/PREREQUISITES.md#tls-certificates) and a [test HTTP service](/docs/examples/PREREQUISITES.md#test-http-service) for this example. +You need a [TLS cert](../PREREQUISITES.md#tls-certificates) and a [test HTTP service](../PREREQUISITES.md#test-http-service) for this example. You will also need to make sure your Ingress targets exactly one Ingress -controller by specifying the [ingress.class annotation](/README.md#annotation-ingressclass), -and that you have an ingress controller [running](/deploy/README.md) in your cluster. +controller by specifying the [ingress.class annotation](../../index.md#annotation-ingressclass), +and that you have an ingress controller [running](../../deploy.md) in your cluster. ## Acquiring an IP diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..5e313e587e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,154 @@ +## Contents + +- [Conventions](#conventions) +- [Requirements](#requirements) +- [Deployment](./deploy.md) +- [Command line arguments](./user-guide/cli-arguments.md) +- [TLS](./user-guide/tls.md) +- [Annotation ingress.class](#annotation-ingressclass) +- [Customizing NGINX](#customizing-nginx) + - [Custom NGINX configuration](./user-guide/configmap.md) + - [Annotations](./user-guide/annotations.md) +- [Source IP address](#source-ip-address) +- [Exposing TCP and UDP Services](./user-guide/exposing-tcp-udp-services.md) +- [Proxy Protocol](#proxy-protocol) +- [ModSecurity Web Application Firewall](./user-guide/modsecurity.md) +- [OpenTracing](./user-guide/opentracing.md) +- [VTS and Prometheus metrics](./examples/customization/custom-vts-metrics-prometheus/README.md) +- [Custom errors](./user-guide/custom-errors.md) +- [NGINX status page](./user-guide/nginx-status-page.md) +- [Running multiple ingress controllers](#running-multiple-ingress-controllers) +- [Disabling NGINX ingress controller](#disabling-nginx-ingress-controller) +- [Retries in non-idempotent methods](#retries-in-non-idempotent-methods) +- [Log format](./user-guide/log-format.md) +- [Websockets](#websockets) +- [Optimizing TLS Time To First Byte (TTTFB)](#optimizing-tls-time-to-first-byte-tttfb) +- [Debug & Troubleshooting](./troubleshooting.md) +- [Limitations](#limitations) +- [Why endpoints and not services?](#why-endpoints-and-not-services) +- [External Articles](./user-guide/external-articles.md) + +## 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. + +## 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 + +```yaml +metadata: + name: foo + annotations: + kubernetes.io/ingress.class: "gce" +``` + +will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like + +```yaml +metadata: + name: foo + annotations: + kubernetes.io/ingress.class: "nginx" +``` + +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. + +### Customizing NGINX + +There are three ways to customize NGINX: + +1. [ConfigMap](./user-guide/configmap.md): using a Configmap to set global configurations in NGINX. +2. [Annotations](./user-guide/annotations.md): use this if you want a specific configuration for a particular Ingress rule. +3. [Custom template](./user-guide/custom-template.md): when more specific settings are required, like [open_file_cache](http://nginx.org/en/./http/ngx_http_core_module.html#open_file_cache), adjust [listen](http://nginx.org/en/./http/ngx_http_core_module.html#listen) options as `rcvbuf` or when is not possible to change the configuration through the ConfigMap. + +## 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. + +If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. + +Another option is to enable proxy protocol using `use-proxy-protocol: "true"`. + +In this mode NGINX does not use the content of the header to get the source IP address of the connection. + +## Proxy Protocol + +If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the [Proxy Protocol](http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt) for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself. + +Amongst others [ELBs in AWS](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/enable-proxy-protocol.html) and [HAProxy](http://www.haproxy.org/) support Proxy Protocol. + +### Running multiple ingress controllers + +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' +``` + +Not specifying the annotation will lead to multiple ingress controllers claiming the same ingress. Specifying a value which does not match the class of any existing ingress controllers will result in all ingress controllers ignoring the ingress. + +The use of multiple ingress controllers in a single cluster is supported in Kubernetes versions >= 1.3. + +### Websockets + +Support for websockets is provided by NGINX out of the box. No special configuration required. + +The only requirement to avoid the close of connections is the increase of the values of `proxy-read-timeout` and `proxy-send-timeout`. + +The default value of this settings is `60 seconds`. + +A more adequate value to support websockets is a value higher than one hour (`3600`). + +**Important:** If the NGINX ingress controller is exposed with a service `type=LoadBalancer` make sure the protocol between the loadbalancer and NGINX is TCP. + +### Optimizing TLS Time To First Byte (TTTFB) + +NGINX provides the configuration option [ssl_buffer_size](http://nginx.org/en/./http/ngx_http_ssl_module.html#ssl_buffer_size) to allow the optimization of the TLS record size. + +This improves the [TLS Time To First Byte](https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/) (TTTFB). +The default value in the Ingress controller is `4k` (NGINX default is `16k`). + +### Retries in non-idempotent methods + +Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error. +The previous behavior can be restored using `retry-non-idempotent=true` in the configuration ConfigMap. + +### Disabling NGINX ingress 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. + +Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller. + +### Limitations + +- Ingress rules for TLS require the definition of the field `host` + +### Why endpoints and not services + +The NGINX ingress controller does not use [Services](http://kubernetes.io/./user-guide/services) to route traffic to the pods. Instead it uses the Endpoints API in order to bypass [kube-proxy](http://kubernetes.io/./admin/kube-proxy/) to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT. diff --git a/deploy/rbac.md b/docs/rbac.md similarity index 100% rename from deploy/rbac.md rename to docs/rbac.md From d1479a2d21ec272f3ded0d76239177863a56317b Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 13:11:47 +0300 Subject: [PATCH 02/10] Move miscellaneous tidbits from README to miscellaneous.md and other files --- docs/development.md | 2 +- docs/examples/rewrite/README.md | 2 +- docs/examples/static-ip/README.md | 2 +- docs/index.md | 155 ++------------------------- docs/miscellaneous.md | 65 +++++++++++ docs/user-guide/customizing-nginx.md | 7 ++ docs/user-guide/multiple-ingress.md | 52 +++++++++ 7 files changed, 133 insertions(+), 152 deletions(-) create mode 100644 docs/miscellaneous.md create mode 100644 docs/user-guide/customizing-nginx.md create mode 100644 docs/user-guide/multiple-ingress.md diff --git a/docs/development.md b/docs/development.md index a9a7e4debe..3170f385e6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,4 +1,4 @@ -# Getting Started +# Developing for NGINX Ingress controller This document explains how to get started with developing for NGINX Ingress controller. It includes how to build, test, and release ingress controllers. diff --git a/docs/examples/rewrite/README.md b/docs/examples/rewrite/README.md index 3ce607992b..d78227eba6 100644 --- a/docs/examples/rewrite/README.md +++ b/docs/examples/rewrite/README.md @@ -5,7 +5,7 @@ This example demonstrates how to use the Rewrite annotations ## Prerequisites You will need to make sure your Ingress targets exactly one Ingress -controller by specifying the [ingress.class annotation](../../index.md#annotation-ingressclass), +controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md), and that you have an ingress controller [running](../../deploy.md) in your cluster. ## Deployment diff --git a/docs/examples/static-ip/README.md b/docs/examples/static-ip/README.md index 348997fc46..28bee9bc6a 100644 --- a/docs/examples/static-ip/README.md +++ b/docs/examples/static-ip/README.md @@ -6,7 +6,7 @@ This example demonstrates how to assign a static-ip to an Ingress on through the You need a [TLS cert](../PREREQUISITES.md#tls-certificates) and a [test HTTP service](../PREREQUISITES.md#test-http-service) for this example. You will also need to make sure your Ingress targets exactly one Ingress -controller by specifying the [ingress.class annotation](../../index.md#annotation-ingressclass), +controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md), and that you have an ingress controller [running](../../deploy.md) in your cluster. ## Acquiring an IP diff --git a/docs/index.md b/docs/index.md index 5e313e587e..6e123c0bf2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,154 +1,11 @@ -## Contents +# NGINX Ingress Controller -- [Conventions](#conventions) -- [Requirements](#requirements) -- [Deployment](./deploy.md) -- [Command line arguments](./user-guide/cli-arguments.md) -- [TLS](./user-guide/tls.md) -- [Annotation ingress.class](#annotation-ingressclass) -- [Customizing NGINX](#customizing-nginx) - - [Custom NGINX configuration](./user-guide/configmap.md) - - [Annotations](./user-guide/annotations.md) -- [Source IP address](#source-ip-address) -- [Exposing TCP and UDP Services](./user-guide/exposing-tcp-udp-services.md) -- [Proxy Protocol](#proxy-protocol) -- [ModSecurity Web Application Firewall](./user-guide/modsecurity.md) -- [OpenTracing](./user-guide/opentracing.md) -- [VTS and Prometheus metrics](./examples/customization/custom-vts-metrics-prometheus/README.md) -- [Custom errors](./user-guide/custom-errors.md) -- [NGINX status page](./user-guide/nginx-status-page.md) -- [Running multiple ingress controllers](#running-multiple-ingress-controllers) -- [Disabling NGINX ingress controller](#disabling-nginx-ingress-controller) -- [Retries in non-idempotent methods](#retries-in-non-idempotent-methods) -- [Log format](./user-guide/log-format.md) -- [Websockets](#websockets) -- [Optimizing TLS Time To First Byte (TTTFB)](#optimizing-tls-time-to-first-byte-tttfb) -- [Debug & Troubleshooting](./troubleshooting.md) -- [Limitations](#limitations) -- [Why endpoints and not services?](#why-endpoints-and-not-services) -- [External Articles](./user-guide/external-articles.md) +This is the documentation for the NGINX Ingress Controller. -## Conventions +It is built around the [Kubernetes Ingress resource](http://kubernetes.io/docs/user-guide/ingress/), using a [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/#understanding-configmaps-and-pods) to store the NGINX configuration. -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}` +Learn more about using Ingress on [k8s.io](http://kubernetes.io/docs/user-guide/ingress/). -## Requirements +## Getting Started -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. - -## 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 - -```yaml -metadata: - name: foo - annotations: - kubernetes.io/ingress.class: "gce" -``` - -will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like - -```yaml -metadata: - name: foo - annotations: - kubernetes.io/ingress.class: "nginx" -``` - -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. - -### Customizing NGINX - -There are three ways to customize NGINX: - -1. [ConfigMap](./user-guide/configmap.md): using a Configmap to set global configurations in NGINX. -2. [Annotations](./user-guide/annotations.md): use this if you want a specific configuration for a particular Ingress rule. -3. [Custom template](./user-guide/custom-template.md): when more specific settings are required, like [open_file_cache](http://nginx.org/en/./http/ngx_http_core_module.html#open_file_cache), adjust [listen](http://nginx.org/en/./http/ngx_http_core_module.html#listen) options as `rcvbuf` or when is not possible to change the configuration through the ConfigMap. - -## 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. - -If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. - -Another option is to enable proxy protocol using `use-proxy-protocol: "true"`. - -In this mode NGINX does not use the content of the header to get the source IP address of the connection. - -## Proxy Protocol - -If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the [Proxy Protocol](http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt) for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself. - -Amongst others [ELBs in AWS](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/enable-proxy-protocol.html) and [HAProxy](http://www.haproxy.org/) support Proxy Protocol. - -### Running multiple ingress controllers - -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' -``` - -Not specifying the annotation will lead to multiple ingress controllers claiming the same ingress. Specifying a value which does not match the class of any existing ingress controllers will result in all ingress controllers ignoring the ingress. - -The use of multiple ingress controllers in a single cluster is supported in Kubernetes versions >= 1.3. - -### Websockets - -Support for websockets is provided by NGINX out of the box. No special configuration required. - -The only requirement to avoid the close of connections is the increase of the values of `proxy-read-timeout` and `proxy-send-timeout`. - -The default value of this settings is `60 seconds`. - -A more adequate value to support websockets is a value higher than one hour (`3600`). - -**Important:** If the NGINX ingress controller is exposed with a service `type=LoadBalancer` make sure the protocol between the loadbalancer and NGINX is TCP. - -### Optimizing TLS Time To First Byte (TTTFB) - -NGINX provides the configuration option [ssl_buffer_size](http://nginx.org/en/./http/ngx_http_ssl_module.html#ssl_buffer_size) to allow the optimization of the TLS record size. - -This improves the [TLS Time To First Byte](https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/) (TTTFB). -The default value in the Ingress controller is `4k` (NGINX default is `16k`). - -### Retries in non-idempotent methods - -Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error. -The previous behavior can be restored using `retry-non-idempotent=true` in the configuration ConfigMap. - -### Disabling NGINX ingress 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. - -Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller. - -### Limitations - -- Ingress rules for TLS require the definition of the field `host` - -### Why endpoints and not services - -The NGINX ingress controller does not use [Services](http://kubernetes.io/./user-guide/services) to route traffic to the pods. Instead it uses the Endpoints API in order to bypass [kube-proxy](http://kubernetes.io/./admin/kube-proxy/) to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT. +See [Deployment](./deploy.md) for a whirlwind tour that will get you started. diff --git a/docs/miscellaneous.md b/docs/miscellaneous.md new file mode 100644 index 0000000000..0820822166 --- /dev/null +++ b/docs/miscellaneous.md @@ -0,0 +1,65 @@ +# 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. + +If the ingress controller is running in AWS we need to use the VPC IPv4 CIDR. + +Another option is to enable proxy protocol using `use-proxy-protocol: "true"`. + +In this mode NGINX does not use the content of the header to get the source IP address of the connection. + +## Proxy Protocol + +If you are using a L4 proxy to forward the traffic to the NGINX pods and terminate HTTP/HTTPS there, you will lose the remote endpoint's IP address. To prevent this you could use the [Proxy Protocol](http://www.haproxy.org/download/1.5/doc/proxy-protocol.txt) for forwarding traffic, this will send the connection details before forwarding the actual TCP connection itself. + +Amongst others [ELBs in AWS](http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/enable-proxy-protocol.html) and [HAProxy](http://www.haproxy.org/) support Proxy Protocol. + +## Websockets + +Support for websockets is provided by NGINX out of the box. No special configuration required. + +The only requirement to avoid the close of connections is the increase of the values of `proxy-read-timeout` and `proxy-send-timeout`. + +The default value of this settings is `60 seconds`. + +A more adequate value to support websockets is a value higher than one hour (`3600`). + +**Important:** If the NGINX ingress controller is exposed with a service `type=LoadBalancer` make sure the protocol between the loadbalancer and NGINX is TCP. + +## Optimizing TLS Time To First Byte (TTTFB) + +NGINX provides the configuration option [ssl_buffer_size](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_buffer_size) to allow the optimization of the TLS record size. + +This improves the [TLS Time To First Byte](https://www.igvita.com/2013/12/16/optimizing-nginx-tls-time-to-first-byte/) (TTTFB). +The default value in the Ingress controller is `4k` (NGINX default is `16k`). + +## Retries in non-idempotent methods + +Since 1.9.13 NGINX will not retry non-idempotent requests (POST, LOCK, PATCH) in case of an error. +The previous behavior can be restored using `retry-non-idempotent=true` in the configuration ConfigMap. + +## Limitations + +- Ingress rules for TLS require the definition of the field `host` + +## Why endpoints and not services + +The NGINX ingress controller does not use [Services](http://kubernetes.io/docs/user-guide/services) to route traffic to the pods. Instead it uses the Endpoints API in order to bypass [kube-proxy](http://kubernetes.io/docs/admin/kube-proxy/) to allow NGINX features like session affinity and custom load balancing algorithms. It also removes some overhead, such as conntrack entries for iptables DNAT. \ No newline at end of file diff --git a/docs/user-guide/customizing-nginx.md b/docs/user-guide/customizing-nginx.md new file mode 100644 index 0000000000..337c8da4ec --- /dev/null +++ b/docs/user-guide/customizing-nginx.md @@ -0,0 +1,7 @@ +# Customizing NGINX + +There are three ways to customize NGINX: + +1. [ConfigMap](./configmap.md): using a Configmap to set global configurations in NGINX. +2. [Annotations](./annotations.md): use this if you want a specific configuration for a particular Ingress rule. +3. [Custom template](./custom-template.md): when more specific settings are required, like [open_file_cache](http://nginx.org/en/./http/ngx_http_core_module.html#open_file_cache), adjust [listen](http://nginx.org/en/./http/ngx_http_core_module.html#listen) options as `rcvbuf` or when is not possible to change the configuration through the ConfigMap. diff --git a/docs/user-guide/multiple-ingress.md b/docs/user-guide/multiple-ingress.md new file mode 100644 index 0000000000..375bc82b16 --- /dev/null +++ b/docs/user-guide/multiple-ingress.md @@ -0,0 +1,52 @@ +# Multiple ingress controllers + +## Running multiple ingress controllers + +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 + +```yaml +metadata: + name: foo + annotations: + kubernetes.io/ingress.class: "gce" +``` + +will target the GCE controller, forcing the nginx controller to ignore it, while an annotation like + +```yaml +metadata: + name: foo + annotations: + kubernetes.io/ingress.class: "nginx" +``` + +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. + +## Disabling NGINX ingress 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. + +Do this if you wish to use one of the other Ingress controllers at the same time as the NGINX controller. + From 4b80166d7687ff0272d6866967353851f7553146 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 13:18:29 +0300 Subject: [PATCH 03/10] Fix some document titles --- docs/examples/customization/configuration-snippets/README.md | 2 ++ docs/examples/customization/custom-configuration/README.md | 1 + docs/examples/customization/custom-errors/README.md | 2 ++ docs/examples/customization/custom-headers/README.md | 2 +- docs/index.md | 2 +- docs/{catalog.md => ingress-controller-catalog.md} | 2 +- 6 files changed, 8 insertions(+), 3 deletions(-) rename docs/{catalog.md => ingress-controller-catalog.md} (97%) diff --git a/docs/examples/customization/configuration-snippets/README.md b/docs/examples/customization/configuration-snippets/README.md index eff7b3eee3..b0f2486a1c 100644 --- a/docs/examples/customization/configuration-snippets/README.md +++ b/docs/examples/customization/configuration-snippets/README.md @@ -1,5 +1,7 @@ +# Configuration Snippets ## Ingress + The Ingress in this example 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](/docs/examples/customization/custom-headers). ```console diff --git a/docs/examples/customization/custom-configuration/README.md b/docs/examples/customization/custom-configuration/README.md index 8772d7a348..bd85c13ac4 100644 --- a/docs/examples/customization/custom-configuration/README.md +++ b/docs/examples/customization/custom-configuration/README.md @@ -1,3 +1,4 @@ +# Custom Configuration Using a [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/) is possible to customize the NGINX configuration diff --git a/docs/examples/customization/custom-errors/README.md b/docs/examples/customization/custom-errors/README.md index 080f59a831..45c2db5fd9 100644 --- a/docs/examples/customization/custom-errors/README.md +++ b/docs/examples/customization/custom-errors/README.md @@ -1,3 +1,5 @@ +# Custom Errors + This example shows how is possible to use a custom backend to render custom error pages. The code of this example is located here [custom-error-pages](https://github.com/kubernetes/ingress-nginx/tree/master/docs/examples/customization/custom-errors) diff --git a/docs/examples/customization/custom-headers/README.md b/docs/examples/customization/custom-headers/README.md index 592c7ec881..b5e4c6022b 100644 --- a/docs/examples/customization/custom-headers/README.md +++ b/docs/examples/customization/custom-headers/README.md @@ -1,4 +1,4 @@ -# Custom configuration +# Custom Headers This example aims to demonstrate the deployment of an nginx ingress controller and use a ConfigMap to configure a custom list of headers to be passed to the upstream diff --git a/docs/index.md b/docs/index.md index 6e123c0bf2..91e3f05c06 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -# NGINX Ingress Controller +# Welcome This is the documentation for the NGINX Ingress Controller. diff --git a/docs/catalog.md b/docs/ingress-controller-catalog.md similarity index 97% rename from docs/catalog.md rename to docs/ingress-controller-catalog.md index 08fac9bc4f..c5b207b6c3 100644 --- a/docs/catalog.md +++ b/docs/ingress-controller-catalog.md @@ -1,4 +1,4 @@ -# Ingress controller Catalog +# Ingress Controller Catalog This is a non-comprehensive list of existing ingress controllers. From dc18dff4317686b6fe31aa782b0f058623abab5a Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 13:19:11 +0300 Subject: [PATCH 04/10] Move deployment documentation under docs/deploy/ --- deploy/README.md | 2 +- docs/{deploy.md => deploy/index.md} | 4 ++-- docs/{ => deploy}/rbac.md | 2 +- docs/development.md | 2 +- docs/examples/rewrite/README.md | 2 +- docs/examples/static-ip/README.md | 2 +- docs/index.md | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) rename docs/{deploy.md => deploy/index.md} (98%) rename docs/{ => deploy}/rbac.md (98%) diff --git a/deploy/README.md b/deploy/README.md index 8048daa46c..c20fc01c9c 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -1,3 +1,3 @@ # Deployment documentation moved! -See (/docs/deploy.md)[../docs/deploy.md]. \ No newline at end of file +See (/docs/deploy)[../docs/deploy/index.md]. \ No newline at end of file diff --git a/docs/deploy.md b/docs/deploy/index.md similarity index 98% rename from docs/deploy.md rename to docs/deploy/index.md index 284f990eb0..12b3654b74 100644 --- a/docs/deploy.md +++ b/docs/deploy/index.md @@ -102,7 +102,7 @@ $ minikube addons disable ingress ``` 2. Use the [docker daemon](https://github.com/kubernetes/minikube/blob/master/docs/reusing_the_docker_daemon.md) -3. [Build the image](./development.md) +3. [Build the image](../development.md) 4. Perform [Mandatory commands](#mandatory-commands) 5. Install the `nginx-ingress-controller` deployment [without RBAC roles](#install-without-rbac-roles) or [with RBAC roles](#install-with-rbac-roles) 6. Edit the `nginx-ingress-controller` deployment to use your custom image. Local images can be seen by performing `docker images`. @@ -318,4 +318,4 @@ and is setup to be used in the deployment [without-rbac](../deploy/without-rbac. - --configmap=$(POD_NAMESPACE)/nginx-configuration ``` -For information on using the config-map, see its [user-guide](./user-guide/configmap.md). +For information on using the config-map, see its [user-guide](../user-guide/configmap.md). diff --git a/docs/rbac.md b/docs/deploy/rbac.md similarity index 98% rename from docs/rbac.md rename to docs/deploy/rbac.md index ebf79aec28..08c1a02914 100644 --- a/docs/rbac.md +++ b/docs/deploy/rbac.md @@ -1,4 +1,4 @@ -# Role Based Access Control - RBAC +# Role Based Access Control (RBAC) ## Overview diff --git a/docs/development.md b/docs/development.md index 3170f385e6..c5f2299453 100644 --- a/docs/development.md +++ b/docs/development.md @@ -107,7 +107,7 @@ $ TAG= REGISTRY=$USER/ingress-controller make docker-push ## Deploying There are several ways to deploy the ingress controller onto a cluster. -Please check the [deployment guide](./deploy.md) +Please check the [deployment guide](./deploy) ## Testing diff --git a/docs/examples/rewrite/README.md b/docs/examples/rewrite/README.md index d78227eba6..6fecb04961 100644 --- a/docs/examples/rewrite/README.md +++ b/docs/examples/rewrite/README.md @@ -6,7 +6,7 @@ This example demonstrates how to use the Rewrite annotations You will need to make sure your Ingress targets exactly one Ingress controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md), -and that you have an ingress controller [running](../../deploy.md) in your cluster. +and that you have an ingress controller [running](../../deploy) in your cluster. ## Deployment diff --git a/docs/examples/static-ip/README.md b/docs/examples/static-ip/README.md index 28bee9bc6a..66343274e2 100644 --- a/docs/examples/static-ip/README.md +++ b/docs/examples/static-ip/README.md @@ -7,7 +7,7 @@ This example demonstrates how to assign a static-ip to an Ingress on through the You need a [TLS cert](../PREREQUISITES.md#tls-certificates) and a [test HTTP service](../PREREQUISITES.md#test-http-service) for this example. You will also need to make sure your Ingress targets exactly one Ingress controller by specifying the [ingress.class annotation](../../user-guide/multiple-ingress.md), -and that you have an ingress controller [running](../../deploy.md) in your cluster. +and that you have an ingress controller [running](../../deploy) in your cluster. ## Acquiring an IP diff --git a/docs/index.md b/docs/index.md index 91e3f05c06..2be8c2c9dc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,4 +8,4 @@ Learn more about using Ingress on [k8s.io](http://kubernetes.io/docs/user-guide/ ## Getting Started -See [Deployment](./deploy.md) for a whirlwind tour that will get you started. +See [Deployment](./deploy) for a whirlwind tour that will get you started. From 34314254f317ebbf09dadaa4403706ccf45b51f6 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 13:25:25 +0300 Subject: [PATCH 05/10] Remove empty ingress-annotations document; fix up annotations.md's layout slightly --- docs/user-guide/annotations.md | 12 +++++------- docs/user-guide/ingress-annotations.md | 0 2 files changed, 5 insertions(+), 7 deletions(-) delete mode 100644 docs/user-guide/ingress-annotations.md diff --git a/docs/user-guide/annotations.md b/docs/user-guide/annotations.md index 5a267018fe..4b9ed3db6a 100644 --- a/docs/user-guide/annotations.md +++ b/docs/user-guide/annotations.md @@ -1,10 +1,10 @@ -**IMPORTANT:** +# Annotations -The key and values in annotations can only be strings. -This means that we want a value with boolean values we need to quote the values, like "true" or "false". -Same for numbers, like "100". +!!! tip + Annotation keys and values can only be strings. + Other types, such as boolean or numeric values must be quoted, + i.e. `"true"`, `"false"`, `"100"`. -# Annotations The following annotations are supported: @@ -71,8 +71,6 @@ The following annotations are supported: |[nginx.ingress.kubernetes.io/lua-resty-waf-ignore-rulesets](#lua-resty-waf)|string| |[nginx.ingress.kubernetes.io/lua-resty-waf-extra-rules](#lua-resty-waf)|string| -**Note:** all the values must be a string. In case of booleans or number it must be quoted. - ### Rewrite In some scenarios the exposed URL in the backend service differs from the specified path in the Ingress rule. Without a rewrite any request will return 404. diff --git a/docs/user-guide/ingress-annotations.md b/docs/user-guide/ingress-annotations.md deleted file mode 100644 index e69de29bb2..0000000000 From 13ace4a5c76596a98f7d5d7a48ac0a3570209c9f Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 13:30:17 +0300 Subject: [PATCH 06/10] Configure mkdocs with mkdocs-material and friends --- .gitignore | 3 +++ docs/.pages | 6 ++++++ docs/deploy/.pages | 1 + mkdocs.yml | 24 ++++++++++++++++++++++++ requirements-docs.txt | 5 +++++ 5 files changed, 39 insertions(+) create mode 100644 docs/.pages create mode 100644 docs/deploy/.pages create mode 100644 mkdocs.yml create mode 100644 requirements-docs.txt diff --git a/.gitignore b/.gitignore index a421505ce6..fd8e1aeed4 100644 --- a/.gitignore +++ b/.gitignore @@ -33,3 +33,6 @@ e2e-tests coverage.txt test/e2e/e2e\.test + +# mkdocs +/site \ No newline at end of file diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000000..09be52c1b8 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,6 @@ +arrange: +- index.md +- deploy +- user-guide +- examples +- ... \ No newline at end of file diff --git a/docs/deploy/.pages b/docs/deploy/.pages new file mode 100644 index 0000000000..e6ef2d1a5c --- /dev/null +++ b/docs/deploy/.pages @@ -0,0 +1 @@ +title: Deployment \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..7b83ffcc6c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,24 @@ +site_name: NGINX Ingress Controller +strict: true +repo_name: 'kubernetes/ingress-nginx' +repo_url: 'https://github.com/kubernetes/ingress-nginx' +markdown_extensions: + - admonition + - codehilite + - pymdownx.inlinehilite + - pymdownx.tasklist(custom_checkbox=true) + - toc: + permalink: true +theme: + name: material + feature: + tabs: true + logo: + icon: 'public' # globe icon + palette: + primary: 'teal' + accent: 'green' +plugins: + - search + - awesome-pages: + collapse_single_pages: true \ No newline at end of file diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000000..0d2bfd4c83 --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,5 @@ +mkdocs-material~=2.7.0 +mkdocs-awesome-pages-plugin~=1.2.0 +mkdocs~=0.17.0 +pygments~=2.2.0 +pymdown-extensions~=4.10 \ No newline at end of file From 17745a920dcf61278afffb216676b53848a0c791 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 14:32:27 +0300 Subject: [PATCH 07/10] Move "Customizing NGINX" documentation under "NGINX Configuration" --- docs/deploy/index.md | 2 +- docs/user-guide/.pages | 3 +++ docs/user-guide/nginx-configuration/.pages | 1 + .../{ => nginx-configuration}/annotations.md | 16 ++++++++-------- .../{ => nginx-configuration}/configmap.md | 3 ++- .../{ => nginx-configuration}/custom-template.md | 0 .../index.md} | 2 +- .../{ => nginx-configuration}/log-format.md | 0 8 files changed, 16 insertions(+), 11 deletions(-) create mode 100644 docs/user-guide/.pages create mode 100644 docs/user-guide/nginx-configuration/.pages rename docs/user-guide/{ => nginx-configuration}/annotations.md (98%) rename docs/user-guide/{ => nginx-configuration}/configmap.md (99%) rename docs/user-guide/{ => nginx-configuration}/custom-template.md (100%) rename docs/user-guide/{customizing-nginx.md => nginx-configuration/index.md} (96%) rename docs/user-guide/{ => nginx-configuration}/log-format.md (100%) diff --git a/docs/deploy/index.md b/docs/deploy/index.md index 12b3654b74..b4e6432bfe 100644 --- a/docs/deploy/index.md +++ b/docs/deploy/index.md @@ -318,4 +318,4 @@ and is setup to be used in the deployment [without-rbac](../deploy/without-rbac. - --configmap=$(POD_NAMESPACE)/nginx-configuration ``` -For information on using the config-map, see its [user-guide](../user-guide/configmap.md). +For information on using the config-map, see its [user-guide](../user-guide/nginx-configuration/configmap.md). diff --git a/docs/user-guide/.pages b/docs/user-guide/.pages new file mode 100644 index 0000000000..946bbcec5b --- /dev/null +++ b/docs/user-guide/.pages @@ -0,0 +1,3 @@ +arrange: +- nginx-configuration +- ... \ No newline at end of file diff --git a/docs/user-guide/nginx-configuration/.pages b/docs/user-guide/nginx-configuration/.pages new file mode 100644 index 0000000000..42ff10d0b0 --- /dev/null +++ b/docs/user-guide/nginx-configuration/.pages @@ -0,0 +1 @@ +title: NGINX Configuration diff --git a/docs/user-guide/annotations.md b/docs/user-guide/nginx-configuration/annotations.md similarity index 98% rename from docs/user-guide/annotations.md rename to docs/user-guide/nginx-configuration/annotations.md index 4b9ed3db6a..f58d5c54d6 100644 --- a/docs/user-guide/annotations.md +++ b/docs/user-guide/nginx-configuration/annotations.md @@ -1,13 +1,13 @@ # Annotations +You can add these Kubernetes annotations to specific Ingress objects to customize their behavior. + !!! tip Annotation keys and values can only be strings. Other types, such as boolean or numeric values must be quoted, i.e. `"true"`, `"false"`, `"100"`. -The following annotations are supported: - |Name | type | |---------------------------|------| |[nginx.ingress.kubernetes.io/add-base-url](#rewrite)|"true" or "false"| @@ -82,14 +82,14 @@ If the scheme of [`base` tag](https://developer.mozilla.org/en/docs/Web/HTML/Ele If the Application Root is exposed in a different path and needs to be redirected, set the annotation `nginx.ingress.kubernetes.io/app-root` to redirect requests for `/`. -Please check the [rewrite](../examples/rewrite/README.md) example. +Please check the [rewrite](../../examples/rewrite/README.md) example. ### Session Affinity The annotation `nginx.ingress.kubernetes.io/affinity` enables and sets the affinity type in all Upstreams of an Ingress. This way, a request will always be directed to the same upstream server. The only affinity type available for NGINX is `cookie`. -Please check the [affinity](../examples/affinity/cookie/README.md) example. +Please check the [affinity](../../examples/affinity/cookie/README.md) example. ### Authentication @@ -113,7 +113,7 @@ This annotation also accepts the alternative form "namespace/secretName", in whi nginx.ingress.kubernetes.io/auth-realm: "realm string" ``` -Please check the [auth](../examples/auth/basic/README.md) example. +Please check the [auth](../../examples/auth/basic/README.md) example. ### Custom NGINX upstream checks @@ -131,7 +131,7 @@ In NGINX, backend server pools are called "[upstreams](http://nginx.org/en/docs/ **Important:** All Ingress rules using the same service will use the same upstream. Only one of the Ingress rules should define annotations to configure the upstream servers. -Please check the [custom upstream check](../examples/customization/custom-upstream-check/README.md) example. +Please check the [custom upstream check](../../examples/customization/custom-upstream-check/README.md) example. ### Custom NGINX upstream hashing @@ -187,7 +187,7 @@ nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream Indicates if the received certificates should be passed or not to the upstream server. By default this is disabled. -Please check the [client-certs](../examples/auth/client-certs/README.md) example. +Please check the [client-certs](../../examples/auth/client-certs/README.md) example. **Important:** @@ -313,7 +313,7 @@ Additionally it is possible to set: `nginx.ingress.kubernetes.io/auth-request-redirect`: `` to specify the X-Auth-Request-Redirect header value. -Please check the [external-auth](../examples/auth/external-auth/README.md) example. +Please check the [external-auth](../../examples/auth/external-auth/README.md) example. ### Rate limiting diff --git a/docs/user-guide/configmap.md b/docs/user-guide/nginx-configuration/configmap.md similarity index 99% rename from docs/user-guide/configmap.md rename to docs/user-guide/nginx-configuration/configmap.md index 65dc1862ad..f164d94dd1 100644 --- a/docs/user-guide/configmap.md +++ b/docs/user-guide/nginx-configuration/configmap.md @@ -1,6 +1,7 @@ -# NGINX Ingress controller configuration ConfigMap +# ConfigMaps ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable. + The ConfigMap API resource stores configuration data as key-value pairs. The data provides the configurations for system components for the nginx-controller. Before you can begin using a config-map it must be [deployed](../../deploy/README.md/#deploying-the-config-map). diff --git a/docs/user-guide/custom-template.md b/docs/user-guide/nginx-configuration/custom-template.md similarity index 100% rename from docs/user-guide/custom-template.md rename to docs/user-guide/nginx-configuration/custom-template.md diff --git a/docs/user-guide/customizing-nginx.md b/docs/user-guide/nginx-configuration/index.md similarity index 96% rename from docs/user-guide/customizing-nginx.md rename to docs/user-guide/nginx-configuration/index.md index 337c8da4ec..9cd5f6a15c 100644 --- a/docs/user-guide/customizing-nginx.md +++ b/docs/user-guide/nginx-configuration/index.md @@ -1,4 +1,4 @@ -# Customizing NGINX +# NGINX Configuration There are three ways to customize NGINX: diff --git a/docs/user-guide/log-format.md b/docs/user-guide/nginx-configuration/log-format.md similarity index 100% rename from docs/user-guide/log-format.md rename to docs/user-guide/nginx-configuration/log-format.md From 1196b48745794d67f441b6f3689310bcf23c31cf Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 14:32:47 +0300 Subject: [PATCH 08/10] Regenerate cli-arguments.md from the actual usage of 0.13 --- docs/user-guide/cli-arguments.md | 108 +++++++++----------- docs/user-guide/convert_arguments_to_doc.py | 41 ++++++++ 2 files changed, 87 insertions(+), 62 deletions(-) create mode 100644 docs/user-guide/convert_arguments_to_doc.py diff --git a/docs/user-guide/cli-arguments.md b/docs/user-guide/cli-arguments.md index ffa21b6d05..91707fd4b5 100644 --- a/docs/user-guide/cli-arguments.md +++ b/docs/user-guide/cli-arguments.md @@ -1,64 +1,48 @@ # Command line arguments -```console -Usage of : - --alsologtostderr log to standard error as well as files - --annotations-prefix string Prefix of the ingress annotations. (default "nginx.ingress.kubernetes.io") - --apiserver-host string The address of the Kubernetes Apiserver to connect to in the format of protocol://address:port, e.g., http://localhost:8080. If not specified, the assumption is that the binary runs inside a Kubernetes cluster and local discovery is attempted. - --configmap string Name of the ConfigMap that contains the custom configuration to use - --default-backend-service string Service used to serve a 404 page for the default backend. Takes the form - namespace/name. The controller uses the first node port of this Service for - the default backend. - --default-server-port int Default port to use for exposing the default server (catch all) (default 8181) - --default-ssl-certificate string Name of the secret - that contains a SSL certificate to be used as default for a HTTPS catch-all server. - Takes the form /. - --election-id string Election id to use for status update. (default "ingress-controller-leader") - --enable-dynamic-configuration When enabled controller will try to avoid Nginx reloads as much as possible by using Lua. Disabled by default. - --enable-ssl-chain-completion Defines if the nginx ingress controller should check the secrets for missing intermediate CA certificates. - If the certificate contain issues chain issues is not possible to enable OCSP. - Default is true. (default true) - --enable-ssl-passthrough Enable SSL passthrough feature. Default is disabled - --force-namespace-isolation Force namespace isolation. This flag is required to avoid the reference of secrets or - configmaps located in a different namespace than the specified in the flag --watch-namespace. - --health-check-path string Defines - the URL to be used as health check inside in the default server in NGINX. (default "/healthz") - --healthz-port int port for healthz endpoint. (default 10254) - --http-port int Indicates the port to use for HTTP traffic (default 80) - --https-port int Indicates the port to use for HTTPS traffic (default 443) - --ingress-class string Name of the ingress class to route through this controller. - --kubeconfig string Path to kubeconfig file with authorization and master location information. - --log_backtrace_at traceLocation when logging hits line file:N, emit a stack trace (default :0) - --log_dir string If non-empty, write log files in this directory - --logtostderr log to standard error instead of files (default true) - --profiling Enable profiling via web interface host:port/debug/pprof/ (default true) - --publish-service string Service fronting the ingress controllers. Takes the form namespace/name. - The controller will set the endpoint records on the ingress objects to reflect those on the service. - --publish-status-address string User customized address to be set in the status of ingress resources. The controller will set the - endpoint records on the ingress using this address. - --report-node-internal-ip-address Defines if the nodes IP address to be returned in the ingress status should be the internal instead of the external IP address - --sort-backends Defines if backends and its endpoints should be sorted - --ssl-passtrough-proxy-port int Default port to use internally for SSL when SSL Passthgough is enabled (default 442) - --status-port int Indicates the TCP port to use for exposing the nginx status page (default 18080) - --stderrthreshold severity logs at or above this threshold go to stderr (default 2) - --sync-period duration Relist and confirm cloud resources this often. Default is 10 minutes (default 10m0s) - --sync-rate-limit float32 Define the sync frequency upper limit (default 0.3) - --tcp-services-configmap string Name of the ConfigMap that contains the definition of the TCP services to expose. - The key in the map indicates the external port to be used. The value is the name of the - service with the format namespace/serviceName and the port of the service could be a - number of the name of the port. - The ports 80 and 443 are not allowed as external ports. This ports are reserved for the backend - --udp-services-configmap string Name of the ConfigMap that contains the definition of the UDP services to expose. - The key in the map indicates the external port to be used. The value is the name of the - service with the format namespace/serviceName and the port of the service could be a - number of the name of the port. - --update-status Indicates if the - ingress controller should update the Ingress status IP/hostname. Default is true (default true) - --update-status-on-shutdown Indicates if the - ingress controller should update the Ingress status IP/hostname when the controller - is being stopped. Default is true (default true) - -v, --v Level log level for V logs - --version Shows release information about the NGINX Ingress controller - --vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging - --watch-namespace string Namespace to watch for Ingress. Default is to watch all namespaces -``` +The following command line arguments are accepted by the main controller executable. + +They are set in the container spec of the `nginx-ingress-controller` Deployment object (see `deploy/with-rbac.yaml` or `deploy/without-rbac.yaml`). + + +| Argument | Description | +|----------|-------------| +| `--alsologtostderr` | log to standard error as well as files | +| `--annotations-prefix string` | Prefix of the ingress annotations. (default "nginx.ingress.kubernetes.io") | +| `--apiserver-host string` | The address of the Kubernetes Apiserver to connect to in the format of protocol://address:port, e.g., http://localhost:8080. If not specified, the assumption is that the binary runs inside a Kubernetes cluster and local discovery is attempted. | +| `--configmap string` | Name of the ConfigMap that contains the custom configuration to use | +| `--default-backend-service string` | Service used to serve a 404 page for the default backend. Takes the form namespace/name. The controller uses the first node port of this Service for the default backend. | +| `--default-server-port int` | Default port to use for exposing the default server (catch all) (default 8181) | +| `--default-ssl-certificate string` | Name of the secret that contains a SSL certificate to be used as default for a HTTPS catch-all server. Takes the form /. | +| `--election-id string` | Election id to use for status update. (default "ingress-controller-leader") | +| `--enable-dynamic-configuration` | When enabled controller will try to avoid Nginx reloads as much as possible by using Lua. Disabled by default. | +| `--enable-ssl-chain-completion` | Defines if the nginx ingress controller should check the secrets for missing intermediate CA certificates. If the certificate contain issues chain issues is not possible to enable OCSP. Default is true. (default true) | +| `--enable-ssl-passthrough` | Enable SSL passthrough feature. Default is disabled | +| `--force-namespace-isolation` | Force namespace isolation. This flag is required to avoid the reference of secrets or configmaps located in a different namespace than the specified in the flag --watch-namespace. | +| `--health-check-path string` | Defines the URL to be used as health check inside in the default server in NGINX. (default "/healthz") | +| `--healthz-port int` | port for healthz endpoint. (default 10254) | +| `--http-port int` | Indicates the port to use for HTTP traffic (default 80) | +| `--https-port int` | Indicates the port to use for HTTPS traffic (default 443) | +| `--ingress-class string` | Name of the ingress class to route through this controller. | +| `--kubeconfig string` | Path to kubeconfig file with authorization and master location information. | +| `--log_backtrace_at traceLocation` | when logging hits line file:N, emit a stack trace (default :0) | +| `--log_dir string` | If non-empty, write log files in this directory | +| `--logtostderr` | log to standard error instead of files (default true) | +| `--profiling` | Enable profiling via web interface host:port/debug/pprof/ (default true) | +| `--publish-service string` | Service fronting the ingress controllers. Takes the form namespace/name. The controller will set the endpoint records on the ingress objects to reflect those on the service. | +| `--publish-status-address string` | User customized address to be set in the status of ingress resources. The controller will set the endpoint records on the ingress using this address. | +| `--report-node-internal-ip-address` | Defines if the nodes IP address to be returned in the ingress status should be the internal instead of the external IP address | +| `--sort-backends` | Defines if backends and its endpoints should be sorted | +| `--ssl-passtrough-proxy-port int` | Default port to use internally for SSL when SSL Passthgough is enabled (default 442) | +| `--status-port int` | Indicates the TCP port to use for exposing the nginx status page (default 18080) | +| `--stderrthreshold severity` | logs at or above this threshold go to stderr (default 2) | +| `--sync-period duration` | Relist and confirm cloud resources this often. Default is 10 minutes (default 10m0s) | +| `--sync-rate-limit float32` | Define the sync frequency upper limit (default 0.3) | +| `--tcp-services-configmap string` | Name of the ConfigMap that contains the definition of the TCP services to expose. The key in the map indicates the external port to be used. The value is the name of the service with the format namespace/serviceName and the port of the service could be a number of the name of the port. The ports 80 and 443 are not allowed as external ports. This ports are reserved for the backend | +| `--udp-services-configmap string` | Name of the ConfigMap that contains the definition of the UDP services to expose. The key in the map indicates the external port to be used. The value is the name of the service with the format namespace/serviceName and the port of the service could be a number of the name of the port. | +| `--update-status` | Indicates if the ingress controller should update the Ingress status IP/hostname. Default is true (default true) | +| `--update-status-on-shutdown` | Indicates if the ingress controller should update the Ingress status IP/hostname when the controller is being stopped. Default is true (default true) | +| `-v`, `--v Level` | log level for V logs | +| `--version` | Shows release information about the NGINX Ingress controller | +| `--vmodule moduleSpec` | comma-separated list of pattern=N settings for file-filtered logging | +| `--watch-namespace string` | Namespace to watch for Ingress. Default is to watch all namespaces | diff --git a/docs/user-guide/convert_arguments_to_doc.py b/docs/user-guide/convert_arguments_to_doc.py new file mode 100644 index 0000000000..9f419672a7 --- /dev/null +++ b/docs/user-guide/convert_arguments_to_doc.py @@ -0,0 +1,41 @@ +#!/usr/bin/env python + +# Copyright 2018 The Kubernetes Authors. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Convert the output of `nginx-ingress-controller --help` to +a Markdown table. +""" + +import re +import sys + +assert sys.version_info[0] == 3, 'This script requires Python 3' + +data = sys.stdin.read() +data = data.replace('\t', ' ' * 8) # Expand tabs +data = data.replace('\n' + (' ' * 8 * 2), ' ') # Unwrap lines + +print(''' +| Argument | Description | +|----------|-------------| +'''.rstrip()) + +for arg_m in re.finditer('^\s+(-.+?)\s{2,}(.+)$', data, flags=re.MULTILINE): + arg, description = arg_m.groups() + print('| `{arg}` | {description} |'.format( + arg=arg.replace(', ', '`, `'), + description=description, + )) From e677ea22e202e102460d4235f67b820ff927e15e Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 14:33:39 +0300 Subject: [PATCH 09/10] Remove default-ssl-certificate.md (the content is already in tls.md) --- docs/user-guide/default-ssl-certificate.md | 103 --------------------- 1 file changed, 103 deletions(-) delete mode 100644 docs/user-guide/default-ssl-certificate.md diff --git a/docs/user-guide/default-ssl-certificate.md b/docs/user-guide/default-ssl-certificate.md deleted file mode 100644 index 549f672b04..0000000000 --- a/docs/user-guide/default-ssl-certificate.md +++ /dev/null @@ -1,103 +0,0 @@ -# Default SSL Certificate - -NGINX provides the option to configure a server as a catch-all with [server name _](http://nginx.org/en/docs/http/server_names.html) for requests that do not match any of the configured server names. This configuration works without issues for HTTP traffic. -In case of HTTPS, NGINX requires a certificate. -For this reason the Ingress controller provides the flag `--default-ssl-certificate`. The secret behind this flag contains the default certificate to be used in the mentioned scenario. If this flag is not provided NGINX will use a self signed certificate. - -Running without the flag `--default-ssl-certificate`: - -```console -$ curl -v https://10.2.78.7:443 -k -* Rebuilt URL to: https://10.2.78.7:443/ -* Trying 10.2.78.4... -* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0) -* ALPN, offering http/1.1 -* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH -* successfully set certificate verify locations: -* CAfile: /etc/ssl/certs/ca-certificates.crt - CApath: /etc/ssl/certs -* TLSv1.2 (OUT), TLS header, Certificate Status (22): -* TLSv1.2 (OUT), TLS handshake, Client hello (1): -* TLSv1.2 (IN), TLS handshake, Server hello (2): -* TLSv1.2 (IN), TLS handshake, Certificate (11): -* TLSv1.2 (IN), TLS handshake, Server key exchange (12): -* TLSv1.2 (IN), TLS handshake, Server finished (14): -* TLSv1.2 (OUT), TLS handshake, Client key exchange (16): -* TLSv1.2 (OUT), TLS change cipher, Client hello (1): -* TLSv1.2 (OUT), TLS handshake, Finished (20): -* TLSv1.2 (IN), TLS change cipher, Client hello (1): -* TLSv1.2 (IN), TLS handshake, Finished (20): -* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 -* ALPN, server accepted to use http/1.1 -* Server certificate: -* subject: CN=foo.bar.com -* start date: Apr 13 00:50:56 2016 GMT -* expire date: Apr 13 00:50:56 2017 GMT -* issuer: CN=foo.bar.com -* SSL certificate verify result: self signed certificate (18), continuing anyway. -> GET / HTTP/1.1 -> Host: 10.2.78.7 -> User-Agent: curl/7.47.1 -> Accept: */* -> -< HTTP/1.1 404 Not Found -< Server: nginx/1.11.1 -< Date: Thu, 21 Jul 2016 15:38:46 GMT -< Content-Type: text/html -< Transfer-Encoding: chunked -< Connection: keep-alive -< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload -< -The page you're looking for could not be found. - -* Connection #0 to host 10.2.78.7 left intact -``` - -Specifying `--default-ssl-certificate=default/foo-tls`: - -```console -core@localhost ~ $ curl -v https://10.2.78.7:443 -k -* Rebuilt URL to: https://10.2.78.7:443/ -* Trying 10.2.78.7... -* Connected to 10.2.78.7 (10.2.78.7) port 443 (#0) -* ALPN, offering http/1.1 -* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH -* successfully set certificate verify locations: -* CAfile: /etc/ssl/certs/ca-certificates.crt - CApath: /etc/ssl/certs -* TLSv1.2 (OUT), TLS header, Certificate Status (22): -* TLSv1.2 (OUT), TLS handshake, Client hello (1): -* TLSv1.2 (IN), TLS handshake, Server hello (2): -* TLSv1.2 (IN), TLS handshake, Certificate (11): -* TLSv1.2 (IN), TLS handshake, Server key exchange (12): -* TLSv1.2 (IN), TLS handshake, Server finished (14): -* TLSv1.2 (OUT), TLS handshake, Client key exchange (16): -* TLSv1.2 (OUT), TLS change cipher, Client hello (1): -* TLSv1.2 (OUT), TLS handshake, Finished (20): -* TLSv1.2 (IN), TLS change cipher, Client hello (1): -* TLSv1.2 (IN), TLS handshake, Finished (20): -* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256 -* ALPN, server accepted to use http/1.1 -* Server certificate: -* subject: CN=foo.bar.com -* start date: Apr 13 00:50:56 2016 GMT -* expire date: Apr 13 00:50:56 2017 GMT -* issuer: CN=foo.bar.com -* SSL certificate verify result: self signed certificate (18), continuing anyway. -> GET / HTTP/1.1 -> Host: 10.2.78.7 -> User-Agent: curl/7.47.1 -> Accept: */* -> -< HTTP/1.1 404 Not Found -< Server: nginx/1.11.1 -< Date: Mon, 18 Jul 2016 21:02:59 GMT -< Content-Type: text/html -< Transfer-Encoding: chunked -< Connection: keep-alive -< Strict-Transport-Security: max-age=15724800; includeSubDomains; preload -< -The page you're looking for could not be found. - -* Connection #0 to host 10.2.78.7 left intact -``` From 8aa9db8397cc0627cfd9991ce23c60197d348801 Mon Sep 17 00:00:00 2001 From: Aarni Koskela Date: Tue, 24 Apr 2018 14:50:33 +0300 Subject: [PATCH 10/10] Move documents related to third-party extensions under third-party-addons --- docs/{ => user-guide}/miscellaneous.md | 0 docs/user-guide/{ => third-party-addons}/modsecurity.md | 0 docs/user-guide/{ => third-party-addons}/opentracing.md | 0 3 files changed, 0 insertions(+), 0 deletions(-) rename docs/{ => user-guide}/miscellaneous.md (100%) rename docs/user-guide/{ => third-party-addons}/modsecurity.md (100%) rename docs/user-guide/{ => third-party-addons}/opentracing.md (100%) diff --git a/docs/miscellaneous.md b/docs/user-guide/miscellaneous.md similarity index 100% rename from docs/miscellaneous.md rename to docs/user-guide/miscellaneous.md diff --git a/docs/user-guide/modsecurity.md b/docs/user-guide/third-party-addons/modsecurity.md similarity index 100% rename from docs/user-guide/modsecurity.md rename to docs/user-guide/third-party-addons/modsecurity.md diff --git a/docs/user-guide/opentracing.md b/docs/user-guide/third-party-addons/opentracing.md similarity index 100% rename from docs/user-guide/opentracing.md rename to docs/user-guide/third-party-addons/opentracing.md