Use Cases

Learning Kubernetes

For developers new to Kubernetes who want to explore concepts and experiment with different configurations.

Recommended Setup

ksail cluster init \
  --name learning \
  --distribution Vanilla \
  --cni Cilium \
  --gitops-engine None

Workflow

ksail cluster create

# Apply, inspect, and iterate
ksail workload apply -f my-deployment.yaml
ksail workload get pods
ksail workload apply -f updated-deployment.yaml
ksail workload logs deployment/my-app

ksail cluster delete

Tips

• Use ksail workload gen to generate example manifests
• Use ksail workload explain <resource> to learn about Kubernetes resources
• Use ksail workload watch to watch for file changes and auto-apply; it scopes kubectl apply to the nearest directory containing a kustomization file recognized by kubectl (kustomization.yaml, kustomization.yml, or Kustomization) for faster iteration, falling back to kubectl apply -f <dir> --recursive when no kustomization boundary is found; add --initial-apply to sync the cluster at startup before entering the loop
• Use ksail cluster connect to open K9s for interactive exploration

Iterating on Applications

For developers building and testing applications locally before deploying to staging or production.

Recommended Setup

ksail cluster init \
  --name dev \
  --distribution K3s \
  --cni Cilium \
  --csi Enabled \
  --gitops-engine Flux \
  --local-registry localhost:5050

Workflow

ksail cluster create

# Build and push to local registry
docker build -t localhost:5050/my-app:dev .
docker push localhost:5050/my-app:dev

# Update k8s/deployment.yaml: image: localhost:5050/my-app:dev
ksail workload push
ksail workload reconcile

Tips

• Use ksail workload logs -f deployment/my-app for live log streaming
• Use ksail workload exec deployment/my-app -- /bin/sh for debugging
• Keep terminal running with ksail cluster info to monitor cluster health
• Pair KSail with Tilt, Skaffold, DevSpace, Telepresence, or mirrord to automate the build-deploy loop, hot-reload interpreted code, or bridge local↔remote traffic

Testing in CI/CD

For automated testing in CI/CD pipelines where reproducibility and speed matter.

Recommended Setup

ksail.yaml

apiVersion: ksail.io/v1alpha1
kind: Cluster
spec:
  cluster:
    distribution: K3s
    cni: Cilium
    gitOpsEngine: Flux
    localRegistry:
      registry: localhost:5050
  workload:
    sourceDirectory: k8s

GitHub Actions (Recommended)

Use the official ksail-cluster composite action to provision a cluster in one step. It handles installation, Helm chart caching, mirror registry caching, and image pre-pulling automatically.

.github/workflows/test.yaml

name: Integration Tests

on:
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Provision KSail cluster
        id: cluster
        uses: devantler-tech/ksail/.github/actions/ksail-cluster@v5.59.0
        with:
          distribution: K3s   # Vanilla, K3s, Talos, VCluster, KWOK
          sops-age-key: ${{ secrets.SOPS_AGE_KEY }}  # optional: import SOPS key + create sops-age secret
          delete: true         # delete cluster at the end (runs even on failure)

      - name: Build and push app image
        run: |
          docker build -t localhost:5050/my-app:${{ github.sha }} .
          docker push localhost:5050/my-app:${{ github.sha }}

      - name: Deploy and test
        env:
          KUBECONFIG: ${{ steps.cluster.outputs.kubeconfig }}
        run: |
          sed -i "s|image:.*|image: localhost:5050/my-app:${{ github.sha }}|" k8s/deployment.yaml
          ksail workload push
          ksail workload reconcile
          ksail workload wait deployment/my-app --for=condition=available
          npm run test:integration

For the full action inputs reference, PR preview patterns, and GitOps CI workflows, see PR Preview Clusters.

Other CI Systems

For non-GitHub CI (GitLab CI, CircleCI, etc.), install KSail directly and run lifecycle commands:

# Install (see https://github.com/devantler-tech/ksail/releases for available versions)
VERSION=5.59.0
curl -sSL "https://github.com/devantler-tech/ksail/releases/download/v${VERSION}/ksail_${VERSION}_linux_amd64.tar.gz" | tar -xz
sudo mv ksail /usr/local/bin/

# Provision cluster (using declarative ksail.yaml)
ksail cluster create

# ... run tests ...

# Cleanup
ksail cluster delete

Tips

• Use --timeout flags to handle slow CI runners
• Cache Docker layers for faster builds
• Use matrix builds to test across multiple Kubernetes versions/distributions
• Use --ttl as a best-effort safety net — the cluster auto-destroys when the TTL elapses provided the ksail cluster create process stays alive
• Consider using ksail cluster start and ksail cluster stop if tests can share a cluster