This procedure walks you through setting up a 3-node cluster using the Rancher Kubernetes Engine (RKE). The cluster’s sole purpose is running pods for Rancher. The setup is based on:

• Layer 7 Loadbalancer with SSL termination (HTTPS)

In an Kubernetes setup that uses a layer 7 load balancer, the load balancer accepts Rancher client connections over the HTTP protocol (i.e., the application level). This application-level access allows the load balancer to read client requests and then redirect to them to cluster nodes using logic that optimally distributes load.

Kubernetes Rancher install with layer 7 load balancer, depicting SSL termination at load balancer

Installation of Rancher in a high-availability configuration involves multiple procedures. Review this outline to learn about each procedure you need to complete.

• 1. Provision Linux Hosts
• 3. Configure DNS
• 5. Download RKE Config File Template
• 7. Configure Certificates
• 9. Configure Rancher version
• 11. Run RKE

1. Provision Linux Hosts

Provision three Linux hosts according to our .

2. Configure Load Balancer

When using a load balancer in front of Rancher, there’s no need for the container to redirect port communication from port 80 or port 443. By passing the header , this redirect is disabled. This is the expected configuration when terminating SSL externally.

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

• WebSocket connections
• SPDY / HTTP/2 protocols
• Passing / setting the following headers:

Health checks can be executed on the /healthz endpoint of the node, this will return HTTP 200.

We have example configurations for the following load balancers:

• NGINX configuration

3. Configure DNS

Choose a fully qualified domain name (FQDN) that you want to use to access Rancher (e.g., rancher.yourdomain.com).

1. Log into your DNS server a create a DNS A record that points to the IP address of your load balancer.

2. Validate that the DNS A is working correctly. Run the following command from any terminal, replacing HOSTNAME.DOMAIN.COM with your chosen FQDN:

   nslookup HOSTNAME.DOMAIN.COM

   Step Result: Terminal displays output similar to the following:

4. Install RKE

RKE (Rancher Kubernetes Engine) is a fast, versatile Kubernetes installer that you can use to install Kubernetes on your Linux hosts. We will use RKE to setup our cluster and run Rancher.

1. Follow the RKE Install instructions.

2. Confirm that RKE is now executable by running the following command:

   rke --version

RKE uses a YAML config file to install and configure your Kubernetes cluster. There are 2 templates to choose from, depending on the SSL certificate you want to use.

1. Rename the file to rancher-cluster.yml.

6. Configure Nodes

Once you have the rancher-cluster.yml config file template, edit the nodes section to point toward your Linux hosts.

1. Open rancher-cluster.yml in your favorite text editor.

2. Update the nodes section with the information of your Linux hosts.

   For each node in your cluster, update the following placeholders: IP_ADDRESS_X and USER. The specified user should be able to access the Docker socket, you can test this by logging in with the specified user and run docker ps.

   nodes:
       # The IP address or hostname of the node
   - address: IP_ADDRESS_1
       # User that can login to the node and has access to the Docker socket (i.e. can execute `docker ps` on the node)
       # When using RHEL/CentOS, this can't be root due to https://bugzilla.redhat.com/show_bug.cgi?id=1527565
       user: USER
       role: [controlplane,etcd,worker]
       # Path the SSH key that can be used to access to node with the specified user
       ssh_key_path: ~/.ssh/id_rsa
   - address: IP_ADDRESS_2
       user: USER
       role: [controlplane,etcd,worker]
       ssh_key_path: ~/.ssh/id_rsa
   - address: IP_ADDRESS_3
       user: USER
       role: [controlplane,etcd,worker]
       ssh_key_path: ~/.ssh/id_rsa

3. Optional: By default, is configured to take backup snapshots of your data. To disable these snapshots, change the backup directive setting to false, as depicted below.

   services:
     etcd:
       backup: false

7. Configure Certificates

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.

Choose from the following options:

Option A—Bring Your Own Certificate: Self-Signed

In kind: Secret with name: cattle-keys-ingress, replace <BASE64_CA> with the base64 encoded string of the CA Certificate file (usually called ca.pem or ca.crt)

After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

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

If you are using a Certificate Signed By A Recognized Certificate Authority, you don’t need to perform any step in this part.

8. Configure FQDN

There is one reference to <FQDN> in the RKE config file. Replace this reference with the FQDN you chose in .

2. In the kind: Ingress with name: cattle-ingress-http:

   Replace <FQDN> with the FQDN chosen in 3. Configure DNS.

   Step Result: After replacing the values, the file should look like the example below (the base64 encoded strings should be different):

   apiVersion: extensions/v1beta1
     kind: Ingress
     metadata:
       namespace: cattle-system
       name: cattle-ingress-http
       annotations:
         nginx.ingress.kubernetes.io/proxy-connect-timeout: "30"
         nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"   # Max time in seconds for ws to remain shell window open
         nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"   # Max time in seconds for ws to remain shell window open
     spec:
       rules:
         http:
           paths:
           - backend:
               serviceName: cattle-service
               servicePort: 80

3. Save the file and close it.

9. Configure Rancher version

The last reference that needs to be replaced is <RANCHER_VERSION>. This needs to be replaced with a Rancher version which is marked as stable. The latest stable release of Rancher can be found in the GitHub README. Make sure the version is an actual version number, and not a named tag like stable or latest. The example below shows the version configured to v2.0.6.

      spec:
        serviceAccountName: cattle-admin
        - image: rancher/rancher:v2.0.6
          imagePullPolicy: Always

After you close your RKE config file, rancher-cluster.yml, back it up to a secure location. You can use this file again when it’s time to upgrade Rancher.

11. Run RKE

With all configuration in place, use RKE to launch Rancher. You can complete this action by running the rke up command and using the --config parameter to point toward your config file.

1. From your workstation, make sure rancher-cluster.yml and the downloaded rke binary are in the same directory.

2. Open a Terminal instance. Change to the directory that contains your config file and rke.

3. Enter one of the rke up commands listen below.

   rke up --config rancher-cluster.yml

   Step Result: The output should be similar to the snippet below:

12. Back Up Auto-Generated Config File

During installation, RKE automatically generates a config file named kube_config_rancher-cluster.yml in the same directory as the rancher-cluster.yml file. Copy this file and back it up to a safe location. You’ll use this file later when upgrading Rancher Server.

What’s Next?

• Recommended: Review Creating Backups—High Availability Back Up and Restore to learn how to backup your Rancher Server in case of a disaster scenario.
• Create a Kubernetes cluster: .

FAQ and Troubleshooting

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-----

To encode your certificates in base64:

1. Change directory to where the PEM file resides.

2. Run one of the following commands. Replace FILENAME with the name of your certificate.

   # MacOS
   cat FILENAME | base64
   # Linux
   cat FILENAME | base64 -w0
   # Windows
   certutil -encode FILENAME FILENAME.base64

To decode your certificates in base64:

1. Copy the generated base64 string.

2. Run one of the following commands. Replace YOUR_BASE64_STRING with the previously copied base64 string.

   # MacOS
   echo YOUR_BASE64_STRING | base64 -D
   # Linux
   echo YOUR_BASE64_STRING | base64 -d
   # Windows
   certutil -decode FILENAME.base64 FILENAME.verify

The order of adding certificates is as follows:

Command:

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