Skip to main content
Version: 2.8.8

Install Chaos Mesh using Helm

This document describes how to install Chaos Mesh in the production environment.

Prerequisites​

Before installing Chaos Mesh, make sure that:

To check whether Helm is installed, execute the following command:

helm version

The expected output is as follows:

version.BuildInfo{Version:"v3.5.4", GitCommit:"1b5edb69df3d3a08df77c9902dc17af864ff05d1", GitTreeState:"dirty", GoVersion: "go1.16.3"}

If your actual output is similar to the expected output with Version, GitCommit, GitTreeState, and GoVersion, it means that Helm is installed successfully.

info

In this document, Helm v3 is used to operate Chaos Mesh. If Helm v2 is used in your environment, refer to Migrating Helm v2 to v3 or modify the Helm version to the v2 format.

Install Chaos Mesh using Helm​

Step 1: Add Chaos Mesh repository​

Add the Chaos Mesh repository to the Helm repository:

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

Step 2: View the installable versions of Chaos Mesh​

To see charts that can be installed, execute the following command:

helm search repo chaos-mesh
info

The above command will output the latest release of the chart. If you want to install a historical version, execute the following command to view all released versions:

helm search repo chaos-mesh -l

After the above command is completed, you can start installing Chaos Mesh.

Step 3: Create the namespace to install Chaos Mesh​

It is recommended to install Chaos Mesh under the chaos-mesh namespace, or you can specify any namespace to install Chaos Mesh:

kubectl create ns chaos-mesh

Step 4: Install Chaos Mesh in different environments​

As the daemons of different container runtimes listen on different socket paths, you need to set the appropriate values during installation. You can run the following installation commands according to different environments.

info

To install a specific version of Chaos Mesh, add the --version x.y.z parameter after helm install. For example, helm install chaos-mesh chaos-mesh/chaos-mesh -n=chaos-mesh --version 2.1.0.

tip

To ensure high availability, Chaos Mesh turns on leader-election feature by default. If you do not need to use this feature, you can disable it manually with --set controllerManager.leaderElection.enabled=false.

If version <2.6.1, you still need to set --set controllerManager.replicaCount=1 to reduce the controller manager to one replica.

Limit experiments to one namespace​

By default, clusterScoped is true, and Chaos Mesh watches for experiments across the cluster. Set clusterScoped to false to watch for experiments and select their targets in a single namespace. Set that namespace with controllerManager.targetNamespace, which defaults to chaos-mesh and applies only when clusterScoped is false.

The Helm --namespace flag selects where to install Chaos Mesh. The experiment namespace can be different. Even in namespace-scoped mode, installing the chart requires permission to create cluster-scoped resources such as CRDs and ClusterRoles.

For example, to install Chaos Mesh in chaos-mesh and run experiments in app-ns, first create the app-ns namespace. Save the following values as namespace-scope.yaml.

clusterScoped: false
controllerManager:
  targetNamespace: app-ns
dnsServer:
  targetNamespace: app-ns

When the chart deploys Chaos DNS Server, set dnsServer.targetNamespace to the same namespace so the chart grants it permissions there.

Add -f namespace-scope.yaml to the installation command for your container runtime. Create your experiment resources in app-ns and select targets in that namespace.

Verify the installation​

To check the running status of Chaos Mesh, execute the following command:

kubectl get pods -n chaos-mesh -l app.kubernetes.io/instance=chaos-mesh

The expected output is as follows:

NAME                                       READY   STATUS    RESTARTS   AGE
chaos-controller-manager-7b8c86cc9-44dzf   1/1     Running   0          17m
chaos-controller-manager-7b8c86cc9-mxw99   1/1     Running   0          17m
chaos-controller-manager-7b8c86cc9-xmc5v   1/1     Running   0          17m
chaos-daemon-sg2k2                         1/1     Running   0          17m
chaos-dashboard-b9dbc6b68-hln25            1/1     Running   0          17m
chaos-dns-server-546675d89d-qkjqq          1/1     Running   0          17m

If your actual output is similar to the expected output, then Chaos Mesh has been successfully installed.

info

If the STATUS of your actual output is not Running, then execute the following command to check the Pod details, and troubleshoot issues according to the error information.

# Take the chaos-controller as an example
kubectl describe po -n chaos-mesh chaos-controller-manager-7b8c86cc9-44dzf
info

If leader election is turned off, chaos-controller-manager should only have 1 replication.

NAME                                        READY   STATUS    RESTARTS   AGE
chaos-controller-manager-676d8567c7-ndr5j   1/1     Running   0          24m
chaos-daemon-6l55b                          1/1     Running   0          24m
chaos-dashboard-b9dbc6b68-hln25             1/1     Running   0          44m
chaos-dns-server-546675d89d-qkjqq           1/1     Running   0          44m

Run Chaos experiments​

After verifying that the installation is complete, you can run a Chaos experiment to experience the features of Chaos Mesh.

For the method to run the experiment, it is recommended to refer to Run a Chaos experiment. After successfully creating the experiment, you can observe the running status of the experiment on the Chaos Dashboard.

Upgrade Chaos Mesh​

To upgrade Chaos Mesh, execute the following command:

helm upgrade chaos-mesh chaos-mesh/chaos-mesh
info

To upgrade to a specific version of Chaos Mesh, add the --version x.y.z parameter after helm upgrade. For example, helm upgrade chaos-mesh chaos-mesh/chaos-mesh -n=chaos-mesh --version 2.1.0.

info

If you have upgraded Chaos Mesh in a non-Docker environment, you will need to add the appropriate parameters as described in Step 4: Install Chaos Mesh in different environments.

To modify the configuration, set different values according to your needs. For example, execute the following command to upgrade and uninstall chaos-dashboard:

info

For more values and their usages, refer to all values.

warning

Currently, the latest CustomResourceDefinition (CRD) is not applied during the Helm upgrading, which might cause errors. To avoid this situation, you can apply the latest CRD manually:

Uninstall Chaos Mesh​

To uninstall Chaos Mesh, execute the following command:

helm uninstall chaos-mesh -n chaos-mesh

FAQs​

How can I install the latest version of Chaos Mesh?​

The helm/chaos-mesh/values.yaml file defines the image of the latest version (the master branch). To install the latest version of Chaos Mesh, execute the following command:

# Clone repository
git clone https://github.com/chaos-mesh/chaos-mesh.git
cd chaos-mesh

helm install chaos-mesh helm/chaos-mesh -n=chaos-mesh

How can I disable the safe mode?​

Safe mode allows you to disable authentication to the Chaos Mesh dashboard, and should only be used for non-production deployments. Safe mode is enabled by default. To disable the safe mode, specify dashboard.securityMode as false during the installation or upgrade:

How can I persist Chaos Dashboard data?​

Chaos Dashboard uses SQLite as the default database engine. If PV (Persistent Volumes) is disabled, the data of Chaos Dashboard will be lost after a reboot occurs. To avoid data loss, you can refer to the Persistence of Chaos Dashboard Data document to enable PV for Chaos Dashboard or set MySQL and PostgreSQL as the database engine.