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

updating single-node install topics for consistency

Browse Source
This commit is contained in:
Mark Bishop
2018-06-01 10:31:30 -07:00
parent 62fedd0723
commit 59dd9c0707
4 changed files with 156 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/rancher/v2.x/en/installation/single-node-install-external-lb/_index.md
+60 -38
View File
@@ -4,33 +4,36 @@ weight: 260
---
For development environments, we recommend installing Rancher by running a single Docker container. In this installation scenario, you'll deploy Rancher to a Linux host using a single Docker container. Then you will configure an external load balancer to work with Rancher.
>**Note:**
> If you want don't want to use an external load balancer, see [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install/).
## Overview
>**Want to skip the external load balancer?**
> See [Single Node Installation]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install) instead.
Installation of Rancher on a single node with an external load balancer involves multiple procedures. Review this overview to learn about each procedure you need to complete.
1. [Provision Linux Host](#part-1-provision-linux-host)
## Installation Outline
Installation of Rancher on a single node with an external load balancer involves multiple procedures. Review this outline to learn about each procedure you need to complete.
1. [Provision Linux Host](#1-provision-linux-host)
Provision a single Linux host to launch your {{< product >}} Server.
2. [Choose an SSL Option and Install Rancher](#part-2-choose-an-ssl-option-and-install-rancher)
2. [Choose an SSL Option and Install Rancher](#2-choose-an-ssl-option-and-install-rancher)
Choose an SSL option for Rancher communication encryption. After choosing an option, run the command that accompanies it to deploy Rancher.
3. [Configure Load Balancer](#part-3-configure-load-balancer)
3. [Configure Load Balancer](#3-configure-load-balancer)
Setup a load balancer to direct communications with Rancher and your Kubernetes cluster.
4. **For those using a certificate signed by a recognized CA:**
[Remove Default Certificates](#part-4-remove-default-certificates)
[Remove Default Certificates](#4-remove-default-certificates)
If you chose [Option B](#option-b-bring-your-own-certificate-signed-by-recognized-ca) as your SSL option, log into the Rancher UI and remove the certificates that Rancher automatically generates.
## Part 1-Provision Linux Host
## 1. Provision Linux Host
Provision a single Linux host to launch your {{< product >}} Server.
@@ -42,15 +45,23 @@ Provision a single Linux host to launch your {{< product >}} Server.
{{< requirements_software >}}
<a id="port-requirements"></a>
{{< requirements_ports >}}
{{< note_server-tags >}}
## Part 2-Choose an SSL Option and Install Rancher
## 2. Choose an SSL Option and Install Rancher
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
You can choose from the following scenarios:
>**Attention Air Gap Users:**
> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL.
>
> Example:
```
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
```
- [Option A-Bring Your Own Certificate: Self-Signed](#option-a-bring-your-own-certificate-self-signed)
- [Option B-Bring Your Own Certificate: Signed by Recognized CA](#option-b-bring-your-own-certificate-signed-by-recognized-ca)
@@ -67,14 +78,14 @@ If you elect to use a self-signed certificate to encrypt communication, you must
**To Install Rancher Using a Self-Signed Cert:**
While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.
1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
rancher/rancher:latest
```
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /etc/your_certificate_directory/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
rancher/rancher:latest
```
### Option B-Bring Your Own Certificate: Signed by Recognized CA
@@ -82,20 +93,22 @@ If your cluster is public facing, it's best to use a certificate signed by a rec
>**Prerequisites:**
>
>- The certificate files must be in [PEM format](#ssl-faq-troubleshooting).
>- The certificate files must be in base64.
>- The certificate files must be in [PEM format](#pem).
>- The certificate files must be encoded in [base64](#base64).
**To Install Rancher Using a Cert Signed by a Recognized CA:**
If you use a certificate signed by a recognized CA, installing your certificate in the Rancher container isn't necessary. Just run the basic install command below.
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
rancher/rancher:latest
```
1. Enter the following command.
## Part 3-Configure Load Balancer
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
rancher/rancher:latest
```
## 3. Configure Load Balancer
When using a load balancer in front of your Rancher container, there's no need for the container to redirect port communication from port 80 or port 443. By passing the header `X-Forwarded-Proto:
https` header, this redirect is disabled.
@@ -106,16 +119,17 @@ The load balancer or proxy has to be configured to support the following:
* **SPDY** / **HTTP/2** protocols
* Passing / setting the following headers:
| Header | Value | Description |
|---------------------|----------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Host` | Hostname 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` does not redirect HTTP to HTTPS. |
| `X-Forwarded-Port` | Port used to reach Rancher. | To identify the protocol that 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. |
| Header | Value | Description |
|--------|-------|-------------|
| `Host` | Hostname 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` does not redirect HTTP to HTTPS.
| `X-Forwarded-Port` | Port used to reach Rancher. | To identify the protocol that 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.
### Example Nginx configuration
This Nginx configuration is tested on Nginx 1.13 (mainline) and 1.14 (stable).
This Nginx configuration is tested on Nginx version 1.13 (mainline) and 1.14 (stable).
```
upstream rancher {
@@ -154,28 +168,36 @@ server {
}
```
## Part 4-Remove Default Certificates
## 4. Remove Default Certificates
**For those using a certificate signed by a recognized CA:**
>**Note:** If you're using a self-signed certificate, you don't have to complete this part.
>**Note:** If you're using a self-signed certificate, don't complete this procedure. Continue to [What's Next?](#what-s-next)
By default, Rancher automatically generates self-signed certificates for itself after installation. However, since you've provided your own certificates, you must disable the certificates that Rancher generated for itself.
**To Remove the Default Certificates:**
1. Log into Rancher.
2. Select **Settings** > **cacerts**.
3. Choose `Edit` and remove the contents. Then click `Save`.
<br/>
## What's Next?
You have a couple of options:
Create a backup of your Rancher Server in case of a disaster scenario. For more information, see [Backing Up Your Rancher Server]({{< baseurl >}}/rancher/v2.x/en/installation/after-installation/single-node-backup-and-restoration/#backing-up-your-rancher-server).
- Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/).
- Create a Kubernettes cluster: [Creating a Cluster]({{ <baseurl> }}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/).
## SSL FAQ / Troubleshooting
<br/>
## FAQ and Troubleshooting
{{< ssl_faq >}}
## Persistent data
## Persistent Data
{{< persistentdata >}}
content/rancher/v2.x/en/installation/single-node-install/_index.md
+74 -65
View File
@@ -5,24 +5,24 @@ weight: 250
For development environments, we recommend installing Rancher by running a single Docker container. In this installation scenario, you'll install Docker on a single Linux host, and then install Rancher on your host using a single Docker container.
>**Note:**
> If you want to use an external load balancer, see [Single Node Installation with an External Loadbalancer]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install-external-lb)
>
>**Want to use an external load balancer?**
> See [Single Node Installation with an External Loadbalancer]({{< baseurl >}}/rancher/v2.x/en/installation/single-node-install-external-lb) instead.
## Overview
Installation of Rancher on a single node involves multiple procedures. Review this overview to learn about each procedure you need to complete.
## Installation Outline
1. [Provision Linux Host](#part-1-provision-linux-host)
Installation of Rancher on a single node involves multiple procedures. Review this outline to learn about each procedure you need to complete.
1. [Provision Linux Host](#1-provision-linux-host)
Provision a single Linux host to launch your {{< product >}} Server.
2. [Choose an SSL Option and Install Rancher](#part-2-choose-an-ssl-option-and-install-rancher)
2. [Choose an SSL Option and Install Rancher](#2-choose-an-ssl-option-and-install-rancher)
Choose an SSL option for Rancher communication encryption. After choosing an option, run the command that accompanies it to deploy Rancher.
## Part 1-Provision Linux Host
## 1. Provision Linux Host
Provision a single Linux host to launch your {{< product >}} Server.
@@ -40,47 +40,51 @@ Provision a single Linux host to launch your {{< product >}} Server.
{{< note_server-tags >}}
## Part 2-Choose an SSL Option and Install Rancher
## 2. Choose an SSL Option and Install Rancher
For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.
>**Attention Air Gap Users:**
> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose. Replace `<REGISTRY.DOMAIN.COM:PORT>` with your private registry URL.
>
> Example:
```
<REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest
```
Choose from the following options:
>**Attention Air Gap Users:**
> If you are visiting this page to complete [Air Gap Installation]({{< baseurl >}}/rancher/v2.x/en/installation/air-gap-installation/), you must prepend your private registry URL to the server tag when running the installation command in the option that you choose.
>
> Example: `<registry.yourdomain.com:port>/rancher/rancher:latest`
>
- [Option A—Default Self-Signed Certificate](#option-a-default-self-signed-certificate)
- [Option B—Bring Your Own Certificate: Self-Signed](#option-b-bring-your-own-certificate-self-signed)
- [Option C—Bring Your Own Certificate: Signed by Recognized CA](#option-c-bring-your-own-certificate-signed-by-recognized-ca)
- [Option D—Let's Encrypt Certificates](#option-d-let-s-encrypt-certificate)
- [Option A-Default Self-Signed Certificate](#option-a-default-self-signed-certificate)
- [Option B-Bring Your Own Certificate: Self-Signed](#option-b-bring-your-own-certificate-self-signed)
- [Option C-Bring Your Own Certificate: Signed by Recognized CA](#option-c-bring-your-own-certificate-signed-by-recognized-ca)
- [Option D-Let's Encrypt Certificates](#option-d-let-s-encrypt-certificate)
### Option A—Default Self-Signed Certificate
### Option A-Default Self-Signed Certificate
If you install Rancher without specifying your own certificate, Rancher generates a self-signed certificate that's used for encryption. If you're satisfied with this certificate, there's no need to obtain your own.
If you install Rancher without using your own certificate, Rancher generates a self-signed certificate that's used for encryption. If you're satisfied with this certificate, there's no need to obtain your own.
**To Install Rancher Using the Default Certificate:**
1. From your Linux host, run the Docker command to install Rancher without any additional parameters:
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
rancher/rancher:latest
```
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
rancher/rancher:latest
```
### Option B-Bring Your Own Certificate: Self-Signed
### Option B—Bring Your Own Certificate: Self-Signed
Your Rancher install can use a self-signed certificate that you provide to encrypt communications.
>**Prerequisites:**
>Create a self-signed certificate.
>
>- The certificate files must be in [PEM format](#ssl-faq-troubleshooting).
>- The certificate files must be in base64.
>- Make sure that your certificate file includes all the intermediate certificates in the chain. The order of certificates in this case is your own certificate first, followed by the intermediates. For an example, refer to the [SSL FAQ / Troubleshooting](#ssl-faq-troubleshooting).
>- The certificate files must be in [PEM format](#pem).
>- The certificate files must be encoded in [base64](#base64).
>- In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see [SSL FAQ / Troubleshooting](#cert-order).
**To Install Rancher Using a Self-Signed Cert:**
@@ -89,38 +93,37 @@ Your Rancher install can use a self-signed certificate that you provide to encry
1. After creating your certificate, run the Docker command to install Rancher, pointing toward your certificate files.
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /etc/<CERT_DIRECTORY>/fullchain.pem:/etc/rancher/ssl/cert.pem \
-v /etc/<CERT_DIRECTORY>/privkey.pem:/etc/rancher/ssl/key.pem \
-v /etc/<CERT_DIRECTORY>/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
rancher/rancher:latest
```
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /etc/<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
-v /etc/<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
-v /etc/<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
rancher/rancher:latest
```
### Option C-Bring Your Own Certificate: Signed by Recognized CA
### Option C—Bring Your Own Certificate: Signed by Recognized CA
If you're publishing your app publically, you should ideally be using a certificate signed by a recognized CA.
**Before You Start:**
>**Prerequisites:**
>
>- The certificate files must be in [PEM format](#ssl-faq-troubleshooting).
>- The certificate files must be in base64.
>- Make sure that the container includes your certificate file and the key file. In this case, mounting an additional CA certificate file is unnecessary because the cert is signed by a recognized CA.
>- The certificate files must be in [PEM format](#pem).
>- The certificate files must be encoded in [base64](#base64).
>- Make sure that the container includes your certificate file and the key file. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
**To Install Rancher Using a Certificate Signed by a Recognized CA:**
After obtaining your certificate, run the Docker command to deploy Rancher, pointing toward your certificate files.
1. After obtaining your certificate, run the Docker command to deploy Rancher while pointing toward your certificate files.
```
docker run -d --restart=unless-stopped \
-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:latest
```
```
docker run -d --restart=unless-stopped \
-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:latest
```
By default, Rancher automatically generates self-signed certificates for itself after installation. However, since you've provided your own certificates, you must disable the certificates that Rancher generated for itself.
@@ -132,11 +135,11 @@ By default, Rancher automatically generates self-signed certificates for itself
### Option D-Let's Encrypt Certificate
Rancher supports Let's Encrypt certificates. Let's Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.
Rancher supports Let's Encrypt certificates. Let's Encrypt uses an `http-01 challenge` to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, `rancher.mydomain.com`) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.
>**Prerequisites:**
>
>- Let's Encrypt is an internet service, this cannot be used out of the box on an internal/airgapped network.
>- Let's Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
>- Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (`rancher.mydomain.com` for example).
>- Open port `TCP/80` on your Linux host. The Let's Encrypt http-01 challenge can come from any source IP address, so port `TCP/80` must be open to all IP addresses.
@@ -145,26 +148,32 @@ Rancher supports Let's Encrypt certificates. Let's Encrypt uses an http-01 chall
Run the following commands from your Linux host.
1. Run the Docker command
1. Run the Docker command.
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
rancher/rancher:latest \
--acme-domain rancher.mydomain.com
```
```
docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
rancher/rancher:latest \
--acme-domain rancher.mydomain.com
```
>
>**Remember:** Let's Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see [Let's Encrypt documentation on rate limits](https://letsencrypt.org/docs/rate-limits/).
## What's Next?
Create a backup of your Rancher Server in case of a disaster scenario. For more information, see [Backing Up Your Rancher Server]({{< baseurl >}}/rancher/v2.x/en/installation/after-installation/single-node-backup-and-restoration/#backing-up-your-rancher-server).
You have a couple of options:
## SSL FAQ / Troubleshooting
- Create a backup of your Rancher Server in case of a disaster scenario: [Single Node Backup and Restoration]({{< baseurl >}}/rancher/v2.x/en/installation/backups-and-restoration/single-node-backup-and-restoration/).
- Create a Kubernettes cluster: [Creating a Cluster]({{ <baseurl> }}/rancher/v2.x/en/tasks/clusters/creating-a-cluster/).
<br/>
## FAQ and Troubleshooting
{{< ssl_faq >}}
## Persistent data
## Persistent Data
{{< persistentdata >}}
layouts/shortcodes/persistentdata.html
+1 -1
View File
@@ -1,5 +1,5 @@
<div>
<p>Rancher uses etcd as datastore. When using the Single Node Install, the embedded etcd will be used. The persistent data will be stored in <code>/var/lib/rancher</code> inside the container. You can bind mount a host volume to this location to preserve data on the host it is running on.</p>
<p>Rancher uses <code>etcd</code> as datastore. When using the Single Node Install, the embedded <code>etcd</code> is be used. The persistent data is at the following path in the container: <code>/var/lib/rancher</code>. You can bind mount a host volume to this location to preserve data on the host it is running on.</p>
<p><b>Command</b></p>
layouts/shortcodes/ssl_faq.html
+21 -3
View File
@@ -1,4 +1,4 @@
<h3>How do I know if my certificates are in PEM format?</h3>
<h3 id="pem">How Do I Know if My Certificates are in PEM Format?</h3>
<p>You can recognize the PEM format by the following traits:</p>
<ul>
@@ -17,7 +17,25 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END CERTIFICATE-----
</pre>
<h3>What is the order of certificates if I want to add my intermediate(s)?</h3>
<h3 id="base64">How Can I Encode My PEM Files in base64?</h3>
<p>To encode your certificates in base64:</p>
<ol>
<li>Change directory to where the PEM file resides.</li>
<li>Run one of the following commands. Replace <code>FILENAME</code> with the name of your certificate.
<pre style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4">
# MacOS
cat FILENAME | base64
# Linux
cat FILENAME | base64 -w0
# Windows
certutil -encode FILENAME FILENAME.base64
</pre>
</li>
</ol>
<h3 id="cert-order">What is the Order of Certificates if I Want to Add My Intermediate(s)?</h3>
<p>The order of adding certificates is as follows:</p>
@@ -30,7 +48,7 @@ VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END CERTIFICATE-----
</pre>
<h3>How do I validate my certificate chain?</h3>
<h3 id="validate-cert-chain">How Do I Validate My Vertificate Chain?</h3>
<p>You can validate the certificate chain by using the <code>openssl</code> binary. If the output of the command (see the command example below) ends with <code>Verify return code: 0 (ok)</code>, your certificate chain is valid. The <code>ca.pem</code> file must be the same as you added to the <code>rancher/rancher</code> container. When using a certificate signed by a recognized Certificate Authority, you can omit the <code>-CAfile</code> parameter.</p>