Skip to content
KSail

Workload Management

Everything you do to workloads lives under one command family: ksail workload. The subcommands follow familiar kubectl and Helm patterns, so existing muscle memory transfers — and because the tooling is embedded, there is nothing else to install.

Terminal window
ksail workload get pods
ksail workload logs deployment/nginx -f
ksail workload gen deployment my-app --image=nginx --port=80

Two ways to deploy

Section titled “Two ways to deploy”

There are two ways to get manifests onto a cluster. Pick by what you’re doing, not by preference.

  1. Imperative — for learning and the inner loop. Apply a directory straight at the cluster and iterate:

    Terminal window
    ksail workload apply -k ./k8s

    This is the quickest way to push manifests while you experiment. Pair it with watch to auto-apply on every file save.

  2. GitOps — recommended for real environments. Your manifests are the source of truth: KSail compiles your source directory into a versioned OCI artifact, and Flux or ArgoCD reconciles the cluster to match.

    Terminal window
    ksail workload push        # compile the source dir and push the OCI artifact
    ksail workload reconcile   # tell the GitOps engine to pull and apply

Inspect and debug

Section titled “Inspect and debug”

Day-2 commands work against whatever your kubeconfig points at, no matter how the workload got there:

Terminal window
ksail workload get pods                     # list resources
ksail workload describe pod/nginx-abc123    # full status and events
ksail workload logs deployment/nginx -f     # stream logs (-f to follow)
ksail workload exec deployment/nginx -- sh  # run a command in a container
ksail workload explain deployment.spec      # API field documentation

To block until something is ready — handy in scripts and CI:

Terminal window
ksail workload wait deployment/nginx --for=condition=available
ksail workload watch          # live view of resources as they change

Operate

Section titled “Operate”

Scale and manage rollouts the way you already know:

Terminal window
ksail workload scale deployment/nginx --replicas=3
ksail workload rollout status deployment/nginx
ksail workload rollout restart deployment/nginx
ksail workload rollout undo deployment/nginx

Scaffold new manifests with gen instead of writing YAML from scratch:

Terminal window
ksail workload gen deployment my-app --image=nginx --port=80 > k8s/my-app.yaml

Run one service locally

Section titled “Run one service locally”

Use ksail workload intercept when you want a process on your machine to serve one Deployment’s live inbound traffic while its cluster dependencies stay in place. The command redirects one pod’s TCP port for the duration of the session and restores the pod’s remote traffic handling on Ctrl-C.

Follow the Local Service Intercepts guide for a complete example, including an in-cluster traffic client, the local process, port selection, and cleanup. Use workload mirror instead when you only need a read-only copy.

Check before you ship

Section titled “Check before you ship”

ksail workload validate and ksail workload scan inspect your manifests fully offline, without a cluster — which makes them an ideal CI gate:

Terminal window
ksail workload validate   # schema validation + Flux ${VAR} substitution expansion
ksail workload scan       # security posture via Kubescape (NSA, MITRE, and more)

See Validate configuration for how ${VAR} substitution is expanded during validation.

Move images around

Section titled “Move images around”

Beyond push/reconcile, the workload family also handles container images and secrets:

Command What it does
images List the container images your workloads require
export / import Move images as tar archives — air-gapped environments, CI caching
cipher Encrypt and decrypt SOPS secrets — see Secret Management

Target a specific environment

Section titled “Target a specific environment”

Any workload command can run against a different config with --config. One repository, one workflow, a config per environment:

Terminal window
# Validate the prod config's manifests offline, then deliver
ksail --config ksail.prod.yaml workload validate
ksail --config ksail.prod.yaml workload push
ksail --config ksail.prod.yaml workload reconcile

See the Multi-Environment guide for the full pattern.

Section titled “Related”