8.3 KiB
Installation Guide
Contents
Prerequisite Generic Deployment Command
The following Mandatory Command is required for all deployments.
!!! attention These commands depend on having kubectl version 1.14 or newer.
!!! 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 different paths for the same host, the ingress controller will merge the definitions.
kubectl create namespace ingress-nginx
cat << EOF > kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: ingress-nginx
bases:
- github.com/kubernetes/ingress-nginx/deploy/cluster-wide
- # provider-specific, see below
EOF
Provider Specific Steps
There are cloud provider specific kustomize bases.
Docker for Mac
Kubernetes is available in Docker for Mac (from version 18.06.0-ce)
Add github.com/kubernetes/ingress-nginx/deploy/cloud-generic to the bases list in kustomization.yaml and run kubectl apply --kustomize ..
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-controllerdeployment exists:
$ 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
Elastic Load Balancer - ELB
This setup requires to choose in which layer (L4 or L7) we want to configure the ELB:
- Layer 4: use TCP as the listener protocol for ports 80 and 443.
- Layer 7: use HTTP as the listener protocol for port 80 and terminate TLS in the ELB
Check that no change is necessary with regards to the ELB idle timeout. In some scenarios, users may want to modify the ELB idle timeout, so please check the ELB Idle Timeouts section for additional information. If a change is required, users will need to override the value of the annotation service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout on the service object.
To do this, create a patch file which will replace the annotation.
cat << EOF > elb-timeout.yaml
kind: Service
apiVersion: v1
metadata:
name: ingress-nginx
annotations:
service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "3600" # Recommended value for WebSockets
EOF
After creating the patch file, reference it in your kustomization.yaml:
patchesStrategicMerge:
- elb-timeout.yaml
For L4:
To deploy the default example, add the base github.com/kubernetes/ingress-nginx/deploy/aws/l4 and then run kubectl apply --kustomize .
For L7:
Create a a patch that will annotate the ingress-controller's service with your ssl certificate id.
cat << EOF > elb-ssl.yaml
kind: Service
apiVersion: v1
metadata:
name: ingress-nginx
annotations:
# replace with the correct value of the generated certificate in the AWS console
service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"
EOF
Reference this patch in your kustomization.yaml:
patchesStrategicMerge:
- elb-ssl.yaml
Then add the l7 base, github.com/kubernetes/ingress-nginx/deploy/aws/l7 and execute kubectl apply --kustomize .
This example creates an ELB with just two listeners, one in port 80 and another in port 443
ELB Idle Timeouts
In some scenarios users will need to modify the value of the ELB 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 ELB idle timeout will work for most scenarios, unless the NGINX keepalive_timeout has been modified, in which case service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout will need to be modified to ensure it is less than the keepalive_timeout the user has configured.
Please Note: An idle timeout of 3600s is recommended when using WebSockets.
More information with regards to idle timeouts for your Load Balancer can be found in the official AWS documentation.
Network Load Balancer (NLB)
This type of load balancer is supported since v1.10.0 as an ALPHA feature. Use the base github.com/kubernetes/ingress-nginx/deploy/aws/nlb and execute kubectl apply --kustomize .
GCE-GKE
!!! attention
If you're using GKE you need to 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)
Use the base github.com/kubernetes/ingress-nginx/deploy/cloud-generic and execute kubectl apply --kustomize .
Important Note: proxy protocol is not supported in GCE/GKE
Azure
Use the base github.com/kubernetes/ingress-nginx/deploy/cloud-generic and execute kubectl apply --kustomize .
Bare-metal
Using NodePort:
Use the base github.com/kubernetes/ingress-nginx/deploy/baremetal and execute kubectl apply --kustomize .
!!! 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 --all-namespaces -l app.kubernetes.io/name=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.
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 stable/nginx-ingress from the official charts repository.
To install the chart with the release name my-nginx:
helm install stable/nginx-ingress --name my-nginx
If the kubernetes cluster has RBAC enabled, then run:
helm install stable/nginx-ingress --name my-nginx --set rbac.create=true
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