# chaoskube: Controlled Kubernetes Pod Termination

> chaoskube is a Kubernetes chaos tool that periodically selects and terminates random pods. Its filtering and schedule controls help teams contain failures, but broad defaults can include system pods and the chaoskube pod itself.

**linki/chaoskube** — chaoskube periodically kills random pods in your Kubernetes cluster.

- Repository: https://github.com/linki/chaoskube
- Stars: 1,932 · Forks: 128
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/linki-chaoskube

## What chaoskube Does in a Kubernetes Cluster

chaoskube addresses a specific failure-testing question: what happens when an arbitrary pod disappears while the rest of a Kubernetes system continues running? It periodically chooses a pod and terminates it, which can expose assumptions about replication, retries, service discovery, readiness, and recovery. The intended audience is engineers and operators who already manage Kubernetes and want repeatable pod-level disruption.

The tool is intentionally narrower than a general chaos platform. Its documented mechanism is pod termination, not node destruction, packet loss, latency injection, or arbitrary resource modification. That narrower scope makes the behavior easier to reason about, but it also limits the kinds of resilience properties it can exercise. A deployment that tolerates one pod restart does not necessarily demonstrate tolerance for simultaneous control-plane failure, unavailable nodes, corrupted disks, or degraded network paths.

The default behavior deserves attention. The README states that chaoskube targets any pod in any namespace, including system pods and itself. It also says the tool starts in dry-run mode, so it does not kill anything until the user explicitly disables that behavior. Those defaults are useful for inspection, but enabling real termination without narrowing the target set can create failures in namespaces that were not meant to participate.

## chaoskube Selection, Scheduling, and Termination Flow

Based on the repository layout and documentation, the executable is built in Go and its Kubernetes-facing packages include `terminator/`, `internal/`, and `metrics/`. The README describes the operating sequence as startup, connection to the cluster, filter setup, quiet-time setup, timezone setup, and then periodic termination. The default interval is 10 minutes.

Target selection is assembled from Kubernetes metadata rather than from a fixed workload name. The documented filters include namespaces, namespace labels, pod labels, pod annotations, pod names, owner-reference kinds, and minimum pod age. The examples show ordinary selector syntax such as excluding `kube-system`, selecting a specific label, and restricting the owner kind to `DaemonSet`. A name filter can include pods containing `foo` or `bar` while excluding names containing `prod`.

The schedule can also restrict when termination occurs. The startup output records fields for days of the year, times of day, weekdays, timezone, and UTC offset. The README does not document every combination or explain retry behavior when the cluster has no eligible pods. That omission matters because a target set that looks configured can still produce no disruption if selectors match nothing.

For observability, the documentation mentions a simple HTTP endpoint intended for Kubernetes liveness and readiness probes. It listens on port 8080 by default and can be disabled with `--metrics-address=""`. The available Prometheus dependency in `go.mod` indicates a metrics-oriented codebase, but the README only explicitly documents the health endpoint, so this article does not assume additional exported metrics.

## Installing the Helm Release and Performing a Dry Run

The README gives a Helm installation path. The following command adds the project's chart repository, installs the chart, waits for the operation through `--atomic`, and creates the `chaoskube` namespace if it is absent:

```console
$ helm repo add chaoskube https://linki.github.io/chaoskube/
$ helm install chaoskube chaoskube/chaoskube --atomic --namespace=chaoskube --create-namespace
```

After installation, the first safe use is to inspect the application logs and confirm the connection, target filter, interval, timezone, and dry-run state. The documented default interval is 10 minutes, and the example startup line reports `dryRun=true`. Seeing the configured filter in the log is more useful than seeing only a successful container start, because it shows which pods the process considers eligible.

For a cluster-local deployment, the README says that targeting the same cluster is sufficient. A local or cross-cluster invocation can instead use `--master` or `--kubeconfig`. The documentation says that, by default, chaoskube uses the standard kubeconfig path in the user's home, so the current kubeconfig context determines the target cluster. That default is convenient for a workstation experiment, but it is also a meaningful operational boundary: a changed context can redirect the tool to another cluster.

Do not enable real termination as the first action. Once the target set has been reviewed, the documented switch is `--no-dry-run`:

The README does not provide a complete raw manifest for an executable local installation, so teams using the container should refer to `examples/` and `examples/rbac.yaml` rather than inventing RBAC or deployment settings.

## Narrowing chaoskube to Intended Workloads

The most important configuration decision is not the interval. It is the target filter. The README gives a mixed example that selects a labeled application while excluding production and `kube-system` namespaces and ignoring a critical-pod annotation:

```console
$ chaoskube \
    --labels 'app=mate,chaos,stage!=production' \
    --annotations '!scheduler.alpha.kubernetes.io/critical-pod' \
    --namespaces '!kube-system,!production'
```

