Kubernetes

Memgraph can be deployed on Kubernetes. The easiest way to do that is with Helm, the package manager for Kubernetes. Helm uses a packaging format called charts. A chart is a collection of files that describe a related set of Kubernetes resources.

Currently, we prepared and released the following charts:

• Memgraph standalone Helm chart
• Memgraph high availability Helm chart
• Memgraph Lab Helm chart
• Memgraph MCP Helm chart

The Helm charts are published on Artifact Hub. For details on the implementation of the Helm charts, check Memgraph Helm charts repository.

Due to numerous possible use cases and deployment setups via Kubernetes, the provided Helm charts are a starting point you can modify according to your needs. This page will highlight some of the specific parts of the Helm charts that you might want to adjust.

Memgraph standalone Helm chart

Memgraph is a stateful application (database), hence the Helm chart for standalone Memgraph is configured to deploy Memgraph as a Kubernetes StatefulSet workload.

It will deploy a single Memgraph instance in a single pod.

Typically, when deploying a stateful application like Memgraph, a StatefulSet workload is used to ensure that each pod has a unique identity and stable network identity. When deploying Memgraph, it is also necessary to define a PersistentVolumeClaims to store the data directory (/var/lib/memgraph). This enables the data to be persisted even if the pod is restarted or deleted.

Storage configuration

By default, the Helm chart will create a PersistentVolumeClaim (PVC) for storage and logs. If the storage class for PVC is not defined, PVC will use the default one available in the cluster. The storage class can be configured in the values.yaml file. To avoid losing your data, make sure you have Retain reclaim policy set on your storage class. If you delete PersistentVolumeClaim without having Retain reclaim policy, you will lose your data because PersistentVolume will get deleted too. The alternative to creating a new storage class is to patch your existing storage class by applying the Retain policy. This is necessary because the default Kubernetes policy is Delete. The patching can be done using the following bash script:

#!/bin/bash
 
# Get all Persistent Volume names
PVS=$(kubectl get pv --no-headers -o custom-columns=":metadata.name")
 
# Loop through each PV and patch it
for pv in $PVS; do
  echo "Patching PV: $pv"
  kubectl patch pv $pv -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}'
done
 
echo
 
 
An example of a storage class for AWS EBS volumes: 
 
