Quickstart: Deploy a Neo4j instance to an AWS Elastic Kubernetes Service (EKS) cluster

A quick start guide for deploying a Neo4j instance to an AWS Elastic Kubernetes Service (EKS) cluster using Neo4j Helm charts.

1. Prerequisites

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

eksctl create cluster -f <(echo "
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
  name: my-neo4j-eks-cluster
  region: ${AWS_DEFAULT_REGION}
managedNodeGroups:
  - name: my-node-1
    availabilityZones:
      - "${AWS_AVAILABILITY_ZONE}"
    minSize: 1
    maxSize: 2
    instanceType: c4.xlarge
    desiredCapacity: 1
    volumeSize: 10
    ssh:
      allow: true
iam:
  withOIDC: true
")

You can configure kubectl to use your EKS cluster using:

aws eks update-kubeconfig --name my-neo4j-eks-cluster

To install Neo4j, perform the following steps:

2. Create an AWS EBS disk

Create an AWS EBS disk using the following command. This is a normal AWS EBS disk and not Kubernetes specific:

aws ec2 create-volume --availability-zone=${AWS_AVAILABILITY_ZONE} --size=64 --volume-type=gp3 --tag-specifications 'ResourceType=volume,Tags=[{Key=volume,Value=neo4j-k8s}]'

Fetch the ID of the disk that was just created.

aws ec2 describe-volumes --filters Name=tag:volume,Values=neo4j-k8s --query "Volumes[*].{ID:VolumeId}" --output text
Example result
vol-0795be227aff63b2a

3. Create a Helm deployment values file

Create a new file my-neo4j.values.yaml with the following content, replacing <volume id> with the ID of the disk you created:

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:
      awsElasticBlockStore:
        volumeID: "<volume id>"
        fsType: ext4

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  7 19:52:58 2021
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    Thank you for installing neo4j-standalone.
    
    Your release "my-neo4j" has been installed .
    
    To view the progress of the rollout try:
    
      $ kubectl rollout status --watch --timeout=600s statefulset/my-neo4j-release
    
    
    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
    
    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

5. Uninstall Neo4j and clean up created resources

5.1. Uninstall Neo4j Helm deployment

  1. Uninstall Neo4j Helm deployment.

    helm uninstall my-neo4j-release
    release "my-neo4j-release" uninstalled
  2. Uninstalling the Helm Release does not remove the AWS EBS disk, nor does it remove the data it contains:

    aws ec2 describe-volumes --filters Name=tag:volume,Values=neo4j-k8s --query "Volumes[*].{ID:VolumeId}" --output text

    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 you delete the EKS cluster, the EBS disk with the Neo4j data will still exist. Note that the disk will be deleted if its Resource Group is deleted.

5.2. Fully remove all the data and resources

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

  1. Delete the AWS EBS disk using the volume ID:

    aws ec2 delete-volume --volume-id "<volume id>"

If you are sure that you want to delete the entire EKS Kubernetes cluster, run:

eksctl delete cluster my-neo4j-eks-cluster