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). Traffic can reach it either through explicit routing (a Kubernetes Service, HTTP_PROXY / HTTPS_PROXY environment variables, or proxyRemoteHost / proxyRemotePort) or via transparent interception — when transparentProxyEnabled is set, MockServer accepts traffic redirected to it by iptables REDIRECT / TPROXY rules and uses the original destination (or the Host header) to choose the forwarding target. See the Service Mesh / Sidecar Mode page for transparent-interception setup.

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-7.0.0
          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.

Scaling beyond one replica: the manifests above run a single replica, so the in-line expectation chaos and any PUT /mockserver/serviceChaos registration apply to that one pod. If you scale the MockServer Deployment to multiple replicas behind a Service, run the clustered HA variant so that service-scoped HTTP, TCP and gRPC chaos registrations replicate across every replica — otherwise a control-plane registration only affects the single pod that received it. See Fleet-wide Chaos.

 

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-7.0.0
          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 proxies and mocks at L7 (HTTP/HTTPS), but it can be placed in-path transparently via Linux iptables REDIRECT / TPROXY (set transparentProxyEnabled to true — see Service Mesh / Sidecar Mode), and it can inject transport-layer faults via TCP-Layer Chaos. It does not rewrite or manipulate arbitrary raw (non-HTTP) packets.

 

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.

Yes. Set transparentProxyEnabled to true and MockServer intercepts traffic redirected to it by iptables REDIRECT / TPROXY rules, using the original destination (or the Host header) to choose the forwarding target — see the Service Mesh / Sidecar Mode page for setup. Alternatively, route traffic explicitly via HTTP_PROXY / HTTPS_PROXY environment variables, a Kubernetes Service, or the proxyRemoteHost / proxyRemotePort configuration.

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