Skip to content

feat: Single-step HA K8s installation #1508

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
as51340 wants to merge 2 commits into
base: memgraph-3-8
Choose a base branch
from
Open

feat: Single-step HA K8s installation #1508

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
89b1ec5
feat: Single-step K8s installation
as51340 Jan 13, 2026
50c6800
docs: Describe different installation namespace
as51340 Jan 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 24 additions & 57 deletions pages/clustering/high-availability/setup-ha-cluster-k8s.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,11 @@ the license and organization name during the installation.
helm install <release-name> memgraph/memgraph-high-availability --set env.MEMGRAPH_ENTERPRISE_LICENSE=<your-license>,env.MEMGRAPH_ORGANIZATION_NAME=<your-organization-name>
```

Replace `<release-name>` with a name of your choice for the release and set the
Enterprise license.

Replace `<release-name>` with a name of your choice for the release and provide your Enterprise license.
The cluster will be fully connected once installation completes. Note that the install command may take a moment while instances establish connections.
If clients connect from outside the cluster, update the Bolt server address on each instance to use its external IP as explained in the section on setting up the cluster.
If for your installation, you are using a namespace different from the default one, make sure to change `--coordinator-hostname` flag in your `values.yaml` file where
coordinators flags are specified.

<Callout type="info"> **Tip:** Always install a specific chart version. Using
the `latest` tag can lead to unexpected behavior if pods restart and pull newer,
Expand Down Expand Up @@ -333,66 +335,31 @@ Memgraph's environment variables.

## Setting up the cluster

Although many configuration options exist, especially for networking, the overall
workflow for creating a Memgraph HA cluster is always the same:

1. **Provision the Kubernetes cluster.** Ensure your nodes, storage, and
networking are ready.

2. **Label nodes (optional)** according to your chosen affinity strategy. For
example, when using `nodeSelection`, label nodes as `data-node` or
`coordinator-node`.

3. **Install the Memgraph HA Helm chart** using `helm install`.
Although many configuration options exist, especially for networking, the workflow for creating a Memgraph HA cluster follows these steps:

4. **Install auxiliary components** (if needed), such as `ingress-nginx` for
external access.
1. Provision the Kubernetes cluster. Ensure your nodes, storage, and networking are ready.
2. Label nodes according to your chosen affinity strategy (optional). For example, when using `nodeSelection`, label nodes as `data-node` or `coordinator-node`.
3. Install the Memgraph HA Helm chart using `helm install`. This creates a fully connected cluster.
4. Install auxiliary components for external access, such as `ingress-nginx` (optional).
5. Update Bolt server addresses if clients will connect from outside the cluster (optional).

5. **Connect the Memgraph instances** to form the HA cluster.
### Update bolt server

### Connect instances
This step is required only when:
- Clients access the database from outside the cluster, and
- You're using bolt+routing for client-side routing

The final step, connecting instances, is **manual**. Each instance must be
informed about the **external addresses** through which it is reachable. Without
this, client-side routing cannot work.

Run the following Cypher queries on **any coordinator**:
Each instance must know its external address for routing to work correctly. Run the following queries on the leader coordinator:

```cypher
ADD COORDINATOR 1 WITH CONFIG {
"bolt_server": "<bolt-server-coord1>",
"management_server": "memgraph-coordinator-1.default.svc.cluster.local:10000",
"coordinator_server": "memgraph-coordinator-1.default.svc.cluster.local:12000"
};

ADD COORDINATOR 2 WITH CONFIG {
"bolt_server": "<bolt-server-coord2>",
"management_server": "memgraph-coordinator-2.default.svc.cluster.local:10000",
"coordinator_server": "memgraph-coordinator-2.default.svc.cluster.local:12000"
};

ADD COORDINATOR 3 WITH CONFIG {
"bolt_server": "<bolt-server-coord3>",
"management_server": "memgraph-coordinator-3.default.svc.cluster.local:10000",
"coordinator_server": "memgraph-coordinator-3.default.svc.cluster.local:12000"
};

REGISTER INSTANCE instance_0 WITH CONFIG {
"bolt_server": "<bolt-server-instance0>",
"management_server": "memgraph-data-0.default.svc.cluster.local:10000",
"replication_server": "memgraph-data-0.default.svc.cluster.local:20000"
};

REGISTER INSTANCE instance_1 WITH CONFIG {
"bolt_server": "<bolt-server-instance1>",
"management_server": "memgraph-data-1.default.svc.cluster.local:10000",
"replication_server": "memgraph-data-1.default.svc.cluster.local:20000"
};

SET INSTANCE instance_1 TO MAIN;
```

Note that the only the `bolt_server` values need to be changed. The correct
UPDATE CONFIG FOR COORDINATOR 1 WITH CONFIG {"bolt_server": "<bolt-server-coord1>"};
UPDATE CONFIG FOR COORDINATOR 2 WITH CONFIG {"bolt_server": "<bolt-server-coord2>"};
UPDATE CONFIG FOR COORDINATOR 3 WITH CONFIG {"bolt_server": "<bolt-server-coord3>"};
UPDATE CONFIG FOR INSTANCE instance_0 WITH CONFIG {"bolt_server": "<bolt-server-instance0>"};
UPDATE CONFIG FOR INSTANCE instance_1 WITH CONFIG {"bolt_server": "<bolt-server-instance1>"};
```

Note that the only the `bolt_server` values are provided. The correct
value depends on the type of external access you configured (LoadBalancer IP,
Ingress host/port, NodePort, etc.).

Expand Down