K3s (K3d)

K3s is a lightweight, certified Kubernetes distribution for resource-constrained environments. K3d runs K3s clusters in Docker containers — each node is a container, with a dedicated load balancer container routing traffic to control planes — providing fast 15–30 s cluster creation with batteries-included defaults (ServiceLB, local-path-provisioner, metrics-server), standard k3d.yaml files, and no vendor lock-in.

K3s (K3d) is ideal for quick local development, CI/CD pipelines with ephemeral clusters, resource-constrained machines or CI runners, and multi-node topology testing.

Quick Start

Requires Docker (installation prerequisites).

ksail cluster init --name my-cluster --distribution K3s --control-planes 1 --workers 2
ksail cluster create
ksail cluster info && kubectl get nodes  # verify
ksail cluster delete                     # cleanup

ksail cluster init creates ksail.yaml (KSail config) and k3d.yaml (K3d cluster config).

Configuration

Basic Configuration

# yaml-language-server: $schema=https://raw.githubusercontent.com/devantler-tech/ksail/main/schemas/ksail-config.schema.json
apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  cluster:
    distribution: K3s
    distributionConfig: k3d.yaml

K3d-Specific Configuration

apiVersion: k3d.io/v1alpha5
kind: Simple
servers: 1       # control-plane nodes
agents: 2        # worker nodes
ports:
  - port: 8080:80@loadbalancer

Built-in Components

K3s includes these components by default—KSail does not reinstall them:

| Component | Notes | |-----------|-------| | ServiceLB (Klipper-LB) | LoadBalancer support via host ports | | local-path-provisioner | Dynamic PersistentVolume provisioning | | Metrics Server | kubectl top and HPA support | | CoreDNS | Cluster DNS | | Traefik | Ingress controller (can be disabled) |

Registry Mirrors

Configure registry mirrors to avoid rate limits. KSail enables docker.io, ghcr.io, quay.io, and registry.k8s.io mirrors by default. Override with --mirror-registry flags:

ksail cluster init --name my-cluster --distribution K3s \
  --mirror-registry 'docker.io=https://registry-1.docker.io' \
  --mirror-registry 'ghcr.io=https://ghcr.io' \
  --mirror-registry 'quay.io=https://quay.io' \
  --mirror-registry 'registry.k8s.io=https://registry.k8s.io'

K3d injects registry configuration so all nodes use your mirrors automatically.

Troubleshooting

1. Cluster Creation Fails

Symptom: ksail cluster create fails with Docker errors.

docker ps          # Check Docker is running
df -h              # Check available disk space
docker system prune -f   # WARNING: removes unused containers, networks, images, and build cache
ksail cluster create

2. Nodes Not Ready

Symptom: kubectl get nodes shows NotReady status.

kubectl describe node <node-name>
kubectl get pods -n kube-system
ksail cluster delete && ksail cluster create

3. LoadBalancer Stuck in Pending

K3s uses ServiceLB (Klipper-LB), which binds to host ports. Ensure the port is not already in use and update ports in k3d.yaml (e.g., 9080:80@loadbalancer) if needed.

docker ps --format "table {{.Names}}\t{{.Ports}}" | grep k3d

4. Port Already in Use

Symptom: address already in use error during cluster creation.

k3d cluster list
k3d cluster delete <cluster-name>
# Or initialize with a different name:
ksail cluster init --name my-cluster-2 --distribution K3s

5. Out of Memory or Disk Space

Reduce node count in ksail.yaml (workers: 0 for a single-node cluster) and run docker system prune. Increase Docker Desktop resources under Settings → Resources.

Advanced Topics

Worker Node Scaling

Unlike Vanilla (Kind), K3s supports in-place worker node scaling. Update agents in k3d.yaml and run ksail cluster update to add or remove worker containers without recreation.

Disabling Built-in Components

k3d.yaml

options:
  k3s:
    extraArgs:
      - arg: --disable=traefik      # Remove Traefik ingress
        nodeFilters: ["server:*"]
      - arg: --disable=servicelb    # Remove ServiceLB (use MetalLB instead)
        nodeFilters: ["server:*"]

Custom CNI

ksail.yaml

spec:
  cluster:
    cni: Cilium

When cni: Cilium is set, KSail automatically passes --flannel-backend=none, --disable-network-policy, and --disable=traefik to the K3s server. Traefik is disabled because Cilium installs Gateway API CRDs (e.g. backendtlspolicies.gateway.networking.k8s.io) that conflict with Traefik's CRD ownership, causing the K3s helm-install-traefik pod to enter CrashLoopBackOff. You do not need to add these flags manually in k3d.yaml.

Kubernetes Version

K3s version is determined by the K3d image. Pin a specific version in k3d.yaml (see K3d image tags):

image: rancher/k3s:v1.35.3-k3s1

Port Mappings

ports:
  - port: 8080:80@loadbalancer    # HTTP
  - port: 8443:443@loadbalancer   # HTTPS
  - port: 30080:30080@agent:0     # NodePort on first worker

Integration with Native K3d

KSail generates standard k3d.yaml files—use K3d CLI directly (k3d cluster create --config k3d.yaml) if needed. No vendor lock-in: configurations are portable and KSail can interact with any K3d cluster accessible via your kubeconfig.