Installation

This document describes how to install Chaos Mesh to perform chaos experiments against your application in Kubernetes.

If you want to try Chaos Mesh on your laptop (Linux or macOS), you can refer the following two documents:

Prerequisites

Before deploying Chaos Mesh, make sure the following items have been installed:

  • Kubernetes version >= 1.12
  • RBAC enabled (optional)

Install Chaos Mesh

  1. curl -sSL https://mirrors.chaos-mesh.org/latest/install.sh | bash

The above command installs all the CRDs, required service account configuration, and all components. Before you start running a chaos experiment, verify if Chaos Mesh is installed correctly.

If you are using k3s or k3d, please also specify --k3s flag.

  1. curl -sSL https://mirrors.chaos-mesh.org/latest/install.sh | bash -s -- --k3s

Note:

install.sh is suitable for trying Chaos Mesh out. If you want to use Chaos Mesh in production or other serious scenarios, Helm is the recommended deployment method.

Verify your installation

Verify if Chaos Mesh is running (For the use of kubectl, you can refer to the documentation.)

  1. kubectl get pod -n chaos-testing

Expected output:

  1. NAME                                        READY   STATUS    RESTARTS   AGE
  2. chaos-controller-manager-6d6d95cd94-kl8gs   1/1     Running   0          3m40s
  3. chaos-daemon-5shkv                          1/1     Running   0          3m40s
  4. chaos-dashboard-d998856f6-vgrjs             1/1     Running   0          3m40s

Uninstallation

You can uninstall Chaos Mesh by deleting the namespace.

  1. curl -sSL https://mirrors.chaos-mesh.org/latest/install.sh | bash -s -- --template | kubectl delete -f -

Install by helm

You also can install Chaos Mesh by helm. Before you start installing, make sure that helm v2 or helm v3 is installed correctly.

Step 1: Add Chaos Mesh repository to Helm repos

  1. helm repo add chaos-mesh https://charts.chaos-mesh.org

After adding the repository successfully, you can search available version by the following command:

  1. helm search repo chaos-mesh

Step 2: Create custom resource type

To use Chaos Mesh, you must create the related custom resource type first.

  1. curl -sSL https://mirrors.chaos-mesh.org/latest/crd.yaml | kubectl apply -f -

For kuberentes < 1.15, --validate=false is needed to ignore the unexpected fields

  1. curl -sSL https://mirrors.chaos-mesh.org/latest/crd.yaml | kubectl apply --validate=false -f -

Step 3: Install Chaos Mesh

Note:

Currently, Chaos Dashboard is not installed by default. If you want to try it out, add --set dashboard.create=true in the helm install commands below. Refer to Configuration for more information.

Depending on your environment, there are two methods of installing Chaos Mesh:

  • Install in Docker environment

    1. Create namespace chaos-testing:

      1. kubectl create ns chaos-testing
  1. 2.  Install Chaos Mesh using helm:
  3.     -   For helm 2.X
  5.     ```
  6.     helm install chaos-mesh/chaos-mesh --name=chaos-mesh --namespace=chaos-testing
  7.     ```
  11.     -   For helm 3.X
  13.     ```
  14.     helm install chaos-mesh chaos-mesh/chaos-mesh --namespace=chaos-testing
  15.     ```
  19. 3.  Check whether Chaos Mesh pods are installed:
  21.     ```
  22.     kubectl get pods --namespace chaos-testing -l app.kubernetes.io/instance=chaos-mesh
  23.     ```
  27.     Expected output:
  29.     ```
  30.     NAME                                        READY   STATUS    RESTARTS   AGE
  31.     chaos-controller-manager-6d6d95cd94-kl8gs   1/1     Running   0          3m40s
  32.     chaos-daemon-5shkv                          1/1     Running   0          3m40s
  33.     chaos-daemon-jpqhd                          1/1     Running   0          3m40s
  34.     chaos-daemon-n6mfq                          1/1     Running   0          3m40s
  35.     chaos-dashboard-d998856f6-vgrjs             1/1     Running   0          3m40s
  36.     ```

  • Install in containerd environment (kind)

    1. Create namespace chaos-testing:

      1. kubectl create ns chaos-testing
  1. 2.  Install Chaos Mesh using helm:
  3.     -   for helm 2.X
  5.     ```
  6.     helm install chaos-mesh/chaos-mesh --name=chaos-mesh --namespace=chaos-testing --set chaosDaemon.runtime=containerd --set chaosDaemon.socketPath=/run/containerd/containerd.sock
  7.     ```
  11.     -   for helm 3.X
  13.     ```
  14.     helm install chaos-mesh chaos-mesh/chaos-mesh --namespace=chaos-testing --set chaosDaemon.runtime=containerd --set chaosDaemon.socketPath=/run/containerd/containerd.sock
  15.     ```
  19. 3.  Check whether Chaos Mesh pods are installed:
  21.     ```
  22.     kubectl get pods --namespace chaos-testing -l app.kubernetes.io/instance=chaos-mesh
  23.     ```
  27.     Expected output:
  29.     ```
  30.     NAME                                        READY   STATUS    RESTARTS   AGE
  31.     chaos-controller-manager-6d6d95cd94-kl8gs   1/1     Running   0          3m40s
  32.     chaos-daemon-5shkv                          1/1     Running   0          3m40s
  33.     chaos-daemon-jpqhd                          1/1     Running   0          3m40s
  34.     chaos-daemon-n6mfq                          1/1     Running   0          3m40s
  35.     chaos-dashboard-d998856f6-vgrjs             1/1     Running   0          3m40s
  36.     ```

  • Install in containerd environment (k3s)

    1. Create namespace chaos-testing:

      1. kubectl create ns chaos-testing
  1. 2.  Install Chaos Mesh using helm:
  3.     -   for helm 2.X
  5.     ```
  6.     helm install chaos-mesh/chaos-mesh --name=chaos-mesh --namespace=chaos-testing --set chaosDaemon.runtime=containerd --set chaosDaemon.socketPath=/run/k3s/containerd/containerd.sock
  7.     ```
  11.     -   for helm 3.X
  13.     ```
  14.     helm install chaos-mesh chaos-mesh/chaos-mesh --namespace=chaos-testing --set chaosDaemon.runtime=containerd --set chaosDaemon.socketPath=/run/k3s/containerd/containerd.sock
  15.     ```
  19. 3.  Check whether Chaos Mesh pods are installed:
  21.     ```
  22.     kubectl get pods --namespace chaos-testing -l app.kubernetes.io/instance=chaos-mesh
  23.     ```
  27.     Expected output:
  29.     ```
  30.     NAME                                        READY   STATUS    RESTARTS   AGE
  31.     chaos-controller-manager-6d6d95cd94-kl8gs   1/1     Running   0          3m40s
  32.     chaos-daemon-5shkv                          1/1     Running   0          3m40s
  33.     chaos-daemon-jpqhd                          1/1     Running   0          3m40s
  34.     chaos-daemon-n6mfq                          1/1     Running   0          3m40s
  35.     chaos-dashboard-d998856f6-vgrjs             1/1     Running   0          3m40s
  36.     ```

After executing the above commands, you should be able to see the output indicating that all Chaos Mesh pods are up and running. Otherwise, check the current environment according to the prompt message or create an issue for help.