1. Set up Infrastructure and Private Registry

This section describes how to:

  • Provision the underlying infrastructure for a Rancher management server in an air-gapped environment.

  • Setup the private container image registry required to distribute images to your Rancher nodes.

Although Rancher can be installed on any CNCF-certified Kubernetes cluster, the specific infrastructure requirements depend on whether you are deploying SUSE Rancher Prime on SUSE® Rancher Prime: K3s or SUSE® Rancher Prime: RKE2. For more information on the available installation options, refer to Installing SUSE Rancher Prime.

The following tabs provide infrastructure recommendations and tutorials for K3s and RKE2.

  • K3s

  • RKE2

To install the Rancher management server on a high-availability K3s cluster, set up the following infrastructure:

  • Linux nodes: Two Linux nodes (when using an external datastore) or three Linux nodes (when using embedded etcd), typically virtual machines hosted by your infrastructure provider.

  • Datastore: Stores cluster data using either an external database (PostgreSQL, MySQL, or etcd) or an embedded etcd datastore.

  • Load balancer: Directs incoming traffic across your nodes.

  • DNS record: Maps an FQDN to the load balancer. Downstream Kubernetes clusters must be able to reach this Rancher server URL.

  • Private image registry: Distributes container images to your nodes.

Node Requirements

Node requirements for a high-availability K3s cluster depend on your chosen datastore architecture:

  • External datastore: Requires a minimum of two control plane nodes. Because state and quorum are managed by your external database (such as PostgreSQL or MySQL), the K3s control plane nodes remain stateless.

  • Embedded etcd: Requires a minimum of three control plane nodes to maintain etcd quorum.

In an embedded etcd configuration, Rancher server data is stored in etcd across all three nodes. An etcd cluster requires an odd number of nodes to maintain quorum and elect a leader. If etcd loses quorum, a split-brain condition occurs, which can require restoring the cluster from a backup. In a three-node setup, if one node fails, the remaining two nodes retain a majority and continue operating without service disruption

1. Set up Linux Nodes

These hosts are disconnected from the internet, but must be able to access your private registry.

Ensure that your nodes meet the general installation requirements for operating systems, container runtimes, hardware, and networking.

For an example of setting up Linux nodes as Amazon EC2 instances, see Setting Up Nodes in Amazon EC2.

2. Set up External Datastore

K3s supports datastores other than etcd, providing flexibility to select a database that fits your environment.

For a high-availability K3s installation using an external datastore, set up one of the following databases:

  • PostgreSQL (certified for versions 10.7 and 11.5)

  • MySQL (certified for version 5.7)

  • etcd (certified for version 3.3.15)

During K3s installation, pass the database connection parameters to K3s.

For an example of setting up a MySQL database on Amazon RDS, see MySQL Database in Amazon RDS.

For a complete list of datastore configuration options, see the SUSE® Rancher Prime: K3s Datastore Documentation.

3. Set up the Load Balancer

Set up a load balancer to direct traffic to the Rancher replicas on both nodes. This prevents a single node outage from interrupting communication with the Rancher management server.

When you set up Kubernetes, K3s deploys a Traefik Ingress controller. This controller listens on ports 80 and 443 of the worker nodes and handles traffic destined for specific hostnames.

When you install Rancher, the system creates an Ingress resource. This resource instructs the Traefik Ingress controller to listen for traffic destined for the Rancher hostname. When the Traefik Ingress controller receives traffic for the Rancher hostname, it forwards the traffic to the running Rancher pods in the cluster.

Determine whether to use a Layer 4 or Layer 7 load balancer for your deployment:

  • Layer 4 load balancer: Forwards raw TCP traffic to your nodes. Layer 4 load balancing is recommended. Configure the load balancer to forward traffic to ports TCP/80 and TCP/443 on the Rancher management cluster nodes. The cluster Ingress controller redirects HTTP traffic to HTTPS, terminates TLS on port TCP/443, and forwards HTTP traffic on port TCP/80 to the Rancher Ingress pod.

  • Layer 7 load balancer: Provides advanced routing features, such as centralizing TLS termination at the load balancer or making routing decisions based on HTTP attributes. If terminating TLS at a Layer 7 load balancer, use the --set tls=external option during Rancher installation. For details, see Rancher Helm Chart Options.

For load balancer configuration examples, see:

Do not use the local cluster load balancer or Ingress for applications other than Rancher. Sharing this Ingress with other workloads can cause WebSocket errors during configuration reloads. Dedicate the local cluster exclusively to Rancher.

