Kubernetes operator¶
The operator manages FastMock declaratively with two custom resources:
MockServerdescribes a FastMock instance. The operator creates its Deployment, Services, configuration, admin tokens, PodDisruptionBudget and optional HTTPRoute.MockApidescribes mocks for aMockServer: inline stubs, an OpenAPI document or WireMock mappings. The operator imports them through the admin API and keeps them in sync.
Teams can then keep their mocks next to their application manifests (GitOps), and platform owners keep control over images, secrets and security settings through operator policies.
Install¶
helm upgrade --install fastmock-operator deploy/helm/fastmock-operator -n fastmock-system --create-namespace \
--set image.repository=registry.example.com/platform/fastmock-operator --set image.tag=0.1.0 \
--set server.image.repository=registry.example.com/platform/fastmock --set server.image.tag=0.1.0
Helm installs the CRDs (mockservers.fastmock.io, mockapis.fastmock.io, version v1alpha1) on first install.
| Value | Default | Meaning |
|---|---|---|
image.repository, image.tag, image.pullPolicy |
fastmock-operator, chart appVersion, IfNotPresent |
Operator image. |
imagePullSecrets |
[] |
For the operator pod. |
server.image.repository, server.image.tag |
fastmock, chart appVersion |
Default FastMock image for MockServers without spec.image (FASTMOCK_OPERATOR_SERVER_IMAGE). |
server.allowedImagePrefixes |
[] (the repository of the default image) |
Image prefixes a MockServer may use (FASTMOCK_OPERATOR_ALLOWED_IMAGE_PREFIXES). |
watchNamespace |
"" (all namespaces) |
Watch only one namespace; the operator then gets a Role instead of a ClusterRole. |
logLevel |
info |
Operator log level. |
resources |
requests 50m/64Mi, limits 500m/256Mi |
|
metrics.serviceMonitor.enabled, .interval |
false, 30s |
ServiceMonitor for the operator's /metrics. |
podSecurityContext, securityContext |
non-root 65532, read-only root FS, no capabilities | |
nodeSelector, tolerations, affinity |
empty |
The operator runs one replica (Recreate strategy) and serves /healthz, /readyz and /metrics on port 8081.
MockServer¶
apiVersion: fastmock.io/v1alpha1
kind: MockServer
metadata:
name: payments
namespace: team-payments
spec:
replicas: 2
storage:
mode: postgres
database: {name: payments-mock-storage, key: database-url}
valkey: {name: payments-mock-storage, key: valkey-url}
adminTokensSecret: {name: payments-mock-tokens, key: tokens}
secretsSecret: payments-mock-hook-secrets
env:
FASTMOCK_STUB_SECRETS: delivery-hook
FASTMOCK_JOURNAL_RETENTION: 6h
otelEndpoint: http://otel-collector.observability.svc:4318
resources:
requests: {cpu: 100m, memory: 128Mi}
limits: {cpu: "1", memory: 512Mi}
route:
hostnames: [payments-mock.example.com]
parentRefs:
- {name: internal-gateway, namespace: gateway-system}
Every Secret it references must carry the label fastmock.io/allow-mount: "true" (see Policies):
kubectl -n team-payments create secret generic payments-mock-storage \
--from-literal=database-url='postgres://fastmock:<password>@db.example.com:5432/payments_mock?sslmode=verify-full' \
--from-literal=valkey-url='redis://:<password>@valkey.example.com:6379/'
kubectl -n team-payments label secret payments-mock-storage fastmock.io/allow-mount=true
Fields¶
| Field | Default | Meaning |
|---|---|---|
image |
operator default image | FastMock image; must match an allowed prefix. |
replicas |
1 |
Replicas. More than 1 requires storage.mode: postgres. A PodDisruptionBudget (minAvailable: 1) is created when replicas > 1. |
imagePullSecrets |
[] |
Names of pull Secrets (each must be labelled). |
storage.mode |
memory |
memory or postgres. Omitting the whole storage block means memory. |
storage.database |
none | {name, key} of a Secret holding the PostgreSQL URL (key defaults to url). Required for postgres. |
storage.valkey |
none | {name, key} of a Secret holding the Valkey URL (key defaults to url). Required for postgres. |
storage.valkeyPrefix |
fastmock:<name>: |
Valkey key prefix, so several servers can share one Valkey. |
adminTokensSecret |
none | {name, key} of a Secret with your name:role:sha256hex token lines. key defaults to tokens. |
secretsSecret |
none | Secret mounted at /etc/fastmock/secrets (HMAC keys, plugin secrets). |
plugins |
[] (all) |
Plugins to enable. |
pluginSettings |
{} |
plugin → {key: value}, rendered as FASTMOCK_PLUGIN_<PLUGIN>_<KEY>. |
env |
{} |
Extra settings; security-relevant variables are refused (see Policies). |
otelEndpoint |
none | OTLP endpoint; sets OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_SERVICE_NAME=fastmock-<name>. |
resources |
requests 100m/64Mi, limits 2/512Mi |
Container resources. |
route |
none | {hostnames, parentRefs}: creates an HTTPRoute <name> for the data port. Removing the field deletes the route. |
What the operator creates¶
All objects are named after the MockServer, owned by it (deleted with it) and labelled
app.kubernetes.io/managed-by: fastmock-operator.
| Object | Name | Content |
|---|---|---|
| Secret | <name>-operator-token |
The operator's own admin token (generated once). |
| Secret | <name>-admin-tokens |
Your token lines plus fastmock-operator:admin:<hash>, mounted as FASTMOCK_ADMIN_TOKENS_FILE. |
| ConfigMap | <name>-config |
Environment: listeners, storage mode, log format, Valkey prefix, plugins, OTLP, env. |
| ServiceAccount | <name> |
Without token automount. |
| Deployment | <name> |
Hardened pod (non-root 65532, read-only root FS, no capabilities, seccomp), probes on /healthz and /readyz, rolling update with maxUnavailable: 0. A checksum of configuration and tokens rolls the pods when they change. |
| Service | <name> (port 8080), <name>-admin (port 9090) |
Data and admin ports. |
| PodDisruptionBudget | <name> |
When replicas > 1. |
| HTTPRoute | <name> |
When route is set (needs Gateway API CRDs). |
The status shows the in-cluster URLs: status.adminUrl = http://<name>-admin.<namespace>.svc:9090,
status.dataUrl = http://<name>.<namespace>.svc:8080.
MockApi¶
apiVersion: fastmock.io/v1alpha1
kind: MockApi
metadata:
name: billing
namespace: team-payments
spec:
serverRef: {name: payments}
openapi:
configMapRef: {name: billing-openapi, key: openapi.yaml}
pathPrefix: /billing
validateRequests: true
wiremock:
configMapRef: {name: billing-wiremock, key: mappings.json}
stubs:
- name: billing health
request: {method: GET, urlPath: /billing/health}
response: {status: 200, body: ok}
- name: invoice paid webhook
request: {method: POST, urlPathTemplate: "/billing/invoices/{id}/pay"}
response: {status: 202}
callbacks:
- url: http://billing-app.team-payments.svc:8080/hooks/invoice
jsonBody: {invoiceId: "{{request.pathParams.id}}", status: PAID}
correlation: "{{request.pathParams.id}}"
| Field | Default | Meaning |
|---|---|---|
serverRef.name |
required | MockServer in the same namespace. |
tag |
<namespace>.<name> |
Tag of the imported stubs. |
stubs |
[] |
Stub objects exactly as in the admin API (Concepts: stubs). |
openapi.inline or openapi.configMapRef |
none | OpenAPI 3 document (JSON or YAML) inline or from a ConfigMap key. |
openapi.pathPrefix |
"" |
Prefix added to every generated path. |
openapi.validateRequests |
true |
Generated stubs reject requests that violate the document. |
wiremock.inline or wiremock.configMapRef |
none | WireMock mappings, JSON or YAML. |
How it is applied:
- Inline stubs are imported with tag
<tag>, the OpenAPI stubs with<tag>:openapi, the WireMock stubs with<tag>:wiremock. Each import replaces the previous stubs of its tag, so removing a stub from the resource removes it from the server; removing a whole section deletes its tag. Details of the conversions: Importing, WireMock and MockServer import. - The operator imports only when the effective input changed: the spec, the content of the referenced
ConfigMaps, or the server (a re-created
MockServergets a new UID). Every 5 minutes it re-reads the ConfigMaps and checks that the server still has the expected number of stubs (for example after a memory-mode server restarted); missing stubs are re-imported. - Deleting a
MockApideletes its stubs. The finalizerfastmock.io/stubskeeps the resource until the removal succeeded, as long as theMockServerexists; if the server is gone, the finalizer is released without cleanup.
Status and conditions¶
MockServer¶
| Field | Meaning |
|---|---|
status.readyReplicas |
Ready pods of the Deployment. |
status.observedGeneration |
Generation the status refers to. |
status.adminUrl, status.dataUrl |
In-cluster URLs. |
status.conditions |
See below. |
| Condition | Status | Reason | Meaning |
|---|---|---|---|
Ready |
True | Available |
At least one replica is ready (message: 2/2 replicas ready). |
Ready |
False | Progressing |
Applied, no replica ready yet. |
Ready |
False | InvalidSpec |
storage.mode is not memory/postgres, postgres without database and valkey, or more than one replica with memory storage. |
Ready |
False | ImageNotAllowed |
The image does not match an allowed prefix. |
Ready |
False | EnvNotAllowed |
spec.env sets a variable that is reserved for dedicated fields. |
Ready |
False | SecretNotAllowed |
A referenced Secret lacks the label fastmock.io/allow-mount: "true". |
Ready |
False | SecretNotFound |
A referenced Secret does not exist. |
RouteReady |
True / False | Applied / ApplyFailed |
Only when route is set; ApplyFailed usually means Gateway API is not installed. |
When a resource is refused (InvalidSpec, ImageNotAllowed, EnvNotAllowed, SecretNotAllowed,
SecretNotFound) nothing is applied and an existing Deployment keeps running unchanged. Secret problems are
re-checked every minute, the others when the resource changes and every 5 minutes.
kubectl -n team-payments get mockserver payments -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.reason}: {.message}{"\n"}{end}'
Ready=False SecretNotAllowed: referenced Secrets must carry the label fastmock.io/allow-mount=true: storage.database=payments-mock-storage
MockApi¶
| Field | Meaning |
|---|---|
status.importedStubs |
Stubs imported in the last successful sync. |
status.warnings |
Conversion warnings of the OpenAPI/WireMock importers. |
status.lastSyncTime |
Time of the last successful import. |
status.appliedHash |
Hash of the applied input (spec, ConfigMap contents, server UID). |
status.observedGeneration |
| Condition | Status | Reason | Meaning |
|---|---|---|---|
Synced |
True | Synced |
14 stubs applied with tag team-payments.billing |
Synced |
False | ServerNotReady |
The MockServer is missing, being deleted or has no ready replica; retried every 15 s. |
Synced |
False | SyncFailed |
The import failed: invalid stub, unparsable document, missing ConfigMap or key, admin API error. The message tells which. |
Policies¶
MockServer resources are written by application teams, while the operator runs with broad permissions. To keep
the operator from being used to run arbitrary images, read arbitrary Secrets or weaken FastMock's security
settings, it enforces three policies:
- Image allow-list.
spec.image(or the default image) must start with one ofserver.allowedImagePrefixes; the prefix must end at a path, tag or digest boundary, soregistry.example.com/fastmockallowsregistry.example.com/fastmock:1.2andregistry.example.com/fastmock@sha256:...but notregistry.example.com/fastmock-other. Without explicit prefixes only the repository of the default image is allowed. Otherwise:ImageNotAllowed. - Secret opt-in. Every Secret named in
storage.database,storage.valkey,adminTokensSecret,secretsSecretandimagePullSecretsmust have the labelfastmock.io/allow-mount: "true". A Secret owner thereby agrees that FastMock pods may mount it. Otherwise:SecretNotAllowed. - Reserved environment.
spec.envmust not setFASTMOCK_AUTH_DISABLED,FASTMOCK_ADMIN_TOKENS,FASTMOCK_ADMIN_TOKENS_FILE,FASTMOCK_ADMIN_ALLOWED_ORIGINS,FASTMOCK_SECRETS_DIR,FASTMOCK_SECRET_*,FASTMOCK_CALLBACK_DENIED_CIDRS,FASTMOCK_CALLBACK_ALLOWED_HOSTS,FASTMOCK_DATABASE_URL,FASTMOCK_VALKEY_URL,FASTMOCK_VALKEY_PREFIX,FASTMOCK_STORAGE,FASTMOCK_LISTEN,FASTMOCK_ADMIN_LISTENor anyLD_*variable (names are compared case-insensitively). Use the dedicated fields instead. Otherwise:EnvNotAllowed.
Combine these with a namespace-level policy engine (Kyverno, Gatekeeper) or watchNamespace if only some
namespaces should get mock servers.
RBAC¶
The chart grants the operator (as a ClusterRole, or a Role in watchNamespace):
| API group | Resources | Verbs |
|---|---|---|
fastmock.io |
mockservers |
get, list, watch |
fastmock.io |
mockapis |
list, watch, patch |
fastmock.io |
mockservers/status, mockapis/status |
patch |
fastmock.io |
mockservers/finalizers |
update |
| core | secrets, configmaps |
get, create, patch |
| core | services, serviceaccounts |
create, patch |
apps |
deployments |
get, list, watch, create, patch |
policy |
poddisruptionbudgets |
get, create, patch, delete |
gateway.networking.k8s.io |
httproutes |
get, create, patch, delete |
It cannot list Secrets, only read those it is pointed at, and the Secret-label policy limits which of those it
mounts. Users need RBAC on mockservers and mockapis in their namespaces; reading the generated
<name>-operator-token Secret is equivalent to admin access to that FastMock, so do not grant get secrets more
widely than needed.
Monitoring the operator¶
| Metric | Labels | Meaning |
|---|---|---|
fastmock_operator_reconciles_total |
kind (MockServer, MockApi), result (ok, error) |
Reconciliations. |
fastmock_operator_reconcile_duration_seconds |
kind |
Reconciliation time. |
Logs are JSON; a refused resource logs MockServer refused with reason and msg. Failed reconciliations are
retried with backoff from 5 s up to 5 minutes. The Grafana dashboard has an
operator panel.
Upgrading¶
Helm installs CRDs only on the first install and never upgrades them. After upgrading the chart, apply the CRDs yourself:
helm upgrade fastmock-operator deploy/helm/fastmock-operator -n fastmock-system -f values.yaml
kubectl apply --server-side -f deploy/helm/fastmock-operator/crds/fastmock.io.yaml
The CRD file is generated from the operator code (fastmock-operator crd), so it always matches the operator
version of the same chart. Existing MockServers are re-applied with the new operator's manifests; their pods
roll only if the generated Deployment changed. Changing the default server image (server.image.tag) rolls
every MockServer that does not pin spec.image.
Uninstalling the chart leaves the CRDs and therefore all MockServer/MockApi resources and their objects in
place. Delete the resources first if you want everything removed; deleting the CRDs deletes all resources of
those kinds.