Best Practices for Organizing and Naming Chaos Experiments in ChaosBlade

ChaosBlade organizes chaos experiments using a strict target-action tuple where targets are nouns (e.g., network, docker) and actions are verbs (e.g., delay, kill), enforced through the ExpModelCommandSpec and ExpActionCommandSpec interfaces in the exec/ directory.

Organizing and naming chaos experiments consistently is critical for maintaining readable, maintainable chaos engineering suites. In the chaosblade-io/chaosblade repository, the project enforces a rigid semantic model that governs how experiments are structured, named, and extended. This guide explains the proven conventions derived from the source code that keep the CLI predictable and the codebase modular.

Understanding the ChaosBlade Experiment Model

The foundation of organizing chaos experiments in ChaosBlade rests on a four-part tuple: target → scope → matcher → action. This model is formally defined in docs/chaos_experiment_model_EN.md and implemented through three core interfaces in the Go source code:

• ExpModelCommandSpec – Defines the target (noun)
• ExpActionCommandSpec – Defines the action (verb) and its matchers
• ExpFlagSpec – Defines parameters for both matchers and actions

In exec/<target>/spec.go, the target specification returns a slice of action specifications, creating a hierarchical relationship that the CLI renders as subcommands. For example, the network target in exec/network/spec.go groups actions like delay, loss, and dns.

Naming Conventions for Targets and Actions

ChaosBlade enforces a strict linguistic pattern documented in docs/logic_flow_Introduction_EN.md: targets are nouns, actions are verbs.

Target Naming (Nouns)

Targets represent the component under test and must be concrete nouns:

• network – Network interfaces and traffic
• docker – Docker containers
• k8s – Kubernetes resources
• jvm – Java virtual machine
• dubbo – Dubbo services

In exec/<target>/spec.go, the Name() method returns this noun, which becomes the first-level subcommand in the CLI.

Action Naming (Verbs)

Actions describe the fault being injected and must be verbs:

• delay – Add latency
• loss – Drop packets
• kill – Terminate processes
• fullload – Generate resource exhaustion
• corrupt – Damage data

In exec/<target>/<action>_executor.go, the executor implementation follows the naming convention <Target><Action>Executor (e.g., NetworkDelayExecutor).

Repository Organization and File Structure

The directory layout in chaosblade-io/chaosblade mirrors the target-action model, making it straightforward to locate and extend experiments.

Target Directories

Each target resides in its own package under exec/:

exec/
├── network/
│   ├── spec.go          # NetworkCommandSpec

│   ├── delay.go         # DelayActionSpec + executor

│   └── loss.go          # LossActionSpec + executor

├── docker/
│   ├── spec.go
│   └── container_kill.go
└── k8s/
    ├── spec.go
    └── pod_kill.go

Key Files and Their Roles

File	Purpose	Naming Convention
exec/<target>/spec.go	Declares *TargetCommandSpec and lists available actions	Lower-case directory matching target noun
exec/<target>/executor.go	Implements Executor interface for actions	<Target><Action>Executor struct name
cli/cmd/exp.go	Registers all targets with Cobra CLI	Uses createExecutorKey(target, action) generating target-action keys
cli/cmd/create.go	Parses flags into ExpModel.ActionFlags	Iterates via cmd.Flags().VisitAll
data/experiment.go	Persists experiment metadata	Column names mirror CLI flag names (snake_case)

Flag Naming and Matcher Patterns

Flags in ChaosBlade follow strict conventions to ensure consistency across the CLI and the underlying data model.

Flag Naming Rules

As defined in docs/chaos_experiment_model_EN.md and implemented in cli/cmd/create.go, flags must be:

• Lower-case, hyphen-separated (e.g., --cpu-percent, --container-id)
• Consistent across interfaces – the ExpFlag.Name in the spec matches the Cobra flag name exactly
• Marked required explicitly – set Required: true in the ExpFlagSpec definition so Cobra enforces presence

Matcher vs. Action Flags

The model distinguishes between two flag types:

Matchers (filtering criteria):

• Defined in the action spec's Matchers() method
• Examples: --consumer, --service, --pid, --device
• Narrow the blast radius before fault injection

Action Flags (injection parameters):

• Defined in the action spec's Flags() method
• Examples: --time, --offset, --cpu-percent
• Control the specific behavior of the fault

In cli/cmd/create.go, the createExpModel function automatically populates ActionFlags by visiting all non-boolean flags, ensuring no manual duplication is needed.

Extending ChaosBlade with New Experiments

