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:
Retry-After)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.
HTTP_PROXY/HTTPS_PROXY environment variables, or proxyRemoteHost/proxyRemotePort configurationattemptToProxyIfNoMatchingExpectation 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.
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.
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: 1080Create 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.
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.
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.
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.
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.
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=ClusterIPThen 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.
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:
CertificateAuthorityCertificate.pem) bundled in the JAR. Add this certificate to your application's trust store.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.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.pemFor 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.
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.
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.
proxyRemoteHost, proxyRemotePort, and attemptToProxyIfNoMatchingExpectation