Skip to main content
Version: 0.9.1

Develop a New Chaos

After preparing the development environment, let's develop a new type of chaos, HelloWorldChaos, which only prints a "Hello World!" message to the log. Generally, to add a new chaos type for Chaos Mesh, you need to take the following steps:

Add the chaos object in controller

In Chaos Mesh, all chaos types are managed by the controller manager. To add a new chaos type, you need to start from adding the corresponding reconciler type in the controller, as instructed in the following steps:

  1. Add the HelloWorldChaos object in the controller manager main.go.

    You will notice existing chaos types such as PodChaos, NetworkChaos and IOChaos. Add the new type below them:

        if err = (&controllers.HelloWorldChaosReconciler{
    Client: mgr.GetClient(),
    Log: ctrl.Log.WithName("controllers").WithName("HelloWorldChaos"),
    }).SetupWithManager(mgr); err != nil {
    setupLog.Error(err, "unable to create controller", "controller", "HelloWorldChaos")
  2. Under controllers, create a helloworldchaos_controller.go file and edit it as below:

    package controllers

    import (

    chaosmeshv1alpha1 ""

    ctrl ""

    // HelloWorldChaosReconciler reconciles a HelloWorldChaos object
    type HelloWorldChaosReconciler struct {
    Log logr.Logger


    func (r *HelloWorldChaosReconciler) Reconcile(req ctrl.Request) (ctrl.Result, error) {
    logger := r.Log.WithValues("reconciler", "helloworldchaos")

    // the main logic of `HelloWorldChaos`, it prints a log `Hello World!` and returns nothing.
    logger.Info("Hello World!")

    return ctrl.Result{}, nil

    func (r *HelloWorldChaosReconciler) SetupWithManager(mgr ctrl.Manager) error {
    // exports `HelloWorldChaos` object, which represents the yaml schema content the user applies.
    return ctrl.NewControllerManagedBy(mgr).


The comment // is an authority control mechanism that decides which account can access this reconciler. To make it accessible by the dashboard and chaos-controller-manager, you need to modify controller-manager-rbac.yaml accordingly:

- apiGroups: ['']
- podchaos
- networkchaos
- iochaos
- helloworldchaos # Add this line in all group
verbs: ['*']

Register the CRD

The HelloWorldChaos object is a custom resource object in Kubernetes. This means you need to register the corresponding CRD in the Kubernetes API. To do this, modify kustomization.yaml by adding the corresponding line as shown below:

- bases/chaos-mesh.org_podchaos.yaml
- bases/chaos-mesh.org_networkchaos.yaml
- bases/chaos-mesh.org_iochaos.yaml
- bases/chaos-mesh.org_helloworldchaos.yaml # this is the new line

Implement the schema type

To implement the schema type for the new chaos object, add helloworldchaos_types.go in the api directory and modify it as below:

package v1alpha1

import (
metav1 ""

// +kubebuilder:object:root=true

// HelloWorldChaos is the Schema for the helloworldchaos API
type HelloWorldChaos struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`

// +kubebuilder:object:root=true

// HelloWorldChaosList contains a list of HelloWorldChaos
type HelloWorldChaosList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Items []HelloWorldChaos `json:"items"`

func init() {
SchemeBuilder.Register(&HelloWorldChaos{}, &HelloWorldChaosList{})

With this file added, the HelloWorldChaos schema type is defined and can be called by the following YAML lines:

kind: HelloWorldChaos
name: <name-of-this-resource>
namespace: <ns-of-this-resource>

Make the Docker image

Having the object successfully added, you can make a Docker image and push it to your registry:

make docker-push


The default DOCKER_REGISTRY is localhost:5000, which is preset in hack/ You can overwrite it to any registry to which you have access permission.

Run chaos

You are almost there. In this step, you will pull the image and apply it for testing.

Before you pull any image for Chaos Mesh (using helm install or helm upgrade), modify values.yaml of helm template to replace the default image with what you just pushed to your local registry.

In this case, the template uses pingcap/chaos-mesh:latest as the default target registry, so you need to replace it with localhost:5000, as shown below:

clusterScoped: true

# Also see clusterScoped and controllerManager.serviceAccount
create: true

serviceAccount: chaos-controller-manager
image: localhost:5000/pingcap/chaos-mesh:latest
image: localhost:5000/pingcap/chaos-daemon:latest
image: localhost:5000/pingcap/chaos-dashboard:latest

Now take the following steps to run chaos:

  1. Get the related custom resource type for Chaos Mesh:

    kubectl apply -f manifests/
    kubectl get crd
  2. Install Chaos Mesh:

    The arguments --set chaosDaemon.runtime=containerd --set chaosDaemon.socketPath=/run/containerd/containerd.sock is used to to support network chaos on kind.

  3. Create chaos.yaml in any location with the lines below:

    kind: HelloWorldChaos
    name: hello-world
    namespace: chaos-testing
  4. Apply the chaos:

    kubectl apply -f /path/to/chaos.yaml
    kubectl get HelloWorldChaos -n chaos-testing

    Now you should be able to check the Hello World! result in the log:

    kubectl logs chaos-controller-manager-{pod-post-fix} -n chaos-testing


    {pod-post-fix} is a random string generated by Kubernetes, you can check it by executing kubectl get po -n chaos-testing.

Next steps

Congratulations! You have just added a chaos type for Chaos Mesh successfully. Let us know if you run into any issues during the process. If you feel like doing other types of contributions, refer to Add facilities to chaos daemon (WIP).