A layer-7 load balancer can be beneficial if you want to centralize your TLS termination in your infrastructure. Layer-7 load balancing also offers the capability for your load balancer to make decisions based on HTTP attributes such as cookies, etc. that a layer-4 load balancer is not able to concern itself with.

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.

Make sure that your node fulfills the general installation requirements.

Installation Outline

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:

Option A-Bring Your Own Certificate: Self-Signed

To Install Rancher Using a Self-Signed Cert:

  1. While running the Docker command to deploy Rancher, point Docker toward your CA certificate file.

Option B-Bring Your Own Certificate: Signed by Recognized CA

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

Prerequisites:

  • The certificate files must be in PEM format.

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 parameter to the container.

  1. Enter the following command.

    1. ```
    2. docker run -d --restart=unless-stopped \
    3. -p 80:80 -p 443:443 \
    4. rancher/rancher:latest --no-cacerts
    5. ```

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

This NGINX configuration is tested on NGINX 1.14.

  • Replace rancher-server with the IP address or hostname of the node running the Rancher container.
  • Replace both occurrences 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.

What’s Next?

  • Recommended: Review Single Node Backup and Restore. Although you don’t have any data you need to back up right now, we recommend creating backups after regular Rancher use.
  • Create a Kubernetes cluster: .

For help troubleshooting certificates, see this section.

Advanced Options

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.

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

If you are visiting this page to complete an , 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:

Rancher uses etcd as a datastore. When Rancher is installed with Docker, 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:

  1. docker run -d --restart=unless-stopped \
  2.   -p 80:80 -p 443:443 \
  3.   -v /opt/rancher:/var/lib/rancher \
  4.   rancher/rancher:latest

As of Rancher v2.5, privileged access is required.

This layer 7 NGINX configuration is tested on NGINX version 1.13 (mainline) and 1.14 (stable).