index.md

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.

!!! danger The admission webhook require conectivity 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`.

Contents

• Provider Specific Steps
  • Docker for Mac
  • minikube
  • AWS
  • GCE - GKE
  • Azure
  • Digital Ocean
  • 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/controller-0.32.0/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/controller-0.32.0/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/controller-0.32.0/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.

!!! note "" 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: console kubectl create clusterrolebinding cluster-admin-binding \ --clusterrole cluster-admin \ --user $(gcloud config get-value account)

!!! danger For private clusters, you will need to either add an additional firewall rule that allows master nodes access port 8443/tcp on worker nodes, or change the existing rule that allows access to ports 80/tcp, 443/tcp and 10254/tcp to also allow access to port 8443/tcp.

See the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules) on adding rules and the [Kubernetes issue](https://github.com/kubernetes/kubernetes/issues/79739) for more detail.

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-0.32.0/deploy/static/provider/cloud/deploy.yaml

!!! failure Important Proxy protocol is not supported in GCE/GKE

Azure

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-0.32.0/deploy/static/provider/cloud/deploy.yaml

Digital Ocean

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-0.32.0/deploy/static/provider/do/deploy.yaml

Bare-metal

Using NodePort:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-0.32.0/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 my-release ingress-nginx/ingress-nginx

If you are using Helm 2 then specify release name using --name flag

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx/
helm install --name ingress-nginx ingress-nginx/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