This section is about how to deploy Rancher for your air gapped environment. An air gapped environment could be where Rancher server will be installed offline, behind a firewall, or behind a proxy. There are tabs for either a high availability (recommended) or a single node installation.

The single node installation is for Rancher users that are wanting to test out Rancher. Instead of running on a Kubernetes cluster, you install the Rancher server component on a single node using a docker run command. Since there is only one node and a single Docker container, if the node goes down, there is no copy of the etcd data available on other nodes and you will lose all the data of your Rancher server. Important: If you install Rancher following the single node installation guide, there is no upgrade path to transition your single node installation to a HA installation. Instead of running the single node installation, you have the option to follow the HA install guide, but only use one node to install Rancher. Afterwards, you can scale up the etcd nodes in your Kubernetes cluster to make it a HA installation.

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.

Environment Variable Key Environment Variable Value Description
CATTLE_SYSTEM_DEFAULT_REGISTRY <REGISTRY.YOURDOMAIN.COM:PORT> Configure Rancher server to always pull from your private registry when provisioning clusters.
CATTLE_SYSTEM_CATALOG bundled Configure Rancher server to use the packaged copy of Helm system charts. The system charts repository contains all the catalog items required for features such as monitoring, logging, alerting and global DNS. These Helm charts are located in GitHub, but since you are in an air gapped environment, using the charts that are bundled within Rancher is much easier than setting up a Git mirror. Available as of v2.3.0

Do you want to…

  • For Rancher prior to v2.3.0, you will need to mirror the system-charts repository to a location in your network that Rancher can reach. Then, after Rancher is installed, you will need to configure Rancher to use that repository. For details, refer to the documentation on setting up the system charts for Rancher prior to v2.3.0.

Choose from the following options:

If you are installing Rancher in a development or testing environment where identity verification isn’t a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

Log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder.

Placeholder Description
<REGISTRY.YOURDOMAIN.COM:PORT> Your private registry URL and port.
<RANCHER_VERSION_TAG> The release tag of the Rancher version that you want to install.
docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they’re connecting to your instance of Rancher.

Prerequisites: From a computer with an internet connection, create a self-signed certificate using OpenSSL or another method of your choice.

  • The certificate files must be in PEM format.
  • 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.

After creating your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Use the -v flag and provide the path to your certificates to mount them in your container.

Placeholder Description
<CERT_DIRECTORY> The path to the directory containing your certificate files.
<FULL_CHAIN.pem> The path to your full certificate chain.
<PRIVATE_KEY.pem> The path to the private key for your certificate.
<CA_CERTS> The path to the certificate authority’s private key.
<REGISTRY.YOURDOMAIN.COM:PORT> Your private registry URL and port.
<RANCHER_VERSION_TAG> The release tag of the Rancher version that you want to install.
docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
    -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
    -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

In development or testing environments where you’re exposing an app publicly, use a certificate signed by a recognized CA so that your user base doesn’t encounter security warnings.

Prerequisite: The certificate files must be in PEM format.

After obtaining your certificate, log into your Linux host, and then run the installation command below. When entering the command, use the table below to replace each placeholder. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.

Placeholder Description
<CERT_DIRECTORY> The path to the directory containing your certificate files.
<FULL_CHAIN.pem> The path to your full certificate chain.
<PRIVATE_KEY.pem> The path to the private key for your certificate.
<REGISTRY.YOURDOMAIN.COM:PORT> Your private registry URL and port.
<RANCHER_VERSION_TAG> The release tag of the Rancher version that you want to install.

Note: Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.

docker run -d --restart=unless-stopped \
    -p 80:80 -p 443:443 \
    --no-cacerts \
    -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
    -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
    -e CATTLE_SYSTEM_DEFAULT_REGISTRY=<REGISTRY.YOURDOMAIN.COM:PORT> \ # Set a default private registry to be used in Rancher
    -e CATTLE_SYSTEM_CATALOG=bundled \ #Available as of v2.3.0, use the packaged Rancher system charts
    <REGISTRY.YOURDOMAIN.COM:PORT>/rancher/rancher:<RANCHER_VERSION_TAG>

If you are installing Rancher v2.3.0+, the installation is complete.

If you are installing Rancher versions prior to v2.3.0, you will not be able to use the packaged system charts. Since the Rancher system charts are hosted in Github, an air gapped installation will not be able to access these charts. Therefore, you must configure the Rancher system charts.