Deploying MockServer Helm Chart

There are four ways to deploy the MockServer helm chart:

1. via OCI registry (recommended, Helm 3.8+)
2. via chart repository
3. via package
4. via local source

Deploy Via OCI Registry

The chart is published to the GitHub Container Registry as an OCI artifact. No helm repo add is needed — helm install can pull straight from oci://:

helm upgrade --install --kube-context <your kube context> --namespace mockserver --create-namespace --version {{ site.mockserver_version }} mockserver oci://ghcr.io/mock-server/charts/mockserver

To inspect chart metadata for a specific version without installing:

helm show chart oci://ghcr.io/mock-server/charts/mockserver --version {{ site.mockserver_version }}

To browse the full list of published versions, open the package page on GHCR: github.com/orgs/mock-server/packages/container/package/charts%2Fmockserver

The OCI artifact is public — no authentication is required for helm pull or helm install. Every released chart version (5.3.0 onward) is available at the same path.

To mirror the chart into a private OCI registry (Harbor, Artifactory, ECR, GAR, ACR, etc.):

helm pull oci://ghcr.io/mock-server/charts/mockserver --version {{ site.mockserver_version }}
helm push mockserver-{{ site.mockserver_version }}.tgz oci://<your-private-registry>/<namespace>

Deploy Via Chart Repository

The legacy HTTP-based Helm repository remains available at www.mock-server.com:

helm repo add mockserver https://www.mock-server.com
helm repo update

Then the helm chart can be installed as follows:

helm upgrade --install --kube-context <your kube context> --namespace mockserver --create-namespace --version {{ site.mockserver_version }} mockserver mockserver/mockserver

If using get the following error:

Error: failed to download "mockserver/mockserver" at version "{{ site.mockserver_version }}"

Then update local cache of helm charts:

helm repo update

Deploy Via Package

To run MockServer in Kubernetes the easiest way is to use the existing MockServer helm chart.

This is available by using www.mock-server.com as a chart repo, with the following command:

helm upgrade --install --namespace mockserver mockserver http://www.mock-server.com/mockserver-{{ site.mockserver_version }}.tgz

Deploy Via Local Source

If you have helm chart source folder (i.e. you have the repository cloned):

helm upgrade --install --namespace mockserver mockserver helm/mockserver

The commands above will install MockServer into a namespace called mockserver with default configuration (as per the embedded values.yaml).

MockServer will then be available on domain name mockserver.mockserver.svc.cluster.local, as long as the namespace you are calling from isn't prevented (by network policy) to call the mockserver namespace.

Chart Deployment Status

To view the logs:

kubectl -n mockserver logs --tail=100 -l app=mockserver,release=mockserver

or open the UI

To wait until the deployment is complete run:

kubectl -n mockserver rollout status deployments mockserver

To check the status of the deployment without waiting, run the following command and confirm the mockserver has the Running status:

kubectl -n mockserver get po -l release=mockserver

To undeploy the helm chart:

helm delete -n mockserver mockserver

Basic MockServer Configuration

Modify the arguments used to start the docker container by setting values explicitly using --set, as follows:

helm upgrade --install --namespace mockserver --set app.serverPort=1080 --set app.logLevel=INFO mockserver http://www.mock-server.com/mockserver-{{ site.mockserver_version }}.tgz

The following values are supported:

• app.serverPort (default: 1080)
• app.logLevel (default: INFO)
• app.proxyRemoteHost (no default)
• app.proxyRemotePort (no default)
• app.jvmOptions (no default)
• image.snapshot (default: false) - set true to use latest snapshot version
• podLabels (default: {}) - additional labels to add to the MockServer pods
• imagePullSecrets (default: []) - list of image pull secrets for private registries

For example configure a proxyRemoteHost and proxyRemotePort, as follows:

helm upgrade --install --namespace mockserver --set app.serverPort=1080 --set app.proxyRemoteHost=www.mock-server.com --set app.proxyRemotePort=443 mockserver http://www.mock-server.com/mockserver-{{ site.mockserver_version }}.tgz

Double check the correct arguments have been passed to the pod, as follows:

kubectl -n mockserver logs -l app=mockserver,release=mockserver

Detailed MockServer Configuration

There are two ways to provide MockServer configuration (properties file, expectation initialization JSON, TLS certificates, etc.):

