For development and testing environments that have a special requirement to terminate TLS/SSL at a load balancer instead of your Rancher Server container, deploy Rancher and configure a load balancer to work with it it conjunction. This install procedure walks you through deployment of Rancher using a single container, and then provides a sample configuration for a layer 7 Nginx load balancer.

Want to skip the external load balancer? See Single Node Installation instead.

Installation Outline

1. Provision Linux Host

Provision a single Linux host according to our Requirements to launch your Rancher Server.

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.

Do you want to…

  • Complete an Air Gap Installation?
  • Record all transactions with the Rancher API?

See Advanced Options below before continuing.

Choose from the following options:

If you elect to use a self-signed certificate to encrypt communication, you must install the certificate on your load balancer (which you’ll do later) and your Rancher container. Run the Docker command to deploy Rancher, pointing it toward your certificate.

Prerequisites: Create a self-signed certificate.

To Install Rancher Using a Self-Signed Cert:

  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
    

If your cluster is public facing, it’s best to use a certificate signed by a recognized CA.

Prerequisites:

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. We do have to make sure there is no default CA certificate generated and stored, you can do this by passing the --no-cacerts parameter to the container.

  1. Enter the following command.

    docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    rancher/rancher:latest --no-cacerts
    

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.

The load balancer or proxy has to be configured to support the following:

  • WebSocket connections
  • 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.

    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 layer 7 Nginx configuration is tested on Nginx version 1.13 (mainline) and 1.14 (stable).

Note: This Nginx configuration is only an example and may not suit your environment. For complete documentation, see NGINX Load Balancing - TCP and UDP Load Balancer.

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;
        proxy_buffering off;
    }
}

server {
    listen 80;
    server_name rancher.yourdomain.com;
    return 301 https://$server_name$request_uri;
}


What’s Next?


FAQ and Troubleshooting

How Do I Know if My Certificates are in PEM Format?

You can recognize the PEM format by the following traits:

  • The file begins with the following header:
    -----BEGIN CERTIFICATE-----
  • The header is followed by a long string of characters. Like, really long.
  • The file ends with a footer:
    -----END CERTIFICATE-----

PEM Certificate Example:

----BEGIN CERTIFICATE-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END CERTIFICATE-----

PEM Certificate Key Example:

-----BEGIN RSA PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END RSA PRIVATE KEY-----

If your key looks like the example below, see How Can I Convert My Certificate Key From PKCS8 to PKCS1?

-----BEGIN PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END PRIVATE KEY-----

How Can I Convert My Certificate Key From PKCS8 to PKCS1?

If you are using a PKCS8 certificate key file, Rancher will log the following line:

ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true})

To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below:

openssl rsa -in key.pem -out convertedkey.pem

You can now use convertedkey.pem as certificate key file for Rancher.

What is the Order of Certificates if I Want to Add My Intermediate(s)?

The order of adding certificates is as follows:

-----BEGIN CERTIFICATE-----
%YOUR_CERTIFICATE%
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
%YOUR_INTERMEDIATE_CERTIFICATE%
-----END CERTIFICATE-----

How Do I Validate My Certificate Chain?

You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. The ca.pem file must be the same as you added to the rancher/rancher container. When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

Command:
openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
...
    Verify return code: 0 (ok)

Advanced Options

API Auditing

If you want to record all transactions with the Rancher API, enable the API Auditing feature by adding the flags below into your install command.

-e AUDIT_LEVEL=1 \
-e AUDIT_LOG_PATH=/var/log/auditlog/rancher-api-audit.log \
-e AUDIT_LOG_MAXAGE=20 \
-e AUDIT_LOG_MAXBACKUP=20 \
-e AUDIT_LOG_MAXSIZE=100 \

Air Gap

If you are visiting this page to complete an Air Gap Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

Example:

 <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

Persistent Data

Rancher uses etcd as datastore. When using the Single Node Install, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher. You can bind mount a host volume to this location to preserve data on the host it is running on.

Command:
docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /host/rancher:/var/lib/rancher \
  rancher/rancher:latest