--- title: Chaos Proxy in Kubernetes shortTitle: Chaos Proxy in K8s description: Deploy MockServer as a chaos proxy in Kubernetes to inject faults into service-to-service and external API calls using forward expectations with chaos profiles. layout: page pageOrder: 2 section: 'Chaos Testing' subsection: true sitemap: priority: 0.8 changefreq: 'monthly' lastmod: 2026-05-30T08:00:00+00:00 keywords: chaos testing kubernetes, fault injection kubernetes, sidecar proxy chaos, egress proxy fault injection, test resilience kubernetes, simulate dependency failure schema_faq: - question: "How do I inject faults into a service's external API calls in Kubernetes?" answer: "Deploy MockServer as a sidecar or standalone proxy in your Kubernetes cluster, set your application's HTTP_PROXY / HTTPS_PROXY environment variables to point at MockServer, and create forward expectations with chaos profiles for the target hosts. MockServer forwards requests to the real upstream and probabilistically injects errors or latency into the responses it relays back." - question: "How do I make a dependency intermittently fail in a Kubernetes cluster?" answer: "Place MockServer between your application and the dependency using a Kubernetes Service that routes to MockServer instead of the real backend. Create a forward expectation that sends requests to the real upstream host and attach a chaos profile with an errorStatus (e.g. 503), an errorProbability (e.g. 0.3 for 30% failures), and optionally a latency delay. Only matched requests get chaos; other traffic passes through normally." - question: "Does MockServer support transparent traffic interception in Kubernetes?" answer: "Yes. When transparentProxyEnabled is set to true, MockServer can intercept traffic redirected by iptables REDIRECT rules, using the Host header to determine the forwarding target. See the Service Mesh / Sidecar Mode page for setup details. Alternatively, you can use explicit routing via HTTP_PROXY / HTTPS_PROXY environment variables, a Kubernetes Service pointing at MockServer, or the proxyRemoteHost / proxyRemotePort configuration." - question: "How do I intercept HTTPS traffic through MockServer in Kubernetes?" answer: "For HTTPS interception, clients must trust MockServer's Certificate Authority (CA). MockServer dynamically generates TLS certificates signed by its CA. You can use the default CA certificate bundled with MockServer or generate a unique one with dynamicallyCreateCertificateAuthorityCertificate. Add the CA certificate to your application's trust store — for JVM apps use keytool, for others mount the CA PEM and configure the system or application trust store. See the TLS Configuration page for details." ---

MockServer can be deployed as a chaos proxy in Kubernetes to inject faults (errors, latency, stateful failures) into real service-to-service calls and external API calls. Instead of mocking a dependency, you route traffic through MockServer and let it forward requests to the real upstream while probabilistically injecting failures into the responses.

This is useful for:

- Testing how your service handles an unreliable internal dependency (e.g. a payment service returning 503s)
- Simulating external API rate limiting (e.g. a third-party API returning 429 with `Retry-After`)
- Verifying timeout handling when an upstream becomes slow
- Testing circuit breakers, retries, and fallback behaviour under realistic conditions

This page builds on the Chaos Testing & Fault Injection page, which covers the `chaos` profile fields in detail. Here we focus on deployment patterns in Kubernetes that put MockServer in the request path so chaos profiles apply to real upstream traffic.

## How It Works

1. Deploy MockServer in your Kubernetes cluster (standalone Deployment, sidecar container, or via the Helm chart)
2. Route your application's traffic through MockServer — using a Kubernetes Service, `HTTP_PROXY`/`HTTPS_PROXY` environment variables, or `proxyRemoteHost`/`proxyRemotePort` configuration
3. Create forward expectations with chaos profiles — MockServer forwards matched requests to the real upstream and injects faults according to the chaos profile
4. Unmatched requests pass through normally (when `attemptToProxyIfNoMatchingExpectation` is `true`, which is the default)

