Skip to content

K3s

Lightweight, fully conformant Kubernetes distribution that ships as a single binary with containerd and a set of packaged add-ons, and has a documented air-gap installation.

ID k3s
Layer orchestration
Version v1.37.2+k3s1
Tiers T1, T2
Requires nothing
License Apache-2.0
Evidence docs
Last verified 2026-11-22
  • A small single-node or few-node Kubernetes cluster is wanted: the introduction page lists edge, air-gapped environments and embedded Kubernetes among its uses and describes a single binary (under 100 MB) with SQLite as the default datastore and etcd, MySQL and PostgreSQL as alternatives.
  • A documented air-gap route with files is needed: the air-gap page gives three ways to load images (private registry, manual copy of the archive, embedded registry mirror) and a script install with INSTALL_K3S_SKIP_DOWNLOAD.
  • Compliance hardening is the main goal from day one: the RKE2 introduction describes RKE2 as focusing on security and compliance for the U.S. Federal Government sector, with defaults that pass the CIS Kubernetes Benchmark with minimal operator intervention and FIPS 140-2 support; K3s has its own security pages, which this entry did not read, so this is a pointer to RKE2, not a finding about K3s.
  • GPUs: the Advanced page says NVIDIA GPUs need the NVIDIA Container Runtime on the node: install the nvidia-container package repository (https://nvidia.github.io/libnvidia-container/), install the nvidia container runtime packages and the NVIDIA drivers (the page’s example installs nvidia-container-runtime, cuda-drivers-fabricmanager-515 and nvidia-headless-515-server with apt), then install or restart K3s; K3s adds the NVIDIA runtimes to its containerd configuration when it finds the executables, and Pods must set runtimeClassName: nvidia unless –default-runtime is changed. The page adds that the runtime is often used with the NVIDIA Device Plugin (a Kubernetes add-on from the NVIDIA k8s-device-plugin project). The container toolkit and runtime packages, the drivers, the device plugin and their images are outside the catalog; the page names no AMD or Intel GPU procedure and no offline procedure for these parts.
  • An external SQL datastore is optional: the datastore page names MySQL (certified against 8.0 and 8.4) and PostgreSQL (15.12, 16.7 and 17.3) as options next to embedded etcd and SQLite. PostgreSQL is therefore not listed in requires.
  • The k3s-selinux RPM and the operating system packages it needs must be staged by the operator on SELinux-enabled air-gapped nodes (air-gap page); they are outside the catalog.
  • No paid edition or license check was found in the K3s documentation read.

No container images.

Packages:

  • k3s
  • k3s-airgap-images-amd64.tar.zst
  • install.sh

What the software tries to fetch while it runs, and how to stage it instead.

  • Container images not inside the air-gap image archive: with the private-registry route, the images of the archive are pushed to an OCI registry and registries.yaml is written on each node; containerd tries a default endpoint for every registry as a last resort (https://index.docker.io/v2 for docker.io), and the documentation says –disable-default-registry-endpoint stops that fallback, which it describes as wanted in a true air-gapped environment (Private Registry Configuration page).
  • Install script downloads: install.sh downloads the K3s binary and, on hosts with SELinux, looks for the k3s-selinux RPM unless the files are staged; the air-gap page sets INSTALL_K3S_SKIP_DOWNLOAD=true to run it with the staged binary, and the environment variable reference gives INSTALL_K3S_SKIP_SELINUX_RPM=true to skip the automatic RPM installation. Without INSTALL_K3S_SKIP_DOWNLOAD, the script (source at the release tag) resolves the version through https://update.k3s.io/v1-release/channels (INSTALL_K3S_CHANNEL_URL) and downloads from https://github.com/k3s-io/k3s/releases/download (INSTALL_K3S_ARTIFACT_URL).
  • k3s-selinux RPM: the air-gap page says it must be installed manually on air-gapped nodes with SELinux enabled and that it needs container-selinux, policycoreutils and selinux-policy from the operating system; the exact file names are in airgap.notes. The operating system’s packages are outside the catalog.
  • Automated upgrades (optional, not part of the first installation): the air-gap page says the images rancher/k3s-upgrade (tag of the K3s release with + replaced by -), rancher/system-upgrade-controller and rancher/kubectl must be in the private registry, with the last two read from the system-upgrade-controller manifest; the page’s version numbers are examples and this entry names no tags for them. Not listed in images because the page names no tag for the K3s version of this entry for the two helper images.

No license server is contacted.

What How to turn it off
Traefik version check in the packaged ingress controller (enabled by default, disabled with –disable=traefik). K3s deploys Traefik from the HelmChart in manifests/traefik.yaml at the release tag, which uses the chart traefik-41.6.101+up41.6.1 (chart file from the k3s-charts repository) and sets only the system default registry and the image, no global Traefik option. The chart’s values set global.checkNewVersion: true and global.sendAnonymousUsage: false (read from the chart file). Traefik’s documentation (v3.7.15) says checkNewVersion is enabled by default and that Traefik then periodically contacts update.traefik.io, sharing the running Traefik version and the public IP address of the instance, and states that the collected IP addresses are also used for marketing purposes; sendAnonymousUsage (a daily report of version and an anonymized static configuration) is opt-in and off here. The K3s documentation read does not mention either setting. Create a HelmChartConfig named traefik in the kube-system namespace in /var/lib/rancher/k3s/server/manifests/traefik-config.yaml with valuesContent global: checkNewVersion: false (the Helm add-ons page shows this mechanism for the packaged Traefik, with other values; the key global.checkNewVersion is from the chart’s values and Traefik’s data-collection page), or start K3s with –disable=traefik (packaged components page), which removes the ingress controller.

Offline behavior is documented but not verified: the entry author did not run K3s. The files in airgap.packages are for linux/amd64 (x86_64) hosts: k3s is the binary (place it in /usr/local/bin and make it executable, same version as the image archive), k3s-airgap-images-amd64.tar.zst is the image archive (copy it to /var/lib/rancher/k3s/agent/images/ on every node, or docker image load it and push the images to a private registry), and install.sh is the script from https://get.k3s.io (run with INSTALL_K3S_SKIP_DOWNLOAD=true). The images inside the archive are not listed separately. Files for other architectures, named by the release v1.37.2+k3s1 (the requirements page lists x86_64, armhf and arm64/aarch64): arm64: k3s-arm64 and k3s-airgap-images-arm64.tar.zst; armhf: k3s-armhf and k3s-airgap-images-arm.tar.zst. The release also publishes the image archives as .tar and .tar.gz for each of amd64, arm and arm64 (the air-gap page names the .tar.zst file), the checksum files sha256sum-amd64.txt, sha256sum-arm64.txt and sha256sum-arm.txt, and k3s-images.txt; the air-gap page names none of these, so they are not listed in packages, and the page names no release file for the install script (it points to get.k3s.io, and install.sh is also in the repository at the release tag). Other route named by the documentation: embedded registry mirror (Spegel), disabled by default, enabled with –embedded-registry on the servers plus a mirrors entry in registries.yaml; all nodes then host a registry on port 6443 and use port 5001 for the peer-to-peer network, and images imported from the air-gap archive are shared between nodes. SELinux (air-gap page and Advanced page): on air-gapped nodes with SELinux enabled the k3s-selinux policy RPM must be installed by hand before the install script runs; it is distribution-specific and is not in packages. The air-gap page points to the releases of k3s-io/k3s-selinux (releases/latest, which on 2026-11-22 is the tag v1.6.latest.1, published 2024-09-16; the tag v1.6.stable.1 has the same file names; later tags named v1.7.testing.N exist and the page does not point to them): the el8 file is k3s-selinux-1.6-1.el8.noarch.rpm and the el9 file is k3s-selinux-1.6-1.el9.noarch.rpm (the release also has el7, coreos, sle and slemicro files, each with a .src.rpm). The Advanced page says the install script fails where the policy is missing unless INSTALL_K3S_SELINUX_WARN=true makes it log a warning. The script at the release tag (setup_selinux) is narrower: the whole check is skipped when /usr/share/selinux does not exist, when INSTALL_K3S_SKIP_SELINUX_RPM=true, and when INSTALL_K3S_SKIP_DOWNLOAD is true or selinux, so the air-gap page’s command (INSTALL_K3S_SKIP_DOWNLOAD=true) does not run it and does not fail on a missing policy, although the page still requires the policy on SELinux-enabled nodes. When the check runs, the error Failed to find the k3s-selinux policy is fatal, whatever the SELinux mode, unless INSTALL_K3S_SELINUX_WARN=true makes it a warning (on hosts with /usr/sbin/transactional-update or the coreos target it only warns to reboot); only the error Failed to apply container_runtime_exec_t to the K3s binary is gated on SELINUX=enforcing in /etc/selinux/config, and it is fatal under the same condition. The Advanced page also says K3s has to be started with –selinux (or K3S_SELINUX=true) to use SELinux enforcement. Image archives are imported on every start; a .cache.json file in the images directory limits the import to changed archives (page warns that pruned images are then not restored). Nodes without a default route need a default route (a dummy interface is enough). Defaults that matter for the design: the servers are schedulable; the datastore is SQLite by default with embedded etcd, MySQL, MariaDB and PostgreSQL as documented alternatives. K3s deploys packaged add-ons (CoreDNS, Traefik, local-storage, metrics-server and the servicelb controller) from manifests; –disable=traefik (or a traefik.yaml.skip file) turns Traefik off; Traefik’s own version check and usage reporting settings in the packaged configuration are described in telemetry. Outbound calls: no K3s telemetry, analytics, usage statistics, phone-home or update-check documentation was found on 2026-11-22 (searched the pages of k3s-io/docs and the repository at the release tag; a search is not proof of absence); vet before adoption. The documented network calls of the installation are the version and download requests of install.sh described in runtime_downloads, which the air-gap procedure avoids, and the Traefik version check described in telemetry.

All values were read on 2026-11-21 from the pages in sources. The version v1.37.2+k3s1 is the latest GitHub release (published 2026-11-03, not a prerelease) and is also the version of both the stable and the latest channel at update.k3s.io on that date; the file names under airgap.packages are the release assets listed by the GitHub API for that release. The k3s-io/docs repository has no tags, so its pages are cited at commit 8b33d6f4106826376a9784bc21d0fbba8dccbc69 (the head of its default branch on 2026-11-21, which is documentation of the current release line; its commands use the example version v1.33.3+k3s1, while this entry names the files of v1.37.2+k3s1). K3s was not run by the entry author: the offline behavior is documented but not verified in a disconnected network.

Sources:

Source of this page: skills/airgap-architect/catalog/components/k3s.toml.