Skip to main content

Local Development Cluster (k3d)

Test Kuploy on your local machine using k3d, a lightweight wrapper around k3s that runs a full Kubernetes cluster inside Docker.

This is useful for:

  • Testing Docker image builds before deploying to production
  • End-to-end testing of the full deploy-an-app-through-kuploy flow
  • Validating changes to kuploy-k8s manifests

Prerequisites​

  • Docker running
  • k3d installed (brew install k3d or curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash)
  • kubectl installed
  • kuploy-k8s cloned locally

Create the Cluster​

k3d cluster create kuploy-dev \
  --port "8080:80@loadbalancer" \
  --port "8443:443@loadbalancer"

This gives you a single-node cluster with k3s's built-in ServiceLB and Traefik Ingress controller. LoadBalancer services work out of the box -- no metallb or extra setup.

Verify:

kubectl cluster-info
kubectl get nodes

Deploy Kuploy​

Use the standard kuploy-k8s deploy script against your local cluster:

cd kuploy-k8s

# Check prerequisites
python deploy.py preflight

# Deploy
python deploy.py

This deploys PostgreSQL, Redis, and Kuploy into the kuploy namespace, same as production.

Loading Local Images​

When testing locally built Docker images (instead of pulling from the registry):

# Build the image
docker build -t ceduth/kuploy:dev -f Dockerfile .

# Import into k3d (no push to registry needed)
k3d image import ceduth/kuploy:dev -c kuploy-dev

# Update the deployment to use your local image
kubectl set image deployment/kuploy kuploy=ceduth/kuploy:dev -n kuploy
tip

k3d copies the image directly into the k3s containerd store. No local registry needed.

Accessing Kuploy​

After deployment, Kuploy is reachable via the Ingress on your mapped ports.

If you configured a domain in the Ingress (e.g., kuploy.local):

# Add to /etc/hosts
echo "127.0.0.1 kuploy.local" | sudo tee -a /etc/hosts

Then open http://kuploy.local:8080 in your browser.

Alternatively, use port-forward for quick access without Ingress:

kubectl port-forward svc/kuploy 3000:3000 -n kuploy
# Open http://localhost:3000

Teardown​

k3d cluster delete kuploy-dev

This removes everything -- cluster, containers, volumes. Clean slate.

Tips​

  • Coexists with other clusters. k3d creates its own kubeconfig context (k3d-kuploy-dev). Switch between clusters with kubectl config use-context k3d-kuploy-dev.
  • Fast iteration. After code changes: docker build → k3d image import → kubectl rollout restart deployment/kuploy -n kuploy.
  • Resource usage. k3s is lightweight: ~300MB RAM for the cluster node. You can run it alongside kind or other clusters without issues.