Adding a new chaos experiment requires following the established organizational patterns to maintain CLI consistency and code readability.

Step 1: Create the Target Specification

Create exec/<target>/spec.go implementing ExpModelCommandSpec:

type DiskCommandSpec struct{}

func (*DiskCommandSpec) Name() string { 
    return "disk"  // noun
}

func (*DiskCommandSpec) Actions() []exec.ExpActionCommandSpec {
    return []exec.ExpActionCommandSpec{
        &CorruptActionSpec{},
    }
}

Step 2: Define the Action Specification

Create exec/<target>/<action>.go implementing ExpActionCommandSpec:

type CorruptActionSpec struct{}

func (*CorruptActionSpec) Name() string { 
    return "corrupt"  // verb
}

func (*CorruptActionSpec) Matchers() []exec.ExpFlagSpec {
    return []exec.ExpFlagSpec{
        &exec.ExpFlag{Name: "path", Desc: "file path to corrupt", Required: true},
    }
}

func (*CorruptActionSpec) Flags() []exec.ExpFlagSpec {
    return []exec.ExpFlagSpec{
        &exec.ExpFlag{Name: "bytes", Desc: "number of bytes to overwrite", Required: true},
    }
}

func (*CorruptActionSpec) Executor(channel exec.Channel) exec.Executor {
    return &DiskCorruptExecutor{channel}
}

Step 3: Implement the Executor

Create exec/<target>/<action>_executor.go:

type DiskCorruptExecutor struct {
    channel exec.Channel
}

func (dce *DiskCorruptExecutor) Exec(uid string, ctx context.Context, model *spec.ExpModel) *spec.Response {
    // Implementation here
    return dce.channel.Run(ctx, "corrupt", model.ActionFlags)
}

Step 4: Registration

The cli/cmd/exp.go file automatically registers any new target via the AddCommand method. No additional registration is required if the target spec is properly placed in exec/.

After these steps, the command blade create disk corrupt --path /var/log/app.log --bytes 1024 becomes available immediately.

Summary

• ChaosBlade uses a strict target-action tuple (noun-verb) defined in docs/chaos_experiment_model_EN.md and implemented via ExpModelCommandSpec and ExpActionCommandSpec.
• Targets are always nouns (e.g., network, docker, k8s) and reside in exec/<target>/spec.go.
• Actions are always verbs (e.g., delay, kill, corrupt) with executors named <Target><Action>Executor.
• Flags are lower-case and hyphen-separated (e.g., --cpu-percent), defined in the action spec's Matchers() and Flags() methods.
• Extending the suite requires only adding files to exec/<target>/ following the established patterns; cli/cmd/exp.go handles registration automatically.

Frequently Asked Questions

How does ChaosBlade enforce the noun-verb naming convention?

The convention is documented in docs/logic_flow_Introduction_EN.md and enforced structurally through the interface design. The ExpModelCommandSpec interface requires a Name() method that returns the target (noun), while ExpActionCommandSpec requires a Name() method that returns the action (verb). The CLI construction in cli/cmd/exp.go concatenates these values to form commands like blade create network delay, making the grammatical structure visible to users.

What is the difference between matchers and action flags in ChaosBlade?

Matchers are filtering criteria defined in the Matchers() method of an action spec that narrow the blast radius before injection, such as --service, --consumer, or --device. Action flags are parameters that control the fault behavior itself, defined in the Flags() method, such as --time, --offset, or --cpu-percent. In cli/cmd/create.go, both are parsed into the ExpModel.ActionFlags map, but they serve distinct semantic purposes in the experiment definition.

Where should I place files when adding a new chaos experiment target?

New targets belong in a dedicated package under exec/<target>/, following the pattern established by existing modules like exec/network/ or exec/docker/. You must create spec.go to implement ExpModelCommandSpec, individual action files (e.g., delay.go) to implement ExpActionCommandSpec, and <action>_executor.go files for the Executor implementation. The cli/cmd/exp.go file automatically discovers and registers these packages, requiring no manual updates to the command registry.

How does ChaosBlade ensure flag consistency across the CLI and data persistence?

Flag consistency is enforced by convention and implementation. In the source code, flag names defined in ExpFlagSpec implementations (e.g., cpu-percent, container-id) use lower-case, hyphen-separated formatting. These same names are used as keys in the ExpModel.ActionFlags map populated by cli/cmd/create.go. When persisting experiment metadata in data/experiment.go, column names mirror these CLI flag names (using snake_case for database compatibility), ensuring traceability from command-line invocation through to stored experiment records.

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