```yaml
storageClass:
  name: "gp2"
  provisioner: "kubernetes.io/aws-ebs"
  storageType: "gp2"
  fsType: "ext4"
  reclaimPolicy: "Retain"
  volumeBindingMode: "Immediate"

Default template for a storage class is part of the Helm chart and can be found in the repository. If you don’t want to create a new storage class, set storageClass.create to false.

More details on the configuration options can be found in the configuration section.

Secrets

The Helm chart allows you to use Kubernetes secrets to store Memgraph credentials. By default, the secrets are disabled. If you want to use secrets, you can enable them in the values.yaml file.

The secrets are prepared to work for environment variables MEMGRAPH_USER and MEMGRAPH_PASSWORD.

Probes

Memgraph standalone chart uses startup, readiness and liveness probes. The startup probe is used to determine when a container application has started. The liveness probe is used to determine when a container should be restarted. The readiness probe is used to determine when a container is ready to start accepting traffic. The startup probe will succeed only after the recovery of the Memgraph has finished. Liveness and readiness probes will start after the startup probe succeeds. By default, the startup probe has to succeed within 2 hours. If the recovery from backup takes longer than that, update the configuration to the value that is high enough. The liveness and readiness probe have to succeed at least once in 5 minutes for a pod to be considered ready.

System configuration

The Helm chart will set the linux kernel vm.max_map_count parameter to 524288 by default to ensure Memgraph won’t run into issues with memory mapping.

Installing Memgraph standalone Helm chart

To include a standalone Memgraph into your Kubernetes cluster, you need to add the repository and install Memgraph.

The steps below will work in the Minikube environment, but you can also use them in other Kubernetes environments with minor adjustments.

Add the repository

Add the Memgraph Helm chart repository to your local Helm setup by running the following command:

helm repo add memgraph https://memgraph.github.io/helm-charts

Make sure to update the repository to fetch the latest Helm charts available:

helm repo update

Install Memgraph

To install Memgraph Helm chart, run the following command:

helm install <release-name> memgraph/memgraph

Replace <release-name> with the name of the release you chose.

Install Memgraph standalone chart with minikube

If you are installing Memgraph standalone chart locally with minikube, we are strongly recommending to enable csi-hostpath-driver and use its storage class. Otherwise, you could have problems with attaching PVCs to pods.

1. Enable csi-hostpath-driver

minikube addons disable storage-provisioner
minikube addons disable default-storageclass
minikube addons enable volumesnapshots
minikube addons enable csi-hostpath-driver

2. Create a storage class with csi-hostpath-driver as a provider (file sc.yaml)

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: csi-hostpath-delayed
provisioner: hostpath.csi.k8s.io
volumeBindingMode: WaitForFirstConsumer
reclaimPolicy: Delete

3. kubectl apply -f sc.yaml

4. Set storageClassName to csi-hostpath-delayed in values.yaml

Access Memgraph

Once Memgraph is installed, you can access it using the provided services and endpoints, such as various client libraries, command-line interface mgconsole or visual user interface Memgraph Lab.

Monitoring

Memgraph’s standalone chart integrates with Kubernetes monitoring tools through:

• The kube-prometheus-stack Helm chart
• Memgraph’s Prometheus exporter

The chart kube-prometheus-stack should be installed independently from HA chart with the following command:

helm install kube-prometheus-stack prometheus-community/kube-prometheus-stack \
  -f kube_prometheus_stack_values.yaml \
  --namespace monitoring \
  --create-namespace

kube_prometheus_stack_values.yaml is optional. A template is available in the upstream chart’s repository. If you install the kube-prometheus-stack in a non-default namespace, allow cross-namespace scraping. You can allow this by adding the following configuration to your kube_prometheus_stack_values.yaml file:

prometheus:
  prometheusSpec:
    serviceMonitorSelectorNilUsesHelmValues: false

In order to use Memgraph’s Prometheus exporter and ServiceMonitor make sure to update values.yaml configuration file:

prometheus:
  enabled: true
  namespace: monitoring
  memgraphExporter:
    port: 9115
    pullFrequencySeconds: 5
    repository: memgraph/mg-exporter
    tag: 0.2.1
  serviceMonitor:
    kubePrometheusStackReleaseName: kube-prometheus-stack
    interval: 15s

If you set prometheus.enabled to false, resources from charts/memgraph/templates/mg-exporter.yaml will still be installed into the monitoring namespace. Refer to the configuration table later in the document for details on all parameters.

To uninstall kube-prometheus-stack, run:

helm uninstall kube-prometheus-stack --namespace monitoring

NOTE: The stack’s CRDs are not deleted automatically and must be removed manually:

kubectl delete crd alertmanagerconfigs.monitoring.coreos.com
kubectl delete crd alertmanagers.monitoring.coreos.com
kubectl delete crd podmonitors.monitoring.coreos.com
kubectl delete crd probes.monitoring.coreos.com
kubectl delete crd prometheusagents.monitoring.coreos.com
kubectl delete crd prometheuses.monitoring.coreos.com
kubectl delete crd prometheusrules.monitoring.coreos.com
kubectl delete crd scrapeconfigs.monitoring.coreos.com
kubectl delete crd servicemonitors.monitoring.coreos.com
kubectl delete crd thanosrulers.monitoring.coreos.com

Remote metrics and logs

The standalone chart can also ship:

• metrics to a remote Prometheus-compatible backend via vmagentRemote (remote_write)
• logs to a Loki-compatible backend via vectorRemote

This is useful when your observability stack lives in a separate cluster or in a managed service.

Prerequisites:

• keep prometheus.enabled: true so mg-exporter is deployed
• for standalone deployments, enable Memgraph monitoring endpoints:
  • service.enableHttpMonitoring: true
  • service.enableWebsocketMonitoring: true
• when vectorRemote.enabled: true, add --monitoring-port=<service.websocketPortMonitoring> and --monitoring-address=0.0.0.0 to memgraphConfig
• if you only need remote shipping and do not want duplicate scraping from kube-prometheus, set prometheus.serviceMonitor.enabled: false

Example values.yaml:

prometheus:
  enabled: true
  namespace: monitoring
  serviceMonitor:
    enabled: false
 
service:
  enableHttpMonitoring: true
  enableWebsocketMonitoring: true
 
memgraphConfig:
  - "--data-directory=/var/lib/memgraph/mg_data"
  - "--also-log-to-stderr=true"
  - "--monitoring-port=7444"
  - "--monitoring-address=0.0.0.0"
 
vmagentRemote:
  enabled: true
  namespace: monitoring
  remoteWrite:
    url: "https://<prom-remote-write>/api/v1/write"
    # Optional: only set basicAuth when your remote_write endpoint requires basic auth.
    basicAuth:
      secretName: monitoring-basic-auth
      usernameKey: username
      passwordKey: password
  externalLabels:
    cluster_id: "memgraph-standalone"
    service_name: "memgraph"
    cluster_env: "dev"
 
vectorRemote:
  enabled: true
  logsEndpoint: "https://<loki-endpoint>"
  # Optional: only set auth when your endpoint requires basic auth.
  auth:
    secretName: monitoring-basic-auth
    usernameKey: username
    passwordKey: password
  extraLabels:
    cluster_id: "memgraph-standalone"
    service_name: "memgraph"
    cluster_env: "dev"
    role: "standalone"

Create credentials secret in the namespace where vmagent runs (usually monitoring):

kubectl create secret generic monitoring-basic-auth -n monitoring \
  --from-literal=username='<username>' \
  --from-literal=password='<password>'

For the standalone Vector sidecar, create the same secret in the Memgraph release namespace as well:

kubectl create secret generic monitoring-basic-auth -n <memgraph-namespace> \
  --from-literal=username='<username>' \
  --from-literal=password='<password>'

Kubernetes infrastructure metrics

vmagentRemote can additionally scrape Kubernetes infrastructure metrics (kube-state-metrics, node-exporter, kubelet) required by kube-prometheus-stack Kubernetes and Node dashboards, and remote-write them to your centralized monitoring cluster.

Enable Kubernetes scraping by extending your existing vmagentRemote values:

vmagentRemote:
  # ... existing fields (enabled, remoteWrite, externalLabels) ...
  kubernetes:
    enabled: true
    kubeStateMetrics:
      enabled: true
      jobName: kube-state-metrics
      targets:
        - kube-prometheus-stack-kube-state-metrics.monitoring.svc.cluster.local:8080
    nodeExporter:
      enabled: true
      jobName: node-exporter
      targets:
        - kube-prometheus-stack-prometheus-node-exporter.monitoring.svc.cluster.local:9100
    kubelet:
      enabled: true
      jobName: kubelet
      metricsPath: /metrics/cadvisor
      apiServerAddress: kubernetes.default.svc:443
      insecureSkipVerify: false

Notes:

• RBAC and ServiceAccount resources are created only when an enabled scrape job requires Kubernetes API access (for example kubelet.enabled=true or nodeExporter.useKubernetesDiscovery=true).
• Keep jobName values aligned with dashboard and recording-rule expectations unless you also update those queries.
• Dashboards that rely on precomputed recording-rule series still require rule evaluation in your monitoring stack.

A ready-to-use example values file is available in the Helm charts repository: examples/remote-monitoring/values-standalone-k8s-metrics.yaml.

Node affinity

The chart exposes the full Kubernetes nodeAffinity spec via the nodeAffinity parameter. This allows you to constrain which nodes Memgraph Pods can be scheduled on based on node labels, using both requiredDuringSchedulingIgnoredDuringExecution and preferredDuringSchedulingIgnoredDuringExecution rules.

Example values.yaml configuration:

nodeAffinity:
  requiredDuringSchedulingIgnoredDuringExecution:
    nodeSelectorTerms:
      - matchExpressions:
          - key: topology.kubernetes.io/zone
            operator: In
            values:
              - antarctica-east1
              - antarctica-west1
  preferredDuringSchedulingIgnoredDuringExecution:
    - weight: 1
      preference:
        matchExpressions:
          - key: my-organization/node-performance
            operator: In
            values:
              - best

For more information, see the Kubernetes documentation on node affinity.

External access with LoadBalancer

By default, the standalone Helm chart creates a ClusterIP service, which is only accessible from within the Kubernetes cluster. If you need to access Memgraph from outside the cluster (e.g., from a local developer machine), you can enable an additional LoadBalancer service.

To enable the LoadBalancer service, set service.loadBalancer.enabled to true in your values.yaml file:

service:
  loadBalancer:
    enabled: true
    type: LoadBalancer
    enableBolt: true

The LoadBalancer service uses the same ports as the main service (Bolt, WebSocket monitoring, HTTP monitoring) but exposes them externally. You can restrict access using loadBalancerSourceRanges:

service:
  loadBalancer:
    enabled: true
    loadBalancerSourceRanges:
      - 1.2.3.4/32
      - 10.0.0.0/8

Additional options like externalTrafficPolicy, ipFamilyPolicy, and ipFamilies are available for fine-grained network configuration. See the configuration table for all parameters.

Configuration options

The following table lists the configurable parameters of the Memgraph standalone chart and their default values.

For all available database settings, refer to the configuration settings docs.

Memgraph high availability Helm chart

Please continue on our Memgraph high availability Helm chart setup.

Memgraph Lab Helm chart

A Helm chart for deploying Memgraph Lab on Kubernetes.

Installing the Memgraph Lab Helm chart

To install the Memgraph Lab Helm chart, follow the steps below:

helm install <release-name> memgraph/memgraph-lab

Replace <release-name> with a name of your choice for the release.

Changing the default chart values

To change the default chart values, run the command with the specified set of flags:

helm install <resource-name> memgraph/memgraph-lab --set <flag1>=<value1>,<flag2>=<value2>,...

Or you can modify a values.yaml file and override the desired values:

helm install <resource-name> memgraph/memgraph-lab -f values.yaml

Gateway API support

The Memgraph Lab Helm chart supports the Kubernetes Gateway API for external access. When enabled, the chart creates an HTTPRoute resource to route HTTP(S) traffic to Memgraph Lab. You can either let the chart create its own Gateway or attach the route to a pre-existing one.

Chart-managed Gateway

To let the chart create a Gateway with an HTTPRoute:

gateway:
  enabled: true
  gatewayClassName: "eg"
  listeners:
    - name: lab-http
      port: 80
      protocol: HTTP

For HTTPS with TLS termination:

gateway:
  enabled: true
  gatewayClassName: "eg"
  listeners:
    - name: lab-https
      port: 443
      protocol: HTTPS
      tls:
        certificateRefs:
          - name: lab-tls-secret

Existing (external) Gateway

To attach an HTTPRoute to a pre-existing Gateway (for example, a shared Gateway that also serves the HA chart):

gateway:
  enabled: true
  existingGatewayName: "memgraph-gateway"

When the existing Gateway uses different listener names than the chart defaults, use httpRoute.sectionNames to specify which listener names the route should attach to:

gateway:
  enabled: true
  existingGatewayName: "memgraph-gateway"
  httpRoute:
    sectionNames:
      - lab-http

You can also configure host-based routing with httpRoute.hostnames:

gateway:
  enabled: true
  existingGatewayName: "memgraph-gateway"
  httpRoute:
    sectionNames:
      - lab-http
    hostnames:
      - lab.example.com

Configuration options

The following table lists the configurable parameters of the Memgraph Lab chart and their default values.

Memgraph Lab can be further configured with environment variables in your values.yaml file.

env:
  - name: QUICK_CONNECT_MG_HOST
    value: memgraph
  - name: QUICK_CONNECT_MG_PORT
    value: "7687"
  - name: KEEP_ALIVE_TIMEOUT_MS
    value: 65000

In case you added Nginx Ingress service or web server for a reverse proxy, update the following proxy timeout annotations to avoid potential timeouts:

proxy_read_timeout X;
proxy_connect_timeout X;
proxy_send_timeout X;

where X is the number of seconds the connection (request query) can be alive. Additionally, update the Memgraph Lab KEEP_ALIVE_TIMEOUT_MS environment variable to a higher value to ensure that Memgraph Lab stays connected to Memgraph when running queries over 65 seconds.

Refer to the Memgraph Lab documentation for details on how to configure Memgraph Lab.

Memgraph MCP Helm chart

A Helm chart for deploying the Memgraph MCP server on Kubernetes. The MCP server exposes Memgraph to LLM clients via the Model Context Protocol, so you can connect agentic applications running in your cluster to a Memgraph backend.

The chart deploys the MCP server as a Deployment fronted by a ClusterIP Service on port 8000. The server connects to a Memgraph instance over Bolt using the URL configured via the MEMGRAPH_URL environment variable; Memgraph itself is not deployed by this chart, so install it separately (for example with the standalone or HA chart) before installing memgraph-mcp.

Installing the Memgraph MCP Helm chart

Before installing, review the env and authSecret sections in values.yaml. The defaults assume Memgraph is reachable at bolt://memgraph-data-0:7687 and that no authentication is required (authSecret.enabled=false).

To install the chart against an unauthenticated Memgraph instance, run:

helm install <release-name> memgraph/memgraph-mcp

Replace <release-name> with a name of your choice for the release.

If your Memgraph deployment requires authentication, create a Kubernetes secret with the credentials and enable authSecret:

kubectl create secret generic mcp-auth-secret \
  --from-literal=MEMGRAPH_USER=<your-user> \
  --from-literal=MEMGRAPH_PASSWORD=<your-password>

helm install <release-name> memgraph/memgraph-mcp \
  --set authSecret.enabled=true

The secret name and key names are configurable via authSecret.name, authSecret.userKey, and authSecret.passwordKey.

Changing the default chart values

To change the default chart values, run the command with the specified set of flags:

helm install <release-name> memgraph/memgraph-mcp --set <flag1>=<value1>,<flag2>=<value2>,...

Or modify a values.yaml file and override the desired values:

helm install <release-name> memgraph/memgraph-mcp -f values.yaml

Connecting the MCP server to Memgraph

The MCP server is configured through environment variables passed via the env list in values.yaml. The most important variables are:

Example values.yaml snippet connecting the MCP server to a standalone Memgraph release named memgraph in the same namespace:

env:
  - name: MEMGRAPH_URL
    value: bolt://memgraph:7687
  - name: MEMGRAPH_DATABASE
    value: memgraph
  - name: MCP_SERVER
    value: server
  - name: MCP_TRANSPORT
    value: streamable-http
  - name: MCP_READ_ONLY
    value: "true"
 
authSecret:
  enabled: true
  name: mcp-auth-secret
  userKey: MEMGRAPH_USER
  passwordKey: MEMGRAPH_PASSWORD

Once installed, the MCP server is available inside the cluster at http://<release-name>-memgraph-mcp:8000/mcp. To reach it from outside the cluster, use kubectl port-forward or override service.type to expose the service through a NodePort or LoadBalancer.

Configuration options

The following table lists the configurable parameters of the Memgraph MCP chart and their default values.

Refer to the MCP documentation for details on how to use the Memgraph MCP server with LLM clients.