HTTPChaos

Inject HTTP failures and manipulate HTTP requests/responses

HTTPChaos allows you to intercept and manipulate HTTP traffic to test how your application handles HTTP-level failures, delays, and data corruption.

Supported Actions

HTTPChaos supports multiple HTTP manipulation actions:

• abort: Abort HTTP connections
• delay: Add latency to HTTP requests or responses
• replace: Replace HTTP request/response content (path, method, status code, body, headers, queries)
• patch: Patch/append HTTP content (body, headers, queries)

Configuration

Basic Example

kind: HTTPChaos
apiVersion: chaos-mesh.org/v1alpha1
metadata:
  name: nginx-http-patch
spec:
  selector:
    namespaces:
      - default
    labelSelectors:
      app: nginx
  mode: all
  target: Response
  patch:
    body:
      type: JSON
      value: '{"status":"Failed","reason":"hacked by Chaos Mesh"}'
  port: 80
  path: '*'

Spec Fields

selector · PodSelectorSpec · required

Specifies the target pods for the chaos experiment. See PodChaos documentation for selector details.

mode · string · required

Selection mode: one, all, fixed, fixed-percent, or random-max-percent

target · string · required

Specifies whether to target requests or responses:

• Request: Manipulate HTTP requests
• Response: Manipulate HTTP responses

port · int32 · required

Target port to proxy and inject chaos

path · string

URI path pattern to match. Supports wildcards (e.g., "/api/*", "*")

method · string

HTTP method to match (e.g., GET, POST, PUT, DELETE)

code · int32

HTTP status code to match (only applicable when target is Response). Example: 200, 404, 500

request_headers · map[string]string

Request headers to match. Key-value pairs of header name and value.

response_headers · map[string]string

Response headers to match. Key-value pairs of header name and value.

duration · string

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

Action Fields

abort · bool

If true, abort the HTTP connection

delay · string

Delay to add to HTTP request/response. Format: “300ms”, “2s”. Valid units: ns, us, ms, s, m, h.

replace · ReplaceActions

Replace HTTP request/response content

Show ReplaceActions fields

path · string

Replace URI path (Request only)

method · string

Replace HTTP method (Request only). Example: "POST"

code · int32

Replace HTTP status code (Response only). Example: 500

body · []byte

Replace HTTP body content

queries · map[string]string

Replace URI query parameters (Request only). Example: {"foo": "unknown"} changes /?foo=bar to /?foo=unknown

headers · map[string]string

Replace HTTP headers. Key-value pairs of header name and value.

patch · PatchActions

Patch/append HTTP request/response content

Show PatchActions fields

body · PatchBodyAction

Patch HTTP body

Show PatchBodyAction fields

type · string · required

Patch type. Currently only supports "JSON" (merge patch JSON per RFC 7396)

value · string · required

JSON patch content

queries · [][]string

Append URI query parameters (Request only). Example: [["foo", "bar"], ["foo", "unknown"]]

headers · [][]string

Append HTTP headers. Example: [["Set-Cookie", "<one cookie>"], ["Set-Cookie", "<another cookie>"]]

tls · TLSConfig

TLS configuration for HTTPS traffic

Show TLSConfig fields

secretName · string · required

Name of Kubernetes secret containing TLS certificates

secretNamespace · string · required

Namespace of the secret

certName · string · required

Key name for certificate in secret (e.g., "tls.crt")

keyName · string · required

Key name for private key in secret (e.g., "tls.key")

caName · string

Key name for CA certificate in secret (e.g., "ca.crt")

remoteCluster · string

Remote cluster where chaos will be deployed

Examples

Patch Response Body

Replace JSON response with custom content:

kind: HTTPChaos
apiVersion: chaos-mesh.org/v1alpha1
metadata:
  name: nginx-http-patch
spec:
  selector:
    namespaces:
      - default
    labelSelectors:
      app: nginx
  mode: all
  target: Response
  patch:
    body:
      type: JSON
      value: '{"status":"Failed","reason":"hacked by Chaos Mesh"}'
  port: 80
  path: '*'

Add Response Delay

Add 2 second delay to all responses:

