How to Execute Chaos Experiments Remotely via SSH Channel in ChaosBlade

ChaosBlade enables you to execute chaos experiments remotely via SSH channel by passing the --channel=ssh flag, which delegates execution to the SSH executor that establishes a secure connection, deploys the binary, and runs commands on the target host without requiring a resident agent.

ChaosBlade is an open-source chaos engineering platform that supports multiple execution modes for fault injection. When targeting infrastructure where you cannot install a permanent agent, you can execute chaos experiments remotely via SSH channel. This approach leverages the --channel=ssh flag to route commands through the SSH executor, enabling secure, on-demand fault injection against any reachable Linux host.

How the SSH Channel Works

The SSH channel implementation follows a delegation pattern across the ChaosBlade executor stack. When you specify --channel=ssh, the core CLI builds an experiment model containing the channel flag, and the appropriate executor instantiates an SSHExecutor to handle remote communication.

CLI to Experiment Model

In cli/cmd/create.go, the blade create command parses user flags and constructs an ExpModel. When --channel=ssh is present, the model's ActionFlags map contains channel: "ssh":

// From cli/cmd/create.go
model.ActionFlags["channel"] = "ssh"
model.ActionFlags["target"] = "192.168.10.5"

Executor Selection and Delegation

Each domain-specific executor checks the channel flag and delegates to the SSH executor when appropriate. In exec/os/executor.go, the OS executor detects the SSH channel and instantiates exec.SSHExecutor:

// From exec/os/executor.go lines 42-48
if model.ActionFlags["channel"] == "ssh" {
    sshExecutor := &exec.SSHExecutor{}
    return sshExecutor.Exec(uid, ctx, model)
}

This pattern repeats across the middleware executor (exec/middleware/executor.go lines 42-48), cloud executor (exec/cloud/executor.go lines 42-48), and Kubernetes compose executor (exec/kubernetes/executor_compose.go lines 45-50), providing consistent SSH support across all target types.

Remote Execution via SSHExecutor

The SSHExecutor implementation resides in the external module chaosblade-exec-os (version v1.8.0) within exec/ssh.go. This executor:

• Establishes an SSH connection to the target host using configured credentials
• Copies the ChaosBlade binary to the remote host (or uses a pre-installed binary)
• Constructs the chaos command using the same arguments passed locally
• Executes the command remotely via ssh <user>@<host> <command>
• Captures the JSON-encoded spec.Response from the remote process and returns it to the local client

Executing Remote Chaos Experiments via SSH

To execute chaos experiments remotely via SSH channel, append the --channel=ssh flag to any standard blade create command and specify the target host using --target.

Running a CPU Burn Experiment on a Remote Host

The following command initiates a CPU burn experiment on a remote Linux host at 192.168.10.5:

blade create cpu burn \
    --target=192.168.10.5 \
    --channel=ssh \
    --cpu-percent=80 \
    --timeout=60

The CLI constructs an ExpModel where ActionFlags["channel"]="ssh" and Target="192.168.10.5". The OS executor detects the SSH flag, creates an SSHExecutor, and runs the remote command chaos_os cpu burn --target=192.168.10.5 --cpu-percent=80 --timeout=60.

Destroying Remote Experiments

To stop a remote experiment, use the blade destroy command with the same channel and target flags, plus the experiment UID returned by the create command:

blade destroy cpu burn \
    --target=192.168.10.5 \
    --channel=ssh \
    --uid=1234567890abcdef

The destroy operation follows the same SSH delegation path, sending the destroy command to the remote host to clean up the injected fault.

Programmatic Execution with the Go SDK

You can also execute chaos experiments remotely via SSH channel programmatically using the ChaosBlade Go SDK. Instantiate an ExpModel with the channel flag set to ssh:

import (
    "context"
    "github.com/chaosblade-io/chaosblade-spec-go/spec"
    "github.com/chaosblade-io/chaosblade-spec-go/util"
)

