Quickstart: Deploy a Neo4j cluster for analytic queries
The feature is available in the Neo4j Helm chart from version 5.14.
This quickstart shows how to configure and deploy a special Neo4j cluster that comprises one primary server and N secondary servers to support analytic queries.
The primary server handles the transaction workloads, whereas the secondary servers are configured with the Neo4j Graph Data Science library (GDS) and are used only for the analytic workload.
Information on using GDS in a cluster can be found in the Neo4j Graph Data Science library documentation.
The cluster is deployed to a cloud or a local Kubernetes cluster using the Neo4j Helm chart.
Prerequisites
Before you can deploy a Neo4j cluster on Kubernetes, you need to have:
-
A Kubernetes cluster running and the
kubectl
command-line tool installed and configured to communicate with your cluster. For more information, see Quickstart: Deploy a cluster → Prerequisites. -
A valid license for Neo4j Enterprise Edition. For more information, see Install GDS Enterprise Edition (EE) and Bloom plugins.
-
(Optional) A valid license for GDS Enterprise Edition. To install a licensed plugin, you must provide the license files in a Kubernetes secret. For more information, see Install GDS Enterprise Edition (EE) and Bloom plugins.
Create a value YAML file for each type of server
To set up a Neo4j cluster for analytic queries, you need to create a value YAML file for each type of server, primary and secondary. For example:
Create a value YAML file for the primary server, for example, primary-value.yaml:
neo4j:
name: analytics-cluster
acceptLicenseAgreement: "yes"
edition: enterprise
password: my-password
volumes:
data:
mode: defaultStorageClass
# Disable the Neo4j load balancer and enable the internal service so that the servers can access each other:
services:
neo4j:
enabled: false
internals:
enabled: true
# Enable the analytics cluster and set the type to primary:
analytics:
enabled: true
type:
name: primary
Create a value YAML file for the secondary servers, for example, secondary-gds.yaml. The password must be the same as for the primary server. If you are using GDS Enterprise Edition, you also need to create a secret with the license file and mount it as the /licenses volume mount. For more information on how to create a secret, see Install GDS Enterprise Edition (EE) and Bloom plugins.
neo4j:
name: analytics-cluster
acceptLicenseAgreement: "yes"
edition: enterprise
password: my-password
volumes:
data:
mode: defaultStorageClass
# Define the volume mount for the license file:
licenses:
disableSubPathExpr: true
mode: volume
volume:
secret:
secretName: gds-license
items:
- key: gds.license
path: gds.license
# Set the environment variables to download the plugins:
env:
NEO4J_PLUGINS: '["graph-data-science"]'
# Set the configuration for the plugins directory and the mount for the license file:
config:
gds.enterprise.license_file: "/licenses/gds.license"
server.directories.plugins: "plugins"
# Disable the Neo4j load balancer and enable the internal service so that the servers can access each other:
services:
neo4j:
enabled: false
internals:
enabled: true
# Enable the analytics cluster and set the type to secondary:
analytics:
enabled: true
type:
name: secondary
For all available options, see Customizing a Neo4j Helm chart.
Install the servers
-
Install a single Neo4j server using the neo4j-primary.yaml file, created in the previous section:
helm install primary neo4j/neo4j -f /path/to/neo4j-primary.yaml
-
Install the first secondary server using the secondary-gds.yaml file, created in the previous section:
helm install gds1 neo4j/neo4j -f /path/to/secondary-gds.yaml
-
Repeat step 2 to deploy a second secondary server. Use a different name, for example, gds2.
Verify that the GDS library is installed and licensed
-
Connect to each of the
gds
pods using thekubectl exec
command:kubectl exec -it gds1-0 -- bash
-
From the bin folder, connect to the
system
database of thegds1
server using thecypher-shell
command:cypher-shell -u neo4j -p my-password -d system -a bolt://gds1-internals.default.svc.cluster.local:7687
-
Run the following Cypher function to verify that the GDS library is installed:
RETURN gds.version();
-
Call
gds.isLicensed()
to verify that the GDS library is licensed:RETURN gds.isLicensed();
The returned value must be
true
.
Verify the cluster formation
To verify that the cluster is deployed and running, you can install a load balancer and access Neo4j from the Neo4j Browser.
-
Deploy a Neo4j load balancer to the same namespace as the Neo4j cluster:
helm install lb neo4j/neo4j-load-balancer --set neo4j.name="analytics-cluster"
-
When deployed, copy the
EXTERNAL_IP
of the LoadBalancer service. For more information, see Access the Neo4j cluster from outside Kubernetes. -
In a web browser, open the Neo4j Browser at http://EXTERNAL_IP:7474/browser and log in using the password you have configured in your values YAML files.
-
Run the
SHOW SERVERS
command to verify that the cluster is deployed and running. -
Run the
SHOW DATABASES
command to verify that the standalone server is of typeprimary
and the GDS servers are of typesecondary
.