NetworkChaos API

API reference for NetworkChaos CRD

NetworkChaos allows you to simulate various network failures including delays, packet loss, corruption, duplication, partitions, and bandwidth limitations.

API Version and Kind

apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos

Metadata

Standard Kubernetes object metadata.

metadata.name · string · required

Name of the NetworkChaos resource.

metadata.namespace · string

Namespace of the NetworkChaos resource.

Spec Fields

NetworkChaosSpec

action · NetworkChaosAction · required

Specific network chaos action.

Enum values:

• netem - Combination of delay, loss, duplicate, corrupt
• delay - Add network delay
• loss - Drop packets
• duplicate - Duplicate packets
• corrupt - Corrupt packet data
• partition - Create network partition
• bandwidth - Limit bandwidth

Default: delay

selector · PodSelectorSpec · required

Selector for targeting pods. Inherits all fields from PodSelector (inline). See Common Types.

mode · SelectorMode · required

Mode to run chaos action: one, all, fixed, fixed-percent, random-max-percent

value · string

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

duration · *string

Duration of the chaos action. Format: "300ms", "1.5h", "2h45m"

Valid time units: ns, us, ms, s, m, h

device · string

Network device to be affected (e.g., eth0). If not specified, the first non-loopback device is used.

direction · Direction · default: "to"

Traffic direction to apply the action.

Enum values:

• to - Traffic from source to target
• from - Traffic from target to source
• both - Traffic in both directions

Applies to netem and partition actions.

target · *PodSelector

Target network peer. When specified, chaos only affects traffic between source and target.

Applies to netem and partition actions.

target:
  selector:
    namespaces:
      - default
    labelSelectors:
      app: database
  mode: all

targetDevice · string

Network device to be affected in target scope.

externalTargets · []string

Network targets outside Kubernetes cluster.

externalTargets:
  - 8.8.8.8
  - example.com

remoteCluster · string

Remote cluster where chaos will be deployed.

TcParameter (inline fields)

Traffic control parameters embedded in NetworkChaosSpec.

delay · *DelaySpec

Delay specification (for delay and netem actions).

loss · *LossSpec

Packet loss specification (for loss and netem actions).

duplicate · *DuplicateSpec

Packet duplication specification (for duplicate and netem actions).

corrupt · *CorruptSpec

Packet corruption specification (for corrupt and netem actions).

bandwidth · *BandwidthSpec

Bandwidth limitation specification (for bandwidth action).

rate · *RateSpec

Rate control specification.

Network Action Specifications

DelaySpec

Defines network delay parameters.

latency · string · required

Base latency to add. Format: "10ms", "100ms", "1s"

Pattern: ^[0-9]+(\.[0-9]+)?(ns|us|ms|s|m|h)$

delay:
  latency: "100ms"

correlation · string · default: "0"

Correlation between successive delay values (0-100). Controls how much the previous delay affects the current one.

correlation: "50"  # 50% correlation

jitter · string · default: "0ms"

Random variation in delay. Format: "10ms"

Pattern: ^[0-9]+(\.[0-9]+)?(ns|us|ms|s|m|h)$

jitter: "10ms"  # ±10ms variation

reorder · *ReorderSpec

Packet reordering configuration.

ReorderSpec

reorder · string · required

Percentage of packets to reorder (0-100).

correlation · string · default: "0"

Correlation for reordering.

gap · int · required

Distance between reordered packets.

LossSpec

Defines packet loss parameters.

loss · string · required

Percentage of packets to drop (0-100).

loss:
  loss: "25"  # Drop 25% of packets

correlation · string · default: "0"

Correlation between successive loss events.

DuplicateSpec

Defines packet duplication parameters.

duplicate · string · required

Percentage of packets to duplicate (0-100).

duplicate:
  duplicate: "10"  # Duplicate 10% of packets

correlation · string · default: "0"

Correlation between successive duplication events.

CorruptSpec

Defines packet corruption parameters.

corrupt · string · required

Percentage of packets to corrupt (0-100).

corrupt:
  corrupt: "5"  # Corrupt 5% of packets

correlation · string · default: "0"

Correlation between successive corruption events.

BandwidthSpec

Defines bandwidth limitation parameters using Token Bucket Filter.

rate · string · required

Speed limit. Units: bit, kbit, mbit, gbit, tbit, bps, kbps, mbps, gbps, tbps

Note: bps means bytes per second.

bandwidth:
  rate: "1mbps"  # Limit to 1 megabit per second

limit · uint32 · required

Number of bytes that can be queued waiting for tokens.

Minimum: 1

limit: 1000

buffer · uint32 · required

Maximum bytes that tokens can be available for instantaneously.

Minimum: 1

buffer: 1000

peakrate · *uint64

Maximum depletion rate of the bucket. Only necessary for perfect millisecond timescale shaping.

Minimum: 0

minburst · *uint32

Size of the peakrate bucket. Should be set to MTU for perfect accuracy.

Minimum: 0

RateSpec

rate · string · required

Speed limit with units (bit, kbit, mbit, gbit, tbit, bps, kbps, mbps, gbps, tbps).

Status Fields

NetworkChaosStatus

conditions · []ChaosCondition

Current conditions. See ChaosStatus.

experiment · ExperimentStatus

Last known experiment state.

instances · map[string]int64

PodNetworkChaos generation for each affected pod.

Examples

Network Delay

apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos
metadata:
  name: network-delay
  namespace: chaos-mesh
spec:
  action: delay
  mode: one
  selector:
    namespaces:
      - default
    labelSelectors:
      app: web
  delay:
    latency: "100ms"
    jitter: "10ms"
    correlation: "50"
  duration: "30s"

Packet Loss

apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos
metadata:
  name: network-loss
spec:
  action: loss
  mode: fixed
  value: "2"
  selector:
    namespaces:
      - production
    labelSelectors:
      tier: backend
  loss:
    loss: "25"
    correlation: "25"
  duration: "1m"

Network Partition

apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos
metadata:
  name: network-partition
spec:
  action: partition
  mode: all
  selector:
    namespaces:
      - default
    labelSelectors:
      app: frontend
  direction: both
  target:
    selector:
      namespaces:
        - default
      labelSelectors:
        app: database
    mode: all
  duration: "1m"

Bandwidth Limit

apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos
metadata:
  name: bandwidth-limit
spec:
  action: bandwidth
  mode: one
  selector:
    namespaces:
      - default
  bandwidth:
    rate: "1mbps"
    limit: 20000
    buffer: 10000
  duration: "2m"

Combined Netem Actions

apiVersion: chaos-mesh.org/v1alpha1
kind: NetworkChaos
metadata:
  name: netem-combined
spec:
  action: netem
  mode: all
  selector:
    namespaces:
      - default
    labelSelectors:
      app: api
  delay:
    latency: "50ms"
    jitter: "10ms"
  loss:
    loss: "10"
  duplicate:
    duplicate: "5"
  corrupt:
    corrupt: "2"
  duration: "1m"

Next Steps

IOChaos API

File system and I/O fault injection

Common Types

Shared types and selectors