Try to improve the installation guide (#7757)
* move generic instructions to the beginning of the file * add an example of ingress resource creation * simplify a few commands to make them shorter and simpler * add short paragraphs about PROXY protocol and traffic policy This tries to address the concerns I expressed in #7701.
This commit is contained in:
Jérôme Petazzoni
GitHub
parent
62ab435958
commit
ce165f9078
1 changed files with 159 additions and 70 deletions
|
|
@ -1,37 +1,21 @@
|
|||
# Installation Guide
|
||||
|
||||
!!! attention
|
||||
The default configuration watches Ingress object from **all namespaces**.
|
||||
There are multiple ways to install the NGINX ingress controller:
|
||||
- with [Helm](https://helm.sh), using the project repository chart;
|
||||
- with `kubectl apply`, using YAML manifests;
|
||||
- with specific addons (e.g. for [minikube](#minikube) or [MicroK8s](#microk8s)).
|
||||
|
||||
To change this behavior use the flag `--watch-namespace` to limit the scope to a particular namespace.
|
||||
|
||||
!!! warning
|
||||
If multiple Ingresses define paths for the same host, the ingress controller **merges the definitions**.
|
||||
|
||||
!!! danger
|
||||
The [admission webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) requires connectivity between Kubernetes API server and the ingress controller.
|
||||
|
||||
In case [Network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) or additional firewalls, please allow access to port `8443`.
|
||||
|
||||
!!! attention
|
||||
The first time the ingress controller starts, two [Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) create the SSL Certificate used by the admission webhook.
|
||||
For this reason, there is an initial delay of up to two minutes until it is possible to create and validate Ingress definitions.
|
||||
|
||||
You can wait until it is ready to run the next command:
|
||||
|
||||
```yaml
|
||||
kubectl wait --namespace ingress-nginx \
|
||||
--for=condition=ready pod \
|
||||
--selector=app.kubernetes.io/component=controller \
|
||||
--timeout=120s
|
||||
```
|
||||
On most Kubernetes clusters, the ingress controller will work without requiring any extra configuration. If you want to get started as fast as possible, you can check the [quick start](#quick-start) instructions. However, in many environments, you can improve the performance or get better logs by enabling extra features. we recommend that you check the [environment-specific instructions](#environment-specific-instructions) for details about optimizing the ingress controller for your particular environment or cloud provider.
|
||||
|
||||
## Contents
|
||||
|
||||
- [Provider Specific Steps](#provider-specific-steps)
|
||||
<!-- Quick tip: run `grep '^##' index.md` to check that the table of contents is up to date. -->
|
||||
|
||||
- [Quick start](#quick-start)
|
||||
- [Environment-specific instructions](#environment-specific-instructions)
|
||||
- [Docker Desktop](#docker-desktop)
|
||||
- [minikube](#minikube)
|
||||
- [microk8s](#microk8s)
|
||||
- [MicroK8s](#microk8s)
|
||||
- [AWS](#aws)
|
||||
- [GCE - GKE](#gce-gke)
|
||||
- [Azure](#azure)
|
||||
|
|
@ -40,18 +24,26 @@ You can wait until it is ready to run the next command:
|
|||
- [Exoscale](#exoscale)
|
||||
- [Oracle Cloud Infrastructure](#oracle-cloud-infrastructure)
|
||||
- [Bare-metal](#bare-metal)
|
||||
- [Verify installation](#verify-installation)
|
||||
- [Detect installed version](#detect-installed-version)
|
||||
- [Using Helm](#using-helm)
|
||||
- [Miscellaneous](#miscellaneous)
|
||||
|
||||
### Provider Specific Steps
|
||||
## Quick start
|
||||
|
||||
#### Docker Desktop
|
||||
You can deploy the ingress controller with the following command:
|
||||
|
||||
Kubernetes is available in Docker Desktop
|
||||
```console
|
||||
helm upgrade --install ingress-nginx ingress-nginx \
|
||||
--repo https://kubernetes.github.io/ingress-nginx \
|
||||
--namespace ingress-nginx --create-namespace
|
||||
```
|
||||
|
||||
- Mac, from [version 18.06.0-ce](https://docs.docker.com/docker-for-mac/release-notes/#stable-releases-of-2018)
|
||||
- Windows, from [version 18.06.0-ce](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18060-ce-win70-2018-07-25)
|
||||
It will install the controller in the `ingress-nginx` namespace, creating that namespace if it doesn't already exist.
|
||||
|
||||
!!! info
|
||||
This command is *idempotent*:
|
||||
- if the ingress controller is not installed, it will install it,
|
||||
- if the ingress controller is already installed, it will upgrade it.
|
||||
|
||||
This requires Helm version 3. If you prefer to use a YAML manifest, you can run the following command instead:
|
||||
|
||||
!!! attention
|
||||
Before running the command at your terminal, make sure Kubernetes is enabled at Docker settings
|
||||
|
|
@ -60,23 +52,112 @@ Kubernetes is available in Docker Desktop
|
|||
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.0.4/deploy/static/provider/cloud/deploy.yaml
|
||||
```
|
||||
|
||||
!!! info
|
||||
The YAML manifest in the command above was generated with `helm template`, so you will end up with almost the same resources as if you had used Helm to install the controller.
|
||||
|
||||
If you are running an old version of Kubernetes (1.18 or earlier), please read
|
||||
[this paragraph](#running-on-Kubernetes-versions-older-than-1.19) for specific instructions.
|
||||
|
||||
### Pre-flight check
|
||||
|
||||
A few pods should start in the `ingress-nginx` namespace:
|
||||
|
||||
```console
|
||||
kubectl get pods --namespace=ingress-nginx
|
||||
```
|
||||
|
||||
After a while, they should all be running. The following command will wait for the ingress controller pod to be up, running, and ready:
|
||||
|
||||
```console
|
||||
kubectl wait --namespace ingress-nginx \
|
||||
--for=condition=ready pod \
|
||||
--selector=app.kubernetes.io/component=controller \
|
||||
--timeout=120s
|
||||
```
|
||||
|
||||
### Local testing
|
||||
|
||||
Let's create a simple web server and the associated service:
|
||||
|
||||
```console
|
||||
kubectl create deployment demo --image=httpd --port=80
|
||||
kubectl expose deployment demo
|
||||
```
|
||||
|
||||
Then create an ingress resource. The following example uses an host that maps to `localhost`:
|
||||
|
||||
```console
|
||||
kubectl create ingress demo-localhost --class=nginx \
|
||||
--rule=demo.localdev.me/*=demo:80
|
||||
```
|
||||
|
||||
Now, forward a local port to the ingress controller:
|
||||
|
||||
```console
|
||||
kubectl port-forward --namespace=ingress-nginx service/ingress-nginx-controller 8080:80
|
||||
```
|
||||
|
||||
At this point, if you access http://demo.localdev.me:8080/, you should see an HTML page telling you "It works!".
|
||||
|
||||
### Online testing
|
||||
|
||||
If your Kubernetes cluster is a "real" cluster that supports services of type `LoadBalancer`, it will have allocated an external IP address or FQDN to the ingress controller.
|
||||
|
||||
You can see that IP address or FQDN with the following command:
|
||||
|
||||
```console
|
||||
kubectl get service ingress-nginx-controller --namespace=ingress-nginx
|
||||
```
|
||||
|
||||
Set up a DNS record pointing to that IP address or FQDN; then create an ingress resource. The following example assumes that you have set up a DNS record for `www.demo.io`:
|
||||
|
||||
```console
|
||||
kubectl create ingress demo --class=nginx \
|
||||
--rule=www.demo.io/*=demo:80
|
||||
```
|
||||
|
||||
You should then be able to see the "It works!" page when you connect to http://www.demo.io/. Congratulations, you are serving a public web site hosted on a Kubernetes cluster! 🎉
|
||||
|
||||
## Environment-specific instructions
|
||||
|
||||
### Local development clusters
|
||||
|
||||
#### minikube
|
||||
|
||||
For standard usage:
|
||||
The ingress controller can be installed through minikube's addons system:
|
||||
|
||||
```console
|
||||
minikube addons enable ingress
|
||||
```
|
||||
|
||||
#### microk8s
|
||||
#### MicroK8s
|
||||
|
||||
For standard usage:
|
||||
The ingress controller can be installed through MicroK8s's addons system:
|
||||
|
||||
```console
|
||||
microk8s enable ingress
|
||||
```
|
||||
|
||||
Please check the microk8s [documentation page](https://microk8s.io/docs/addon-ingress)
|
||||
Please check the MicroK8s [documentation page](https://microk8s.io/docs/addon-ingress) for details.
|
||||
|
||||
#### Docker Desktop
|
||||
|
||||
Kubernetes is available in Docker Desktop:
|
||||
|
||||
- Mac, from [version 18.06.0-ce](https://docs.docker.com/docker-for-mac/release-notes/#stable-releases-of-2018)
|
||||
- Windows, from [version 18.06.0-ce](https://docs.docker.com/docker-for-windows/release-notes/#docker-community-edition-18060-ce-win70-2018-07-25)
|
||||
|
||||
The ingress controller can be installed on Docker Desktop using the default [quick start](#quick-start) instructions.
|
||||
|
||||
On most systems, if you don't have any other service of type `LoadBalancer` bound to port 80, the ingress controller will be assigned the `EXTERNAL-IP` of `localhost`, which means that it will be reachable on localhost:80. If that doesn't work, you might have to fall back to the `kubectl port-forward` method described in the [local testing section](#local-testing).
|
||||
|
||||
### Cloud deployments
|
||||
|
||||
If the load balancers of your cloud provider do active healthchecks on their backends (most do), you can change the `externalTrafficPolicy` of the ingress controller Service to `Local` (instead of the default `Cluster`) to save an extra hop in some cases. If you're installing with Helm, this can be done by adding `--set controller.service.externalTrafficPolicy=Local` to the `helm install` or `helm upgrade` command.
|
||||
|
||||
Furthermore, if the load balancers of your cloud provider support the PROXY protocol, you can enable it, and it will let the ingress controller see the real IP address of the clients. Otherwise, it will generally see the IP address of the upstream load balancer. This must be done both in the ingress controller (with e.g. `--set controller.config.use-proxy-protocol=true`) and in the cloud provider's load balancer configuration to function correctly.
|
||||
|
||||
In the following sections, we provide YAML manifests that enable these options when possible, using the specific options of various cloud providers.
|
||||
|
||||
#### AWS
|
||||
|
||||
|
|
@ -189,7 +270,7 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/cont
|
|||
|
||||
A [complete list of available annotations for Oracle Cloud Infrastructure](https://github.com/oracle/oci-cloud-controller-manager/blob/master/docs/load-balancer-annotations.md) can be found in the [OCI Cloud Controller Manager](https://github.com/oracle/oci-cloud-controller-manager) documentation.
|
||||
|
||||
#### Bare-metal
|
||||
### Bare metal clusters
|
||||
|
||||
Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport):
|
||||
|
||||
|
|
@ -203,50 +284,58 @@ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/cont
|
|||
!!! info
|
||||
For extended notes regarding deployments on bare-metal, see [Bare-metal considerations](./baremetal.md).
|
||||
|
||||
### Verify installation
|
||||
## Miscellaneous
|
||||
|
||||
To check if the ingress controller pods have started, run the following command:
|
||||
### Checking ingress controller version
|
||||
|
||||
```console
|
||||
kubectl get pods -n ingress-nginx \
|
||||
-l app.kubernetes.io/name=ingress-nginx --watch
|
||||
```
|
||||
|
||||
Once the ingress controller pods are running, you can cancel the command 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`.
|
||||
Run `nginx-ingress-controller --version` within the pod, for instance with `kubectl exec`:
|
||||
|
||||
```console
|
||||
POD_NAMESPACE=ingress-nginx
|
||||
POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx --field-selector=status.phase=Running -o jsonpath='{.items[0].metadata.name}')
|
||||
|
||||
kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version
|
||||
POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx --field-selector=status.phase=Running -o name)
|
||||
kubectl exec $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version
|
||||
```
|
||||
|
||||
## Using Helm
|
||||
### Scope
|
||||
|
||||
By default, the controller watches Ingress objects from all namespaces. If you want to change this behavior, use the flag `--watch-namespace` or check the Helm chart value `controller.scope` to limit the controller to a single namespace.
|
||||
|
||||
See also [“How to easily install multiple instances of the Ingress NGINX controller in the same cluster”](https://kubernetes.github.io/ingress-nginx/#how-to-easily-install-multiple-instances-of-the-ingress-nginx-controller-in-the-same-cluster) for more details.
|
||||
|
||||
### Webhook network access
|
||||
|
||||
!!! warning
|
||||
The controller uses an [admission webhook](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) to validate Ingress definitions. Make sure that you don't have [Network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) or additional firewalls preventing connections from the API server to the `ingress-nginx-controller-admission` service.
|
||||
|
||||
### Certificate generation
|
||||
|
||||
!!! attention
|
||||
Only Helm v3 is supported
|
||||
The first time the ingress controller starts, two [Jobs](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) create the SSL Certificate used by the admission webhook.
|
||||
|
||||
NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart from the project repository.
|
||||
To install the chart with the release name `ingress-nginx`:
|
||||
THis can cause an initial delay of up to two minutes until it is possible to create and validate Ingress definitions.
|
||||
|
||||
```console
|
||||
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
|
||||
helm repo update
|
||||
You can wait until it is ready to run the next command:
|
||||
|
||||
helm install ingress-nginx ingress-nginx/ingress-nginx
|
||||
```yaml
|
||||
kubectl wait --namespace ingress-nginx \
|
||||
--for=condition=ready pod \
|
||||
--selector=app.kubernetes.io/component=controller \
|
||||
--timeout=120s
|
||||
```
|
||||
|
||||
[For multiple NGINX Ingress controllers](https://kubernetes.github.io/ingress-nginx/#how-to-easily-install-multiple-instances-of-the-ingress-nginx-controller-in-the-same-cluster)
|
||||
### Running on Kubernetes versions older than 1.19
|
||||
|
||||
## Detect installed version:
|
||||
Ingress resources evolved over time. They started with `apiVersion: extensions/v1beta1`, then moved to `apiVersion: networking.k8s.io/v1beta1` and more recently to `apiVersion: networking.k8s.io/v1`.
|
||||
|
||||
```console
|
||||
POD_NAME=$(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath='{.items[0].metadata.name}')
|
||||
kubectl exec -it $POD_NAME -- /nginx-ingress-controller --version
|
||||
```
|
||||
Here is how these Ingress versions are supported in Kubernetes:
|
||||
- before Kubernetes 1.19, only `v1beta1` Ingress resources are supported
|
||||
- from Kubernetes 1.19 to 1.21, both `v1beta1` and `v1` Ingress resources are supported
|
||||
- in Kubernetes 1.22 and above, only `v1` Ingress resources are supported
|
||||
|
||||
And here is how these Ingress versions are supported in NGINX Ingress Controller:
|
||||
- before version 1.0, only `v1beta1` Ingress resources are supported
|
||||
- in version 1.0 and above, only `v1` Ingress resources are
|
||||
|
||||
As a result, if you're running Kubernetes 1.19 or later, you should be able to use the latest version of the NGINX Ingress Controller; but if you're using an old version of Kubernetes (1.18 or earlier) you will have to use version 0.X of the NGINX Ingress Controller (e.g. version 0.49).
|
||||
|
||||
The Helm chart of the NGINX Ingress Controller switched to version 1 in version 4 of the chart. In other words, if you're running Kubernetes 1.19 or earlier, you should use version 3.X of the chart (this can be done by adding `--version='<4'` to the `helm install` command).
|
||||
|
|
|
|||
Loading…
Reference in a new issue