Use Cases

KSail supports three primary use cases with workflows tailored to each scenario: learning Kubernetes, iterating on applications, and testing in CI/CD.

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

Why this configuration:

• Vanilla distribution – Standard upstream Kubernetes behavior
• Cilium CNI – Modern networking with observability features
• No GitOps – Direct kubectl/apply workflow for immediate feedback

Workflow

1. Create cluster

   ksail cluster create

2. Apply manifests directly

   ksail workload apply -f my-deployment.yaml
   ksail workload get pods

3. Experiment with changes

   ksail workload apply -f updated-deployment.yaml
   ksail workload logs deployment/my-app

4. Clean up

   ksail cluster delete

Tips

• Use ksail workload gen to generate example manifests
• Use ksail workload explain <resource> to learn about Kubernetes resources
• 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 LocalPathProvisioner \
  --gitops-engine Flux \
  --local-registry \
  --local-registry-port 5050

Why this configuration:

• K3s distribution – Fast startup and low resource usage
• Cilium CNI – Network policies and observability
• LocalPathProvisioner CSI – Persistent volumes for stateful apps
• Flux GitOps – Declarative deployments matching production patterns
• Local registry – Fast image iteration without pushing to remote registry

Workflow

1. Create cluster

   ksail cluster create

2. Build and push image

   docker build -t localhost:5050/my-app:dev .
   docker push localhost:5050/my-app:dev

3. Update manifests

   k8s/deployment.yaml

   image: localhost:5050/my-app:dev

4. Deploy via GitOps

   ksail workload push
   ksail workload reconcile

5. Iterate

   # Make code changes
   docker build -t localhost:5050/my-app:dev .
   docker push localhost:5050/my-app:dev
   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

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:
    name: ci-test
    distribution: K3s
    cni: Cilium
    gitOpsEngine: Flux
    localRegistry: Enabled
  workload:
    sourceDirectory: k8s

Why this configuration:

• K3s distribution – Fastest startup time for CI
• Cilium CNI – Required for network policies
• Flux GitOps – Test actual deployment workflow
• Declarative config – Reproducible across CI runs

CI Pipeline Example

.github/workflows/test.yaml

name: Integration Tests

on:
  pull_request:
    branches: [main]

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

      - name: Install KSail
        run: |
          curl -sSL https://github.com/devantler-tech/ksail/releases/latest/download/ksail_linux_amd64 -o ksail
          chmod +x ksail
          sudo mv ksail /usr/local/bin/

      - name: Create cluster
        run: ksail cluster create

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

      - name: Deploy
        run: |
          sed -i "s|image:.*|image: localhost:5050/my-app:${{ github.sha }}|" k8s/deployment.yaml
          ksail workload push
          ksail workload reconcile

      - name: Run tests
        run: |
          # Wait for deployment
          ksail workload wait deployment/my-app --for=condition=available

          # Run integration tests
          npm run test:integration

      - name: Cleanup
        if: always()
        run: 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
• Consider using ksail cluster start and ksail cluster stop if tests can share a cluster

Configuration Comparison

Aspect	Learning	Development	CI/CD
Distribution	Vanilla	K3s	K3s
CNI	Cilium	Cilium	Cilium
CSI	None	LocalPathProvisioner	None
GitOps	None	Flux	Flux
Local Registry	Optional	Yes	Yes
Declarative Config	Optional	Recommended	Required
Cluster Lifetime	Session	Days/Weeks	Minutes

Next Steps

• Features – Deep dive into KSail capabilities
• Concepts – Understand the underlying technologies
• Configuration – Complete configuration reference