How the Kubernetes Executor Interacts with ChaosBlade CRDs: Implementation Deep Dive

The Kubernetes executor in the chaosblade-io/chaosblade repository serves as a translation bridge that converts CLI experiment specifications into Kubernetes Custom Resource Definitions (CRDs), then manages the full lifecycle of these resources—including creation, status polling, and deletion—using the controller-runtime client.

The Kubernetes executor is a critical component in the ChaosBlade chaos engineering platform that enables users to run experiments against containerized workloads. This article examines how the Kubernetes executor interacts with ChaosBlade CRDs by analyzing the source code in exec/kubernetes/executor.go and related files, revealing the exact mechanisms for client initialization, resource translation, and lifecycle management.

Architecture Overview: From CLI Command to ChaosBlade CRD

The Kubernetes executor implements the spec.Executor interface, acting as the control plane bridge between the ChaosBlade CLI and the Kubernetes API server. Unlike local executors that directly manipulate system resources, the Kubernetes executor does not perform chaos injection itself. Instead, it translates experiment definitions into v1alpha1.ChaosBlade CRD objects and delegates execution to the ChaosBlade Operator running inside the cluster.

This architecture ensures that the same experiment model used for local Docker or OS attacks can be reused for Kubernetes workloads, with only the executor implementation changing to accommodate the CRD-based orchestration layer.

Step-by-Step: How the Kubernetes Executor Processes CRDs

The executor follows a strict pipeline when interacting with ChaosBlade CRDs, from establishing the API connection to cleaning up resources.

Building the Kubernetes Client Connection

Before any CRD operations, the executor establishes a controller-runtime client via the newClient() function in exec/kubernetes/executor.go. This function supports three authentication modes:

• Kubeconfig file: Specified via the --kubeconfig flag
• Kubectl proxy: Specified via the --kubectl-proxy flag for scenarios where direct API access is restricted
• In-cluster configuration: Automatically detected when running inside a Kubernetes pod

The resulting client.Client is cached in the package-level cli variable to ensure connection reuse across multiple operations, reducing API server load and improving performance.

Translating CLI Models to ChaosBlade CRD Objects

The convertExpModelToChaosBladeObject() function serves as the translation engine between CLI flags and the CRD schema defined in the operator repository. This function:

1. Extracts the experiment UID, scope, target, and action from the spec.ExpModel
2. Filters out Kubernetes-specific flags (kubeconfig, waiting-time, kubectl-proxy, token) that control client behavior rather than the experiment itself
3. Maps remaining flags to v1alpha1.FlagSpec objects within the CRD's Experiment array

The resulting v1alpha1.ChaosBlade object contains the complete experiment specification that the ChaosBlade Operator consumes to perform the actual injection.

Creating and Monitoring the CRD

When executing an experiment, the create() function posts the CRD to the Kubernetes API using cli.Create(), then immediately retrieves the created object via the get() helper to obtain the server-generated metadata and initial status.

The executor then enters a polling loop via QueryStatus(), which:

• Fetches the current ChaosBlade resource using the controller-runtime client
• Inspects the status.phase field (values include Running, Destroyed, Error)
• Maps these phases to spec.Response objects for CLI presentation

The completed() helper determines when polling should terminate—either when the phase reaches a terminal state (Running for creation, Destroyed for deletion) or when the --waiting-time duration expires.

Destroying ChaosBlade CRD Resources

For experiment cleanup, the delete() function constructs a minimal ChaosBlade object containing only the resource name (UID) and issues a cli.Delete() call to the Kubernetes API.

When the --force-remove flag is specified, the executor invokes RemoveFinalizer() to strip finalizers from the CRD before deletion. This prevents the resource from hanging in a terminating state when the operator is unable to complete cleanup logic, ensuring the experiment record is removed even if the underlying chaos injection cannot be fully reversed.

Practical Examples: Creating and Destroying Kubernetes Experiments

The following examples demonstrate how the Kubernetes executor translates CLI commands into CRD operations.

Creating a pod network loss experiment:

# Using a kubeconfig file

blade create k8s pod-network loss --names my-pod --namespace default --percent 30 \
    --kubeconfig ~/.kube/config