4. Set up the DNS Record

After setting up the load balancer, create a DNS record to route traffic to it. Depending on your environment, create either a record pointing to the load balancer IP address or a CNAME record pointing to the load balancer hostname. Ensure that this record matches the exact hostname intended for the Rancher server.

Specify this hostname during Rancher installation. This hostname cannot be changed after installation.

For instructions on routing domain traffic to an Amazon ELB load balancer, see the AWS Route 53 Documentation.

5. Set up a Private Image Registry

Rancher supports air-gapped installations using a private registry. Ensure that you have a private registry or an alternative mechanism to distribute container images to your nodes.

During K3s cluster setup, create a url-k3s-private-registry-configuration[private registry configuration file] containing your registry configuration details.

To deploy a new private registry, see the documentation for your container runtime:

To install the Rancher management server on a high-availability RKE2 cluster, set up the following infrastructure:

  • Linux nodes: Three Linux nodes, typically virtual machines hosted by an infrastructure provider such as Amazon EC2, Google Compute Engine, or VMware vSphere.

  • Load balancer: Directs incoming traffic across all three nodes.

  • DNS record: Maps an FQDN to the load balancer. Downstream Kubernetes clusters must be able to reach this Rancher server URL.

  • Private image registry: Distributes container images to your nodes.

Deploy all nodes in the same region or data center. Nodes can be distributed across separate availability zones within that region.

Node Requirements

In a high-availability RKE2 cluster, Rancher server data is stored in etcd across all three nodes.

An etcd cluster requires an odd number of nodes to maintain quorum and elect a leader. If etcd loses quorum, a split-brain condition occurs, which can require restoring the cluster from a backup. In a three-node setup, if one node fails, the remaining two nodes retain a majority and continue operating without service disruption.

1. Set up Linux Nodes

These nodes are disconnected from the Internet, but must be able to access your private registry.

Ensure that your nodes meet the general installation requirements for operating systems, container runtimes, hardware, and networking.

For an example of setting up Linux nodes as Amazon EC2 instances, see Setting Up Nodes in Amazon EC2.

2. Set up the Load Balancer

Set up a load balancer to distribute traffic to the Rancher replicas across all three nodes. This prevents a single node outage from interrupting access to the Rancher management server.

During cluster setup, RKE2 deploys an NGINX Ingress controller that listens on ports 80 and 443 of the worker nodes for incoming host-based traffic.

When you install Rancher, the installer creates an Ingress resource instructing the NGINX Ingress controller to route requests for the Rancher hostname directly to the Rancher pods in the cluster.

Determine whether to use a Layer 4 or Layer 7 load balancer for your deployment:

  • Layer 4 load balancer: Forwards raw TCP traffic to your nodes. Layer 4 load balancing is recommended. Configure the load balancer to forward traffic to ports TCP/80 and TCP/443 on the Rancher management cluster nodes. The cluster Ingress controller redirects HTTP traffic to HTTPS, terminates TLS on port TCP/443, and forwards HTTP traffic on port TCP/80 to the Rancher Ingress pod.

  • Layer 7 load balancer: Provides advanced routing features, such as centralizing TLS termination at the load balancer or making routing decisions based on HTTP attributes. If terminating TLS at a Layer 7 load balancer, use the --set tls=external option during Rancher installation. For details, see Rancher Helm Chart Options.

For load balancer configuration examples, see:

Do not use the local cluster load balancer or Ingress for applications other than Rancher. Sharing this Ingress with other workloads can cause WebSocket errors during configuration reloads. Dedicate the local cluster exclusively to Rancher.

3. Set up the DNS Record

After setting up the load balancer, create a DNS record to route traffic to it. Depending on your environment, create either an A record pointing to the load balancer IP address or a CNAME record pointing to the load balancer hostname. Ensure that this record matches the exact hostname intended for the Rancher server.

Specify this hostname during Rancher installation. This hostname cannot be changed after installation.

For instructions on routing domain traffic to an Amazon ELB load balancer, see the AWS Route 53 Documentation.

4. Set up a Private Image Registry

Rancher supports air-gapped installations using a private registry. Ensure that you have a private registry or an alternative mechanism to distribute container images to your nodes.

During RKE2 cluster setup, create a url-rke2-private-registry-configuration[private registry configuration file] containing your registry details.

To deploy a new private registry, see the documentation for your container runtime: