Access the Neo4j cluster from outside Kubernetes

By default, server-side routing is used for accessing a Neo4j cluster from outside Kubernetes.

1. Access the Neo4j cluster using a load balancer and Cypher Shell

To access a Neo4j cluster from outside Kubernetes, you need to install the neo4j-cluster-loadbalancer service.

  1. Install the load balancer service using the release name lb, the neo4j/neo4j-cluster-loadbalancer Helm Chart, and the name of your cluster as a value of the neo4j.name parameter.

    Alternatively, you can create a values.yaml file with all the configurations for the service. To see what options are configurable on the neo4j/neo4j-cluster-loadbalancer Helm Chart, use helm show values neo4j/neo4j-cluster-loadbalancer.

    helm install lb neo4j/neo4j-cluster-loadbalancer --set neo4j.name=my-cluster
    NAME: lb
    LAST DEPLOYED: Mon Nov 8 16:11:11 2021
    NAMESPACE: default
    STATUS: deployed
    REVISION: 1
    TEST SUITE: None
    NOTES:
    Thank you for installing neo4j-cluster-loadbalancer.
    
    Your release “lb” has been installed in namespace “default”.
    
    To view the status of your Load Balancer service you can use
     $ kubectl get service lb-neo4j
    
    Once your Load Balancer has an External-IP assigned you can connect to your Neo4j cluster using “neo4j://:7687”. Try:
    
     $ cypher-shell -a “neo4j://:7687"
    
    Graphs are everywhere!
  2. Check that the lb service is available:

    kubectl get services  | grep lb
    NAME               TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)                                                                   AGE
    lb-neo4j           LoadBalancer   10.51.248.52    34.65.252.122   7474:31712/TCP,7473:31942/TCP,7687:31649/TCP                              3m
  3. Use kubectl describe service to see the service details:

    kubectl describe service lb-neo4j
    Name:                     lb-neo4j
    Namespace:                default
    Labels:                   app=my-cluster
                              app.kubernetes.io/managed-by=Helm
                              helm.neo4j.com/neo4j.name=my-cluster
                              helm.neo4j.com/service=neo4j
    Annotations:              cloud.google.com/neg: {"ingress":true}
                              meta.helm.sh/release-name: lb
                              meta.helm.sh/release-namespace: default
    Selector:                 app=my-cluster,helm.neo4j.com/neo4j.loadbalancer=include,helm.neo4j.com/neo4j.name=my-cluster
    Type:                     LoadBalancer
    IP Families:              
    IP:                       10.112.6.150
    IPs:                      10.112.6.150
    LoadBalancer Ingress:     35.205.81.95
    Port:                     http  7474/TCP
    TargetPort:               7474/TCP
    NodePort:                 http  31627/TCP
    Endpoints:                10.108.0.3:7474,10.108.1.19:7474,10.108.2.14:7474 + 1 more...
    Port:                     https  7473/TCP
    TargetPort:               7473/TCP
    NodePort:                 https  32750/TCP
    Endpoints:                10.108.0.3:7473,10.108.1.19:7473,10.108.2.14:7473 + 1 more...
    Port:                     tcp-bolt  7687/TCP
    TargetPort:               7687/TCP
    NodePort:                 tcp-bolt  31988/TCP
    Endpoints:                10.108.0.3:7687,10.108.1.19:7687,10.108.2.14:7687 + 1 more...
    Session Affinity:         None
    External Traffic Policy:  Local
    HealthCheck NodePort:     31343
    Events:                   

    The load-balancer service can send requests to all members of the cluster. You can see that it has four endpoints: three cores and one read-replica.

  4. Run cypher-shell from the local machine and connect to the LoadBalancer Ingress address, in the example 34.65.252.122:

    ./cypher-shell -a neo4j://34.65.252.122 -u neo4j -p my-password
    If you don't see a command prompt, try pressing enter.
    Connected to Neo4j using Bolt protocol version 4.4 at neo4j://34.65.252.122:7687 as user neo4j.
    Type :help for a list of available commands or :exit to exit the shell.
    Note that Cypher queries must end with a semicolon.
  5. Run the Cypher command SHOW DATABASES to verify that all cluster members are online:

    SHOW DATABASES;
    +----------------------------------------------------------------------------------------------------------------------------------------------------------+
    | name     | aliases | access       | address                                 | role           | requestedStatus | currentStatus | error | default | home  |
    +----------------------------------------------------------------------------------------------------------------------------------------------------------+
    | "neo4j"  | []      | "read-write" | "core-1.default.svc.cluster.local:7687" | "follower"     | "online"        | "online"      | ""    | TRUE    | TRUE  |
    | "neo4j"  | []      | "read-write" | "core-3.default.svc.cluster.local:7687" | "follower"     | "online"        | "online"      | ""    | TRUE    | TRUE  |
    | "neo4j"  | []      | "read-write" | "core-2.default.svc.cluster.local:7687" | "leader"       | "online"        | "online"      | ""    | TRUE    | TRUE  |
    | "neo4j"  | []      | "read-write" | "rr-1.default.svc.cluster.local:7687"   | "read_replica" | "online"        | "online"      | ""    | TRUE    | TRUE  |
    | "system" | []      | "read-write" | "core-1.default.svc.cluster.local:7687" | "leader"       | "online"        | "online"      | ""    | FALSE   | FALSE |
    | "system" | []      | "read-write" | "core-3.default.svc.cluster.local:7687" | "follower"     | "online"        | "online"      | ""    | FALSE   | FALSE |
    | "system" | []      | "read-write" | "core-2.default.svc.cluster.local:7687" | "follower"     | "online"        | "online"      | ""    | FALSE   | FALSE |
    | "system" | []      | "read-write" | "rr-1.default.svc.cluster.local:7687"   | "read_replica" | "online"        | "online"      | ""    | FALSE   | FALSE |
    +----------------------------------------------------------------------------------------------------------------------------------------------------------+
    
    8 rows
    ready to start consuming query after 110 ms, results consumed after another 109 ms

    You can see that the nodes are advertising their internal addresses, but since you connected without using internal addresses, you use server-side routing.

2. Access the Neo4j cluster using a load balancer and Neo4j Browser

  1. Open a web browser and point it to the LoadBalancer Ingress address and port 7474, in this example, http://34.65.252.122:7474/browser.

  2. Once connected, verify that all databases are up and running using SHOW DATABASES in the Browser Editor:

    SHOW DATABASES
    +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    │ "name"   │ "aliases" │ "access"     │ "address"                               │ "role"         │ "requestedStatus" │ "currentStatus" │ "error" │ "default" │ "home" │
    +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    │ "neo4j"  │ []        │ "read-write" │ "core-1.default.svc.cluster.local:7687" │ "follower"     │ "online"          │ "online"        │ ""      │ true      │ true   │
    │ "neo4j"  │ []        │ "read-write" │ "core-3.default.svc.cluster.local:7687" │ "follower"     │ "online"          │ "online"        │ ""      │ true      │ true   │
    │ "neo4j"  │ []        │ "read-write" │ "core-2.default.svc.cluster.local:7687" │ "leader"       │ "online"          │ "online"        │ ""      │ true      │ true   │
    │ "neo4j"  │ []        │ "read-write" │ "rr-1.default.svc.cluster.local:7687"   │ "read_replica" │ "online"          │ "online"        │ ""      │ true      │ true   │
    │ "system" │ []        │ "read-write" │ "core-1.default.svc.cluster.local:7687" │ "leader"       │ "online"          │ "online"        │ ""      │ false     │ false  │
    │ "system" │ []        │ "read-write" │ "core-3.default.svc.cluster.local:7687" │ "follower"     │ "online"          │ "online"        │ ""      │ false     │ false  │
    │ "system" │ []        │ "read-write" │ "core-2.default.svc.cluster.local:7687" │ "follower"     │ "online"          │ "online"        │ ""      │ false     │ false  │
    │ "system" │ []        │ "read-write" │ "rr-1.default.svc.cluster.local:7687"   │ "read_replica" │ "online"          │ "online"        │ ""      │ false     │ false  │
    +----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+