public/rancher-docs
1
0
Fork 0
mirror of https://github.com/rancher/rancher-docs.git synced 2026-09-25 04:28:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

removing sections moved to other parts

Browse Source
This commit is contained in:
Mark Bishop
2018-05-10 12:19:13 -07:00
committed by Mark Bishop
parent 77ce10ce08
commit 194c1d5a5a
7 changed files with 0 additions and 888 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/installation/load-balancing-config/_index.md
-13
View File
@@ -1,13 +0,0 @@
---
title: Load Balancing
weight: 300
draft: true
---
# Load Balancer Configuration
Following {{< product >}} installation, you have the option of configuring an external load balancer to direct cluster traffic.
Rancher has tested a few load balancer configurations. Choose from the options available. There is no "best" configuration. Choose the load balancer that best suits your needs.
When configuring an external load balancer, the steps for setting up a load balancer vary based on your install: single-node or high-availability.
content/rancher/v2.x/en/installation/load-balancing-config/config-amazon-alb/_index.md
-135
View File
@@ -1,135 +0,0 @@
---
title: Configure Amazon ALB
weight: 305
---
# Configure Amazon ALB
Amazon Elastic Load Balancing offers a couple of different load balancers that we're tested. This procedure provides step-by-step instruction for configuring Amazon Application Load Balancer (ALB) with your Rancher Server.
## Objectives
Configuring an Amazon ALB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
1. [Create Target Groups](#create-target-groups)
Begin by creating two target groups for each http protocol: http and https. You'll add your Kubernetes nodes to both groups.
2. [Register Targets](#register-targets)
Add your server nodes to the groups.
3. [Create Your ALB](#create-your-alb)
Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add one of the target groups you created in **1. Create Target Groups**.
4. [Add Your Second Target Group](#add-your-second-target-group)
The Wizard in **3. Create Your ALB** only allows you to add a single target group. Go back into Amazon's console and add the second target group manually.
### Create Target Groups
Your first ALB configuration step is to create two target groups: one for HTTP, the other for HTTPS.
Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get started.
The document below will guide you through this process. Use the data in the tables below to complete the procedure.
[Amazon Documentation: Create a Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-target-group.html)
#### Target Group 1 (HTTP)
Option | Setting
----------------------------|------------------------------------
Target Group Name | `rancher-http-80`
Protocol | `HTTP`
Port | `80`
Target type | `instance`
VPC | Choose your VPC
Protocol<br/>(Health Check) | `HTTP`
#### Target Group 2 (HTTPS)
Option | Setting
----------------------------|------------------------------------
Target Group Name | `rancher-https-443`
Protocol | `HTTPS`
Port | `443`
Target type | `instance`
VPC | Choose your VPC
Protocol<br/>(Health Check) | `HTTPS`
### Register Targets
Next, add your nodes assigned either the `controlplane` or `worker` role to _both_ of your target groups.
[Amazon Documentation: Register Targets with Your Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-register-targets.html)
### Create Your ALB
Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add one of the target groups you created in [Create Target Groups](#create-target-groups).
1. From your web browser, navigate to the [Amazon EC2 Console](https://console.aws.amazon.com/ec2/).
2. From the navigation pane, choose **LOAD BALANCING** > **Load Balancers**.
3. Click **Create Load Balancer**.
4. Choose **Application Load Balancer**.
5. Complete the **Step 1: Configure Load Balancer** form.
- **Basic Configuration**
- Name: `rancher-http-https`
- Scheme: `internet-facing`
- IP address type: `ipv4`
- **Listeners**
Add the **Load Balancer Protocols** and **Load Balancer Ports** below.
- `HTTP`: `80`
- `HTTPS`: `443`
- **Availability Zones**
- Select Your **VPC** and **Availability Zones**.
6. Complete the **Step 2: Configure Security Settings** form.
>**Installing in a High-Availability Configuration?**
> - If you are using self-signed certificates, the certificate and key must be signed by the same certificate authority that signed `cattle-keys-server`.
> - If you are using SSL passthrough, you must use a certificate signed by a public certificate authority.
7. Complete the **Step 3: Configure Security Groups** form.
8. Complete the **Step 4: Configure Routing** form.
1. From the **Target Group** drop-down, choose **Existing target group**.
2. Add target group `rancher-http-80`.
>**Note:** The wizard lets you add only one group. You will add your second group in the next procedure, [Add Your Second Target Group](#add-your-second-target-group).
9. Complete **Step 5: Register Targets**. Since you registered your targets earlier, all you have to do it click **Next: Review**.
10. Complete **Step 6: Review**. Look over the load balancer details and click **Create** when you're satisfied.
11. After AWS creates the ALB, click **Close**.
### Add Your Second Target Group
The load balancer is created, but you still need to add your second target group. Use the Amazon EC2 Console and add the second target group manually.
1. From the navigation pane, choose **LOAD BALANCING** > **Load Balancers**.
2. From the grid of load balancers, select your load balancer.
3. Select the **Listeners** tab. Select the `HTTPS: 443` **Listener ID**. Then click **Edit**.
4. From the **Default target group** drop-down, select `rancher-https-443`. Click **Save**.
5. Review the **Listeners** tab to make sure the protocols for the **Listener ID**s and **Rules** match. The following **Listener ID**s should be matched to the following **Rules**:
- `HTTP: 80`: `rancher-http-80`
- `HTTPS:443`: `rancher-https-443`
content/rancher/v2.x/en/installation/load-balancing-config/config-amazon-nlb/_index.md
-124
View File
@@ -1,124 +0,0 @@
---
title: Configure Amazon NLB
weight: 310
---
# Configure Amazon NLB
Amazon Elastic Load Balancing offers a couple of different load balancers that we're tested. This procedure provides step-by-step instruction for configuring Amazon Network Load Balancer (NLB) with your Rancher Server.
## Objectives
Configuring an Amazon NLB is a multistage process. We've broken it down into multiple tasks so that it's easy to follow.
1. [Create Target Groups](#create-target-groups)
Begin by creating two target groups for each http protocol: http and https. You'll add your Kubernetes nodes to both groups.
2. [Register Targets](#register-targets)
Add your Kubernettes nodes to the groups.
3. [Create Your NLB](#create-your-NLB)
Use Amazon's Wizard to create an Application Load Balancer. As part of this process, you'll add one of the target groups you created in **1. Create Target Groups**.
4. [Add Your Second Target Group](#placeholder)
The Wizard in **3. Create Your NLB** only allows you to add a single target group. Go back into Amazon's console and add the second target group manually.
### Create Target Groups
Your first NLB configuration step is to create two target groups for the TCP protocol: one on port 80, the other on port 443.
Log into the [Amazon AWS Console](https://console.aws.amazon.com/ec2/) to get started.
The document below will guide you through this process. Use the data in the tables below to complete the procedure.
[Amazon Documentation: Create a Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-target-group.html)
#### Target Group 1 (TCP)
Option | Setting
----------------------------|------------------------------------
Target Group Name | `rancher-tcp-80`
Protocol | `TCP`
Port | `80`
Target type | `instance`
VPC | Choose your VPC
Protocol<br/>(Health Check) | `TCP`
#### Target Group 2 (TCP)
Option | Setting
----------------------------|------------------------------------
Target Group Name | `rancher-tcp-443`
Protocol | `TCP`
Port | `443`
Target type | `instance`
VPC | Choose your VPC
Protocol<br/>(Health Check) | `TCP`
### Register Targets
Next, add your Kubernetes nodes assigned either the `controlplane` or `worker` role to _both_ of your target groups.
[Amazon Documentation: Register Targets with Your Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/target-group-register-targets.html)
### Create Your NLB
1. From your web browser, navigate to the [Amazon EC2 Console](https://console.aws.amazon.com/ec2/).
2. From the navigation pane, choose **LOAD BALANCING** > **Load Balancers**.
3. Click **Create Load Balancer**.
4. Choose **Network Load Balancer**.
5. Complete the **Step 1: Configure Load Balancer** form.
- **Basic Configuration**
- Name: `rancher-http-https`
- Scheme: `internet-facing`
- IP address type: `ipv4`
- **Listeners**
Add the **Load Balancer Protocols** and **Load Balancer Ports** below.
- `TCP`: `80`
- `TCP`: `443`
- **Availability Zones**
- Select Your **VPC** and **Availability Zones**.
6. Complete the **Step 2: Configure Routing** form.
1. From the **Target Group** drop-down, choose **Existing target group**.
2. Add target group `rancher-tcp-80`.
>**Note:** The wizard lets you add only one group. You will add your second group in the next procedure, [Add Your Second Target Group](#add-your-second-target-group).
7. Complete **Step 3: Register Targets**. Since you registered your targets earlier, all you have to do it click **Next: Review**.
8. Complete **Step 4: Review**. Look over the load balancer details and click **Create** when you're satisfied.
9. After AWS creates the ALB, click **Close**.
### Add Your Second Target Group
The load balancer is created, but you still need to add your second target group. Use the Amazon EC2 Console and add the second target group manually.
1. From the navigation pane, choose **LOAD BALANCING** > **Load Balancers**.
2. From the grid of load balancers, select your load balancer.
3. Select the **Listeners** tab. Select the `TCP: 443` **Listener ID**. Then click **Edit**.
4. From the **Default target group** drop-down, select `rancher-tcp-443`. Click **Save**.
5. Review the **Listeners** tab to make sure the protocols for the **Listener ID**s and **Rules** match. The following **Listener ID**s should be matched to the following **Rules**:
- `TCP: 80`: `rancher-tcp-80`
- `TCP:443`: `rancher-tcp-443`
content/rancher/v2.x/en/installation/load-balancing-config/config-nginx/_index.md
-68
View File
@@ -1,68 +0,0 @@
---
title: Configure Nginx
weight: 315
---
# Configure Nginx
Nginx is a popular application platform that can be used as a load balancer. Rancher supports use of Nginx with ngx_http_v2_module enabled, which isn't enabled by default. Use the following parameter when setting up Nginx to enable the module: `--with-http_v2_module`.
>**Note:**
>- Nginx is not supported if you are using SSL passthrough.
>- If you are using self-signed certificates, the certificate and key must be signed by same certificate authority as `cattle-keys-server`.
After the server is running, use the code sample below as a template when setting up your Nginx config file. Replace the variables with host names or IP addresses from your environment.
```
upstream rancher {
server <rancher_server_ip1>;
server <rancher_server_ip2>;
}
map $http_upgrade $connection_upgrade {
default Upgrade;
'' close;
}
server {
listen 443 ssl http2 default_server;
server_name <FQDN>;
if ($host != $server_name) {
return 301 https://$server_name$request_uri;
}
ssl_certificate <CERT_FILE>;
ssl_certificate_key <KEY_FILE>;
location / {
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
# mitigate HTTPoxy Vulnerability
# https://www.nginx.com/blog/mitigating-the-httpoxy-vulnerability-with-Nginx/
proxy_set_header Proxy "";
proxy_http_version 1.1;
# This allows the ability for the execute shell window to remain open for up to 30 minutes. Without this parameter, the default is 1 minute and will automatically close.
proxy_connect_timeout 30s;
proxy_send_timeout 1800s;
proxy_read_timeout 1800s;
proxy_pass http://rancher;
}
}
server {
listen 80;
server_name <FQDN>;
return 301 https://$server_name$request_uri;
}
```
content/rancher/v2.x/en/installation/server-installation/ha-server-install/ssl-passthrough/_index.md
-148
View File
@@ -1,148 +0,0 @@
---
title: SSL Passthrough
weight: 275
draft: true
---
# High Availability Install with SSL Passthrough
In this scenario, your High-Availability Rancher Servers handle SSL decryption rather than a Load Balancer.
## Before you Start:
Complete [SSL Config: In the Rancher Container]({{< baseurl >}}/rancher/v2.x/en/installation/ssl-config/#certificate-host-inside-the-rancher-container).
## Objectives
We've broken installation of Rancher with SSL passthrough into a series of smaller tasks. Here's what you'll do during install.
1. [Provision Linux Hosts](#provision-linux-hosts)
Begin by provisioning Linux hosts. Make sure your hosts meet Rancher requirements.
2. [Get RKE](#get-rke)
Download the Rancher Kubernetes Engine (RKE) installer from GitHub.
3. [Get YAML Config File Template](#get-yaml-template)
During installation, RKE uses a `.yml` config file containing specifications for your cluster. Download our template from GitHub.
4. [Edit YAML Config File Template](#edit-yaml-template)
Edit the `.yml` config file so that it's pointing toward your Linux hosts.
5. [Run RKE](#run-rke)
Finally, run the RKE installer with it pointing toward your `.yml` config file.
### Provision Linux Hosts
Before you install Rancher, confirm you meet the requirements. Provision three new Linux hosts using the requirements below.
#### Requirements
{{< requirements_os >}}
{{< requirements_hardware >}}
{{< requirements_software >}}
{{< requirements_ports >}}
### Get RKE
Rancher Kubernetes Engine (RKE) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. You can download RKE from GitHub.
1. From your workstation, open a web browser and navigate to our [RKE Releases](https://github.com/rancher/rke/releases) page. Download the latest RKE installer.
2. Make the RKE binary that you just downloaded executable. Open Terminal, change directory to the location of the RKE binary, and then run the following command:
```
$ chmod +x rke
```
>**Note:** Adjust the command for the version of RKE that you downloaded (e.g., `rke_darwin-amd64`)
3. Confirm that RKE is now executable by running the following command:
```
$ ./rke -version
```
**Result:** You receive output similar to what follows:
```
rke version v<N.N.N>
```
### Get YAML Config File Template
During installation, RKE uses a `.yml` config file to install and configure your Kubernetes cluster. Download the `3-node-passthrough.yml` config file linked below to get you started.
[Download SSL Passthrough YAML Config Template](https://github.com/rancher/rancher/blob/master/rke-templates/3-node-passthrough.yml)
### Edit YAML Template
Once you have `3-node-passthrough.yml`, edit the nodes section to point toward your Linux hosts.
1. Open `3-node-passthrough.yml`, which you just downloaded.
2. Update the `nodes` section with your [Linux hosts](#provision-linux-hosts).
For each node in your cluster, update the following placeholders:
- `<IP>`: The IP address or hostname of the node.
- `<USER>`: The node root user (usually `root`).
- `<PEM_FILE>`: The path of the `.pem` file used to authenticate.
**Example YAML**
nodes:
- address: <IP> # IP to access nodes
user: <USER> # root user (usually 'root')
role: [controlplane,etcd,worker] # K8s roles for node
ssh_key_path: <PEM_FILE> # path to PEM file
- address: <IP>
user: <USER>
role: [controlplane,etcd,worker]
ssh_key_path: <PEM_FILE>
- address: <IP>
user: <USER>
role: [controlplane,etcd,worker]
ssh_key_path: <PEM_FILE>
3. Scroll to `kind: Ingress`. Replace the two `<FQDN>` placeholders with the FQDN mapped to each of your nodes. On your DNS Server, each node should be added to the DNS entry for the FQDN.
**Example YAML**
spec:
rules:
- host: <FQDN> # FQDN to access cattle server
http:
paths:
- backend:
serviceName: cattle-service
servicePort: 80
tls:
- secretName: cattle-keys-ingress
hosts:
- <FQDN> # FQDN to access cattle server
6. Save the `.yml` config file and close it.
### Run RKE
Enter the command to run RKE while pointing to `3-node-passthrough.yml`. RKE installs Kubernetes and Rancher using your parameters.
1. From your workstation, make sure `3-node-passthrough.yml` and RKE are in the same directory.
2. Open a Terminal instance. Change to the directory that contains `3-node-passthrough.yml` and RKE.
3. Enter the following command.
```
rke up --config `3-node-passthrough.yml`
```
### What's Next?
Log in to Rancher to make sure it deployed successfully. Open a web browser and navigate to the FQDN used earlier in this procedure.
content/rancher/v2.x/en/installation/server-installation/ha-server-install/ssl-termination/_index.md
-208
View File
@@ -1,208 +0,0 @@
---
title: SSL Termination
weight: 275
draft: true
---
# High Availability Install with SSL Temination
In this scenario, your Load Balancer handles all SSL decryption, and then forwards the decrypted communications to your cluster.
## Before You Start
Complete [SSL Config: External Load Balancer or Proxy]({{< baseurl >}}/rancher/v2.x/en/installation/ssl-config/#instructions-for-the-loadbalancer-or-proxy)
## Objectives
We've broken installation of Rancher with SSL termination into a series of smaller tasks. Here's what you'll do during your install.
1. [Provision Linux Hosts](#provision-linux-hosts)
Begin by provisioning Linux hosts. Make sure your hosts meet Rancher requirements.
2. [Get RKE](#get-rke)
Download the Rancher Kubernetes Engine (RKE) installer from GitHub.
3. [Get YAML Template](#get-yaml-template)
During installation, RKE uses a `.yml` config file containing specifications for your cluster. Download our template from GitHub.
4. [Edit YAML Template](#edit-yaml-template)
Edit the `.yml` config file so that it's pointing toward your Linux hosts.
5. [Run RKE](#run-rke)
Finally, run the RKE installer with it pointing toward your `.yml` config file.
### Provision Linux Hosts
Before you install Rancher, confirm you meet the requirements. Provision three new Linux hosts using the requirements below.
#### Requirements
{{< requirements_os >}}
{{< requirements_hardware >}}
{{< requirements_software >}}
{{< requirements_ports >}}
##### Certificate Requirements
Before starting this procedure, you should generate or obtain your own certificate.
The certificate can either be:
- Self-signed
- Signed by a certificate authority (CA)
>**Note:**
>-If you use a self-signed certificate, all certificates and keys must be signed by the same CA.<br/>
>-Each `.pem` must be in base-64: `cat <PEM_FILE> | base64`.
### Get RKE
Rancher Kubernetes Engine (RKE) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. You can download RKE from GitHub.
1. From your workstation, open a web browser and navigate to our [RKE Releases](https://github.com/rancher/rke/releases) page. Download the latest RKE installer.
2. Make the RKE binary that you just downloaded executable. Open Terminal, change directory to the location of the RKE binary, and then run the following command:
```
$ chmod +x rke
```
>**Note:** Adjust the command for the version of RKE that you downloaded (e.g., `rke_darwin-amd64`)
3. Confirm that RKE is now executable by running the following command:
```
$ ./rke -version
```
**Result:** You receive output similar to what follows:
```
rke version v<N.N.N>
```
### Get YAML Template
During installation, RKE uses a `.yml` config file to install and configure your Kubernetes cluster. Download the `3-node-certificate.yml` config file linked below to get you started.
[Download 3-node-certificate.yml](https://github.com/rancher/rancher/blob/master/rke-templates/3-node-certificate.yml)
### Edit YAML Template
Once you have the `.yml` config file template, edit the nodes section to point toward your Linux hosts.
1. Open `3-node-certificate.yml`, which you just downloaded.
2. Update the `nodes` section with your [Linux hosts](#provision-linux-hosts).
For each node in your cluster, update the following placeholders:
- `<IP>`: The IP address or hostname of the node.
- `<USER>`: The node root user (usually `root`).
- `<PEM_FILE>`: The path of the `.pem` file used to authenticate.
**Example YAML**
nodes:
- address: <IP> # IP to access nodes
user: <USER> # root user (usually 'root')
role: [controlplane,etcd,worker] # K8s roles for node
ssh_key_path: <PEM_FILE> # path to PEM file
- address: <IP>
user: <USER>
role: [controlplane,etcd,worker]
ssh_key_path: <PEM_FILE>
- address: <IP>
user: <USER>
role: [controlplane,etcd,worker]
ssh_key_path: <PEM_FILE>
3. Scroll to `kind: Ingress`. Replace the two `<FQDN>` placeholders with the FQDN mapped to each of your nodes. On your DNS Server, each node should be added to the DNS entry for the FQDN.
**Example YAML**
spec:
rules:
- host: <FQDN> # FQDN to access cattle server
http:
paths:
- backend:
serviceName: cattle-service
servicePort: 80
tls:
- secretName: cattle-keys-ingress
hosts:
- <FQDN> # FQDN to access cattle server
4. Scroll to the codeblock that follows.
```
apiVersion: v1
kind: Secret
metadata:
name: cattle-keys-server
namespace: cattle-system
type: Opaque
data:
cert.pem: <BASE64_CRT> # ssl cert for cattle server.
key.pem: <BASE64_KEY> # ssl key for cattle server.
cacerts.pem: <BASE64_CA> # CA cert used to sign cattle server cert and key
```
Replace each placeholder with the applicable certificate `.pem`.
- `<BASE64_CRT>`
- `<BASE64_KEY>`
- `<BASE64_CA>`
>**Reminder:** Each `.pem` must be in base-64: `cat <PEM_FILE> | base64`.
5. Scroll to the codeblock that follows.
```
apiVersion: v1
kind: Secret
metadata:
name: cattle-keys-ingress
namespace: cattle-system
type: Opaque
data:
tls.crt: <BASE64_CRT> # ssl cert for ingress. If self-signed, must be signed by same CA as cattle server
tls.key: <BASE64_KEY> # ssl key for ingress. If self-signed, must be signed by same CA as cattle server
```
Replace each placeholder with the applicable `.pem`.
- `<BASE64_CRT>`
- `<BASE64_KEY>`
>**Reminder:** Each `.pem` must be in base-64: `cat <PEM_FILE> | base64`.
6. Save the `.yml` file and close it.
### Run RKE
Enter the command to run RKE while pointing to `3-node-certificate.yml`. RKE installs Kubernetes and Rancher using your parameters.
1. From your workstation, make sure `3-node-certificate.yml` and RKE are in the same directory.
2. Open a Terminal instance. Change to the directory that contains `3-node-certificate.yml` and RKE.
3. Enter the following command.
```
rke up --config 3-node-certificate.yml
```
### What's Next?
Log in to Rancher to make sure it deployed successfully. Open a web browser and navigate to the FQDN used earlier in this procedure.
content/rancher/v2.x/en/installation/ssl-config/_index.md
-192
View File
@@ -1,192 +0,0 @@
---
title: SSL Configuration
weight: 325
draft: true
---
# SSL Configuration
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL encrypts all Rancher communications: login, cluster interaction, and so on.
By default, Rancher generates a self-signed certificate that's used to encrypt communication over port 443 (HTTPS). Any traffic directed to port 80 (HTTP) is automatically forwarded to 443.
If you want to use your own certificate that's self-signed or signed by a commercial certificate authority (CA), refer to the documentation below.
## Before You Start: Choose a Certificate Host
There are two locations that can host your own certificates. Choose one.
- Inside the Rancher container.
- Using an external load balancer or proxy.
## Certificate Host: Inside the Rancher Container
### Automatically Generated Default Self-Signed Certificate
By running the `rancher/rancher` container without any additional parameters or configuration, a self-signed certificate is automatically created on startup.
**Example**
```
docker run -d -p 80:80 -p 443:443 rancher/rancher:v2.0.0
```
### Self-Signed Certificate
You can use your own certificates and let Rancher use them to provide SSL. You can provide them by mounting the certificate files when running the container. The certificate files should be in `.pem` format. Make sure that your certificate file includes all the intermediate certificates in the chain.
| Type | Location in container |
| ---------------------------- | ---------------------------: |
| Certificate file | /etc/rancher/ssl/cert.pem |
| Certificate key file | /etc/rancher/ssl/key.pem |
| CA certificates file | /etc/rancher/ssl/cacerts.pem |
<br/>
**Example**
```
docker run -d -p 80:80 -p 443:443 \
-v /etc/your_certificate_directory/fullchain.pem:/etc/rancher/ssl/cert.pem \
-v /etc/your_certificate_directory/privkey.pem:/etc/rancher/ssl/key.pem \
-v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
rancher/rancher:v2.0.0
```
### Providing your own certificates from a recognized CA to the container
If the certificates you want to use are signed by a recognized CA, you only have to provide the certificate file and the certificate key file to the container. In this case, mounting an additional CA certificate file is not needed as it is signed by a recognized CA.
| Type | Location in container |
| ---------------------------- | ---------------------------: |
| Certificate file | /etc/rancher/ssl/cert.pem |
| Certificate key file | /etc/rancher/ssl/key.pem |
<br/>
**Example**
```
docker run -d -p 80:80 -p 443:443 \
-v /etc/your_certificate_directory/fullchain.pem:/etc/rancher/ssl/cert.pem \
-v /etc/your_certificate_directory/privkey.pem:/etc/rancher/ssl/key.pem \
rancher/rancher:v2.0.0
```
### Using Automatically Requested Let's Encrypt Certificates
Rancher supports requesting Let's Encrypt certificates out-of-the-box. This request uses **HTTP-01 challenge**, which means that the hostname you choose for accessing Rancher (for example, `rancher.mydomain.com`) must point to the IP address of the host that Rancher runs on. Therefore, you must bind your hostname to the Rancher host IP address on your DNS.
Because the Let's Encrypt challenge can originate from any source IP address, port **TCP/80** must be open for every source IP address. You enable the Let's Encrypt functionality by passing the parameter `--acme-domain rancher.mydomain.com` when running the `rancher/rancher` container.
**Example**
```
docker run -d -p 80:80 -p 443:443 rancher/rancher:v2.0.0 --acme-domain rancher.mydomain.com
```
>**Note:** Let's Encrypt provides rate limits for requesting new certificates, keep this in mind when creating and destroying the container multiple times. Read more on this in the [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/).
## Options When Using an External Load Balancer or Proxy
### Terminating SSL at Load Balancer or Proxy
#### Instructions for the `rancher/rancher` Container
**Self-Signed Certificates**
When using self-signed certificates, you must add the CA certificate to the `rancher/rancher` container. This cerrtificate is used to validate connections to Rancher.
| Type | Location in container |
| ---------------------------- | ---------------------------: |
| CA certificates file | /etc/rancher/ssl/cacerts.pem |
**Example**
```
docker run -d -p 80:80 -p 443:443 \
-v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
rancher/rancher:v2.0.0
```
**Certificates from a Commercial CA**
If the certificates you want to use are signed by a commercial CA (like GoDaddy or digicert), you must remove the certificate information that the CA generates by default. You can remove this information by selecting **Settings** in the Rancher UI. From the **cacerts** section, select **...** > **Edit**, remove the contents, and then click **Save**.
#### Instructions for the Load Balancer or Proxy
When using a load balancer or proxy in front of the `rancher/rancher` container, there is no need for the `rancher/rancher` container to redirect port **TCP/80** (HTTP) to port **TCP/443** (HTTPS). By passing the `X-Forwarded-Proto: https` header, this redirect is disabled.
You must configure the load balancer or proxy has to support:
- **WebSocket** connections
- **SPDY** / **HTTP/2**
- passing/setting the following headers:
| Header | Value | Description |
|---------------------|-------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Host` | Domain name used to reach Rancher | To identify the server requested by the client. |
| `X-Forwarded-Proto` | `https` | To identify the protocol that a client used to connect to the load balancer or proxy.<br /><br/>**Note**: If this header is present, `rancher/rancher` cannot redirect HTTP to HTTPS. |
| `X-Forwarded-Port` | Port used to reach Rancher | To identify the protocol that a client used to connect to the load balancer or proxy. |
| `X-Forwarded-For` | IP of the client connection | To identify the originating IP address of a client. |
<br/>
**Example Configuration: Nginx 1.12 / 1.13**
```
upstream rancher {
server rancher-server:80;
}
map $http_upgrade $connection_upgrade {
default Upgrade;
'' close;
}
server {
listen 443 ssl http2;
server_name rancher.yourdomain.com;
ssl_certificate /etc/your_certificate_directory/fullchain.pem;
ssl_certificate_key /etc/your_certificate_directory/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;
}
}
server {
listen 80;
server_name rancher.yourdomain.com;
return 301 https://$server_name$request_uri;
}
```
## FAQ / Troubleshooting
#### How do I validate my certificate chain?
You can validate the certificate chain by using the `openssl` binary. If the output ends with `Verify return code: 0 (ok)`, your certificate chain is valid. The `ca.pem` file should be the same as you supplied to the `rancher/rancher` container. When using a certificate signed by a well known CA, you can omit the `-CAfile` parameter.
**Example**
```
openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
...
Verify return code: 0 (ok)
```
#### How do I know if my certificates are in **PEM** format?
You can recognize the **PEM** format by the header:
```-----BEGIN CERTIFICATE-----```
And the footer:
```-----END CERTIFICATE-----```