Ephemeral Clusters with --ttl

KSail’s --ttl flag creates ephemeral clusters that auto-destroy after a specified duration. This is useful when you want to give yourself or others temporary access to a cluster — for debugging, demos, pair programming, or on-call investigation — without worrying about cleaning it up afterwards.

Note

Automated CI tests don’t need --ttl — create the cluster, run tests, and delete it explicitly. See Testing in CI/CD for that pattern. However, --ttl can be added as a safety net in CI to auto-destroy clusters if the cleanup step is skipped (e.g. runner crash).

How --ttl Works

When you pass --ttl to ksail cluster create, KSail:

1. Creates the cluster normally.
2. Blocks the process, waiting for the TTL to elapse.
3. Auto-deletes the cluster when the timer expires.

# Create a cluster that auto-destroys after 2 hours
ksail cluster create --ttl 2h

Pressing Ctrl+C (or sending SIGINT/SIGTERM) cancels the TTL wait and leaves the cluster running. This lets you extend a session — just delete the cluster manually when you’re done.

Caution

TTL deletion only runs while the ksail cluster create process is alive. If you close the terminal or kill the process, the cluster is not auto-deleted. Use ksail cluster delete to clean up manually.

When to Use --ttl

Scenario	Example	Suggested TTL
Debugging a failing deployment	Spin up a cluster, deploy the broken app, inspect logs and state	--ttl 1h
Demo or walkthrough	Show a feature to a colleague or stakeholder	--ttl 30m
Pair programming	Share a cluster with a teammate for a focused session	--ttl 2h
On-call investigation	Reproduce a production issue in a local cluster	--ttl 1h
Learning / experimentation	Try out a new Helm chart or CRD	--ttl 1h
PR review	Spin up a cluster to manually verify a pull request	--ttl 30m

Basic Usage

Create a Time-Limited Cluster

ksail cluster create --ttl 1h

The process blocks and prints a message:

ℹ cluster will auto-destroy in 1h0m0s (press Ctrl+C to cancel)

When the timer expires, KSail automatically deletes the cluster and exits.

Check Remaining Time

While the cluster is running, you can check the TTL status from another terminal:

ksail cluster info

This appends TTL information to the standard cluster info output, showing the remaining time. You can also see TTL status in the cluster list:

ksail cluster list

Cancel the TTL

Press Ctrl+C in the terminal running ksail cluster create --ttl .... The cluster stays running and you can continue using it. Delete it manually when you’re done:

ksail cluster delete

Running in the Background

If you want to keep using your terminal while the TTL timer runs, background the process:

ksail cluster create --ttl 2h &

The cluster creates normally and the TTL countdown runs in the background. When the timer expires, the cluster is auto-deleted.

Note

If you close the terminal session, the background process may be killed (depending on your shell configuration). To keep it alive, use nohup:

nohup ksail cluster create --ttl 2h &

Kubeconfig Context

KSail writes the kubeconfig context to the configured kubeconfig path (default ~/.kube/config, configurable via spec.cluster.connection.kubeconfig). Use kubectl, k9s, or ksail cluster connect immediately after creation. For context name formats per distribution, see Companion Tools.

Sharing a Cluster

To share a running ephemeral cluster with a colleague on the same network, they need:

1. A minimal kubeconfig for the specific cluster context
2. Network access to the cluster’s API server

Export only the relevant context to avoid leaking unrelated clusters or credentials:

kubectl config view --minify --flatten --context k3d-ksail > /tmp/ksail-kubeconfig.yaml

For local Docker-based clusters, this typically means running on the same machine. For Talos clusters on Hetzner or Omni, the API server is network-accessible and the kubeconfig can be shared directly.

Danger

Kubeconfig files contain cluster credentials (client certificates or tokens). Always share a minimal, context-specific kubeconfig rather than your full ~/.kube/config, use secure channels, and only share with trusted individuals. Note that your kubeconfig path may differ if you configured spec.cluster.connection.kubeconfig.

Distribution Tips

• K3s starts fastest and uses the fewest resources — good for quick debugging sessions.
• Vanilla (Kind) provides standard upstream Kubernetes — useful when you need exact API compatibility.
• Talos is immutable and secure — ideal for reproducing production-like environments.
• VCluster uses the Vind Docker driver to run the control plane directly in Docker containers — no pre-existing host cluster required, useful for lightweight isolated environments.

CI/CD with the GitHub Action

Use the ksail-cluster GitHub Actions composite action to set up KSail, cache Helm charts and mirror images, and run ksail cluster init + ksail cluster create in a single step. See PR Preview Clusters for the full action reference and GitOps CI workflows, or Testing in CI/CD for integration test patterns.