Common Types

Shared types and structures used across Chaos Mesh APIs

Chaos Mesh defines several common types that are shared across different chaos experiment CRDs. Understanding these types is essential for configuring chaos experiments.

Selector Types

PodSelector

Selects which pods to target for chaos injection.

selector · PodSelectorSpec · required

Pod selection criteria

mode · SelectorMode · required

Mode to run chaos action.

Enum values:

• one - Select one random pod
• all - Select all matching pods
• fixed - Select a fixed number of pods
• fixed-percent - Select a fixed percentage of pods
• random-max-percent - Select up to a random percentage of pods

value · string

Required when mode is fixed, fixed-percent, or random-max-percent.

• For fixed: Integer number of pods (e.g., “3”)
• For fixed-percent: Percentage from 0-100 (e.g., “50”)
• For random-max-percent: Max percentage from 0-100 (e.g., “75”)

PodSelectorSpec

Defines the criteria for selecting pods.

namespaces · []string

Namespaces to select pods from. If empty, defaults to the chaos experiment’s namespace.

labelSelectors · map[string]string

Label-based selector. Select pods matching all specified labels.

labelSelectors:
  app: nginx
  environment: production

annotationSelectors · map[string]string

Annotation-based selector. Select pods matching all specified annotations.

fieldSelectors · map[string]string

Field-based selector using Kubernetes field selectors.

fieldSelectors:
  status.phase: Running

expressionSelectors · []LabelSelectorRequirement

Set-based label selector expressions for advanced selection logic.

nodes · []string

Node names. Select only pods running on these nodes.

nodes:
  - node-1
  - node-2

pods · map[string][]string

Explicitly select pods by namespace and name.

pods:
  default:
    - pod-1
    - pod-2
  kube-system:
    - coredns-abc123

nodeSelectors · map[string]string

Select pods on nodes matching these label selectors.

nodeSelectors:
  node-role.kubernetes.io/worker: "true"

podPhaseSelectors · []string

Select pods in specific phases.

Valid values: Pending, Running, Succeeded, Failed, Unknown

podPhaseSelectors:
  - Running

ContainerSelector

Extends PodSelector to select specific containers within pods.

PodSelector · PodSelector · required

All fields from PodSelector are available (inline).

containerNames · []string

List of container names to affect. If not set, the first container will be selected.

containerNames:
  - main
  - sidecar

Status Types

ChaosStatus

Represents the current status of a chaos experiment.

conditions · []ChaosCondition

Current global conditions of the chaos experiment.

experiment · ExperimentStatus · required

Last known experiment state.

ChaosCondition

type · ChaosConditionType · required

Type of condition.

Values:

• Selected - Targets have been selected
• AllInjected - All targets have been injected
• AllRecovered - All targets have been recovered
• Paused - Experiment is paused

status · ConditionStatus · required

Status of the condition: True, False, or Unknown

reason · string

Human-readable reason for the condition.

ExperimentStatus

desiredPhase · DesiredPhase

Target phase for the experiment.

Values:

• Run - Make all targets injected
• Stop - Make all targets not injected

records · []Record

Tracking records for running status (stored in containerRecords field).

Record

Tracks the injection status of a single target.

id · string · required

Unique identifier for this record.

selectorKey · string · required

Key identifying which selector this record belongs to.

phase · Phase · required

Current phase of the target.

Values:

• Not Injected - Target is not injected yet
• Injected - Target is currently injected

injectedCount · int · required

Counter of successful injections.

recoveredCount · int · required

Counter of successful recoveries.

events · []RecordEvent

Essential details about injections and recoveries.

RecordEvent

type · RecordEventType · required

Event outcome.

Values:

• Succeeded - Operation succeeded
• Failed - Operation failed

operation · RecordEventOperation · required

Operation being performed.

Values:

• Apply - Injecting chaos
• Recover - Recovering from chaos

message · string

Detail message, such as failure reason.

timestamp · *metav1.Time · required

When the event was created.

Duration Format

Many chaos experiments accept a duration field specifying how long the chaos should last.

Format: A possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix.

Valid units: ns, us (or µs), ms, s, m, h

Examples:

• "300ms" - 300 milliseconds
• "1.5h" - 1.5 hours
• "2h45m" - 2 hours 45 minutes
• "-1.5h" - Negative 1.5 hours (for TimeChaos offset)

spec:
  duration: "30s"

Remote Cluster

Many chaos types support targeting remote clusters.

remoteCluster · string

Name of the remote cluster where chaos will be deployed. If not specified, chaos is applied to the local cluster.

Selector Mode Examples

Select One Random Pod

selector:
  namespaces:
    - default
  labelSelectors:
    app: myapp
mode: one

Select All Matching Pods

selector:
  namespaces:
    - production
  labelSelectors:
    tier: backend
mode: all

Select Fixed Number of Pods

selector:
  namespaces:
    - default
mode: fixed
value: "3"

Select Percentage of Pods

selector:
  namespaces:
    - default
  labelSelectors:
    app: api
mode: fixed-percent
value: "50"  # 50% of matching pods

Next Steps

PodChaos API

Pod-level chaos injection

NetworkChaos API

Network fault injection