RKE2 Architectural Implementation and Deployment for SUSE Rancher Environments

Published by TechMarmot Editorail Staff on | Category Kubernetes

The landscape of container orchestration has undergone significant shifts toward security-hardened distributions, and RKE2 stands at the forefront of this evolution. Originally conceived with a focus on highly regulated sectors—earning it the moniker "RKE Government"—RKE2 is the next-generation iteration of the Rancher Kubernetes Engine. Unlike its predecessors, RKE2 is designed to be a fully compliant, secure, and lightweight distribution that can function as a standalone cluster or as the foundational layer integrated into a SUSE Rancher management platform. Its architecture is specifically engineered to meet the rigorous demands of modern data centers, offering a streamlined installation process that avoids the complexities of external datastore management while maintaining the high-availability (HA) capabilities required for mission-critical workloads.

At its core, RKE2 is a distribution that bundles the necessary components to run a Kubernetes cluster with minimal external dependencies. By utilizing an embedded container runtime and an integrated etcd datastore, it simplifies the operational burden on DevOps engineers and system administrators. This technical depth is particularly vital when deploying within a Rancher-managed ecosystem, where the interaction between the RKE2 nodes, the Rancher management plane, and the underlying infrastructure must be perfectly synchronized to ensure cluster stability and security.

Core Architectural Principles and Component Lifecycle

The architectural design of RKE2 is centered around a "batteries-included" philosophy, where the runtime image provides almost everything necessary to initialize a functioning Kubernetes node. This approach reduces the attack surface by ensuring that only validated, compatible binaries are present in the environment.

The lifecycle of an RKE2 deployment begins with the extraction of essential binaries from its runtime image. When the service initializes, it flattens the /bin/ directory from the image into a specific data directory. The exact path follows a pattern utilizing a unique identifier: /var/lib/rancher/rke2/data/${RKE2_DATA_KEY}/bin. This isolation ensures that different versions or instances of the runtime do not suffer from binary conflicts.

For the Kubernetes runtime to function as expected, the image must provide several critical components. The primary container runtime is containerd, which acts as the Container Runtime Interface (CRI). To manage the lifecycle of containers effectively, containerd-shim is included to wrap the runc tasks, ensuring that containers continue to run even if the main containerd process restarts. Furthermore, specific shim versions like containerd-shim-runc-v1 and containerd-shim-runc-v2 are provided to maintain compatibility with various container execution standards. The Kubernetes node agent, kubelet, serves as the primary orchestrator on the node, working in tandem with runc, the Open Container Initiative (OCI) runtime.

Beyond the essential Kubernetes primitives, RKE2 provides a suite of operational tooling to facilitate cluster maintenance and inspection:

  • ctr: A low-level tool for containerd maintenance and inspection.
  • crictl: A low-level CRI maintenance and inspection tool.
  • kubectl: The standard Kubernetes command-line interface for cluster management.
  • socat: An essential utility used by containerd for port-forwarding operations.

Once the binaries are extracted, the RKE2 server process takes over the orchestration of static pods. It extracts Helm charts from the image into the /var/lib/rancher/rke2/server/manifests directory. The server process follows a specific sequence to prepare components. For instance, it pulls the kube-apiserver image and initiates a goroutine to wait for the etcd datastore to become available. Only after etcd is healthy will the server write the static pod definition to /var/lib/rancher/rke2/agent/pod-manifests/. A similar, dependent sequence is followed for the kube-controller-manager.

High-Availability Deployment Requirements and Load Balancing

Deploying RKE2 in a High-availability (HA) configuration is the recommended approach for production environments, particularly when used as the backend for SUSE Rancher Prime. An HA setup mitigates the risk of single-point failures by distributing the control plane across multiple nodes.

A robust HA deployment requires a specific infrastructure foundation consisting of three nodes, a dedicated load balancer, and a configured DNS record. The interaction between these components is critical for the stability of the Kubernetes API and the management plane.

The load balancer must be configured with two distinct listeners to accommodate the different communication requirements of the RKE2 cluster:

Listener Target Port Purpose
RKE2 Supervisor 9345 Facilitates communication between RKE2 agents and the server for cluster registration.
Kubernetes API 6443 Provides the standard interface for kubectl and other API-driven tools.

Failure to configure the port 9345 listener will prevent new agent nodes from joining the cluster, while failure to configure port 6443 will render the cluster unreachable for management tasks.

Certificate Management and the TLS-SAN Parameter

Security in RKE2 is enforced through Mutual TLS (mTLS). One of the most common points of failure in new deployments is the occurrence of TLS certificate errors when attempting to access the cluster via a fixed registration address or a specific hostname.

To prevent these errors, the server must be launched with the tls-san (Subject Alternative Name) parameter. This parameter allows the administrator to inject additional hostnames or IP addresses into the server's TLS certificate. This is essential if the cluster is accessed via a DNS name that differs from the node's primary IP. This parameter accepts a list of values, allowing for simultaneous access via both an IP address and a hostname.

Provisioning the RKE2 Server Node

The initialization of the first server node is the most critical step in the cluster lifecycle. This node will host the embedded etcd datastore, which manages the cluster state.

Configuration File Preparation