This kind of filter can turn chaoskube from a broad cluster experiment into a scoped test subject. The annotation example also supports an opt-in model, where workloads indicate that they may be terminated. The repository does not provide a documented policy engine beyond these selectors, so teams must decide which labels and annotations represent permission to participate.

Names and owner kinds need similar attention. The documented `--kinds 'DaemonSet'` example selects only pods owned by a DaemonSet, while `!DaemonSet,!StatefulSet` excludes those kinds. A pod with no OwnerReference is automatically excluded when an include filter is used, according to the README. That rule can be helpful, but it can also make the selected population differ from what an operator sees when browsing pods manually.

Minimum age is another boundary. A new pod can be excluded, which may prevent immediate disruption of recently created workloads, while an old pod can remain eligible after repeated replacements. The README does not state how quickly pod metadata is refreshed or what happens when several eligible pods share the same names. Teams should therefore verify the selector against the exact workload topology rather than infer the target set from labels alone.

## Operational Constraints and the Cost of a False Target

chaoskube is a deliberate source of disruption, so its main failure mode is operational scope error. A selector can match a broader set than intended, and the README explicitly warns about system pods and self-termination by default. A single mistaken namespace flag can therefore turn a controlled experiment into a cluster-wide incident. The HTTP endpoint reduces the risk of running without a process, but it does not validate whether the selected pods are safe to terminate.

The tool also requires Kubernetes permissions to list pods and terminate them. The README points to a provided ClusterRole in the raw-manifest examples, but it does not state that users should grant that role indiscriminately. Permission scope must be checked against the selected namespaces and the chosen installation method. An overly broad role is especially questionable when the intended target is one test namespace.

The 10-minute default is not a guarantee of exactly one termination per 10 minutes. The documentation describes an interval and periodic termination, but it does not document scheduling guarantees, missed executions, random-selection behavior under small populations, or behavior when no eligible pod exists. Those omissions limit how precisely the tool can be modeled in a resilience test plan.

There is also a maintenance consideration. The repository is not archived, the last push was on 2026-10-08, and releases include `v0.39.1` on 2026-07-15 and a Helm chart release on 2026-06-10. This indicates recent repository activity, not that deployment behavior is automatically compatible with every Kubernetes version. The `go.mod` file declares Kubernetes dependencies at `v0.36.2` and Go `1.26.0`, while the example log uses an older Kubernetes version. Compatibility should therefore be verified in the target cluster. The MIT license permits reuse and modification under its terms, but it does not remove operational responsibility for permissions and workload impact.

## How chaoskube Differs from Broader Failure Tools

A real alternative is a manual Kubernetes deletion workflow using tools such as `kubectl`. A manual workflow can give the operator control over the timing of an individual disruption. It does not automatically select random eligible pods, apply periodic intervals, combine Kubernetes metadata filters, or schedule quiet periods.

Another alternative is a broader chaos-engineering platform that can inject faults beyond pod termination. Such a platform may model node loss, network degradation, resource pressure, or service-specific failures, depending on its implementation. chaoskube takes the opposite approach by concentrating on one Kubernetes action. That makes its behavior easier to inspect and its scope easier to constrain, but it cannot answer questions about faults outside the pod deletion boundary.

The practical comparison is between repeatability and breadth. Manual deletion is appropriate for a one-off drill or an incident investigation. chaoskube is more relevant when a team wants a recurring experiment with selection rules. A broader fault-injection tool is the better choice when the resilience claim depends on something other than losing one pod. The documentation does not claim parity with those systems, and that narrower design should be treated as a feature and a boundary.

## Conclusion

Engineers should adopt chaoskube when they need a simple, periodic pod termination experiment against a deliberately selected namespace or workload set. They should not use its broad defaults in a production cluster without first verifying the selectors, permissions, schedule, and scope of the installed chart. Confirm that dry-run remains enabled until the target set is understood, then review the exact Kubernetes RBAC and workload recovery behavior.

## FAQ

### What does chaoskube do?

chaoskube periodically selects and kills random Kubernetes pods so teams can test system behavior under arbitrary pod failures. The README says the default interval is 10 minutes and the default mode is dry-run.

### How do I install chaoskube with Helm?

The README provides a Helm repository command followed by `helm install chaoskube chaoskube/chaoskube --atomic --namespace=chaoskube --create-namespace`. It also points to `examples/` and `examples/rbac.yaml` for the raw-manifest approach.

### How can I prevent chaoskube from killing system pods?

Use documented namespace and metadata filters, such as excluding `kube-system` and selecting specific labels or annotations. The README also warns that the default scope includes system pods and chaoskube itself.

## Sources

- [Issues](https://github.com/linki/chaoskube/issues)
- [License: MIT](https://github.com/linki/chaoskube/blob/master/LICENSE)
- [linki/chaoskube on GitHub](https://github.com/linki/chaoskube)
- [README](https://github.com/linki/chaoskube/blob/master/README.md)
- [Releases](https://github.com/linki/chaoskube/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/linki-chaoskube