1. Inline configuration (recommended) — provide configuration directly in values.yaml
2. External ConfigMap — create a ConfigMap separately (manually, via CI, or using the example mockserver-config chart)

Both approaches mount configuration into the container at /config. See MockServer Configuration for details of all configuration options.

Option 1: Inline Configuration (single chart install)

Set app.config.enabled=true and provide configuration content directly in values. This creates a ConfigMap as part of the main chart — no separate chart or manual ConfigMap creation is needed.

Using --set-string (commas in JSON must be escaped as \,):

helm upgrade --install --namespace mockserver \
  --set app.config.enabled=true \
  --set app.config.properties="mockserver.initializationJsonPath=/config/initializerJson.json" \
  --set-string 'app.config.initializerJson=[{"httpRequest":{"path":"/example"}\,"httpResponse":{"body":"response"}}]' \
  mockserver helm/mockserver

Note: Helm's --set flag treats commas as key/value separators, which corrupts JSON values. Use --set-string with escaped commas (\,) for simple cases, or a values.yaml file (recommended) for anything non-trivial.

Or using a values.yaml file (recommended for complex configuration):

app:
  config:
    enabled: true
    properties: |
      mockserver.initializationJsonPath=/config/initializerJson.json
      mockserver.enableCORSForAPI=true
      mockserver.enableCORSForAllResponses=true
    initializerJson: |
      [
        {
          "httpRequest": { "path": "/example" },
          "httpResponse": { "body": "some response" }
        }
      ]

helm upgrade --install --namespace mockserver -f values.yaml mockserver helm/mockserver

When using inline configuration, pods are automatically restarted on helm upgrade whenever the configuration content changes. This ensures MockServer always runs with the latest configuration.

The following inline config values are supported:

• app.config.enabled (default: false) - set true to create a ConfigMap from inline values
• app.config.properties (default: "") - content of mockserver.properties
• app.config.initializerJson (default: "") - content of initializerJson.json
• app.config.extraFiles (default: {}) - map of additional filenames to content (e.g. TLS certificates)

Option 2: External ConfigMap

If a ConfigMap called mockserver-config (or a custom name) exists in the same namespace, it will be mounted into the MockServer container under the mountPath /config.

This ConfigMap can be used to configure MockServer by containing a mockserver.properties file and other related configuration files such as:

• json expectation initialization, or
• custom TLS CA, X.509 Certificate or Private Key

The mockserver.properties file should load these additional files from the directory /config which is the mountPath for the ConfigMap.

The mapping of the configuration ConfigMap can be configured as follows:

• app.mountedConfigMapName (default: mockserver-config) - name of the configuration ConfigMap (in the same namespace) to mount
• app.propertiesFileName (default: mockserver.properties) - name of the property file in the ConfigMap

helm upgrade --install --namespace mockserver --set app.mountedConfigMapName=other-mockserver-config --set app.propertiesFileName=other-mockserver.properties mockserver helm/mockserver

Extending MockServer Classpath

To use class callbacks or an expectation initializer class the classpath for MockServer must include the specified classes.

To support adding classes to the classpath if a configmap called mockserver-config exists in the same namespace any jar files contained in this configmap will be added into MockServer classpath.

The mapping of the libs configmap can be configured as follows:

• app.mountedLibsConfigMapName (default: mockserver-config) - name of the libs configmap (in the same namespace) to mount

helm upgrade --install --namespace mockserver --set app.mountedLibsConfigMapName=mockserver-libs mockserver helm/mockserver

Persistent Storage

By default, MockServer holds expectations in memory only. On Kubernetes, this means expectations are lost when a pod restarts. To persist expectations across pod restarts, enable persistent storage. This creates (or references) a PersistentVolumeClaim and automatically configures MockServer to save and reload expectations from it.

Quick Start

The simplest way to enable persistence is with a single --set flag:

helm upgrade --install --namespace mockserver \
  --set app.persistence.enabled=true \
  mockserver helm/mockserver

This creates a 256Mi PersistentVolumeClaim using the cluster's default StorageClass, and automatically configures MockServer to persist expectations to it.

How It Works

When app.persistence.enabled=true, the chart:

