diff --git a/content/rancher/v2.x/en/faq/technical/_index.md b/content/rancher/v2.x/en/faq/technical/_index.md index 2264a8c55f4..3f034768af2 100644 --- a/content/rancher/v2.x/en/faq/technical/_index.md +++ b/content/rancher/v2.x/en/faq/technical/_index.md @@ -12,7 +12,15 @@ New password for default admin user (user-xxxxx): ``` -High Availability install: +High Availability install (Helm): +``` +$ KUBECONFIG=./kube_config_rancher-cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- reset-password +New password for default admin user (user-xxxxx): + +``` + +High Availability install (RKE add-on): ``` $ KUBECONFIG=./kube_config_rancher-cluster.yml $ kubectl --kubeconfig $KUBECONFIG exec -n cattle-system $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name=="cattle-server") | .metadata.name') -- reset-password @@ -20,6 +28,7 @@ New password for default admin user (user-xxxxx): ``` + ### I deleted/deactivated the last admin, how can I fix it? Single node install: ``` @@ -29,7 +38,15 @@ New password for default admin user (user-xxxxx): ``` -High Availability install: +High Availability install (Helm): +``` +$ KUBECONFIG=./kube_config_rancher-cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system exec $(kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | head -1 | awk '{ print $1 }') -- ensure-default-admin +New password for default admin user (user-xxxxx): + +``` + +High Availability install (RKE add-on): ``` $ KUBECONFIG=./kube_config_rancher-cluster.yml $ kubectl --kubeconfig $KUBECONFIG exec -n cattle-system $(kubectl --kubeconfig $KUBECONFIG get pods -n cattle-system -o json | jq -r '.items[] | select(.spec.containers[].name=="cattle-server") | .metadata.name') -- ensure-default-admin @@ -37,7 +54,6 @@ New password for default admin user (user-xxxxx): ``` - ### How can I enable debug logging? * Single node install @@ -54,8 +70,27 @@ $ docker exec -ti loglevel --set info OK ``` +* High Availability install (Helm) + * Enable +``` +$ KUBECONFIG=./kube_config_rancher-cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | awk '{ print $1 }' | xargs -I{} kubectl --kubeconfig $KUBECONFIG -n cattle-system exec {} -- loglevel --set debug +OK +OK +OK +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system logs -l app=rancher +``` -* High Availability install + * Disable +``` +$ KUBECONFIG=./kube_config_rancher-cluster.yml +$ kubectl --kubeconfig $KUBECONFIG -n cattle-system get pods -l app=rancher | grep '1/1' | awk '{ print $1 }' | xargs -I{} kubectl --kubeconfig $KUBECONFIG -n cattle-system exec {} -- loglevel --set info +OK +OK +OK +``` + +* High Availability install (RKE add-on) * Enable ``` $ KUBECONFIG=./kube_config_rancher-cluster.yml @@ -71,7 +106,6 @@ $ kubectl --kubeconfig $KUBECONFIG exec -n cattle-system $(kubectl --kubeconfig OK ``` - ### My ClusterIP does not respond to ping ClusterIP is a virtual IP, which will not respond to ping. Best way to test if the ClusterIP is configured correctly, is by using `curl` to access the IP and port to see if it responds. diff --git a/content/rancher/v2.x/en/installation/ha/_index.md b/content/rancher/v2.x/en/installation/ha/_index.md index 24fe7a7b010..1c040ed93a4 100644 --- a/content/rancher/v2.x/en/installation/ha/_index.md +++ b/content/rancher/v2.x/en/installation/ha/_index.md @@ -11,13 +11,13 @@ This procedure walks you through setting up a 3-node cluster with RKE and instal ## Recommended Architecture -* DNS for Rancher should resolve to a layer 4 load balancer +* DNS for Rancher should resolve to a Layer 4 load balancer (TCP) * The Load Balancer should forward port TCP/80 and TCP/443 to all 3 nodes in the Kubernetes cluster. * The Ingress controller will redirect HTTP to HTTPS and terminate SSL/TLS on port TCP/443. * The Ingress controller will forward traffic to port TCP/80 on the pod in the Rancher deployment. -HA Rancher install with layer 4 load balancer, depicting SSL termination at ingress controllers ![Rancher HA]({{< baseurl >}}/img/rancher/ha/rancher2ha.svg) +HA Rancher install with Layer 4 load balancer (TCP), depicting SSL termination at ingress controllers ## Required Tools diff --git a/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md index 26bb172cf6a..c9d51f538d3 100644 --- a/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md +++ b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/_index.md @@ -21,6 +21,7 @@ Configure a load balancer as a basic Layer 4 TCP forwarder. The exact configurat #### Examples +* [NGINX]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/) * [Amazon NLB]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/nlb/) ### [Next: Install Kubernetes with RKE]({{< baseurl >}}/rancher/v2.x/en/installation/ha/kubernetes-rke/) diff --git a/content/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/_index.md b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/_index.md new file mode 100644 index 00000000000..95ef78a58bc --- /dev/null +++ b/content/rancher/v2.x/en/installation/ha/create-nodes-lb/nginx/_index.md @@ -0,0 +1,75 @@ +--- +title: NGINX +weight: 270 +--- +NGINX will be configured as Layer 4 load balancer (TCP) that forwards connections to one of your Rancher nodes. + +>**Note:** +> In this configuration, the load balancer is positioned in front of your nodes. The load balancer can be any host capable of running NGINX. +> +> One caveat: do not use one of your Rancher nodes as the load balancer. + +## Install NGINX + +Start by installing NGINX on the node you want to use as a load balancer. NGINX has packages available for all known operating systems. The versions tested are `1.14` and `1.15`. For help installing NGINX, refer to their [install documentation](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/). + +The `stream` module is required, which is present when using the official NGINX packages. Please refer to your OS documentation on how to install and enable the NGINX `stream` module on your operating system. + +## Create NGINX Configuration + +After installing NGINX, you need to update the NGINX configuration file, `nginx.conf`, with the IP addresses for your nodes. + +1. Copy and paste the code sample below into your favorite text editor. Save it as `nginx.conf`. + +2. From `nginx.conf`, replace ``, ``, and `` with the IPs of your [nodes]({{< baseurl >}}/rancher/v2.x/en/installation/ha/create-nodes-lb/). + + >**Note:** See [NGINX Documentation: TCP and UDP Load Balancing](https://docs.nginx.com/nginx/admin-guide/load-balancer/tcp-udp-load-balancer/) for all configuration options. + +
Example NGINX config
+ ``` + worker_processes 4; + worker_rlimit_nofile 40000; + + events { + worker_connections 8192; + } + + http { + server { + listen 80; + return 301 https://$host$request_uri; + } + } + + stream { + upstream rancher_servers { + least_conn; + server :443 max_fails=3 fail_timeout=5s; + server :443 max_fails=3 fail_timeout=5s; + server :443 max_fails=3 fail_timeout=5s; + } + server { + listen 443; + proxy_pass rancher_servers; + } + } + ``` + +3. Save `nginx.conf` to your load balancer at the following path: `/etc/nginx/nginx.conf`. + +4. Load the updates to your NGINX configuration by running the following command: + + ``` + # nginx -s reload + ``` + +## Option - Run NGINX as Docker container + +Instead of installing NGINX as a package on the operating system, you can rather run it as a Docker container. Save the edited **Example NGINX config** as `/etc/nginx.conf` and run the following command to launch the NGINX container: + +``` +docker run -d --restart=unless-stopped \ + -p 80:80 -p 443:443 \ + -v /etc/nginx.conf:/etc/nginx/nginx.conf \ + nginx:1.14 +``` diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md index e813341cf31..cb0b97ca981 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/_index.md @@ -11,17 +11,31 @@ Rancher installation is managed using the Helm package manager for Kubernetes. Use `helm repo add` command to add the Helm chart repository that contains charts to install Rancher. For more information about the repository choices and which is best for your use case, see [Choosing a Version of Rancher]({{< baseurl >}}/rancher/v2.x/en/installation/server-tags/#helm-chart-repositories). -Replace `` with the Helm chart repository that you want to use (i.e. `latest` or `stable`). +Replace both occurences of `` with the Helm chart repository that you want to use (i.e. `latest` or `stable`). ``` helm repo add rancher- https://releases.rancher.com/server-charts/ ``` -### Install cert-manager +### Choose your SSL Configuration -> **Note:** cert-manager is only required for Rancher generated and LetsEncrypt issued certificates. You may skip this step if you are bringing your own certificates or using the `ingress.tls.source=secret` option. +Rancher Server is designed to be secure by default and requires SSL/TLS configuration. -Rancher relies on [cert-manager](https://github.com/kubernetes/charts/tree/master/stable/cert-manager) from the official Kubernetes Helm chart repository to issue self-signed or LetsEncrypt certificates. +There are three recommended options for the source of the certificate. + +> **Note:** If you want terminate SSL/TLS externally, see [TLS termination on an External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#external-tls-termination). + +| Configuration | Chart option | Description | Requires cert-manager | +|-----|-----|-----|-----| +| [Rancher Generated Certificates](#rancher-generated-certificates) | `ingress.tls.source=rancher` | Use certificates issued by Rancher's generated CA (self signed)
This is the **default** | [yes](#optional-install-cert-manager) | +| [Let’s Encrypt](#let-s-encrypt) | `ingress.tls.source=letsEncrypt` | Use [Let's Encrypt](https://letsencrypt.org/) to issue a certificate | [yes](#optional-install-cert-manager) | +| [Certificates from Files](#certificates-from-files) | `ingress.tls.source=secret` | Use your own certificate files by creating Kubernetes Secret(s) | no | + +### Optional: Install cert-manager + +> **Note:** cert-manager is only required for certificates issued by Rancher's generated CA (`ingress.tls.source=rancher`) and Let's Encrypt issued certificates (`ingress.tls.source=letsEncrypt`). You should skip this step if you are using your own certificate files (option `ingress.tls.source=secret`) or if you use [TLS termination on an External Load Balancer]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/#external-tls-termination). + +Rancher relies on [cert-manager](https://github.com/kubernetes/charts/tree/master/stable/cert-manager) from the official Kubernetes Helm chart repository to issue certificates from Rancher's own generated CA or to request Let's Encrypt certificates. Install `cert-manager` from Kubernetes Helm chart repository. @@ -31,21 +45,21 @@ helm install stable/cert-manager \ --namespace kube-system ``` -### Choose your SSL Configuration +Wait for `cert-manager` to be rolled out: -Rancher server is designed to be secure by default and requires SSL/TLS configuration. - -There are three options for the source of the certificate. - -1. `rancher` - (Default) Use Rancher generated CA/Certificates. -2. `letsEncrypt` - Use [LetsEncrypt](https://letsencrypt.org/) to issue a cert. -3. `secret` - Configure a Kubernetes Secret with your certificate files. +``` +kubectl -n kube-system rollout status deploy/cert-manager +Waiting for deployment "cert-manager" rollout to finish: 0 of 1 updated replicas are available... +deployment "cert-manager" successfully rolled out +```
-#### (Default) Rancher Generated Certificates +#### Rancher Generated Certificates -The default is for Rancher to generate a CA and use the `cert-manager` to issue the certificate for access to the Rancher server interface. +> **Note:** You need to have [cert-manager](#optional-install-cert-manager) installed before proceeding. + +The default is for Rancher to generate a CA and uses `cert-manager` to issue the certificate for access to the Rancher server interface. Because `rancher` is the default option for `ingress.tls.source`, we are not specifying `ingress.tls.source` when running the `helm install` command. - Replace `` with the repository that you configured in [Add the Helm Chart Repository](#add-the-helm-chart-repository) (i.e. `latest` or `stable`). - Set the `hostname` to the DNS name you pointed at your load balancer. @@ -59,12 +73,22 @@ helm install rancher-/rancher \ --set hostname=rancher.my.org ``` -#### LetsEncrypt +Wait for Rancher to be rolled out: -Use [LetsEncrypt](https://letsencrypt.org/)'s free service to issue trusted SSL certs. This configuration uses http validation so the Load Balancer must have a Public DNS record and be accessible from the internet. +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + +#### Let's Encrypt + +> **Note:** You need to have [cert-manager](#optional-install-cert-manager) installed before proceeding. + +This option uses `cert-manager` to automatically request and renew [Let's Encrypt](https://letsencrypt.org/) certificates. This is a free service that provides you with a valid certificate as Let's Encrypt is a trusted CA. This configuration uses HTTP validation (`HTTP-01`) so the load balancer must have a public DNS record and be accessible from the internet. - Replace `` with the repository that you configured in [Add the Helm Chart Repository](#add-the-helm-chart-repository) (i.e. `latest` or `stable`). -- Set `hostname`, `ingress.tls.source=letsEncrypt` and LetsEncrypt options. +- Set `hostname` to the public DNS record, set `ingress.tls.source` to `letsEncrypt` and `letsEncrypt.email` to the email address used for communication about your certificate (for example, expiry notices) >**Using Air Gap?** [Set the `rancherImage` option]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/install-rancher/#install-rancher-using-private-registry) in your command, pointing toward your private registry. @@ -77,16 +101,23 @@ helm install rancher-/rancher \ --set letsEncrypt.email=me@example.org ``` -#### Certificates from Files (Kubernetes Secret) +Wait for Rancher to be rolled out: + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + +#### Certificates from Files Create Kubernetes secrets from your own certificates for Rancher to use. -> **Note:** The common name for the cert will need to match the `hostname` option or the ingress controller will fail to provision the site for Rancher. +> **Note:** The `Common Name` or a `Subject Alternative Names` entry in the server certificate must match the `hostname` option, or the ingress controller will fail to configure correctly. Although an entry in the `Subject Alternative Names` is technically required, having a matching `Common Name` maximizes compatibility with older browsers/applications. If you want to check if your certificates are correct, see [How do I check Common Name and Subject Alternative Names in my server certificate?]({{< baseurl >}}/rancher/v2.x/en/faq/technical/#how-do-i-check-common-name-and-subject-alternative-names-in-my-server-certificate) - Replace `` with the repository that you configured in [Add the Helm Chart Repository](#add-the-helm-chart-repository) (i.e. `latest` or `stable`). -- Set `hostname` and `ingress.tls.source=secret`. - -> **Note:** If you are using a Private CA signed cert, add `--set privateCA=true` +- Set `hostname` and set `ingress.tls.source` to `secret`. +- If you are using a Private CA signed certificate , add `--set privateCA=true` to the command shown below. ``` helm install rancher-/rancher \ @@ -96,7 +127,25 @@ helm install rancher-/rancher \ --set ingress.tls.source=secret ``` -Now that Rancher is running, see [Adding TLS Secrets]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them. +Now that Rancher is deployed, see [Adding TLS Secrets]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/) to publish the certificate files so Rancher and the ingress controller can use them. + +After adding the secrets, check if Rancher was rolled out successfully: + +``` +kubectl -n cattle-system rollout status deploy/rancher +Waiting for deployment "rancher" rollout to finish: 0 of 3 updated replicas are available... +deployment "rancher" successfully rolled out +``` + +If you see the following error: `error: deployment "rancher" exceeded its progress deadline`, you can check the status of the deployment by running the following command: + +``` +kubectl -n cattle-system get deploy rancher +NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE +rancher 3 3 3 3 3m +``` + +It should show the same count for `DESIRED` and `AVAILABLE`. ### Advanced Configurations @@ -116,4 +165,4 @@ Make sure you save the `--set` options you used. You will need to use the same o That's it you should have a functional Rancher server. Point a browser at the hostname you picked and you should be greeted by the colorful login page. -Doesn't Work? Take a look at the [Troubleshooting]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/) Page +Doesn't work? Take a look at the [Troubleshooting]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/troubleshooting/) Page diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md index d9c3eb50cb1..39e9cf47214 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/chart-options/_index.md @@ -86,7 +86,7 @@ We recommend configuring your load balancer as a Layer 4 balancer, forwarding pl You may terminate the SSL/TLS on a L7 load balancer external to the Rancher cluster (ingress). Use the `--set tls=external` option and point your load balancer at port http 80 on all of the Rancher cluster nodes. This will expose the Rancher interface on http port 80. Be aware that clients that are allowed to connect directly to the Rancher cluster will not be encrypted. If you choose to do this we recommend that you restrict direct access at the network level to just your load balancer. -> **Note:** If you are using a Private CA signed cert, add `--set privateCA=true` and see [Adding TLS Secrets - Private CA Signed - Additional Steps]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/#private-ca-signed---additional-steps) to add the CA cert for Rancher. +> **Note:** If you are using a Private CA signed certificate, add `--set privateCA=true` and see [Adding TLS Secrets - Using a Private CA Signed Certificate]({{< baseurl >}}/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/#using-a-private-ca-signed-certificate) to add the CA cert for Rancher. Your load balancer must support long lived websocket connections and will need to insert proxy headers so Rancher can route links correctly. @@ -106,3 +106,50 @@ Your load balancer must support long lived websocket connections and will need t #### Health Checks Rancher will respond `200` to health checks on the `/healthz` endpoint. + + +#### Example NGINX config + +* Replace `IP_NODE1`, `IP_NODE2` and `IP_NODE3` with the IP addresses of the nodes in your cluster. +* Replace both occurences of `FQDN` to the DNS name for Rancher. +* Replace `/certs/fullchain.pem` and `/certs/privkey.pem` to the location of the server certificate and the server certificate key respectively. + +``` +upstream rancher { + server IP_NODE_1:80; + server IP_NODE_2:80; + server IP_NODE_3:80; +} + +map $http_upgrade $connection_upgrade { + default Upgrade; + '' close; +} + +server { + listen 443 ssl http2; + server_name FQDN; + ssl_certificate /certs/fullchain.pem; + ssl_certificate_key /certs/privkey.pem; + + location / { + proxy_set_header Host $host; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header X-Forwarded-Port $server_port; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_pass http://rancher; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close. + proxy_read_timeout 900s; + proxy_buffering off; + } +} + +server { + listen 80; + server_name FQDN; + return 301 https://$server_name$request_uri; +} +``` diff --git a/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md b/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md index 796305b067e..8b1c8b11f3a 100644 --- a/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md +++ b/content/rancher/v2.x/en/installation/ha/helm-rancher/tls-secrets/_index.md @@ -5,7 +5,7 @@ weight: 276 Kubernetes will create all the objects and services for Rancher, but it will not become available until we populate the `tls-rancher-ingress` secret in the `cattle-system` namespace with the certificate and key. -Combine the server certificate followed by the intermediate cert chain your CA provided into a file named `tls.crt`. Copy your key into a file name `tls.key`. +Combine the server certificate followed by any intermediate certificate(s) needed into a file named `tls.crt`. Copy your certificate key into a file named `tls.key`. Use `kubectl` with the `tls` secret type to create the secrets. @@ -15,13 +15,13 @@ kubectl -n cattle-system create secret tls tls-rancher-ingress \ --key=tls.key ``` -### Private CA Signed - Additional Steps +### Using a Private CA Signed Certificate -If you are using a private CA, Rancher will need to have a copy of the CA cert to include when generating agent configs. +If you are using a private CA, Rancher requires a copy of the CA certificate which is used by the Rancher Agent to validate the connection to the server. -Copy the CA cert into a file named `cacerts.pem` and use `kubectl` to create the `tls-ca` secret in the `cattle-system` namespace. +Copy the CA certificate into a file named `cacerts.pem` and use `kubectl` to create the `tls-ca` secret in the `cattle-system` namespace. ->**Important:** Make sure the file is called `cacerts.pem` as Rancher uses that filename to configure the CA cert. +>**Important:** Make sure the file is called `cacerts.pem` as Rancher uses that filename to configure the CA certificate. ``` kubectl -n cattle-system create secret generic tls-ca \ diff --git a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md index 45e501aeaa4..acc8ae97f56 100644 --- a/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md +++ b/content/rancher/v2.x/en/installation/single-node/single-node-install-external-lb/_index.md @@ -132,6 +132,7 @@ server { proxy_set_header Connection $connection_upgrade; # This allows the ability for the execute shell window to remain open for up to 15 minutes. Without this parameter, the default is 1 minute and will automatically close. proxy_read_timeout 900s; + proxy_buffering off; } }