MockServer operates at the HTTP layer (L7). It does not transparently intercept traffic at the network layer (L3/L4) — traffic must be explicitly routed through it. It does not use iptables rules or a service mesh sidecar protocol.

Chaos profiles apply to forward action types: `httpForward`, forward template, forward class callback, forward with override (`httpOverrideForwardedRequest`), and forward with validation. They do not apply to forward object callbacks or the unmatched proxy pass-through path. See the compatibility table on the Chaos Testing page.

## Pattern 1: Reverse Proxy in Front of a Dependency

Route a Kubernetes Service through MockServer so that calls to a dependency go via MockServer, which forwards them to the real backend with chaos injection.

### Kubernetes manifests

Deploy MockServer as a standalone Deployment with a Service. Your application calls the MockServer Service instead of the real dependency.

    ---
    # MockServer Deployment — acts as a reverse proxy for the payment service
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: payment-chaos-proxy
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: payment-chaos-proxy
      template:
        metadata:
          labels:
            app: payment-chaos-proxy
        spec:
          containers:
            - name: mockserver
              image: mockserver/mockserver:mockserver-{{ site.mockserver_version }}
              ports:
                - containerPort: 1080
              env:
                - name: MOCKSERVER_LOG_LEVEL
                  value: "INFO"
    ---
    # Service that your application calls instead of the real payment-service
    apiVersion: v1
    kind: Service
    metadata:
      name: payment-service-chaos
    spec:
      selector:
        app: payment-chaos-proxy
      ports:
        - port: 8080
          targetPort: 1080

### Forward expectation with chaos

Create an expectation that matches requests to the payment service and forwards them to the real backend, injecting 503 errors on 30% of requests with 200ms of added latency:

    PUT /mockserver/expectation

    {
      "httpRequest": {
        "path": "/payments/.*"
      },
      "httpForward": {
        "host": "payment-service.production.svc.cluster.local",
        "port": 8080,
        "scheme": "HTTP"
      },
      "chaos": {
        "errorStatus": 503,
        "errorProbability": 0.3,
        "latency": {
          "timeUnit": "MILLISECONDS",
          "value": 200
        }
      },
      "times": {
        "unlimited": true
      }
    }

Your application connects to `payment-service-chaos:8080` instead of `payment-service:8080`. MockServer forwards every request to the real `payment-service.production.svc.cluster.local:8080` and injects errors and latency according to the chaos profile. When you are done testing, point your application back to the real service.

## Pattern 2: Egress / Forward Proxy

Configure your application to use MockServer as its HTTP(S) proxy by setting `HTTP_PROXY` and `HTTPS_PROXY` environment variables. This lets you inject chaos into calls to external APIs without changing hostnames or Services.

### Application Deployment with proxy env vars

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-app
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: my-app
      template:
        metadata:
          labels:
            app: my-app
        spec:
          containers:
            - name: app
              image: my-app:latest
              env:
                - name: HTTP_PROXY
                  value: "http://mockserver.chaos.svc.cluster.local:1080"
                - name: HTTPS_PROXY
                  value: "http://mockserver.chaos.svc.cluster.local:1080"
                - name: NO_PROXY
                  value: "localhost,127.0.0.1,*.svc.cluster.local"

With these environment variables, your application's HTTP client sends outbound requests via MockServer. Use `NO_PROXY` to exclude internal cluster traffic you do not want to route through MockServer.

### Forward expectation for an external API

Inject 429 rate-limit errors on 50% of requests to `api.stripe.com`:

    PUT /mockserver/expectation

    {
      "httpRequest": {
        "headers": {
          "Host": ["api.stripe.com"]
        }
      },
      "httpForward": {
        "host": "api.stripe.com",
        "port": 443,
        "scheme": "HTTPS"
      },
      "chaos": {
        "errorStatus": 429,
        "errorProbability": 0.5,
        "retryAfter": "30"
      },
      "times": {
        "unlimited": true
      }
    }

Requests to other hosts pass through normally (the default `attemptToProxyIfNoMatchingExpectation` is `true`). Only requests matching the expectation receive chaos injection.

