The integration of Rancher K3s with Docker represents a pivotal shift in how Kubernetes is deployed for local development, edge computing, and air-gapped enterprise environments. K3s, engineered by Rancher and SUSE, is a highly optimized, lightweight Kubernetes distribution that reduces the resource footprint of a standard cluster while maintaining full Kubernetes API compatibility. When deployed via Docker, K3s transitions from a system-level service to a containerized application, allowing developers to spin up complete server and agent nodes within isolated containers. This architecture eliminates the need for complex virtual machine overhead, enabling a rapid iteration cycle for microservices development. The synergy between K3s and Docker is further extended through the use of specialized images that support multiple CPU architectures, ensuring that the cluster can be deployed across a diverse hardware landscape, from x86 servers to ARM-based edge devices.
Docker-Based K3s Server Implementation
Running K3s within a Docker container is a primary method for local development and testing. This approach leverages the rancher/k3s image to encapsulate the entire Kubernetes control plane and worker functionality. To initiate a K3s server using the Docker engine, a specific set of flags and configurations must be applied to ensure the container has the necessary privileges to manage network interfaces and mount the host's filesystem.
The execution of a K3s server via Docker is performed using the following command:
sudo docker run --privileged --name k3s-server-1 --hostname k3s-server-1 -p 6443:6443 -d rancher/k3s:v1.36.1-k3s1 server
This command structure has several critical components that impact the stability and accessibility of the cluster:
- The
--privilegedflag is mandatory. Without this, the K3s container cannot perform the low-level system operations required to manage the Kubernetes runtime, such as manipulating iptables or managing network namespaces. - The
-p 6443:6443mapping exposes the Kubernetes API server to the host machine. This allows external tools likekubectlto communicate with the cluster. - The image tag
rancher/k3s:v1.36.1-k3s1specifies the exact version. It is critical to use a valid version tag because thelatesttag is not maintained by the developers, which could lead to unpredictable behavior or version drift. - The
serverargument at the end of the command tells the container to initialize as a K3s server rather than an agent.
Once the K3s server is operational within the container, the administrator must extract the administrative configuration to manage the cluster from the host OS. This is achieved by copying the k3s.yaml file from the container's internal filesystem to the local .kube directory:
sudo docker cp k3s-server-1:/etc/rancher/k3s/k3s.yaml ~/.kube/config
This operation allows the user to leverage the standard kubectl toolset on the host machine to interact with the containerized K3s API.
K3s Image Specifications and Architecture Support
The rancher/k3s image is designed for broad compatibility, supporting various hardware architectures. This is essential for edge computing, where ARM-based devices are common. The image size varies depending on the architecture, with ARM versions generally being smaller than the x86 counterparts.
The following table details the specifications for the v1.36.1-k3s1 image:
| Architecture | Image Tag | Size | Digest |
|---|---|---|---|
| linux/amd64 | rancher/k3s:v1.36.1-k3s1 | 82.24 MB | 97ee2717a542 |
| linux/arm/v7 | rancher/k3s:v1.36.1-k3s1 | 76.93 MB | 646e83f6384f |
| linux/arm64 | rancher/k3s:v1.36.1-k3s1 | 74.98 MB | 5ce2a98f009b |
Beyond the latest release, several previous versions are available to ensure stability for legacy environments. Version v1.33.12-k3s1 and v1.34.8-k3s1 both maintain a consistent size profile, typically around 80 MB for amd64. The use of "rc" (Release Candidate) tags, such as v1.36.1-rc1-k3s1, allows power users to test new features before they are finalized in a stable release.
A critical constraint in the tagging convention is that Docker images do not allow the use of the + sign in tags. Therefore, K3s utilizes a hyphen - in its version tags to ensure compatibility with the Docker Hub registry.
Air-Gapped Installation Framework
In high-security environments where network access is restricted, an air-gapped installation is required. This process involves manually transporting the necessary images and binaries into the isolated environment. The goal is to create a dedicated Kubernetes cluster that runs only the Rancher server, adhering to best practices for environment isolation.
The installation process for an air-gapped K3s cluster follows a strict sequence of operations:
- Prepare Images Directory
The administrator must obtain the images tar file for the specific architecture (amd64, arm64, etc.) from the K3s releases page. These images must be placed in a specific directory on each node before the K3s service is started.
The following commands are used to prepare the directory and move the archive:
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp ./k3s-airgap-images-$ARCH.tar /var/lib/rancher/k3s/agent/images/
By placing the images in /var/lib/rancher/k3s/agent/images/, K3s can load the necessary container images locally without attempting to reach out to a public registry.
- Create Registry YAML
To manage how K3s pulls images in an air-gapped environment, aregistries.yamlfile must be created. This file is located at/etc/rancher/k3s/registries.yaml. This configuration is vital because it allows the cluster to point to a secure Docker private registry hosted on a bastion server, ensuring that image updates can be managed internally.
Docker Runtime Integration and Installation
K3s can be configured to use Docker as its container runtime instead of the default containerd. This is particularly useful for users who already have an existing Docker-based toolchain or for those who need to monitor containers using docker ps.
To install Docker using the Rancher-provided scripts, the following command is executed:
curl https://releases.rancher.com/install-docker/20.10.sh | sh -
Once Docker is installed, K3s must be installed with the --docker flag to ensure it integrates with the Docker socket. The installation is performed via the following command:
curl -sfL https://get.k3s.io | sh -s - --docker -
After installation, the administrator can verify the cluster's health by listing the pods across all namespaces:
sudo k3s kubectl get pods --all-namespaces
The output of this command typically reveals the core system components:
local-path-provisioner: Manages local storage for the cluster.metrics-server: Collects resource usage data.coredns: Handles DNS resolution within the cluster.traefik: Serves as the default ingress controller.
To verify that Docker is indeed managing the containers, the docker ps command can be used:
sudo docker ps
This will show containers such as k8s_lb-port-443_svclb-traefik-jbmvl_kube-system, which indicate that the K3s service is successfully utilizing the Docker runtime for its load balancers and pods.
SELinux Configuration for K3s
When deploying K3s on distributions that enable SELinux by default, such as CentOS, the system must be configured with the correct SELinux policies. Failure to do so can lead to permission errors where the K3s process is blocked from accessing critical host resources.
K3s provides two primary paths for SELinux management:
- Automatic Installation: The standard installation script automatically attempts to install the SELinux RPM from the Rancher RPM repository. This is the preferred method for connected systems.
- Manual Installation: In air-gapped environments, the automatic installation will fail, requiring the administrator to manually provide the SELinux policy packages.
Maintenance and Upgrade Procedures
Maintaining a K3s cluster requires a structured approach to upgrading binaries and images, especially in air-gapped environments. The upgrade process ensures that the cluster remains secure and benefits from the latest feature sets.
The upgrade workflow consists of the following steps:
- Delete the legacy images tar file to clear space.
- Replace the K3s binary located in
/usr/local/binon every node in the cluster. - Update the install script by downloading the latest version from
https://get.k3s.io. - Re-run the install script using the same environment variables used during the initial setup.
- Restart the K3s service to apply the changes, although the installer often handles this automatically.
Comparative Analysis of K3s and RKE2 Configuration
While K3s is designed for lightness, RKE2 (Rancher Kubernetes Engine 2) is designed for security and government-grade environments. Both can be deployed in air-gapped scenarios, but their configuration files differ.
RKE2 requires a config.yaml file at /etc/rancher/rke2/config.yaml. For a primary server, the configuration must include a shared secret token and a TLS SAN (Subject Alternative Name) for the load balancer:
token: my-shared-secret
tls-san:
- loadbalancer-dns-domain.com
For subsequent servers in the cluster, the configuration must point back to the first server:
server: https://ip-of-first-server:9345
token: my-shared-secret
tls-san:
- loadbalancer-dns-domain.com
A distinct advantage of RKE2 in air-gapped networks is the resolv-conf option for kubelets, which provides more granular control over DNS resolution than the standard K3s configuration.
Detailed Analysis of K3s Dockerization
The shift toward containerizing the Kubernetes control plane via Docker provides a strategic advantage in environment parity. By utilizing the rancher/k3s image, the underlying host operating system is decoupled from the Kubernetes version. This allows for the coexistence of multiple K3s versions on a single host, provided that the ports (such as 6443) do not conflict.
The impact of this architecture is most evident in the resource consumption. With images ranging from 74.98 MB to 82.24 MB, K3s is significantly smaller than standard Kubernetes. This efficiency is achieved by stripping out unnecessary cloud-provider-specific code and consolidating the components into a single binary.
From a DevOps perspective, the ability to copy the k3s.yaml config file directly from a container allows for seamless integration with CI/CD pipelines. A pipeline can spin up a K3s Docker container, deploy a set of microservices, run integration tests, and then destroy the container, ensuring that the testing environment is clean and reproducible every time.
The limitation of this approach is the reliance on the --privileged flag. This introduces a security risk, as the container has nearly the same access to the host kernel as a root user. In production environments, this is why the air-gapped binary installation is often preferred over the Docker-run method, as it allows for more precise control over system permissions and SELinux policies.