Quickstart: Deploy a Neo4j instance to an Azure Kubernetes Service (AKS) cluster

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

1. Prerequisites

  • The az command-line interface (CLI) (https://docs.microsoft.com/en-us/cli/azure/install-azure-cli).

  • 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 Resource Group with:

    • An Azure Kubernetes Service (AKS) cluster.

    • The AKS cluster principal needs to be assigned roles that allow it to manage Microsoft.Compute/disks in the Resource Group.

  • 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 Azure Resource Group and location to use have been set using the AZURE_DEFAULTS_LOCATION and AZURE_DEFAULTS_GROUP environment variables, for example:

    export AZURE_DEFAULTS_GROUP="myneo4jrg"
    export AZURE_DEFAULTS_LOCATION="northeurope"

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

az aks create --name my-neo4j-aks-cluster --node-count=1

You can add the necessary role assignments to the AKS cluster using:

AKS_PRINCIPAL_ID="$(az aks show --name my-neo4j-aks-cluster \
   --query 'identity.principalId' --output tsv)"

az role assignment create --role "Virtual Machine Contributor" \
                          --assignee-object-id "${AKS_PRINCIPAL_ID}"

# update the AKS cluster's credentials so that it picks up the new role assignment
SP_SECRET="$(az ad sp credential reset --name "${AKS_PRINCIPAL_ID}" --query password -o tsv)"

az aks update-credentials \
    --name my-neo4j-aks-cluster \
    --reset-service-principal \
    --service-principal "${AKS_PRINCIPAL_ID}" \
    --client-secret "${SP_SECRET}"

You can configure kubectl to use your AKS cluster using

az aks get-credentials --name my-neo4j-aks-cluster --admin

To install Neo4j, perform the following steps:

2. Create an Azure managed disk

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

az disk create --name "my-neo4j-disk" --size-gb "64" --sku Premium_LRS --max-shares 1

Fetch the ID of the disk that was just created.

az disk show --name "my-neo4j-disk" --query id
Example result
"/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myneo4jrg/providers/Microsoft.Compute/disks/my-neo4j-disk"

3. Create a Helm deployment values file

Create a new file my-neo4j.values.yaml with the following content, replacing <disk 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:
      azureDisk:
        diskName: "my-neo4j-disk"
        diskURI: "<disk id>"
        kind: Managed

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 Azure managed disk, nor does it remove the data it contains:

    az disk show --name "my-neo4j-disk"

    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 AKS cluster, the managed 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 managed disk.

  1. Delete the Azure managed disk:

    az disks delete --name "my-neo4j-disk"

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

az aks delete --name my-neo4j-aks-cluster