Understanding the Relationship Between ChaosBlade and ChaosBlade-Operator

ChaosBlade serves as the core chaos engineering engine and CLI tool, while ChaosBlade-Operator acts as the Kubernetes-specific controller that bridges ChaosBlade experiments to cluster resources via CustomResourceDefinitions.

The chaosblade-io/chaosblade repository provides a universal chaos engineering platform capable of injecting faults into physical machines, containers, and JVM processes. To extend these capabilities into Kubernetes environments, the project leverages ChaosBlade-Operator as its official Kubernetes integration layer, creating a seamless relationship between the core engine and container orchestration workflows.

Architectural Overview: Core Engine vs. Kubernetes Controller

ChaosBlade: The Universal Chaos Engineering Engine

ChaosBlade operates as the foundational command-line tool and library that defines and executes chaos experiments across diverse platforms. It provides the experiment definition language, fault injection mechanisms, and recovery logic required to simulate failures in local processes, Docker containers, and cloud infrastructure. The core engine remains platform-agnostic, exposing a consistent interface for creating, querying, and destroying experiments regardless of the underlying infrastructure.

ChaosBlade-Operator: The Kubernetes Native Extension

ChaosBlade-Operator implements the Kubernetes side of the ecosystem by providing CustomResourceDefinitions (CRDs) and a controller that watches these resources. When installed in a cluster, the operator registers CRDs such as ChaosBladeExperiment and runs a controller that reconciles these custom resources. The operator translates Kubernetes-native experiment specifications into actual fault injection by driving the underlying ChaosBlade engine, either by launching ChaosBlade binaries inside target pods or by executing operator-specific logic.

Technical Integration Points

Go Module Dependency

The relationship between the two projects manifests explicitly in the dependency graph. ChaosBlade declares a versioned module dependency on github.com/chaosblade-io/chaosblade-operator within its go.mod file. This dependency pulls the operator's API types and helper utilities directly into the CLI build, ensuring type compatibility between the core tool and the Kubernetes extension.

The Kubernetes Executor Bridge

The integration logic resides in exec/kubernetes/executor.go, which imports the operator's API types from github.com/chaosblade-io/chaosblade-operator/pkg/apis/chaosblade/v1alpha1. When a user executes chaosblade create k8s ..., the Kubernetes executor instantiates the operator's client, constructs ChaosBladeExperiment objects, and submits them to the cluster via the Kubernetes API. This bridge effectively converts CLI commands into declarative Kubernetes resources that the operator controller processes.

Build System Coupling

The top-level Makefile defines a variable K8S_BLADE_VERSION that points to the operator package and includes build rules to clone, compile, and package the operator binaries alongside the main ChaosBlade binary. Additionally, the helper script scripts/sync_go_mod.sh automates version synchronization, updating the operator dependency in go.mod whenever the main project releases a new version. This ensures that the CLI and operator remain functionally aligned across releases.

Practical Workflow: From CLI Command to Cluster Execution

The relationship becomes concrete when executing a Kubernetes experiment. First, install the operator into your cluster:

# Add the ChaosBlade Helm repository

helm repo add chaosblade https://chaosblade-io.github.io/charts
helm install chaosblade-operator chaosblade/chaosblade-operator --namespace chaosblade --create-namespace

Once the operator registers the CRDs and starts its controller, use the ChaosBlade CLI to create an experiment:

# Create a network loss experiment targeting a specific pod

chaosblade create k8s --action networkLoss --target pod --container myapp-container \
  --namespace default --pod myapp-pod --percent 60 --duration 30s

Behind the scenes, the CLI's Kubernetes executor generates a ChaosBladeExperiment resource:

apiVersion: chaosblade.io/v1alpha1
kind: ChaosBladeExperiment
metadata:
  name: networkloss-xxxxx
  namespace: default
spec:
  target: pod
  action: networkLoss
  scope: container
  container: myapp-container
  pod: myapp-pod
  percent: "60"
  duration: "30s"

The operator controller watches for this resource and orchestrates the actual fault injection by executing the ChaosBlade engine within the target environment.

For programmatic integration, you can use the operator client directly from Go code, leveraging the same types imported by ChaosBlade:

import (
    "context"
    
    cbclient "github.com/chaosblade-io/chaosblade-operator/pkg/client/clientset/versioned"
    cbv1 "github.com/chaosblade-io/chaosblade-operator/pkg/apis/chaosblade/v1alpha1"
    metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

func createNetworkLoss(client cbclient.Interface, namespace, podName, container string) error {
    exp := &cbv1.ChaosBladeExperiment{
        ObjectMeta: metav1.ObjectMeta{
            GenerateName: "networkloss-",
        },
        Spec: cbv1.ChaosBladeExperimentSpec{
            Target:    "pod",
            Action:    "networkLoss",
            Scope:     "container",
            Container: container,
            Pod:       podName,
            Percent:   "60",
            Duration:  "30s",
        },
    }
    _, err := client.ChaosbladeV1alpha1().ChaosBladeExperiments(namespace).Create(context.TODO(), exp, metav1.CreateOptions{})
    return err
}

Summary

• ChaosBlade provides the core chaos engineering engine, CLI tool, and experiment execution logic for multiple platforms including physical machines, Docker, and JVM processes.
• ChaosBlade-Operator implements the Kubernetes integration layer through CRDs and controllers, translating declarative Kubernetes resources into ChaosBlade executions.
• The projects maintain tight coupling through Go module dependencies declared in go.mod, shared API types imported in exec/kubernetes/executor.go, and synchronized build processes managed via Makefile and scripts/sync_go_mod.sh.
• Users must install the operator in their cluster before the ChaosBlade CLI can execute Kubernetes experiments, as the CLI relies on the operator to create and manage ChaosBladeExperiment resources.

Frequently Asked Questions

Is ChaosBlade-Operator required to use ChaosBlade?

No, ChaosBlade-Operator is only required when executing chaos experiments against Kubernetes resources. ChaosBlade functions independently for local process attacks, Docker container faults, and JVM experiments. However, for any experiment targeting pods, nodes, or containers within a Kubernetes cluster, the operator must be installed to provide the necessary CRDs and controller logic.

How does ChaosBlade communicate with the Kubernetes cluster?

ChaosBlade communicates through the Kubernetes API server using the operator's client libraries. When you execute chaosblade create k8s ..., the CLI uses the exec/kubernetes/executor.go implementation to instantiate a client for the ChaosBladeExperiment CRD defined in github.com/chaosblade-io/chaosblade-operator/pkg/apis/chaosblade/v1alpha1. The executor submits the experiment specification as a custom resource, and the operator's controller running inside the cluster watches for these resources and executes the actual fault injection.

Can I use ChaosBlade-Operator without the ChaosBlade CLI?

Yes, you can create ChaosBladeExperiment resources directly using kubectl or Kubernetes client libraries without installing the ChaosBlade CLI on your local machine. The operator watches for these resources independently and executes experiments using the ChaosBlade engine binaries that it manages within the cluster. However, the CLI provides convenience functions for experiment construction, status querying, and result formatting that simplify the user experience.

Where are the CRD definitions located in the source code?

The CRD definitions and Go types for ChaosBladeExperiment are located in the ChaosBlade-Operator repository at pkg/apis/chaosblade/v1alpha1. The ChaosBlade CLI imports these types through its Go module dependency on github.com/chaosblade-io/chaosblade-operator, specifically referencing them in exec/kubernetes/executor.go to ensure type safety when constructing and submitting experiment resources to the Kubernetes API.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}