skills.rest
dydx
dydxCOMMUNITY
Explore all skills by this author →
GitHub

rke2-airgap-registries

Configure air-gapped RKE2 installs, private registries, and containerd image imports.

2|Updated Jul 22, 2026
Search Tags:#kubernetes#containerd#private registry#air-gap#rke2#registries.yaml#spegel
One-click install
npx skills add https://github.com/dydx/rke2-skills --skill rke2-airgap-registries-dydx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: rke2-airgap-registries
Source: https://github.com/dydx/rke2-skills/tree/main/skills/rke2-airgap-registries
Command: npx skills add https://github.com/dydx/rke2-skills --skill rke2-airgap-registries-dydx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Running self-hosted RKE2 in disconnected environments requires getting container images onto nodes without internet access and configuring containerd to pull from private registries, which involves many version-specific flags and configuration files. ## Core Features & Use Cases - Air-Gap Image Delivery: Deploy images via tarballs in /var/lib/rancher/rke2/agent/images/ or push them to a private OCI registry referenced by system-default-registry. - registries.yaml Configuration: Full syntax for mirrors, endpoints, rewrite rules, auth, TLS, wildcard entries, and disabling default endpoint fallback. - Embedded Registry Mirror (Spegel): Enable peer-to-peer image sharing between nodes on ports 9345/5001 with embedded-registry: true. - Use Case: You need to install RKE2 on nodes with no internet access. Download the release image tarballs, place them in the agent images directory on each node, run install.sh with INSTALL_RKE2_ARTIFACT_PATH, and configure registries.yaml to point at your internal mirror. ## Quick Start Ask how to configure /etc/rancher/rke2/registries.yaml so an air-gapped RKE2 cluster pulls all images from your private registry at registry.example.com:5000.

Frequently Asked Questions about rke2-airgap-registries

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I install RKE2 in an air-gapped environment?▼

Download the RKE2 image tarballs, binary tarball, checksums, and install.sh on a connected machine, then either place tarballs in /var/lib/rancher/rke2/agent/images/ on each node or push images to a private registry. Run install.sh with INSTALL_RKE2_ARTIFACT_PATH pointing at the artifacts for a fully offline install.

How do I configure registries.yaml for a private registry in RKE2?▼

Create /etc/rancher/rke2/registries.yaml on every node with a mirrors entry mapping the upstream registry to your endpoint URLs, plus a configs entry keyed by host:port for auth and TLS settings. Restart RKE2 on each node for changes to take effect.

What is the difference between system-default-registry and registries.yaml?▼

system-default-registry in config.yaml rewrites the default docker.io prefix on RKE2 system images to your registry host. registries.yaml provides full control over mirrors, endpoints, rewrites, authentication, and TLS for any registry, and is required for non-system workloads.

Does RKE2 support peer-to-peer image sharing between nodes?▼

Yes, RKE2 embeds Spegel, a distributed registry mirror enabled with embedded-registry: true on server nodes plus mirror entries in registries.yaml. Nodes share images over port 9345 and a P2P network on port 5001, but latest tags are never served peer-to-peer.

Why does my air-gapped RKE2 node fail to start or pull images?▼

RKE2 requires a default route to detect the node IP, which you can satisfy with a black-hole route via a dummy interface. For pull failures, check /var/lib/rancher/rke2/agent/containerd/containerd.log, since kubelet errors often hide the real per-endpoint mirror failures.

How do I import images into RKE2's containerd manually?▼

Use ctr with the socket /run/k3s/containerd/containerd.sock and the k8s.io namespace, for example ctr -a /run/k3s/containerd/containerd.sock -n k8s.io image import myimages.tar. Without the k8s.io namespace the kubelet cannot see the imported images.

Related Skills

Explore More Software Engineering Skills→
taracodlabstaracodlabs
779

network-diagnostics

Diagnose Windows network connectivity and DNS resolution using PowerShell cmdlets.

Official
Intermediate
radius-projectradius-project
1.7k

radius-install-custom

Install Radius control plane on Kubernetes using custom-built images.

Official
Advanced
xalgordxalgord
954

securing-container-registry-with-harbor

Configures Harbor registry security including vulnerability scanning, content trust, RBAC, and immutable tags.

Community
Intermediate
air-gappedair-gapped
5

k8s-components-checker

Survey Kubernetes clusters against an embedded compatibility registry for upgrade-readiness verdicts.

Official
Advanced