# Using kubectl proxy (useful for sidecar containers)

kubectl proxy --port=8080 &
blade create k8s pod-network loss --names my-pod --namespace default --percent 30 \
    --kubectl-proxy http://127.0.0.1:8080 \
    --token <your-bearer-token>

Behind the scenes, the executor calls convertExpModelToChaosBladeObject() to build the CRD, then create() to POST it to the API server.

Destroying an experiment:

# Standard destruction

blade destroy <UID> --target k8s --kubeconfig ~/.kube/config

# Force remove hanging CRDs

blade destroy <UID> --target k8s --kubeconfig ~/.kube/config --force-remove

The executor's delete() function handles the API call, while RemoveFinalizer() cleans up stubborn resources when --force-remove is specified.

Key Source Files in the ChaosBlade Repository

Understanding the Kubernetes executor requires familiarity with these specific files:

• exec/kubernetes/executor.go – Core implementation containing newClient(), convertExpModelToChaosBladeObject(), create(), delete(), and QueryStatus().
• exec/kubernetes/spec.go – Defines Kubernetes-specific CLI flags (kubeconfig, kubectl-proxy, token, waiting-time) and registers the executor with the command framework.
• cli/cmd/destroy.go – CLI entry point for blade destroy that routes to the Kubernetes executor when --target k8s is specified.
• operator/pkg/apis/chaosblade/v1alpha1/chaosblade_types.go – Defines the ChaosBlade CRD schema, including the Experiment and FlagSpec structures used by the executor.
• cli/cmd/query_k8s.go – Implements blade query k8s commands that also utilize the executor's QueryStatus() functionality.

Summary

The Kubernetes executor in ChaosBlade serves as a sophisticated translation and orchestration layer rather than a direct chaos injection tool. Key takeaways include:

• The executor implements a controller-runtime client in newClient() to communicate with the Kubernetes API, supporting kubeconfig files, proxy URLs, and in-cluster configurations.
• CRD translation occurs in convertExpModelToChaosBladeObject(), which maps CLI flags to v1alpha1.FlagSpec objects while filtering out Kubernetes connection parameters.
• The executor manages the full CRD lifecycle through create(), delete(), and QueryStatus(), including polling logic that waits for terminal phases like Running or Destroyed.
• Force removal capabilities via RemoveFinalizer() ensure CRDs can be cleaned up even when the operator fails to complete normal finalization logic.

Frequently Asked Questions

What is the primary role of the Kubernetes executor in ChaosBlade?

The Kubernetes executor acts as a bridge between the ChaosBlade CLI and the Kubernetes control plane. Rather than performing chaos injection directly, it translates user commands into v1alpha1.ChaosBlade CRD objects and uses the controller-runtime client to manage these resources inside the cluster. The actual chaos injection is performed by the ChaosBlade Operator, which watches for these CRDs.

How does the executor convert CLI flags to CRD specifications?

The conversion happens in the convertExpModelToChaosBladeObject() function within exec/kubernetes/executor.go. This function extracts the experiment scope, target, and action from the CLI model, then iterates through all provided flags. It filters out Kubernetes-specific connection flags like kubeconfig, kubectl-proxy, and token, mapping the remaining experiment parameters to v1alpha1.FlagSpec objects within the CRD's experiment array.

What happens if a ChaosBlade CRD deletion hangs or fails?

When standard deletion fails, the executor provides a force-remove mechanism via the RemoveFinalizer() function. If the user specifies the --force-remove flag during blade destroy, the executor strips the finalizers from the CRD before issuing the delete command. This prevents the resource from remaining in a terminating state indefinitely when the ChaosBlade Operator is unable to complete its cleanup logic or is offline.

Can the Kubernetes executor operate from outside the cluster?

Yes, the executor supports external cluster operation through multiple authentication methods implemented in newClient(). Users can specify a local kubeconfig file via --kubeconfig, connect through a kubectl proxy URL using --kubectl-proxy, or provide bearer tokens for authentication. This flexibility allows the ChaosBlade CLI to manage experiments from a developer workstation, CI/CD pipeline, or jump host without requiring installation inside the target cluster.

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