apiVersion: chaos-mesh.org/v1alpha1
kind: HTTPChaos
metadata:
  name: http-delay
spec:
  mode: one
  selector:
    labelSelectors:
      app: web-service
  target: Response
  port: 8080
  delay: "2s"
  duration: "60s"

Abort Connections

Abort HTTP connections to specific endpoint:

apiVersion: chaos-mesh.org/v1alpha1
kind: HTTPChaos
metadata:
  name: http-abort
spec:
  mode: one
  selector:
    labelSelectors:
      app: api-service
  target: Request
  port: 8080
  path: "/api/v1/users"
  method: POST
  abort: true
  duration: "120s"

Replace Status Code

Change successful responses to errors:

apiVersion: chaos-mesh.org/v1alpha1
kind: HTTPChaos
metadata:
  name: http-error-injection
spec:
  mode: one
  selector:
    labelSelectors:
      app: web-service
  target: Response
  port: 80
  code: 200
  replace:
    code: 500
    body: "Internal Server Error"
  duration: "60s"

Modify Request Headers

Add or replace request headers:

apiVersion: chaos-mesh.org/v1alpha1
kind: HTTPChaos
metadata:
  name: http-header-injection
spec:
  mode: one
  selector:
    labelSelectors:
      app: api-gateway
  target: Request
  port: 8080
  patch:
    headers:
      - ["X-Chaos", "true"]
      - ["X-Custom-Header", "test-value"]
  duration: "300s"

Modify Query Parameters

Replace query parameters:

apiVersion: chaos-mesh.org/v1alpha1
kind: HTTPChaos
metadata:
  name: http-query-replace
spec:
  mode: one
  selector:
    labelSelectors:
      app: search-service
  target: Request
  port: 8080
  path: "/search"
  replace:
    queries:
      limit: "10"
      offset: "0"
  duration: "180s"

Filter by Request Headers

Target only requests with specific headers:

apiVersion: chaos-mesh.org/v1alpha1
kind: HTTPChaos
metadata:
  name: http-header-filter
spec:
  mode: one
  selector:
    labelSelectors:
      app: api-service
  target: Request
  port: 8080
  request_headers:
    Authorization: "Bearer test-token"
  delay: "1s"
  duration: "120s"

Use Cases

API Error Handling

Test how your application handles HTTP errors by replacing status codes or aborting connections.

Latency Testing

Simulate slow API responses to test timeout handling and user experience under high latency.

Data Corruption

Use patch or replace actions to inject malformed responses and test input validation.

Authentication Testing

Modify authentication headers or tokens to test authorization and authentication error handling.

Rate Limiting

Combine with delay to simulate rate-limited APIs and test backoff/retry logic.

Best Practices

1. Target Specificity: Use path, method, and header filters to target specific endpoints
2. Start with Non-Critical Endpoints: Test on less critical API endpoints first
3. Use Appropriate Target:
   • Request for testing client-side error handling
   • Response for testing server response processing
4. Monitor Application Behavior: Watch for:
   • Timeout errors
   • Retry loops
   • Circuit breaker activation
   • Error logging
5. TLS Configuration: For HTTPS services, properly configure TLS secrets
6. Body Patching: When using JSON patch, ensure the patch is valid according to RFC 7396
7. Header Format: Use arrays of arrays for patch operations to support multiple headers with same name
8. Realistic Delays: Use delays that match real-world scenarios (100ms-2s for API calls)
9. Test Error Propagation: Verify errors are properly propagated through your service mesh or API gateway

Notes

• HTTPChaos uses a transparent proxy (tproxy) to intercept HTTP traffic
• The chaos daemon runs a proxy process inside the target pod’s network namespace
• Only HTTP/1.x traffic is supported (HTTP/2 support may vary)
• TLS inspection requires proper certificate configuration via the tls field
• Path matching supports wildcards but not full regex
• Multiple HTTPChaos experiments on the same pod/port can conflict
• The proxy adds minimal overhead but may affect high-throughput services
• Body replacement happens in memory - very large bodies may impact performance
• Query parameter replacement replaces the entire query string, patch appends to it