Skip to main content
Version: v2.5

3. Install Kubernetes (Skip for Docker Installs)

Skip this section if you are installing Rancher on a single node with Docker.

This section describes how to install a Kubernetes cluster according to our best practices for the Rancher server environment. This cluster should be dedicated to run only the Rancher server.

As of Rancher v2.5, Rancher can be installed on any Kubernetes cluster, including hosted Kubernetes providers.

The steps to set up an air-gapped Kubernetes cluster on RKE or K3s are shown below.

In this guide, we are assuming you have created your nodes in your air gapped environment and have a secure Docker private registry on your bastion server.

Installation Outline​

  1. Prepare Images Directory
  2. Create Registry YAML
  3. Install K3s
  4. Save and Start Using the kubeconfig File

1. Prepare Images Directory​

Obtain the images tar file for your architecture from the releases page for the version of K3s you will be running.

Place the tar file in the images directory before starting K3s on each node, for example:

sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/

2. Create Registry YAML​

Create the registries.yaml file at /etc/rancher/k3s/registries.yaml. This will tell K3s the necessary details to connect to your private registry.

The registries.yaml file should look like this before plugging in the necessary information:

---
mirrors:
  customreg:
    endpoint:
      - "https://ip-to-server:5000"
configs:
  customreg:
    auth:
      username: xxxxxx # this is the registry username
      password: xxxxxx # this is the registry password
    tls:
      cert_file: <path to the cert file used in the registry>
      key_file:  <path to the key file used in the registry>
      ca_file: <path to the ca file used in the registry>

Note, at this time only secure registries are supported with K3s (SSL with custom CA).

For more information on private registries configuration file for K3s, refer to the K3s documentation.

3. Install K3s​

Rancher needs to be installed on a supported Kubernetes version. To find out which versions of Kubernetes are supported for your Rancher version, refer to the support maintenance terms.

To specify the K3s version, use the INSTALL_K3S_VERSION environment variable when running the K3s installation script.

Obtain the K3s binary from the releases page, matching the same version used to get the airgap images tar. Also obtain the K3s install script at https://get.k3s.io

Place the binary in /usr/local/bin on each node. Place the install script anywhere on each node, and name it install.sh.

Install K3s on each server:

INSTALL_K3S_SKIP_DOWNLOAD=true ./install.sh

Install K3s on each agent:

INSTALL_K3S_SKIP_DOWNLOAD=true K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken ./install.sh

Note, take care to ensure you replace myserver with the IP or valid DNS of the server and replace mynodetoken with the node-token from the server. The node-token is on the server at /var/lib/rancher/k3s/server/node-token

Note: K3s additionally provides a --resolv-conf flag for kubelets, which may help with configuring DNS in air-gap networks.

4. Save and Start Using the kubeconfig File​

When you installed K3s on each Rancher server node, a kubeconfig file was created on the node at /etc/rancher/k3s/k3s.yaml. This file contains credentials for full access to the cluster, and you should save this file in a secure location.

To use this kubeconfig file,

  1. Install kubectl, a Kubernetes command-line tool.
  2. Copy the file at /etc/rancher/k3s/k3s.yaml and save it to the directory ~/.kube/config on your local machine.
  3. In the kubeconfig file, the server directive is defined as localhost. Configure the server as the DNS of your load balancer, referring to port 6443. (The Kubernetes API server will be reached at port 6443, while the Rancher server will be reached at ports 80 and 443.) Here is an example k3s.yaml:
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: [CERTIFICATE-DATA]
    server: [LOAD-BALANCER-DNS]:6443 # Edit this line
  name: default
contexts:
- context:
    cluster: default
    user: default
  name: default
current-context: default
kind: Config
preferences: {}
users:
- name: default
  user:
    password: [PASSWORD]
    username: admin

Result: You can now use kubectl to manage your K3s cluster. If you have more than one kubeconfig file, you can specify which one you want to use by passing in the path to the file when using kubectl:

kubectl --kubeconfig ~/.kube/config/k3s.yaml get pods --all-namespaces

For more information about the kubeconfig file, refer to the K3s documentation or the official Kubernetes documentation about organizing cluster access using kubeconfig files.

Note on Upgrading​

Upgrading an air-gap environment can be accomplished in the following manner:

  1. Download the new air-gap images (tar file) from the releases page for the version of K3s you will be upgrading to. Place the tar in the /var/lib/rancher/k3s/agent/images/ directory on each node. Delete the old tar file.
  2. Copy and replace the old K3s binary in /usr/local/bin on each node. Copy over the install script at https://get.k3s.io (as it is possible it has changed since the last release). Run the script again just as you had done in the past with the same environment variables.
  3. Restart the K3s service (if not restarted automatically by installer).

Note: The "rancher-cluster" parts of the two latter file names are dependent on how you name the RKE cluster configuration file.

Issues or Errors?​

See the Troubleshooting page.

Next: Install Rancher​