Installation Guide ¶
Attention
The default configuration watches Ingress object from all the namespaces.
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.
Contents ¶
- Provider Specific Steps
- Docker for Mac
- minikube
- AWS
- GCE - GKE
- Azure
- Bare-metal
- Verify installation
- Detect installed version
- Using Helm
Provider Specific Steps ¶
Docker for Mac ¶
Kubernetes is available in Docker for Mac (from version 18.06.0-ce)
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud/deploy.yaml
minikube ¶
For standard usage:
minikube addons enable ingress
For development:
- Disable the ingress addon:
minikube addons disable ingress
- Execute
make dev-env
- Confirm the
nginx-ingress-controller
deployment exists:
$ kubectl get pods -n ingress-nginx
NAME READY STATUS RESTARTS AGE
nginx-ingress-controller-fdcdcd6dd-vvpgs 1/1 Running 0 11s
AWS ¶
In AWS we use a Network load balancer (NLB) to expose the NGINX Ingress controller behind a Service of Type=LoadBalancer
.
Network Load Balancer (NLB) ¶
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/aws/deploy.yaml
TLS termination in AWS Load Balancer (ELB) ¶
In some scenarios is required to terminate TLS in the Load Balancer and not in the ingress controller.
For this purpose we provide a template:
- Download deploy-tls-termination.yaml
wget https://raw.githubusercontent.com/kubernetes/ingress-nginx/204739fb6650c48fd41dc9505f8fd9ef6bc768e1/deploy/static/provider/aws/deploy-tls-termination.yaml
-
Edit the file and change:
-
VPC CIDR in use for the Kubernetes cluster:
proxy-real-ip-cidr: XXX.XXX.XXX/XX
- AWS Certificate Manager (ACM) ID
arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX
- Deploy the manifest:
kubectl apply -f deploy-tls-termination.yaml
NLB Idle Timeouts ¶
In some scenarios users will need to modify the value of the NLB idle timeout. Users need to ensure the idle timeout is less than the keepalive_timeout that is configured for NGINX.
By default NGINX keepalive_timeout
is set to 75s
.
The default NLB idle timeout works for most scenarios, unless the NGINX keepalive_timeout has been modified, in which case the annotation
service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout
value must be modified to ensure it is less than the configured keepalive_timeout
.
An idle timeout of 3600
is recommended when using WebSockets
More information with regards to timeouts for can be found in the official AWS documentation
GCE-GKE ¶
Info
Initialize your user as a cluster-admin with the following command:
kubectl create clusterrolebinding cluster-admin-binding \
--clusterrole cluster-admin \
--user $(gcloud config get-value account)
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud/deploy.yaml
Warning
Proxy protocol is not supported in GCE/GKE
Azure ¶
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud/deploy.yaml
Bare-metal ¶
Using NodePort:
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/baremetal/deploy.yaml
Tip
For extended notes regarding deployments on bare-metal, see Bare-metal considerations.
Verify installation ¶
To check if the ingress controller pods have started, run the following command:
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
command.
POD_NAMESPACE=ingress-nginx
POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/name=ingress-nginx -o jsonpath='{.items[0].metadata.name}')
kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version
Using Helm ¶
NGINX Ingress controller can be installed via Helm using the chart from the project repository.
To install the chart with the release name ingress-nginx
:
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm install ingress-nginx
If you are using Helm 2 then specify release name using --name
flag
helm repo add https://kubernetes.github.io/ingress-nginx/
helm install --name ingress-nginx
Detect installed version: ¶
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