func runRemoteCpuBurn() (*spec.Response, error) {
    model := &spec.ExpModel{
        Target:     "192.168.10.5",
        ActionName: "burn",
        ActionFlags: map[string]string{
            "cpu-percent": "80",
            "channel":     "ssh",  // Enable SSH channel
        },
    }
    uid := util.GenerateUID()
    ctx := context.Background()
    
    // Use the OS executor which will delegate to SSHExecutor
    executor := exec.NewExecutor()
    return executor.Exec(uid, ctx, model), nil
}

The SDK mirrors the CLI behavior: when channel is set to ssh, the executor delegates to SSHExecutor to handle the remote connection.

Key Source Files and Implementation Details

The SSH channel implementation spans multiple modules across the ChaosBlade repository:

Module	File	Purpose
Core CLI	cli/cmd/create.go	Parses the --channel=ssh flag and populates the ExpModel.ActionFlags map.
OS Executor	exec/os/executor.go (lines 42-48)	OS executor that checks for channel=ssh and instantiates SSHExecutor.
Middleware Executor	exec/middleware/executor.go (lines 42-48)	Middleware executor with identical SSH delegation logic.
Kubernetes Compose Executor	exec/kubernetes/executor_compose.go (lines 45-50)	Composite executor supporting SSH for pod-level experiments.
Cloud Executor	exec/cloud/executor.go (lines 42-48)	Cloud executor supporting SSH for cloud instance targets.
SSH Executor (external)	chaosblade-exec-os/exec/ssh.go (v1.8.0)	Core SSHExecutor implementing connection establishment, binary transfer, and remote command execution.
Spec Utilities	spec/response.go	JSON response handling shared between local and remote runs.

These files illustrate how the SSH channel flag propagates from the CLI through the executor stack to the remote execution layer, enabling seamless chaos testing on any reachable host.

Summary

• ChaosBlade supports remote execution via the --channel=ssh flag, enabling chaos experiments on any SSH-accessible host without requiring a resident agent.
• The execution flow moves from CLI parsing in cli/cmd/create.go through domain-specific executors (exec/os/executor.go, exec/middleware/executor.go, etc.) that delegate to SSHExecutor when the SSH channel is specified.
• Remote implementation is handled by the SSHExecutor in the chaosblade-exec-os module, which manages SSH connections, binary deployment, and JSON response handling.
• Both CLI and Go SDK support SSH channel execution using identical experiment models and flag configurations.

Frequently Asked Questions

Do I need to install ChaosBlade on the remote host before running experiments?

No. The SSHExecutor automatically copies the ChaosBlade binary to the remote host during the first connection if it is not already present. You can also pre-install the binary to skip the deployment step and reduce experiment startup time.

How does authentication work for the SSH channel?

The SSH channel uses standard SSH authentication mechanisms. You can configure key-based authentication by ensuring your local SSH agent has the appropriate keys, or use password authentication if configured in your SSH client. The SSHExecutor in chaosblade-exec-os/exec/ssh.go leverages the standard Go SSH client libraries to establish the connection.

Can I use the SSH channel with Kubernetes or cloud experiments?

Yes. The SSH channel works across all executor types. The Kubernetes compose executor (exec/kubernetes/executor_compose.go) and cloud executor (exec/cloud/executor.go) both check for the channel=ssh flag and delegate to SSHExecutor when specified. This allows you to run node-level chaos experiments on Kubernetes workers or cloud instances via SSH even when direct API access is unavailable.

What is the performance impact of using SSH compared to local execution?

SSH channel execution introduces network latency for the initial connection and binary deployment (if not cached), plus the overhead of SSH encryption. However, the actual chaos experiment runs at native speed on the remote host. For long-running experiments (network delay, CPU burn, memory pressure), the initial SSH setup overhead is negligible. For very short experiments, consider pre-installing the binary to eliminate deployment time.

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