Installation

C9s can be installed into an existing Kubernetes cluster with version 1.31 or higher. No custom CNI, no additional storage class, no special tuning.

A typical installation method uses the c9s Helm chart distributed as an OCI artifact.

Cluster requirements

• Kubernetes 1.31 or newer. The direct runtime relies on restartable init containers (native sidecars) and server-side field selectors for Link watches.
• Privileged workloads must be admitted in lab namespaces: every device Pod runs a privileged connectivity init-sidecar that wires the Pod's interfaces. If Pod Security Admission is enforced, label lab namespaces with pod-security.kubernetes.io/enforce=privileged. No node-resident agent is installed, and device containers themselves receive only the privilege their containerlab kind declares.
• VXLAN and nftables support in the worker kernel (standard in distribution kernels): the namespace-wide management mesh is kernel VXLAN inside the Pods on the CNI network, and management translation uses an nftables table inside each Pod's namespace. Cross-worker Link wires need nothing special; they are plain UDP between the connectivity sidecars.
• /dev/kvm on workers only when running VM-backed (vrnetlab) kinds; the plan requests the device through ordinary Kubernetes device semantics.
• Pod-to-Pod UDP in lab namespaces: device Pods exchange management mesh traffic on UDP 14789 and link wires on UDP 14790, and their connectivity sidecar watches Links through the Kubernetes API. NetworkPolicies must allow both ports between device Pods and egress to the API server, and must let the kubelet reach TCP 14791 on device Pods, where the connectivity sidecar answers its readiness probe.
• Registry access is cluster administration: private device images use ordinary imagePullSecrets, and mirrors or insecure registries are configured on the workers' container runtime, not in c9s. See Image pulling.

Versions

The charts are versioned with semantic versioning and the available versions can be listed using one of the following methods:

• with make ls-releases command executed in the clabernetes repository
• browsing the published charts on Artifact Hub
• browsing the tags of the clabernetes OCI artifact on GitHub

You don't need to know the exact version to just install c9s, however, if you need to install a specific version, that's how to know what is available.

With helm

A common way to install applications on Kubernetes typically uses helm:

helm upgrade --install --create-namespace --namespace c9s \
    clabernetes oci://ghcr.io/clabernetes/clabernetes/clabernetes

With make

While users can install c9s directly with Helm, the Makefile provided in the clabernetes repository offers a convenient way to install c9s into an existing Kubernetes cluster.

git clone https://github.com/clabernetes/clabernetes
cd clabernetes

The Makefile takes care of all the dependencies and tools, so you can just relax:

make install

make install uses the current Kubernetes context. Set C9S_CONTEXT when installing into a specific context:

C9S_CONTEXT=my-cluster make install

Verify the installation

kubectl -n c9s get pods

The manager Pods must be Running. Then deploy a lab, for example one of the basic examples.

Global configuration

Cluster-wide defaults (pull policy and pull Secrets, default resources, node selectors by image, registry trust and mirrors) live in one Config resource named clabernetes in the c9s namespace. The Helm chart creates it from the globalConfig values. On later upgrades the chart only fills fields that are still unset in the Config; set globalConfig.mergeMode: overwrite to have the chart values replace the whole resource on every upgrade. When the release is managed by Argo CD or Flux, set globalConfig.enabled: false and apply the Config yourself.

Edit the Config directly when you do not manage it through Helm values:

kubectl -n c9s edit configs.c9s.run clabernetes

The manager picks up changes immediately and re-evaluates every Node. See the Config reference for all fields.

Upgrade

This release is a breaking API and runtime cut: there is no in-place upgrade path. Upgrading from any earlier release requires a full uninstall and reinstall. Follow the steps in the 0.9 release notes, which walk through exporting your manifests, uninstalling, updating manifests for the new API, and reinstalling.

Within one release line, re-running the installation commands above (helm upgrade --install, or make install) upgrades the release in place. If you installed with a values file, pass the same -f on upgrade so Helm does not reset the release to chart defaults. The manager applies CRD updates on startup, so additive schema changes take effect without a separate kubectl apply of the CRDs.

Uninstallation

To uninstall c9s, you can remove the Helm release, or run:

make uninstall