Skip to content
Permalink
Browse files

Add new docs

- Add the sources of the new Ingress Controller documentation
(https://docs.nginx.com/nginx-ingress-controller/)
- Update the existing docs and READMEs to point to the new
documentation.
  • Loading branch information
pleshakov committed Jan 10, 2020
1 parent fc2e9a3 commit 36febac1b11e3ab03e9d32a928480522427ae1f5
Showing with 3,224 additions and 1,565 deletions.
  1. +6 −6 README.md
  2. +1 −85 build/README.md
  3. +1 −1 deployments/README.md
  4. +5 −0 docs-web/configuration/configuration-examples.md
  5. +164 −0 docs-web/configuration/global-configuration/command-line-arguments.md
  6. +397 −0 docs-web/configuration/global-configuration/configmap-resource.md
  7. +3 −0 docs-web/configuration/global-configuration/custom-templates.md
  8. +10 −0 docs-web/configuration/global-configuration/index.rst
  9. +24 −0 docs-web/configuration/global-configuration/reporting-resources-status.md
  10. +10 −0 docs-web/configuration/index.rst
  11. +342 −0 docs-web/configuration/ingress-resources/advanced-configuration-with-annotations.md
  12. +54 −0 docs-web/configuration/ingress-resources/basic-configuration.md
  13. +5 −0 docs-web/configuration/ingress-resources/cross-namespace-configuration.md
  14. +135 −0 docs-web/configuration/ingress-resources/custom-annotations.md
  15. +10 −0 docs-web/configuration/ingress-resources/index.rst
  16. +994 −0 docs-web/configuration/virtualserver-and-virtualserverroute-resources.md
  17. +16 −0 docs-web/index.rst
  18. +79 −0 docs-web/installation/building-ingress-controller-image.md
  19. +10 −0 docs-web/installation/index.rst
  20. +273 −0 docs-web/installation/installation-with-helm.md
  21. +166 −0 docs-web/installation/installation-with-manifests.md
  22. +41 −0 docs-web/installation/running-multiple-ingress-controllers.md
  23. +9 −0 docs-web/logging-and-monitoring/index.rst
  24. +20 −0 docs-web/logging-and-monitoring/logging.md
  25. +37 −0 docs-web/logging-and-monitoring/prometheus.md
  26. +39 −0 docs-web/logging-and-monitoring/status-page.md
  27. +34 −0 docs-web/overview.md
  28. +96 −0 docs-web/releases.md
  29. +7 −0 docs-web/third-party-modules/index.rst
  30. +81 −0 docs-web/third-party-modules/opentracing.md
  31. +135 −0 docs-web/troubleshooting.md
  32. +4 −0 docs/README.md
  33. +1 −83 docs/cli-arguments.md
  34. +1 −195 docs/configmap-and-annotations.md
  35. +1 −120 docs/custom-annotations.md
  36. +1 −199 docs/installation.md
  37. +1 −39 docs/multiple-ingress-controllers.md
  38. +4 −4 docs/nginx-ingress-controllers.md
  39. +2 −2 docs/nginx-plus.md
  40. +1 −78 docs/opentracing.md
  41. +1 −20 docs/prometheus.md
  42. +1 −20 docs/report-ingress-status.md
  43. +1 −112 docs/troubleshooting.md
  44. +1 −601 docs/virtualserver-and-virtualserverroute.md
@@ -29,20 +29,20 @@ In the case of NGINX, the Ingress controller is deployed in a pod along with the

NGINX Ingress controller works with both NGINX and NGINX Plus and supports the standard Ingress features - content-based routing and TLS/SSL termination.

Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap and Annotations doc](docs/configmap-and-annotations.md) to learn more about the supported features and customization options.
Additionally, several NGINX and NGINX Plus features are available as extensions to the Ingress resource via annotations and the ConfigMap resource. In addition to HTTP, NGINX Ingress controller supports load balancing Websocket, gRPC, TCP and UDP applications. See [ConfigMap](https://docs.nginx.com/nginx-ingress-controller/configuration/global-configuration/configmap-resource/) and [Annotations](https://docs.nginx.com/nginx-ingress-controller/configuration/ingress-resources/advanced-configuration-with-annotations/) docs to learn more about the supported features and customization options.

As an alternative to the Ingress, NGINX Ingress controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute Resources doc](docs/virtualserver-and-virtualserverroute.md).
As an alternative to the Ingress, NGINX Ingress controller supports the VirtualServer and VirtualServerRoute resources. They enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. See [VirtualServer and VirtualServerRoute Resources doc](https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/).

Read [this doc](docs/nginx-plus.md) to learn more about NGINX Ingress controller with NGINX Plus.

## Getting Started

