c12s-kubespray/roles/kubernetes-apps/ingress_controller/ingress_nginx
gorazio aa30fa8009
Add prometheus annotations to spec in ingress
Added annotations from metadata to spec.template.metadata. Without it, pod does not get any annotations, and Prometheus didn't see it
2018-03-20 08:47:36 +03:00
..
defaults Add Custom ConfigMap Support for ingress-nginx 2018-03-07 21:37:45 +08:00
tasks Integrate kubernetes/ingress-nginx 0.11.0 to Kubespray 2018-03-02 23:33:19 +08:00
templates Add prometheus annotations to spec in ingress 2018-03-20 08:47:36 +03:00
README.md Integrate kubernetes/ingress-nginx 0.11.0 to Kubespray 2018-03-02 23:33:19 +08:00

Installation Guide

Contents

Generic Deployment

The following resources are required for a generic deployment.

Mandatory commands

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/namespace.yaml \
    | kubectl apply -f -

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/default-backend.yaml \
    | kubectl apply -f -

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \
    | kubectl apply -f -

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/tcp-services-configmap.yaml \
    | kubectl apply -f -

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/udp-services-configmap.yaml \
    | kubectl apply -f -

Install without RBAC roles

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/without-rbac.yaml \
    | kubectl apply -f -

Install with RBAC roles

Please check the RBAC document.

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/rbac.yaml \
    | kubectl apply -f -

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/with-rbac.yaml \
    | kubectl apply -f -

Custom Service Provider Deployment

There are cloud provider specific yaml files.

minikube

For standard usage:

minikube addons enable ingress

For development:

  1. Disable the ingress addon:

    $ minikube addons disable ingress
    
  2. Use the docker daemon

  3. Build the image

  4. Perform Mandatory commands

  5. Install the nginx-ingress-controller deployment without RBAC roles or with RBAC roles

  6. Edit the nginx-ingress-controller deployment to use your custom image. Local images can be seen by performing docker images.

    $ kubectl edit deployment nginx-ingress-controller -n ingress-nginx
    

    edit the following section:

    image: <IMAGE-NAME>:<TAG>
    imagePullPolicy: IfNotPresent
    name: nginx-ingress-controller
    
  7. Confirm the nginx-ingress-controller deployment 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. 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

Patch the nginx ingress controller deployment to add the flag --publish-service

kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
  --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"

For L4:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/service-l4.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l4.yaml

For L7:

Change line of the file provider/aws/service-l7.yaml replacing the dummy id with a valid one "arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX" Then execute:

kubectl apply -f provider/aws/service-l7.yaml
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/aws/patch-configmap-l7.yaml

This example creates an ELB with just two listeners, one in port 80 and another in port 443

Listeners

If the ingress controller uses RBAC run:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml

If not run:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml

GCE - GKE

Patch the nginx ingress controller deployment to add the flag --publish-service

kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
  --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/gce-gke/service.yaml \
    | kubectl apply -f -

If the ingress controller uses RBAC run:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml

If not run:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml

Important Note: proxy protocol is not supported in GCE/GKE

Azure

Patch the nginx ingress controller deployment to add the flag --publish-service

kubectl patch deployment -n ingress-nginx nginx-ingress-controller --type='json' \
  --patch="$(curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/publish-service-patch.yaml)"
curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/azure/service.yaml \
    | kubectl apply -f -

If the ingress controller uses RBAC run:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-with-rbac.yaml

If not run:

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/patch-service-without-rbac.yaml

Important Note: proxy protocol is not supported in GCE/GKE

Baremetal

Using NodePort:

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/provider/baremetal/service-nodeport.yaml \
    | kubectl apply -f -

Using Helm

NGINX Ingress controller can be installed via Helm using the chart stable/nginx 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

Verify installation

To check if the ingress controller pods have started, run the following command:

kubectl get pods --all-namespaces -l app=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=ingress-nginx -o jsonpath={.items[0].metadata.name})
kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version

Deploying the config-map

A config map can be used to configure system components for the nginx-controller. In order to begin using a config-map make sure it has been created and is being used in the deployment.

It is created as seen in the Mandatory Commands section above.

curl https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/configmap.yaml \
    | kubectl apply -f -

and is setup to be used in the deployment without-rbac or with-rbac with the following line:

- --configmap=$(POD_NAMESPACE)/nginx-configuration

For information on using the config-map, see its user-guide.