XTesting/kubespray/docs/ingress_controller/ingress_nginx.md

   1 # Installation Guide
   2
   3 ## Contents
   4
   5 - [Prerequisite Generic Deployment Command](#prerequisite-generic-deployment-command)
   6   - [Provider Specific Steps](#provider-specific-steps)
   7     - [Docker for Mac](#docker-for-mac)
   8     - [minikube](#minikube)
   9     - [AWS](#aws)
  10     - [GCE - GKE](#gce-gke)
  11     - [Azure](#azure)
  12     - [Bare-metal](#bare-metal)
  13   - [Verify installation](#verify-installation)
  14   - [Detect installed version](#detect-installed-version)
  15 - [Using Helm](#using-helm)
  16
  17 ## Prerequisite Generic Deployment Command
  18
  19 !!! attention
  20     The default configuration watches Ingress object from *all the namespaces*.
  21     To change this behavior use the flag `--watch-namespace` to limit the scope to a particular namespace.
  22
  23 !!! warning
  24     If multiple Ingresses define different paths for the same host, the ingress controller will merge the definitions.
  25
  26 !!! attention
  27     If you're using GKE you need to initialize your user as a cluster-admin with the following command:
  28
  29 ```console
  30 kubectl create clusterrolebinding cluster-admin-binding \
  31 --clusterrole cluster-admin \
  32 --user $(gcloud config get-value account)
  33 ```
  34
  35 The following **Mandatory Command** is required for all deployments except for AWS. See below for the AWS version.
  36
  37 ```console
  38 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.40.2/deploy/static/provider/cloud/deploy.yaml
  39 ```
  40
  41 ### Provider Specific Steps
  42
  43 There are cloud provider specific yaml files.
  44
  45 #### Docker for Mac
  46
  47 Kubernetes is available in Docker for Mac (from [version 18.06.0-ce](https://docs.docker.com/docker-for-mac/release-notes/#stable-releases-of-2018))
  48
  49 First you need to [enable kubernetes](https://docs.docker.com/docker-for-mac/#kubernetes).
  50
  51 Then you have to create a service:
  52
  53 ```console
  54 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud-generic.yaml
  55 ```
  56
  57 #### minikube
  58
  59 For standard usage:
  60
  61 ```console
  62 minikube addons enable ingress
  63 ```
  64
  65 For development:
  66
  67 1. Disable the ingress addon:
  68
  69 ```console
  70 minikube addons disable ingress
  71 ```
  72
  73 1. Execute `make dev-env`
  74 1. Confirm the `nginx-ingress-controller` deployment exists:
  75
  76 ```console
  77 $ kubectl get pods -n ingress-nginx
  78 NAME                                       READY     STATUS    RESTARTS   AGE
  79 default-http-backend-66b447d9cf-rrlf9      1/1       Running   0          12s
  80 nginx-ingress-controller-fdcdcd6dd-vvpgs   1/1       Running   0          11s
  81 ```
  82
  83 #### AWS
  84
  85 In AWS we use an Elastic Load Balancer (ELB) to expose the NGINX Ingress controller behind a Service of `Type=LoadBalancer`.
  86 Since Kubernetes v1.9.0 it is possible to use a classic load balancer (ELB) or network load balancer (NLB)
  87 Please check the [elastic load balancing AWS details page](https://aws.amazon.com/elasticloadbalancing/details/)
  88
  89 ##### Elastic Load Balancer - ELB
  90
  91 This setup requires to choose in which layer (L4 or L7) we want to configure the Load Balancer:
  92
  93 - [Layer 4](https://en.wikipedia.org/wiki/OSI_model#Layer_4:_Transport_Layer): Use an Network Load Balancer (NLB) with TCP as the listener protocol for ports 80 and 443.
  94 - [Layer 7](https://en.wikipedia.org/wiki/OSI_model#Layer_7:_Application_Layer): Use an Elastic Load Balancer (ELB) with HTTP as the listener protocol for port 80 and terminate TLS in the ELB
  95
  96 For L4:
  97
  98 ```console
  99 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/aws/deploy.yaml
 100 ```
 101
 102 For L7:
 103
 104 Change the value of `service.beta.kubernetes.io/aws-load-balancer-ssl-cert` in the file `provider/aws/deploy-tls-termination.yaml` replacing the dummy id with a valid one. The dummy value is `"arn:aws:acm:us-west-2:XXXXXXXX:certificate/XXXXXX-XXXXXXX-XXXXXXX-XXXXXXXX"`
 105
 106 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](#elb-idle-timeouts) for additional information. If a change is required, users will need to update the value of `service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout` in `provider/aws/deploy-tls-termination.yaml`
 107
 108 Then execute:
 109
 110 ```console
 111 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/aws/deploy-tls-termination.yaml
 112 ```
 113
 114 This example creates an ELB with just two listeners, one in port 80 and another in port 443
 115
 116 ![Listeners](https://github.com/kubernetes/ingress-nginx/raw/master/docs/images/elb-l7-listener.png)
 117
 118 ##### ELB Idle Timeouts
 119
 120 In some scenarios users will need to modify the value of the ELB idle timeout.
 121 Users need to ensure the idle timeout is less than the [keepalive_timeout](http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout) that is configured for NGINX.
 122 By default NGINX `keepalive_timeout` is set to `75s`.
 123
 124 The default ELB idle timeout will work for most scenarios, unless the NGINX [keepalive_timeout](http://nginx.org/en/docs/http/ngx_http_core_module.html#keepalive_timeout) has been modified,
 125 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.
 126
 127 _Please Note: An idle timeout of `3600s` is recommended when using WebSockets._
 128
 129 More information with regards to idle timeouts for your Load Balancer can be found in the [official AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/config-idle-timeout.html).
 130
 131 ##### Network Load Balancer (NLB)
 132
 133 This type of load balancer is supported since v1.10.0 as an ALPHA feature.
 134
 135 ```console
 136 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/aws/service-nlb.yaml
 137 ```
 138
 139 #### GCE-GKE
 140
 141 ```console
 142 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud-generic.yaml
 143 ```
 144
 145 **Important Note:** proxy protocol is not supported in GCE/GKE
 146
 147 #### Azure
 148
 149 ```console
 150 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/cloud-generic.yaml
 151 ```
 152
 153 #### Bare-metal
 154
 155 Using [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport):
 156
 157 ```console
 158 kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/master/deploy/static/provider/baremetal/service-nodeport.yaml
 159 ```
 160
 161 !!! tip
 162     For extended notes regarding deployments on bare-metal, see [Bare-metal considerations](./baremetal.md).
 163
 164 ### Verify installation
 165
 166 To check if the ingress controller pods have started, run the following command:
 167
 168 ```console
 169 kubectl get pods --all-namespaces -l app.kubernetes.io/name=ingress-nginx --watch
 170 ```
 171
 172 Once the operator pods are running, you can cancel the above command by typing `Ctrl+C`.
 173 Now, you are ready to create your first ingress.
 174
 175 ### Detect installed version
 176
 177 To detect which version of the ingress controller is running, exec into the pod and run `nginx-ingress-controller version` command.
 178
 179 ```console
 180 POD_NAMESPACE=ingress-nginx
 181 POD_NAME=$(kubectl get pods -n $POD_NAMESPACE -l app.kubernetes.io/component=controller -o jsonpath='{.items[0].metadata.name}')
 182
 183 kubectl exec -it $POD_NAME -n $POD_NAMESPACE -- /nginx-ingress-controller --version
 184 ```
 185
 186 ## Using Helm
 187
 188 NGINX Ingress controller can be installed via [Helm](https://helm.sh/) using the chart [ingress-nginx/ingress-nginx](https://kubernetes.github.io/ingress-nginx).
 189 Official documentation is [here](https://kubernetes.github.io/ingress-nginx/deploy/#using-helm)
 190
 191 To install the chart with the release name `my-nginx`:
 192
 193 ```console
 194 helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
 195 helm install my-nginx ingress-nginx/ingress-nginx
 196 ```
 197
 198 Detect installed version:
 199
 200 ```console
 201 POD_NAME=$(kubectl get pods -l app.kubernetes.io/name=ingress-nginx -o jsonpath='{.items[0].metadata.name}')
 202 kubectl exec -it $POD_NAME -- /nginx-ingress-controller --version
 203 ```