## Pattern 3: Sidecar Proxy

Run MockServer as a sidecar container in the same pod as your application. This keeps the proxy co-located with the application and avoids a separate Deployment.

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: order-service
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: order-service
      template:
        metadata:
          labels:
            app: order-service
        spec:
          containers:
            # Your application
            - name: order-service
              image: order-service:latest
              env:
                - name: INVENTORY_SERVICE_URL
                  value: "http://localhost:1080"
            # MockServer sidecar — forwards to the real inventory service
            - name: mockserver-sidecar
              image: mockserver/mockserver:mockserver-{{ site.mockserver_version }}
              ports:
                - containerPort: 1080
              env:
                - name: MOCKSERVER_LOG_LEVEL
                  value: "INFO"
                # Forward all unmatched requests to the real inventory service
                - name: MOCKSERVER_PROXY_REMOTE_HOST
                  value: "inventory-service.production.svc.cluster.local"
                - name: MOCKSERVER_PROXY_REMOTE_PORT
                  value: "8080"

With `MOCKSERVER_PROXY_REMOTE_HOST` and `MOCKSERVER_PROXY_REMOTE_PORT` set, MockServer forwards all unmatched requests to the real inventory service. Add expectations with chaos profiles for specific paths to inject faults:

    PUT /mockserver/expectation

    {
      "httpRequest": {
        "path": "/inventory/check"
      },
      "httpForward": {
        "host": "inventory-service.production.svc.cluster.local",
        "port": 8080,
        "scheme": "HTTP"
      },
      "chaos": {
        "errorStatus": 500,
        "errorProbability": 1.0,
        "succeedFirst": 3,
        "failRequestCount": 5
      },
      "times": {
        "unlimited": true
      }
    }

This example lets the first 3 requests to `/inventory/check` succeed, then injects 500 errors on requests 4 through 8, and recovers to normal responses after that. This is useful for testing retry logic and circuit breakers. See Stateful / Count-Based Faults for more on `succeedFirst` and `failRequestCount`.

## Deploying with Helm

The MockServer Helm chart deploys a standalone MockServer instance. You can configure it as a reverse proxy using `app.proxyRemoteHost` and `app.proxyRemotePort` (which map to the `PROXY_REMOTE_HOST` and `PROXY_REMOTE_PORT` environment variables in the Deployment template), and inject a `mockserver.properties` file via the inline config feature for additional settings.

    # Install MockServer as a reverse proxy for the inventory service
    helm install inventory-chaos oci://ghcr.io/mock-server/charts/mockserver \
      --set app.proxyRemoteHost="inventory-service.production.svc.cluster.local" \
      --set app.proxyRemotePort="8080" \
      --set service.type=ClusterIP

Then create forward expectations with chaos profiles via the MockServer API (using `curl`, a client library, or the dashboard UI).

The Helm chart does not have a built-in sidecar template. For sidecar deployments, add MockServer as a container directly in your application's Deployment manifest as shown in Pattern 3 above.

## HTTPS Interception

MockServer can intercept and forward HTTPS traffic, but clients must trust MockServer's Certificate Authority (CA) for this to work. MockServer dynamically generates TLS certificates for upstream hosts, signed by its CA. Without trust, clients will reject MockServer's certificates with TLS handshake errors.

How to establish trust:

- Default CA: MockServer ships with a default CA certificate (`CertificateAuthorityCertificate.pem`) bundled in the JAR. Add this certificate to your application's trust store.
- Dynamic CA: Set `MOCKSERVER_DYNAMICALLY_CREATE_CERTIFICATE_AUTHORITY_CERTIFICATE=true` and `MOCKSERVER_DIRECTORY_TO_SAVE_DYNAMIC_SSL_CERTIFICATE=/certs` to generate a unique CA on startup. Mount the output directory as a shared volume between the MockServer container and your application container, then add the generated CA PEM to your application's trust store.
- Custom CA: Provide your own CA certificate and private key via `mockserver.certificateAuthorityCertificate` and `mockserver.certificateAuthorityPrivateKey`.

