Quickstart: Deploy a Neo4j instance to a Google Kubernetes Engine (GKE) cluster

A quick start guide for deploying a Neo4j instance to a Google Kubernetes Engine (GKE) cluster using Neo4j Helm charts.

1. Prerequisites

  • The gcloud command-line interface (CLI) (https://cloud.google.com/sdk/docs/install).

  • The kubectl Kubernetes client command-line tool (https://kubernetes.io/docs/tasks/tools/).

  • The helm command-line tool (https://helm.sh/docs/intro/install/).

  • A Google Kubernetes Engine (GKE) cluster.

  • Verify that your Kubernetes nodes have sufficient CPU and memory for your Neo4j deployment.

    We recommend using nodes with at least 4 CPUs and 4GB of memory. This size can usually fit a Neo4j instance with 1CPU and 2GB memory. For more information on Neo4j’s system requirements, see System requirements.

  • Verify that you have a valid license if you want to install Neo4j Enterprise Edition. For more information, see https://neo4j.com/licensing/ or write to licensing@neo4j.com.

  • All the shell commands in this guide assume that the GCP Project, compute zone, and region to use have been set using the CLOUDSDK_CORE_PROJECT, CLOUDSDK_COMPUTE_ZONE, and CLOUDSDK_COMPUTE_REGION environment variables, for example:

    export CLOUDSDK_CORE_PROJECT="my-neo4j-project"
    export CLOUDSDK_COMPUTE_ZONE="europe-west2-a"
    export CLOUDSDK_COMPUTE_REGION="europe-west2"

If you do not have a GKE cluster, you can create a single-node one using:

gcloud container clusters create my-neo4j-gke-cluster --num-nodes=1

You can configure kubectl to use your GKE cluster using:

gcloud container clusters get-credentials my-neo4j-gke-cluster

To install Neo4j, perform the following steps:

2. Create a GCP persistent disk

Create a GCP persistent disk using the following command. This is a normal GCP persistent disk and not Kubernetes specific:

gcloud compute disks create --size 128Gi --type pd-ssd "my-neo4j-disk"
Example output
Created [https://www.googleapis.com/compute/v1/projects/my-neo4j-project/zones/europe-west2-a/disks/my-neo4j-disk].
NAME           ZONE            SIZE_GB  TYPE    STATUS
my-neo4j-disk  europe-west2-a  128      pd-ssd  READY

New disks are unformatted. You must format and mount a disk before it
can be used. You can find instructions on how to do this at:

https://cloud.google.com/compute/docs/disks/add-persistent-disk#formatting

The message New disks are unformatted. You must format and mount a disk before it can be used. should not be a cause for concern, and there is no need to take action to format the disk. If necessary, the disk will be formatted automatically when used in Kubernetes.

3. Create a Helm deployment values file

Create a new file my-neo4j.values.yaml with the following content:

neo4j:
  resources:
    cpu: "1"
    memory: "2Gi"

  # Uncomment to set the initial password
  #password: "my-initial-password"

  # Uncomment to use enterprise edition
  #edition: "enterprise"
  #acceptLicenseAgreement: "yes"

volumes:
  data:
    mode: "volume"
    volume:
      gcePersistentDisk:
        pdName: "my-neo4j-disk"

For details of all Neo4j Helm chart configuration options, see Configure and install Neo4j using a customized Helm chart.

4. Install Neo4j

  1. Ensure your Helm chart repositories are up to date:

    helm repo update
  2. Install Neo4j using the deployment values file created in Create a Helm deployment values file:

    helm install my-neo4j-release neo4j/neo4j-standalone -f my-neo4j.values.yaml
    Example output
    NAME: my-neo4j-release
    LAST DEPLOYED: Wed Jul 28 13:16:39 2021
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    Thank you for installing neo4j-standalone.
    
    Your release "my-neo4j-release" has been installed .
    
    To view the progress of the rollout try:
    
      $ kubectl rollout status --watch --timeout=600s statefulset/my-neo4j-release
    
    
    The neo4j user's password has been set to "bO7YDTVOgs7CS1".
    
    Once rollout is complete you can log in to Neo4j at "neo4j://my-neo4j-release.default.svc.cluster.local:7687". Try:
    
      $ kubectl run --rm -it --image "neo4j:4.3.2" cypher-shell \
         -- cypher-shell -a "neo4j://my-neo4j-release.default.svc.cluster.local:7687" -u neo4j -p "bO7YDTVOgs7CS1"
    
    Graphs are everywhere!
  3. Run the kubectl rollout command provided in the output of helm install to watch the Neo4j’s rollout until it is complete.

    kubectl rollout status --watch --timeout=600s statefulset/my-neo4j-release

    Since you have not passed a password for the neo4j user, the Neo4j Helm chart has set an automatically generated one. You can find it in the Helm install output. Please make a note of it.

5. Verify the installation

  1. Check that the statefulset is OK. Initially it will not be ready but just check there is something there.

    kubectl --namespace default get statefulsets
    Example output
    NAME               READY   AGE
    my-neo4j-release   1/1     2m11s
  2. Check that the pod is Running:

    kubectl --namespace default get pods
    Example output
    NAME                 READY   STATUS    RESTARTS   AGE
    my-neo4j-release-0   1/1     Running   0          16m
  3. Check that the pod logs look OK:

    kubectl --namespace default exec my-neo4j-release-0 -- tail -n50 /logs/neo4j.log
    Example output
    2021-07-28 12:45:50.267+0000 INFO  Command expansion is explicitly enabled for configuration
    2021-07-28 12:45:50.280+0000 INFO  Starting...
    2021-07-28 12:45:55.680+0000 INFO  ======== Neo4j 4.3.2 ========
    2021-07-28 12:46:00.006+0000 INFO  Bolt enabled on [0:0:0:0:0:0:0:0%0]:7687.
    2021-07-28 12:46:02.476+0000 INFO  Remote interface available at http://localhost:7474/
    2021-07-28 12:46:02.478+0000 INFO  Started.
  4. Check that the services look OK:

    kubectl get services --namespace default
    Example output
    NAME                     TYPE           CLUSTER-IP      EXTERNAL-IP    PORT(S)                                        AGE
    kubernetes               ClusterIP      10.112.0.1      <none>         443/TCP                                        28h
    my-neo4j-release         ClusterIP      10.112.10.159   <none>         7687/TCP,7474/TCP,7473/TCP                     41m
    my-neo4j-release-admin   ClusterIP      10.112.4.73     <none>         6362/TCP,7687/TCP,7474/TCP,7473/TCP            41m
    my-neo4j-release-neo4j   LoadBalancer   10.112.6.75     34.140.48.23   7474:31420/TCP,7473:31591/TCP,7687:31650/TCP   41m
  5. In a web browser, open the Neo4j Browser at http://<EXTERNAL-IP>:7474/browser.

  6. Use the automatically generated password (as printed in the output of the helm install command) or the one you have configured in the my-neo4j.values.yaml file.

6. Uninstall Neo4j and clean up the created resources

6.1. Uninstall Neo4j Helm deployment

Uninstall the Neo4j Helm deployment.

helm uninstall my-neo4j-release
Example output
release "my-neo4j-release" uninstalled

Uninstalling the Helm release does not remove the GCP persistent disk, nor does it remove the data it contains.

gcloud compute disks describe "my-neo4j-disk"
Example output
creationTimestamp: '2021-07-28T04:54:59.385-07:00'
id: '756334900703722364'
kind: compute#disk
labelFingerprint: 42WmSpB8rSM=
lastAttachTimestamp: '2021-07-28T05:45:03.723-07:00'
lastDetachTimestamp: '2021-07-28T06:00:18.793-07:00'
name: my-neo4j-disk
physicalBlockSizeBytes: '4096'
selfLink: https://www.googleapis.com/compute/v1/projects/my-neo4j-project/zones/europe-west2-a/disks/my-neo4j-disk
sizeGb: '128'
status: READY
type: https://www.googleapis.com/compute/v1/projects/my-neo4j-project/zones/europe-west2-a/diskTypes/pd-ssd
zone: https://www.googleapis.com/compute/v1/projects/my-neo4j-project/zones/europe-west2-a

If you re-create Neo4j with the same settings, it will pick up the same disk again, and all the data will still be on it.

Even if the GKE cluster is deleted, the persistent disk with the Neo4j data will still exist.

6.2. Fully remove all the data and resources

After uninstalling the helm deployment, the only remaining step is to delete the GCP persistent disk.

  1. Delete the GCP persistent disk:

    gcloud compute disks delete my-neo4j-disk
    Example output
    The following disks will be deleted:
     - [my-neo4j-disk] in [europe-west2-a]
    Do you want to continue (Y/n)?  y
    Deleted [https://www.googleapis.com/compute/v1/projects/my-neo4j-project/zones/europe-west2-a/disks/my-neo4j-disk].

    If you want to delete the entire GKE Kubernetes cluster, run:

    gcloud container clusters delete my-neo4j-gke-cluster