k8s-local

name	k8s-local
description	Create and manage local Kubernetes clusters (k3d or kind) and deploy to them with kubectl, helm, helmfile, and skaffold. Use for local k8s cluster setup, dev loops, and debugging.
metadata	{"author":"Médéric HURIER (Fmind)","source":"github.com/fmind/dotfiles/tree/main/skills/k8s-local","created":"2026-06-23T00:00:00.000Z","updated":"2026-07-06T00:00:00.000Z"}

Local Kubernetes Cluster Management

Bootstrap and manage lightweight local Kubernetes clusters with k3d (default, Docker-based K3s) or kind, plus the local dev-tool ecosystem (kubectl, helm, helmfile, skaffold, k9s).

Templates & Resources

• k3d Configuration: Deployed at ~/.config/k3d/local.yaml (source: dot_config/k3d/local.yaml).
• kind Configuration: kind-config.yaml
• Local Cluster CLI: Deployed at ~/.local/bin/dot (source: dot/).
• Ingress Template: ingress-template.yaml

Core Principles

• Cloud Agnostic: Local clusters must mirror production API interfaces. Avoid vendor-specific or platform-specific configurations unless mapping local routes.
• Engine Choice: Use k3d (default/recommended) for lightweight, fast startup times with integrated Traefik ingress and a local registry. Use kind as a fallback for upstream-compatible, multi-node configurations.
• Local Registry Dev Loop: Push locally built Docker images to the local registry at registry.localhost:5050 or load them directly into the cluster engine nodes. (The registry container is named registry.localhost, so the same registry.localhost:5050 reference resolves for both host push and in-cluster pull via the k3s containerd mirror.)
• Declarative Operations: Manage all workloads using declarative configurations (Helm, Helmfile, Skaffold, Kustomize) rather than raw imperatives.

AI Agent Instructions

• Docker Healthcheck: Always run docker info before launching, stopping, or configuring clusters.
• Context Verification: Verify that the active context matches the intended local cluster before running kubectl commands. Use kubectx or kubectl config current-context to ensure the context is k3d-local.
• Local Images: Build local images, tag them for the local registry (registry.localhost:5050/image:tag), and push them, or load them directly into the cluster engine. Set imagePullPolicy: IfNotPresent or Never in deployment specs if using sideloaded or locally tagged images.

Workflow

1. Verify Docker Daemon: Ensure that the Docker runtime is active and running:

   docker info
   

2. Choose and Create Cluster:
   • Using k3d (Recommended): Use the dot CLI to idempotently ensure the cluster is configured and running:

     dot cluster start
     

     Or manually create it using the configuration file:

     k3d cluster create --config ~/.config/k3d/local.yaml
     

   • Using kind:

     kind create cluster --config ~/.agents/skills/k8s-local/resources/kind-config.yaml
     

3. Context & Namespace Switching:
   • List and switch contexts easily:

     kubectx
     kubectx k3d-local # or kind-local-cluster
     

   • List and switch active namespaces:

     kubens
     kubens default
     

4. Validate and Lint Manifests:
   • Validate YAML structures:

     kubeconform -strict <file-or-directory>
     

   • Lint configurations for best practices and security:

     kube-linter lint <file-or-directory>
     

5. Publish or Load Local Images:
   • Using Local Registry (Recommended for k3d): Tag and push the image:

     docker tag <image>:<tag> registry.localhost:5050/<image>:<tag>
     docker push registry.localhost:5050/<image>:<tag>
     

   • Sideloading directly (kind or k3d fallback):
     • For kind:

       kind load docker-image <image>:<tag> --name local-cluster
       

     • For k3d:

       k3d image load <image>:<tag> -c local
       

6. Declarative Deployments:
   • Via Helm:

     helm upgrade --install <release-name> <chart-path> --namespace <namespace> --create-namespace
     

   • Via Helmfile:

     helmfile apply
     

   • Via Skaffold (Development inner-loop):

     skaffold dev
     

   • Via Kustomize:

     kubectl apply -k <kustomization-directory>
     

7. Observability & Debugging:
   • Launch k9s to monitor and manage the cluster interactively:

     k9s
     

   • Tail logs from multiple pods matching a query:

     stern <pod-name-query> -n <namespace>
     

8. Local-Remote Integration:
   • Use mirrord to run a local process inside the context of the cluster:

     mirrord exec --target deploy/<deployment-name> -- <local-command>
     

9. Teardown & Cleanup:
   • For k3d:

     k3d cluster stop local  # Pause to save resources
     k3d cluster start local # Resume cluster
     k3d cluster delete local
     

   • For kind:

     kind delete cluster --name local-cluster
     

Gotchas

1. Port Conflict: Host ports 8080 (HTTP Ingress), 8443 (HTTPS Ingress), 6443 (API Server), and 5050 (Local Registry) must not be occupied by other local services.
2. Image Pull Policies: Kubernetes defaults to pulling images if the tag is latest. Sideloaded or locally published images must use a specific tag, and the manifest must set imagePullPolicy: IfNotPresent or Never.
3. Ingress Controllers: k3d has Traefik enabled by default. kind requires applying an ingress controller manually (e.g. Nginx Ingress Controller).