For JVM applications, add the CA certificate to the JVM trust store:

    keytool -import -trustcacerts -keystore $JAVA_HOME/lib/security/cacerts \
      -storepass changeit -noprompt -alias mockserver-ca \
      -file /certs/CertificateAuthorityCertificate.pem

For non-JVM applications, mount the CA PEM file and configure the application or OS trust store (e.g. `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, or `NODE_EXTRA_CA_CERTS`).

See the TLS Configuration page for full details on MockServer's TLS architecture, including mTLS and custom certificate chains.

Important: MockServer performs L7 (HTTP/HTTPS) proxying only. It does not support L3/L4 transparent TCP interception or raw packet manipulation.

## Selective Chaos Scope

Chaos is injected only for requests that match an expectation with a chaos profile. All other requests are either handled by other expectations or, if `attemptToProxyIfNoMatchingExpectation` is `true` (the default), forwarded to the original destination unchanged.

This means you can inject chaos into specific hosts, paths, or header combinations while leaving everything else untouched. For example, you could inject latency into calls to `/api/slow-endpoint` while leaving `/api/fast-endpoint` and all other paths operating normally.

The `attemptToProxyIfNoMatchingExpectation` property (environment variable: `MOCKSERVER_ATTEMPT_TO_PROXY_IF_NO_MATCHING_EXPECTATION`) controls what happens to unmatched requests. When `true` (default), unmatched requests are forwarded to their original destination based on the Host header. When `false`, unmatched requests receive a 404. See Configuration Properties for details.

## FAQ

Deploy MockServer as a sidecar or standalone proxy in your Kubernetes cluster, set your application's `HTTP_PROXY` / `HTTPS_PROXY` environment variables to point at MockServer, and create forward expectations with chaos profiles for the target hosts. MockServer forwards requests to the real upstream and probabilistically injects errors or latency into the responses it relays back. See Pattern 2: Egress / Forward Proxy above.

Place MockServer between your application and the dependency using a Kubernetes Service that routes to MockServer instead of the real backend. Create a forward expectation that sends requests to the real upstream host and attach a chaos profile with an `errorStatus` (e.g. 503), an `errorProbability` (e.g. 0.3 for 30% failures), and optionally a `latency` delay. Only matched requests get chaos; other traffic passes through normally. See Pattern 1: Reverse Proxy above.

No. MockServer operates at the HTTP layer (L7) and requires explicit routing. Traffic must be directed to MockServer via `HTTP_PROXY` / `HTTPS_PROXY` environment variables, a Kubernetes Service, or the `proxyRemoteHost` / `proxyRemotePort` configuration. It does not intercept traffic transparently at the network layer (L3/L4) and does not use iptables or a service mesh sidecar protocol.

Clients must trust MockServer's Certificate Authority (CA). MockServer dynamically generates TLS certificates signed by its CA. You can use the default CA certificate bundled with MockServer, generate a unique one with `dynamicallyCreateCertificateAuthorityCertificate`, or provide your own CA. Add the CA certificate to your application's trust store. See HTTPS Interception above and the TLS Configuration page.

## Related Pages

- Chaos Testing & Fault Injection — chaos profile fields, examples, and compatibility table
- Driving MockServer from Chaos Orchestrators — Chaos Toolkit, AWS FIS, Azure Chaos Studio and LitmusChaos recipes against the control plane
- Network Latency Debugging — use the same in-path deployment to capture per-request timing, export HAR with breakdowns, and track latency percentiles
- TLS Configuration — CA certificates, mTLS, and TLS trust chains
- Configuration Properties — all properties including `proxyRemoteHost`, `proxyRemotePort`, and `attemptToProxyIfNoMatchingExpectation`
- Isolating Single Service — using MockServer as a reverse proxy to isolate a service for debugging