Quick Start

Get started with Chaos Mesh in minutes

This guide will help you quickly deploy Chaos Mesh and run your first chaos experiment.

Prerequisites

Before you begin, ensure you have:

• A Kubernetes cluster (version 1.12 or later)
• kubectl configured to access your cluster
• Helm 3 installed (for the recommended installation method)

For local testing, you can use Minikube, Kind, or k3s.

Installation

1. Add the Chaos Mesh Helm repository

   helm repo add chaos-mesh https://charts.chaos-mesh.org
   helm repo update
   
2. Create the chaos-mesh namespace

   kubectl create namespace chaos-mesh
   
3. Install Chaos Mesh

   For containerd runtime (most common):

   helm install chaos-mesh chaos-mesh/chaos-mesh \
     --namespace chaos-mesh \
     --set chaosDaemon.runtime=containerd \
     --set chaosDaemon.socketPath=/run/containerd/containerd.sock
   

   For Docker runtime:

   helm install chaos-mesh chaos-mesh/chaos-mesh \
     --namespace chaos-mesh \
     --set chaosDaemon.runtime=docker \
     --set chaosDaemon.socketPath=/var/run/docker.sock
   

   See Installation for other runtime configurations (CRI-O, k3s, microk8s).

4. Verify the installation

   Check that all Chaos Mesh components are running:

   kubectl get pods -n chaos-mesh
   

   You should see output similar to:

   NAME                                        READY   STATUS    RESTARTS   AGE
   chaos-controller-manager-6d6d95cd94-xxx     3/3     Running   0          1m
   chaos-daemon-xxx                            1/1     Running   0          1m
   chaos-dashboard-6d6d95cd94-xxx              1/1     Running   0          1m
   

Access the Dashboard

The Chaos Dashboard provides a web-based interface for managing chaos experiments.

kubectl port-forward -n chaos-mesh svc/chaos-dashboard 2333:2333

Then open your browser to http://localhost:2333.

Run Your First Chaos Experiment

Let’s create a simple pod-kill experiment to test pod resilience.

1. Deploy a sample application

   Create a deployment to test:

   kubectl create deployment nginx --image=nginx --replicas=3
   kubectl expose deployment nginx --port=80
   
2. Create a PodChaos experiment

   Create a file named pod-kill-example.yaml:

   apiVersion: chaos-mesh.org/v1alpha1
   kind: PodChaos
   metadata:
     name: pod-kill-example
     namespace: default
   spec:
     action: pod-kill
     mode: one
     selector:
       namespaces:
         - default
       labelSelectors:
         app: nginx
     duration: "30s"
     scheduler:
       cron: "@every 2m"
   

   This experiment will:

   • Kill one random nginx pod every 2 minutes
   • Run for 30 seconds each time
   • Target pods with label app=nginx
3. Apply the experiment

   kubectl apply -f pod-kill-example.yaml
   

   Watch the pods to see the chaos in action:

   kubectl get pods -w
   

   You’ll see pods being terminated and recreated.

4. Observe in the Dashboard

   Return to the Dashboard at http://localhost:2333 to see:

   • Experiment status and timeline
   • Affected pods
   • Event logs
   • Real-time updates
5. Clean up

   Delete the experiment:

   kubectl delete podchaos pod-kill-example
   

   Delete the sample application:

   kubectl delete deployment nginx
   kubectl delete service nginx
   

More Chaos Experiments

Try other chaos types to test different aspects of your system:

NetworkChaos

Inject network delays, packet loss, and partitions

StressChaos

Generate CPU and memory stress

IOChaos

Simulate I/O delays and errors

TimeChaos

Test time-dependent logic with clock skew

Next Steps

Core Concepts

Learn about Chaos Mesh architecture and components

All Chaos Types

Explore all 14 chaos experiment types

Workflows

Orchestrate complex chaos scenarios

Production Installation

Configure Chaos Mesh for production use

Common Issues

Experiments don't affect my pods

Check selectors: Verify your pod selector matches the target pods:

kubectl get pods --show-labels -n your-namespace

Check RBAC: Ensure the chaos-controller-manager has permission to operate in your namespace.

Check runtime configuration: Verify the chaosDaemon.runtime and chaosDaemon.socketPath match your container runtime.

Chaos Daemon pods are CrashLoopBackOff

This usually indicates an incorrect socket path. Check your container runtime:

kubectl get nodes -o wide

Then update the Helm installation with the correct runtime and socket path for your cluster.

Cannot access Dashboard

Ensure the port-forward is running:

kubectl port-forward -n chaos-mesh svc/chaos-dashboard 2333:2333

Check that the dashboard pod is running:

kubectl get pods -n chaos-mesh | grep dashboard

Get Help

• Documentation: Browse the complete docs for detailed information
• GitHub Issues: Report bugs or request features
• Slack: Join #project-chaos-mesh in CNCF Slack
• Twitter: Follow @chaos_mesh