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

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:

CommandWhat it does
imagesList the container images your workloads require
export / importMove images as tar archives — air-gapped environments, CI caching
cipherEncrypt 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”