Helm chart¶
deploy/helm/fastmock installs one FastMock instance: a Deployment, separate Services for the data and admin
ports, and optionally bundled PostgreSQL and Valkey, Gateway API routes, a PodDisruptionBudget, an HPA,
NetworkPolicies, a ServiceMonitor and a PrometheusRule. It needs Kubernetes 1.30 or newer.
For many instances managed declaratively, see the operator instead.
- Install
- Upgrade and uninstall
- Values
- Production checklist
- Exposing the admin UI with Gateway API
- TLS and mTLS
- NetworkPolicy
- Upgrade notes
Install¶
The chart refuses to render without an admin token Secret, and in postgres mode without database and Valkey
connection settings.
1. Admin tokens. One name:role:sha256hex entry per line, under the key tokens:
fastmock hash-token --generate # or: docker run --rm fastmock:0.1.0 hash-token --generate
kubectl -n mocks create secret generic fastmock-admin-tokens \
--from-literal=tokens="$(printf 'ci:editor:%s\nops:admin:%s\ngrafana:viewer:%s\n' "$CI_HASH" "$OPS_HASH" "$VIEW_HASH")"
2a. External PostgreSQL and Valkey (recommended). Put the connection URLs into a Secret:
kubectl -n mocks create secret generic fastmock-storage \
--from-literal=database-url='postgres://fastmock:<password>@db.example.com:5432/fastmock?sslmode=verify-full' \
--from-literal=valkey-url='redis://:<password>@valkey.example.com:6379/'
helm upgrade --install fastmock deploy/helm/fastmock -n mocks \
--set image.repository=registry.example.com/platform/fastmock --set image.tag=0.1.0 \
--set admin.tokensSecret.name=fastmock-admin-tokens \
--set storage.database.existingSecret=fastmock-storage \
--set storage.valkey.existingSecret=fastmock-storage
Percent-encode special characters in passwords inside URLs.
2b. Bundled PostgreSQL 18 and Valkey 9 (single-instance StatefulSets, for test environments that do not have managed databases):
kubectl -n mocks create secret generic fastmock-db --from-literal=password="$(openssl rand -hex 24)"
kubectl -n mocks create secret generic fastmock-valkey --from-literal=password="$(openssl rand -hex 24)"
helm upgrade --install fastmock deploy/helm/fastmock -n mocks \
--set admin.tokensSecret.name=fastmock-admin-tokens \
--set postgresql.enabled=true --set postgresql.auth.existingSecret=fastmock-db \
--set valkey.enabled=true --set valkey.auth.existingSecret=fastmock-valkey
The passwords reach PostgreSQL, Valkey and FastMock through environment variables from the Secrets
(FASTMOCK_DATABASE_PASSWORD, FASTMOCK_VALKEY_PASSWORD), never through command lines or ConfigMaps. With
networkPolicy.storage: true (default) only FastMock pods may connect to the bundled databases.
2c. Memory mode (one replica, nothing persisted):
helm upgrade --install fastmock deploy/helm/fastmock -n mocks \
--set admin.tokensSecret.name=fastmock-admin-tokens \
--set storage.mode=memory --set replicaCount=1 --set pdb.enabled=false
3. Check it:
kubectl -n mocks rollout status deploy/fastmock
kubectl -n mocks port-forward svc/fastmock-admin 9090:9090 &
curl -s localhost:9090/readyz
Resource names use the release name when it contains fastmock, otherwise <release>-fastmock; below this is
called <fullname>. The Services are <fullname> (data, port service.port) and <fullname>-admin (admin, port
service.adminPort); with the release name fastmock they are fastmock and fastmock-admin. Inside the
cluster tests use http://fastmock.mocks.svc:8080 and http://fastmock-admin.mocks.svc:9090.
Upgrade and uninstall¶
- Rolling updates use
maxUnavailable: 0,maxSurge: 1. A pod that is being stopped withdraws readiness at once, keeps serving forshutdownDelay(5 s) while endpoints are updated, then drains open connections;terminationGracePeriodSeconds(45 s) must stay larger thanshutdownDelayplus 20 s of draining. - Configuration changes roll the pods automatically (the ConfigMap checksum is a pod annotation). Changing only
a Secret (for example the admin tokens) does not: run
kubectl -n mocks rollout restart deploy/fastmock. - Database migrations run at start-up and are additive; the first new pod migrates, old pods keep working.
helm uninstallkeeps the PersistentVolumeClaims of the bundled databases (data-<fullname>-postgresql-0,data-<fullname>-valkey-0); delete them to remove the data.
Values¶
Image and pods¶
| Key | Default | Meaning |
|---|---|---|
image.repository |
fastmock |
Server image repository. |
image.tag |
"" (chart appVersion) |
Image tag. Pin a version or digest in production. |
image.pullPolicy |
IfNotPresent |
|
imagePullSecrets |
[] |
List of {name: ...}; also used by the bundled databases. |
replicaCount |
2 |
Replicas when autoscaling is off. Use 1 with storage.mode: memory. |
resources |
requests 100m/64Mi, limits 2/512Mi |
Server container resources. |
podAnnotations, podLabels |
{} |
Extra pod metadata. |
nodeSelector, tolerations, affinity, topologySpreadConstraints |
empty | Scheduling. |
podSecurityContext |
non-root 65532, fsGroup 65532, RuntimeDefault seccomp |
Pod security context. |
securityContext |
non-root, no privilege escalation, read-only root FS, all capabilities dropped | Container security context. |
serviceAccount.create |
true |
Create a dedicated ServiceAccount (its token is not mounted). |
serviceAccount.name |
"" |
Name to create or use; required when create is false. |
terminationGracePeriodSeconds |
45 |
|
shutdownDelay |
5s |
FASTMOCK_SHUTDOWN_DELAY. |
logFormat |
json |
FASTMOCK_LOG_FORMAT (json or text). |
extraEnv |
[] |
Extra container env entries (any setting), for example FASTMOCK_CALLBACK_RETENTION. |
Admin API¶
| Key | Default | Meaning |
|---|---|---|
admin.tokensSecret.name |
"" (required) |
Secret with the admin token entries. Mounted read-only at /etc/fastmock/admin/tokens (FASTMOCK_ADMIN_TOKENS_FILE). |
admin.tokensSecret.key |
tokens |
Key inside the Secret. |
admin.allowedOrigins |
[] |
FASTMOCK_ADMIN_ALLOWED_ORIGINS: browser origins allowed besides the same origin. |
admin.uiDataPlaneUrls |
[] |
FASTMOCK_UI_DATA_PLANE_URL: exact public origins of the data plane that the web UI may call (its connect-src). |
Storage¶
| Key | Default | Meaning |
|---|---|---|
storage.mode |
postgres |
postgres or memory. |
storage.database.existingSecret |
"" |
Secret with the PostgreSQL URL; required in postgres mode unless postgresql.enabled. |
storage.database.secretKey |
database-url |
Key of the URL. |
storage.database.maxConnections |
10 |
FASTMOCK_DB_MAX_CONNECTIONS per pod. |
storage.valkey.existingSecret |
"" |
Secret with the Valkey URL; required in postgres mode unless valkey.enabled. |
storage.valkey.secretKey |
valkey-url |
Key of the URL. |
storage.valkey.prefix |
fastmock: |
FASTMOCK_VALKEY_PREFIX; give each release that shares a Valkey its own prefix. |
postgresql.enabled |
false |
Deploy a PostgreSQL StatefulSet with the release. |
postgresql.image |
docker.io/library/postgres:18.7-trixie |
|
postgresql.database, postgresql.username |
fastmock, fastmock |
|
postgresql.auth.existingSecret |
"" (required when enabled) |
Secret with the password. |
postgresql.auth.passwordKey |
password |
|
postgresql.storage.size, postgresql.storage.storageClassName |
10Gi, "" |
PVC size and class. |
postgresql.resources |
requests 100m/256Mi, limits 1/1Gi |
|
valkey.enabled |
false |
Deploy a Valkey StatefulSet (append-only persistence, volatile-lru). |
valkey.image |
docker.io/valkey/valkey:9.1.4-trixie |
|
valkey.auth.existingSecret |
"" (required when enabled) |
Secret with the password. |
valkey.auth.passwordKey |
password |
|
valkey.maxMemory |
256mb |
Valkey maxmemory. |
valkey.storage.size, valkey.storage.storageClassName |
2Gi, "" |
|
valkey.resources |
requests 50m/64Mi, limits 500m/384Mi |
Mock behaviour and limits¶
| Key | Default | Variable |
|---|---|---|
callbacks.allowedHosts |
[] |
FASTMOCK_CALLBACK_ALLOWED_HOSTS |
callbacks.deniedCidrs |
"" (server default) |
FASTMOCK_CALLBACK_DENIED_CIDRS (a comma-separated string) |
callbacks.workers |
32 |
FASTMOCK_CALLBACK_WORKERS |
callbacks.timeout |
10s |
FASTMOCK_CALLBACK_TIMEOUT |
secrets.existingSecret |
"" |
Secret mounted at /etc/fastmock/secrets (FASTMOCK_SECRETS_DIR); each key is a secret for HMAC signatures and plugins. |
secrets.stubSecrets |
[] |
FASTMOCK_STUB_SECRETS: names from that Secret that stubs may use. |
secrets.contractSecrets |
{} |
FASTMOCK_CONTRACT_SECRETS: map secret name → [hosts]; names from that Secret that contract tests may send, and the only hosts they may be sent to. A name must not also be in stubSecrets. |
outboundCA.configMap |
"" |
ConfigMap with a PEM bundle of extra CA certificates for outgoing HTTPS; mounted read-only and passed as FASTMOCK_OUTBOUND_CA_FILE. |
outboundCA.key |
ca.crt |
Key inside that ConfigMap. |
journal.retention |
24h |
FASTMOCK_JOURNAL_RETENTION |
journal.maxBodyBytes |
65536 |
FASTMOCK_JOURNAL_MAX_BODY_BYTES |
journal.queue |
2048 |
FASTMOCK_JOURNAL_QUEUE |
journal.scanTimeout |
10s |
FASTMOCK_JOURNAL_SCAN_TIMEOUT |
journal.scanMaxWork |
4294967296 |
FASTMOCK_JOURNAL_SCAN_MAX_WORK |
journal.scanConcurrency |
2 |
FASTMOCK_JOURNAL_SCAN_CONCURRENCY |
limits.maxBodyBytes |
10485760 |
FASTMOCK_MAX_BODY_BYTES |
limits.maxInflightBodyBytes |
134217728 |
FASTMOCK_MAX_INFLIGHT_BODY_BYTES (128 MiB, sized for the 512Mi memory limit) |
limits.maxDelay |
15m |
FASTMOCK_MAX_DELAY |
limits.recordingMaxStubs |
1000 |
FASTMOCK_RECORDING_MAX_STUBS |
limits.headerReadTimeout |
30s |
FASTMOCK_HEADER_READ_TIMEOUT |
kafka.bootstrap |
[] |
FASTMOCK_KAFKA_BOOTSTRAP |
kafka.schemaRegistryUrl |
"" |
FASTMOCK_KAFKA_SCHEMA_REGISTRY_URL |
kafka.allowedTopics |
[] |
FASTMOCK_KAFKA_ALLOWED_TOPICS |
kafka.contractTopics |
[] (reading disabled) |
FASTMOCK_KAFKA_CONTRACT_TOPICS: topics AsyncAPI contract tests may read. |
plugins |
[] (all) |
FASTMOCK_PLUGINS |
pluginSettings |
{} |
Map plugin → {key: value}, rendered as FASTMOCK_PLUGIN_<PLUGIN>_<KEY>. |
Keep limits.maxInflightBodyBytes well below the memory limit: request bodies are held in memory while a
request is processed.
Telemetry¶
| Key | Default | Meaning |
|---|---|---|
otel.endpoint |
"" |
OTEL_EXPORTER_OTLP_ENDPOINT; traces and logs are exported only when set. |
otel.protocol |
http/protobuf |
OTEL_EXPORTER_OTLP_PROTOCOL |
otel.serviceName |
fastmock |
OTEL_SERVICE_NAME |
otel.resourceAttributes |
"" |
OTEL_RESOURCE_ATTRIBUTES, for example deployment.environment=staging |
metrics.serviceMonitor.enabled |
false |
Create a ServiceMonitor that scrapes /metrics on the admin Service. |
metrics.serviceMonitor.interval |
30s |
|
metrics.serviceMonitor.labels |
{} |
Labels your Prometheus selects ServiceMonitors by. |
metrics.prometheusRule.enabled |
false |
Create the alert rules. |
metrics.prometheusRule.labels |
{} |
|
metrics.prometheusRule.unmatchedRatio |
0.2 |
Threshold of FastMockUnmatchedRequests. |
metrics.prometheusRule.callbackBacklog |
1000 |
Threshold of FastMockCallbackBacklog. |
Networking¶
| Key | Default | Meaning |
|---|---|---|
service.type |
ClusterIP |
Type of the data Service (the admin Service is always ClusterIP). |
service.port, service.adminPort |
8080, 9090 |
Service ports. |
service.annotations |
{} |
Annotations of the data Service. |
route.enabled |
false |
HTTPRoute <fullname> for the data port (path prefix /). |
route.hostnames, route.parentRefs |
[] |
Hostnames and Gateway references. |
route.admin.enabled |
false |
HTTPRoute <fullname>-admin for /__admin (prefix) and /readyz. |
route.admin.hostnames |
[] |
|
route.admin.parentRefs |
[] (falls back to route.parentRefs) |
|
networkPolicy.enabled |
false |
Ingress (and optionally egress) policy for FastMock pods. |
networkPolicy.dataFrom |
[] (any) |
from peers allowed on the data port. |
networkPolicy.adminFrom |
[] (any) |
from peers allowed on the admin port (tests, Prometheus, the Gateway, the operator). |
networkPolicy.storage |
true |
With bundled databases, allow connections to them only from FastMock pods. |
networkPolicy.egress.enabled |
false |
Also restrict egress: DNS and the bundled databases are always allowed, plus rules. |
networkPolicy.egress.rules |
[] |
Extra egress rules (external databases, Kafka, callback receivers, proxy targets). |
pdb.enabled, pdb.minAvailable |
true, 1 |
PodDisruptionBudget. Disable for a single replica. |
autoscaling.enabled |
false |
HorizontalPodAutoscaler on CPU (postgres mode only). |
autoscaling.minReplicas, maxReplicas, targetCPUUtilizationPercentage |
2, 6, 70 |
Production checklist¶
A values file that covers the list below (all of it renders with helm template and passes helm lint):
image:
repository: registry.example.com/platform/fastmock
tag: 0.1.0
replicaCount: 3
admin:
tokensSecret:
name: fastmock-admin-tokens
allowedOrigins:
- https://fastmock-admin.example.com
storage:
database:
existingSecret: fastmock-storage
secretKey: database-url
maxConnections: 20
valkey:
existingSecret: fastmock-storage
secretKey: valkey-url
secrets:
existingSecret: fastmock-hook-secrets
stubSecrets:
- delivery-hook
callbacks:
allowedHosts:
- "*.svc.cluster.local"
- hooks.example.com
kafka:
bootstrap:
- kafka-0.kafka.example.svc:9092
schemaRegistryUrl: http://schema-registry.kafka.example.svc:8081
allowedTopics:
- "orders.*"
otel:
endpoint: http://otel-collector.observability.svc:4318
metrics:
serviceMonitor:
enabled: true
prometheusRule:
enabled: true
networkPolicy:
enabled: true
adminFrom:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: monitoring
- podSelector:
matchLabels:
app.kubernetes.io/name: integration-tests
egress:
enabled: true
rules:
- to:
- ipBlock:
cidr: 198.51.100.0/24
ports:
- port: 5432
- port: 6379
- to:
- namespaceSelector:
matchLabels:
kubernetes.io/metadata.name: payments
autoscaling:
enabled: true
minReplicas: 3
maxReplicas: 8
topologySpreadConstraints:
- maxSkew: 1
topologyKey: kubernetes.io/hostname
whenUnsatisfiable: ScheduleAnyway
labelSelector:
matchLabels:
app.kubernetes.io/name: fastmock
app.kubernetes.io/component: server
- [ ] External PostgreSQL and Valkey with backups, TLS to PostgreSQL (
sslmode=verify-full), and a dedicated database user that owns only the FastMock database. Valkey must persist data and must not evict keys without TTL (maxmemory-policy volatile-lruornoeviction). - [ ] Secrets come from your secret manager (External Secrets, Sealed Secrets, CSI driver) into the three Secrets: admin tokens, storage URLs, HMAC keys. Nothing secret goes into values files.
- [ ] Tokens per client (
ci:editor,ops:admin,grafana:viewer); no shared tokens. See token rotation. - [ ] NetworkPolicy on: the admin port only from tests, Prometheus and the Gateway; egress only to the databases, Kafka and the callback/proxy targets.
- [ ] Egress allow-list
callbacks.allowedHostsmatching the egress NetworkPolicy. - [ ] Stub secrets listed explicitly in
secrets.stubSecrets; contract-test secrets insecrets.contractSecrets, each bound only to the host of the service it belongs to. - [ ] Kafka reads for contract tests limited to the topics in
kafka.contractTopics(empty disables them). - [ ] Replicas, PDB, spread: at least 2 replicas,
pdb.enabled, topology spread across nodes; HPA if load varies. - [ ] Resources sized: memory limit above
limits.maxInflightBodyBytesplus stubs and caches;storage.database.maxConnections × replicasbelow the PostgreSQL connection limit. - [ ] Monitoring: ServiceMonitor, PrometheusRule, the Grafana dashboard, OTLP endpoint.
- [ ] Image pinned to a tag or digest from your registry.
- [ ] Admin UI behind a Gateway with TLS and
admin.allowedOriginsset to its URL (next section);admin.uiDataPlaneUrlsset to the public data-plane URL when the UI's test panel should reach it.
Exposing the admin UI with Gateway API¶
The chart's route.admin publishes /__admin and /readyz. To publish the web UI and the API description as
well, create a route like the following (TLS terminates at the Gateway; adjust the names):
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
name: fastmock-admin-ui
namespace: mocks
spec:
parentRefs:
- name: internal-gateway
namespace: gateway-system
sectionName: https
hostnames:
- fastmock-admin.example.com
rules:
- matches:
- path:
type: PathPrefix
value: /__admin
- path:
type: PathPrefix
value: /ui
- path:
type: Exact
value: /openapi.json
backendRefs:
- name: fastmock-admin
port: 9090
and set admin.allowedOrigins: [https://fastmock-admin.example.com] (requests from the UI at that origin are
also accepted as same-origin when the Gateway forwards the original Host). Do not route /metrics publicly;
Prometheus scrapes it inside the cluster. Allow the Gateway's pods in networkPolicy.adminFrom.
TLS and mTLS¶
The data port can serve HTTPS itself, which is needed to mock services that clients reach with mTLS. The
chart has no values for certificate volumes: either let the Gateway terminate TLS and keep the pods on HTTP, or
add a Secret volume with a Helm post-renderer (for example kustomize) and point the variables at it with
extraEnv. Server settings: FASTMOCK_TLS_CERT_FILE, FASTMOCK_TLS_KEY_FILE,
FASTMOCK_TLS_CLIENT_CA_FILE, FASTMOCK_TLS_CLIENT_AUTH (Configuration).
Stubs can match the client certificate fingerprint through the x-fastmock-client-cert-sha256 header.
The admin port is plain HTTP inside the cluster; publish it only through a Gateway or ingress with TLS.
NetworkPolicy¶
With networkPolicy.enabled: true the chart creates one policy for FastMock pods:
- ingress on the data port from
dataFrom(or anywhere when empty), on the admin port fromadminFrom(or anywhere when empty). SetadminFrom. - egress (with
egress.enabled): DNS tokube-dns, the bundled databases, and youregress.rules. Callback receivers, proxy targets, Kafka, external PostgreSQL/Valkey and the OTLP collector must be covered by rules.
With bundled databases, networkPolicy.storage: true adds a second policy that lets only FastMock pods of the
release reach them.
Upgrade notes¶
- 0.1.0: first release.
FASTMOCK_STUB_SECRETS(secrets.stubSecrets) is required for stub HMAC signatures; stubs that reference other secrets produce failed callbacks withsecret ... is not configured. - The chart never deletes PersistentVolumeClaims or database content on upgrade.
- When the operator manages FastMock, upgrade the operator chart instead (Operator).