Deploying applications on Kubernetes becomes more convenient and manageable with Helm charts, which offer a convenient package format for defining, installing, and upgrading even complex Kubernetes applications. In this guide, we leverage the official Neo4j Helm charts, which have replaced the older Labs Helm charts project. Helm charts make deploying Neo4j on Kubernetes a seamless process, providing flexibility and customisation options.

This step-by-step guide focuses on deploying a Neo4j cluster on a local Mac Docker Desktop Kubernetes installation. Notes for Windows users have been added for each step as well. Running a cluster locally is invaluable for testing and troubleshooting Kubernetes-related issues in a controlled environment. Whether you are a developer, system administrator, or just exploring Neo4j on Kubernetes, this article will walk you through the process of setting up a Neo4j cluster with ease.

I won't delve into every aspect of the Neo4j Helm chart repository here. However, the diagram below provides a high-level overview of the Helm charts' functionality and the Kubernetes entities they generate. Basically, when using the Helm chart, your responsibility lies in defining values.yaml files that specify your desired configuration. Executing helm install with these specified values will instantiate a Neo4j cluster. I'll elaborate on this process in greater detail later on.

 

 

If you want to read more about the official Neo4j helm charts, please refer to the documentation here.

Prerequisites:

1. Docker Desktop:

Install Docker Desktop for macOS or Windows based on your OS using the official Docker Documentation. 

2. Enable Kubernetes:

Enable the Docker Desktop Kubernetes engine. Open Docker Desktop, go to "Preferences," select the "Kubernetes" tab, and check the "Enable Kubernetes" option. Apply the changes.
For more information, see Docker official documentation.

3. Verify that you do not have a running instance of Neo4j locally to avoid port clashes.

4. Make sure your Docker Desktop has sufficient hardware resources (CPU, Memory, Virtual Disk). The Docker Desktop default limits can be low by default.  NOTE: If using the Windows wsl install of Docker Desktop, this step will differ than as shown below as the resource configuration will be configured in the associated .wslconfig file⁠. 

5. Install kubectl on your machine. 

For macOS, the install command will depend on which processor you have. See the kubectl macOS install documentation. 
For Windows installations, you can use chocolatey to install and reference the kubectl Windows install documentation.

6. Install Helm on your machine.

For macOS, you can use homebrew: brew install helm
For Windows, you can use chocolatey: choco install kubernetes-helm 
For all methods see the official Helm documentation. 

 

Install Neo4j on Kubernetes

We will be deploying a Neo4j cluster with three servers. Therefore we will be creating and installing 3 server-X.values.yaml files.

1. Add the Neo4j Helm chart repository:

> helm repo add neo4j https://helm.neo4j.com/neo4j 
neo4j has been added to your repositories

2. Create the neo4j namespace and make it as the default in the current context:

>kubectl create namespace neo4j
>kubectl config set-context --current --namespace=neo4j

3. Create 3 Helm deployment values files called: server-1.values.yaml, server-2.values.yaml and server-3.values.yaml individually with the following contents:
 

neo4j:
  name: "neo4j-cluster"
  minimumClusterSize: 3
  resources:
    cpu: "1"
    memory: "4Gi"
  edition: "enterprise"
  password: "password"
  acceptLicenseAgreement: "yes"
  startupProbe:
    failureThreshold: 1000
    periodSeconds: 30
config:
  server.memory.heap.initial_size: "3G"
  server.memory.heap.max_size: "3G"
  server.memory.pagecache.size: "1G"

# podAntiAffinity: false required on Docker Desktop / Minikube (default true)
# so the pods can run on a single k8s node.
podSpec:
  podAntiAffinity: false
volumes:
  data:
    mode: defaultStorageClass
    defaultStorageClass:
      requests:
        storage: 2Gi

4. Install the Neo4j servers using helm install and the values created earlier:

>helm install server-1 neo4j/neo4j --namespace neo4j -f server-1.values.yaml
>helm install server-2 neo4j/neo4j --namespace neo4j -f server-2.values.yaml
>helm install server-3 neo4j/neo4j --namespace neo4j -f server-3.values.yaml

Output example:

helm install server-2 neo4j/neo4j --namespace neo4j -f server-2.values.yaml 
NAME: server-2
LAST DEPLOYED: Thu Dec 28 13:33:04 2023
NAMESPACE: neo4j
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Thank you for installing neo4j.

Your release "server-2" has been installed in namespace "neo4j".
The neo4j user's password has been set to "password".
This release creates a single member of a Neo4j cluster. 
It will not become ready until it is able to form a working Neo4j cluster by joining other Neo4j servers. 
To create a working cluster at least 3 servers are required.

Once you have a working Neo4j cluster, you can access the Neo4j browser using the IP address of the neo4j-cluster-lb-neo4j service
eg. http://[SERVICE_IP]:7474

Graphs are everywhere!

WARNING: Passwords set using 'neo4j.password' will be stored in plain text in the Helm release ConfigMap.
Please consider using 'neo4j.passwordFromSecret' for improved security.

 

Verify the Neo4j cluster is running:

>kubectl get pods 

NAME READY STATUS RESTARTS AGE

server-1-0 1/1 Running 0 147m
server-2-0 1/1 Running 0 147m
server-3-0 1/1 Running 0 147m

Access Neo4j logs

>kubectl exec server-2-0 -- tail /logs/neo4j.log

 

Access Neo4j using the Browser:

By default the Neo4j Helm chart provides a LoadBalancer service for accessing Neo4j from outside the Kubernetes cluster. The LoadBalancer service is configured to expose the Neo4j ports.

>kubectl get services 

You can now access the Neo4j Browser via the External-ip of the loadBalancer service. In this case it's localhost:

http://localhost:7474/browser/

To read more about how to access the Neo4j cluster from outside Kubernetes here.

More details about accessing Neo4j on Kubernetes can be found here.

 

Uninstall Neo4j and clean up the created resources:

To uninstall Neo4j and delete the resources, you can use the Helm uninstall command:

helm uninstall server-1 --namespace neo4j
helm uninstall server-2 --namespace neo4j
helm uninstall server-3 --namespace neo4j

 

Note: When using Helm to uninstall a release, the default behaviour is to preserve PersistentVolumeClaims (PVCs) associated with the release. This can lead to situations where PVCs are not automatically deleted, and they persist even after uninstalling the Helm chart.

Adding the --delete flag instructs Helm to delete associated PVCs along with the release, ensuring a more comprehensive cleanup.

Author: Mounir Babari