1. Install the NGINX Ingress controller using the Kubernetes [manifests](deployments) or the [helm chart](deployments/helm-chart).
1. Install the NGINX Ingress controller using the Kubernetes [manifests](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-manifests/) or the [helm chart](https://docs.nginx.com/nginx-ingress-controller/installation/installation-with-helm/).
1. Configure load balancing for a simple web application:
* Use the Ingress resource. See the [Cafe example](examples/complete-example).
* Or the VirtualServer resource. See the [Basic configuration](examples-of-custom-resources/basic-configuration) example.
1. See additional configuration [examples](examples).
1. Learn more about all available configuration and customization in the [docs](docs).
1. Learn more about all available configuration and customization in the [docs](https://docs.nginx.com/nginx-ingress-controller/).


## NGINX Ingress Controller Releases
@@ -62,8 +62,8 @@ The table below summarizes the options regarding the images, manifests, helm cha

| Version | Description | Image for NGINX | Image for NGINX Plus | Installation Manifests and Helm Chart | Documentation and Examples |
| ------- | ----------- | --------------- | -------------------- | ---------------------------------------| -------------------------- |
| Latest stable release | For production use | `nginx/nginx-ingress:1.6.0`, `nginx/nginx-ingress:1.6.0-alpine` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) or [build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/build). | [Build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/build). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/deployments/helm-chart). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/docs). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/examples). |
| Edge | For testing and experimenting | `nginx/nginx-ingress:edge`, `nginx/nginx-ingress:edge-alpine` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) or [build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/master/build). | [Build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/master/build). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/master/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/master/deployments/helm-chart). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/master/docs). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples). |
| Latest stable release | For production use | `nginx/nginx-ingress:1.6.0`, `nginx/nginx-ingress:1.6.0-alpine` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v1.6.0/deployments/helm-chart). | [Documentation](https://docs.nginx.com/nginx-ingress-controller/). [Examples](https://docs.nginx.com/nginx-ingress-controller/configuration/configuration-examples/). |
| Edge | For testing and experimenting | `nginx/nginx-ingress:edge`, `nginx/nginx-ingress:edge-alpine` from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) or [build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/master/docs-web/installation/building-ingress-controller-image.md). | [Build your own image](https://github.com/nginxinc/kubernetes-ingress/tree/master/docs-web/installation/building-ingress-controller-image.md). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/master/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/master/deployments/helm-chart). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/master/docs-web). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples). |

## Contacts

@@ -1,87 +1,3 @@
# NGINX Ingress Controller

This is an implementation of a Kubernetes Ingress controller for NGINX and NGINX Plus, which provides HTTP load balancing for applications your deploy in your Kubernetes cluster. You can find more details on what an Ingress controller is on the [main page](https://github.com/nginxinc/kubernetes-ingress).

## How to Use the Controller

To find examples on how to deploy, configure and use the Ingress controller, please see [the examples folder](../examples). The examples require the Docker image of the controller to be available to your Kubernetes cluster. We provide such an image though [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/) for NGINX. If you are using NGINX Plus, you need to build the image.

There are other cases when you need to build your own image. For example if you want to customize the controller, either by changing the NGINX configuration templates and/or modifying the controller logic. Please read the next section for instructions on how to build an image.

## How to Build the Controller Image

### Prerequisites

Before you can build the image, make sure that the following software is installed on your machine:
* [Docker](https://www.docker.com/products/docker)
* [GNU Make](https://www.gnu.org/software/make/)
* [git](https://git-scm.com/)
* [OpenSSL](https://www.openssl.org/), optionally, if you would like to generate a self-signed certificate and a key for the default server.
* For NGINX Plus, you must have the NGINX Plus license -- the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`). If you don't have one, you can sign up for a [free 30-day trial](https://www.nginx.com/free-trial-request/).

Although the Ingress controller is written in golang, golang is not required, as the Ingress controller binary will be built in a Docker container.

### Building the Image and Pushing It to the Private Registry

We build the image using the make utility and the provided `Makefile`. Let’s create the controller binary, build an image and push the image to the private registry.

1. Make sure to run the `docker login` command first to login to the registry. If you’re using Google Container Registry, you don’t need to use the docker command to login -- make sure you’re logged into the gcloud tool (using the `gcloud auth login` command) and set the variable `PUSH_TO_GCR=1` when running the make command.

1. Clone the Ingress controller repo:
```
$ git clone https://github.com/nginxinc/kubernetes-ingress/
```

1. Build the image:
* For NGINX:
```
$ make clean
$ make PREFIX=myregistry.example.com/nginx-ingress
```
`myregistry.example.com/nginx-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry.

As the result, the image **myregistry.example.com/nginx-ingress:edge** is built and pushed to the registry. Note that the tag `edge` comes from the `VERSION` variable, defined in the Makefile.

* For NGINX Plus, first, make sure that the certificate (`nginx-repo.crt`) and the key (`nginx-repo.key`) of your license are located in the root of the project:
```
$ ls nginx-repo.*
nginx-repo.crt nginx-repo.key
```
Then run:
```
$ make clean
$ make DOCKERFILE=DockerfileForPlus PREFIX=myregistry.example.com/nginx-plus-ingress
```
`myregistry.example.com/nginx-plus-ingress` defines the repo in your private registry where the image will be pushed. Substitute that value with the repo in your private registry.

As the result, the image **myregistry.example.com/nginx-plus-ingress:edge** is built and pushed to the registry. Note that the tag `edge` comes from the `VERSION` variable, defined in the Makefile.

Next you will find the details about available Makefile targets and variables.

### Makefile Targets

The **Makefile** we provide has the following targets:
* **test**: runs unit tests.
* **nginx-ingress**: creates the controller binary.
* **container**: builds a Docker image.
* **push**: pushes the image to the private Docker registry.
* **all** (the default target): executes the four targets above in the order listed. If one of the targets fails, the execution process stops, reporting an error.

### Makefile Variables

The **Makefile** contains the following main variables for you to customize (either by changing the Makefile or by overriding the variables in the make command):
* **PREFIX** -- the name of the image. The default is `nginx/nginx-ingress`.
* **VERSION** -- the current version of the controller.
* **TAG** -- the tag added to the image. It's set to the value of the `VERSION` variable by default.
* **PUSH_TO_GCR**. If you’re running your Kubernetes in GCE and using Google Container Registry, make sure that `PUSH_TO_GCR = 1`. This means using the `gcloud docker push` command to push the image, which is convenient when pushing images to GCR. By default, the variable is unset and the regular `docker push` command is used to push the image to the registry.
* **DOCKERFILE** -- the path to a Dockerfile. We provide five Dockerfiles:
1. `Dockerfile`, for building a debian-based image with NGINX. It's used by default.
1. `DockerfileForAlpine`, for building an alpine-based image with NGINX.
1. `DockerfileForPlus`, for building an debian-based image with NGINX Plus.
1. `DockerfileWithOpentracing`, for building a debian-based image with NGINX, [opentracing](https://github.com/opentracing-contrib/nginx-opentracing) module and the [Jaeger](https://www.jaegertracing.io/) tracer.
1. `DockerfileWithOpentracingForPlus`, for building a debian-based image with NGINX Plus, [opentracing](https://github.com/opentracing-contrib/nginx-opentracing) module and the [Jaeger](https://www.jaegertracing.io/) tracer.
* **GENERATE_DEFAULT_CERT_AND_KEY** - The Ingress controller requires a certificate and a key for the default HTTP/HTTPS server. You can reference them in a TLS Secret in a command-line argument to the Ingress controller. As an alternative, you can add a file in the PEM format with your certificate and key to the image as `/etc/nginx/secrets/default`. Optionally, you can generate a self-signed certificate and a key during the build process. Set `GENERATE_DEFAULT_CERT_AND_KEY` to `1` to generate a certificate and a key in the `default.pem` file. Note that you must add the `ADD` instruction in the Dockerfile to copy the cert and the key to the image. The default value of `GENERATE_DEFAULT_CERT_AND_KEY` is `0`.
* **DOCKER_BUILD_OPTIONS** -- the [options](https://docs.docker.com/engine/reference/commandline/build/#options) for the `docker build` command. For example, `--pull`.
* **BUILD_IN_CONTAINER** -- By default, to compile the controller we use the [golang](https://hub.docker.com/_/golang/) container that we run as part of the building process. If you want to compile the controller using your local golang environment:
1. Make sure that the Ingress controller repo is in your `$GOPATH`.
1. Specify `BUILD_IN_CONTAINER=0` when you run the make command.
This doc is now available at https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/
@@ -1,6 +1,6 @@
# Installation

This folder includes Kubernetes manifests for installing NGINX or NGINX Plus Ingress controller. Read the installation instructions [here](../docs/installation.md).
This folder includes Kubernetes manifests for installing NGINX or NGINX Plus Ingress controller. Read the installation instructions [here](https://docs.nginx.com/nginx-ingress-controller/installation/).



@@ -0,0 +1,5 @@
# Configuration Examples

Out [GitHub repo](https://github.com/nginxinc/kubernetes-ingress) includes as number of configuration examples:
* [*Examples*](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples) show how to use advanced NGINX features in Ingress resources with annotations.
* [*Examples of Custom Resources*](https://github.com/nginxinc/kubernetes-ingress/tree/master/examples-of-custom-resources) show how to use VirtualServer and VirtualServerResources for a few use cases.

0 comments on commit 36febac

Please sign in to comment.
You can’t perform that action at this time.