1. Creates a PersistentVolumeClaim (unless app.persistence.existingClaimName is set)
2. Mounts the PVC into the container at /persistence (configurable via app.persistence.mountPath)
3. Sets the following environment variables to enable persistence automatically:
   • MOCKSERVER_PERSIST_EXPECTATIONS=true
   • MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=/persistence/persistedExpectations.json
   • MOCKSERVER_INITIALIZATION_JSON_PATH=/persistence/persistedExpectations.json

Important: These environment variables provide defaults. Any matching property in your mockserver.properties file takes precedence over environment variables. If you need custom paths or want to disable auto-initialization, set the equivalent properties in your properties file. See MockServer Configuration for the full property precedence rules.

Persistence Values

The following values control persistent storage:

• app.persistence.enabled (default: false) — set true to enable persistent storage
• app.persistence.existingClaimName (default: "") — name of an existing PVC to use; if empty, the chart creates one
• app.persistence.storageClass (default: "") — StorageClass for the PVC; if empty, the cluster default is used
• app.persistence.accessModes (default: [ReadWriteOnce]) — access modes for the PVC
• app.persistence.size (default: 256Mi) — size of the PVC
• app.persistence.mountPath (default: /persistence) — mount path inside the container
• app.persistence.annotations (default: {}) — annotations for the PVC (only used when creating a new PVC)

Example: Chart-Managed PVC

Let the chart create and manage the PVC:

app:
  persistence:
    enabled: true
    storageClass: "gp3"
    size: 1Gi

helm upgrade --install --namespace mockserver -f values.yaml mockserver helm/mockserver

Example: Existing PVC

If you manage PVCs separately (e.g. via GitOps or Terraform), reference an existing PVC by name:

helm upgrade --install --namespace mockserver \
  --set app.persistence.enabled=true \
  --set app.persistence.existingClaimName=my-mockserver-data \
  mockserver helm/mockserver

Example: Clustering with Shared Storage

For clustered MockServer deployments, use a ReadWriteMany access mode with a shared filesystem such as NFS, AWS EFS, or Azure Files:

replicaCount: 3

app:
  persistence:
    enabled: true
    accessModes:
      - ReadWriteMany
    storageClass: "efs-sc"

See Persisting & Clustering Expectations for more details on how MockServer clustering works.

MockServer URL

Local Kubernetes Cluster (i.e. minikube, microk8s)

If the service type hasn't been modified the following will provide the MockServer URL from outside the cluster.

export NODE_PORT=$(kubectl get -n mockserver -o jsonpath="{.spec.ports[0].nodePort}" services mockserver)
export NODE_IP=$(kubectl get nodes -n mockserver -o jsonpath="{.items[0].status.addresses[0].address}")
export MOCKSERVER_HOST=$NODE_IP:$NODE_PORT
echo http://$MOCKSERVER_HOST

To test the installation the following curl command should return the ports MockServer is bound to:

curl -v -X PUT http://$MOCKSERVER_HOST/status

Docker for Desktop

Docker for Desktop automatically exposes LoadBalancer services.

On MacOS Docker for Desktop runs inside Hyperkit so the node IP address is not reachable, therefore the only way to call services is via the exposed LoadBalancer service added by Docker for Desktop.

To ensure that Docker for Desktop exposes MockServer update the service type to LoadBalancer using --set service.type=LoadBalancer and set the exposed port using --set service.port=1080, as follows:

helm upgrade --install --namespace mockserver --set service.type=LoadBalancer --set service.port=1080 mockserver http://www.mock-server.com/mockserver-{{ site.mockserver_version }}.tgz

MockServer will then be reachable on http://localhost:1080

For LoadBalancer services it is possible to query kubernetes to programmatically determine the MockServer base URL as follows:

export SERVICE_IP=$(kubectl get svc --namespace mockserver mockserver -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
export MOCKSERVER_HOST=$SERVICE_IP:1081
echo http://$MOCKSERVER_HOST

Outside Remote Kubernetes Cluster (i.e. Azure AKS, AWS EKS, etc) via Port Forward

kubectl -n mockserver port-forward svc/mockserver 1080:1080 &
export MOCKSERVER_HOST=127.0.0.1:1080
echo http://$MOCKSERVER_HOST

Inside Kubernetes Cluster

If a DNS server has been installed in the Kubernetes cluster the following DNS name should be available mockserver.<namespace>.svc.cluster.local, i.e. mockserver.mockserver.svc.cluster.local

Helm Delete

To completely remove the chart:

helm delete mockserver --purge