Before executing the installation script, the directory structure for the configuration must be established. The configuration is managed through a YAML file located at /etc/rancher/rke2/config.yaml.

  1. Create the directory: mkdir -p /etc/rancher/rke2/
  2. Define the configuration in /etc/rancher/rke2/config.yaml.

A standard configuration for a server node should include the following parameters:

  • token: A pre-shared secret used to authenticate agents to the server. If this is not explicitly defined, RKE2 will generate a random token and store it at /var/lib/rancher/rke2/server/node-token.
  • tls-san: A list of hostnames or IPs to include in the TLS certificate.
  • write-kubeconfig-mode: Defines the permissions for the generated rke2.yaml file (e.g., "0644").
  • node-label: Custom labels applied to the node for scheduling purposes.

Example configuration file content:

yaml write-kubeconfig-mode: "0644" token: my-shared-secret tls-san: - my-kubernetes-domain.com - 192.168.1.100 node-label: - "environment=production" - "role=control-plane"

Installation and Execution

Once the configuration is in place, the installation is performed via a shell script. To control specific versions of the Kubernetes distribution, the INSTALL_RKE2_VERSION environment variable should be utilized.

bash curl -sfL https://get.rke2.io | sh - systemctl enable rke2-server.service systemctl start rke2-server.service

After the service starts, the administrator should verify the health of the server using the following command:

bash systemctl status rke2-server

Accessing the Kubernetes API

Once the server is active, the kubectl binary is available within the RKE2 data directory. For ease of use, it is standard practice to create a symbolic link to /usr/local/bin/. Additionally, the KUBECONFIG environment variable must be pointed to the credentials generated by RKE2.

```bash

Create symlink for kubectl

ln -s $(find /var/lib/rancher/rke2/data/ -name kubectl) /usr/local/bin/kubectl

Set the kubeconfig path

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml

Verify node status

kubectl get node
```

For remote management, the /etc/rancher/rke2/rke2.yaml file should be copied to the management workstation. Note that the server IP address within this file must be manually updated to reflect the actual IP or DNS name of the RKE2 server.

Provisioning RKE2 Agent Nodes

The agent nodes are the worker nodes that execute the actual containerized workloads. The installation process for an agent is highly similar to the server installation but requires a specific installation type and a configuration file that points back to the server.

Agent Installation and Configuration

To install an agent, the INSTALL_RKE2_TYPE environment variable must be set to agent. This prevents the installation of the control plane components (like etcd or kube-apiserver) on the worker node.

  1. Execute the agent installation:
    curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE=agent sh -
  2. Create the configuration directory:
    mkdir -p /etc/rancher/rke2/
  3. Configure the agent to find the server:
    echo "server: https://<SERVER_IP>:9345" > /etc/rancher/rke2/config.yaml
  4. Provide the shared token (retrieved from the server node):
    echo "token: <SHARED_TOKEN>" >> /etc/rancher/rke2/config.yaml
  5. Enable and start the service:
    systemctl enable rke2-agent.service
    systemctl start rke2-agent.service

The token used here is vital; it facilitates the establishment of control plane Mutual TLS (mTLS) certificate termination. By using a pre-shared token rather than a "trust on first use" model, RKE2 ensures a much higher security posture during the node joining process.

Integration with Helm and Rancher Management

After the RKE2 cluster is functional, it is often used as the substrate for Rancher. To manage Rancher through the Kubernetes API, Helm is typically required for deploying the necessary charts.

Helm Installation and Repository Configuration

Helm can be installed directly onto the server node to prepare the cluster for Rancher deployment:

bash curl -#L https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Once Helm is installed, the specific repositories required for Rancher and its dependencies (such as cert-manager) must be added:

bash helm repo add rancher-latest https://releases.rancher.com/server-charts/latest helm repo add jetstack https://charts.jetstack.io

This prepares the environment for the deployment of the Rancher management server, which can then be used to provision and manage additional RKE2 clusters across the enterprise through a unified interface.

Analysis of Operational Lifecycle and Maintenance

The lifecycle of an RKE2 deployment is characterized by its alignment with upstream Kubernetes releases. This is a critical feature for organizations that require rapid access to new Kubernetes capabilities and security patches. The RKE2 project aims to release patch updates within one week of the upstream release and minor version updates within 30 days.

From an operational standpoint, the transition from a single-node setup to an HA cluster involves a significant increase in complexity regarding networking (load balancers and DNS) but a massive decrease in operational risk. The use of systemd for service management ensures that RKE2 integrates seamlessly with standard Linux administration workflows, allowing for predictable restarts, logging via journalctl, and standard monitoring of service status.

The security model of RKE2, rooted in mTLS and the "RKE Government" heritage, provides a hardened foundation that is difficult to achieve with standard, non-specialized Kubernetes distributions. By strictly controlling the binaries through the runtime image and ensuring that all component communication is authenticated via shared tokens and TLS SANs, RKE2 provides a clear path for deploying Kubernetes in environments where security is the primary directive.

Sources

  1. SUSE Documentation: RKE2 for Rancher
  2. RKE2 Official Documentation
  3. Rancher Blog: Simple RKE2, Longhorn, and Rancher Install
  4. RKE2 GitHub Repository

Related Posts