Access a Neo4j cluster

This section describes how to access a Neo4j cluster running on Kubernetes.

A Neo4j cluster is accessible via Kubernetes Services. Neo4j has a number of different interfaces for different application and operational purposes. For more details, see Neo4j ports.

1. Supported Kubernetes services

The Neo4j Helm chart publishes four K8s services:

  • Neo4j Service — a ClusterIP service for application neo4j/bolt and http(s) connections to the Neo4j database, originating from inside the Kubernetes cluster.

  • Admin Service — a “Headless” (DNS only) service that includes all Neo4j ports for admin connections to Neo4j inside Kubernetes. It is only available inside the Kubernetes cluster and access to it should be guarded. The Admin service can be used for Neo4j DBMS administration, performing backups, and collecting metrics.

  • Internal Service — a “Headless” (DNS only) internal service that includes all Neo4j ports required for causal clustering.

  • External — a LoadBalancer service for application neo4j/bolt and http(s) connections originating from outside the Kubernetes cluster. This service is installed using the neo4j/neo4j-cluster-loadbalancer Neo4j Helm Chart.

Table 1. K8s services per Neo4j interface
Neo4j Interface Default Port Neo4j Service Admin Service Internal Service External Service

Bolt (neo4j:// and bolt:// protocols)

7687

Yes

Yes*

Yes

Yes

Neo4j Browser HTTP

7474

Yes

Yes*

Yes

Yes

Neo4j Browser HTTPS

7473

Yes

Yes*

Yes

Yes

Neo4j Cypher HTTP API

7474

Yes

Yes*

Yes

Yes

Neo4j Cypher HTTPS API

7473

Yes

Yes*

Yes

Yes

Neo4j Backup

6362

No

Yes

Yes

No

Graphite Monitoring

2003

No

No but configurable

No but configurable

No

Prometheus Metrics

2004

No

No but configurable

No but configurable

No

Java Management Extensions (JMX)

3637

No

No but configurable

No but configurable

No

Causal Cluster discovery management

5000

No

No

Yes

No

Causal Cluster transaction

6000

No

No

Yes

No

Causal Cluster RAFT

7000

No

No

Yes

No

Causal Cluster routing connector

7688

No

No

Yes

No

*The Admin service bypasses health checks. This allows it to be used to make connections for administrative purposes when the database is in an unhealthy state. However, you must not use it to connect from applications that require the database to be in a healthy state.

2. Applications accessing Neo4j from inside Kubernetes

2.1. Access Neo4j using DNS

To access Neo4j from an application in the same Kubernetes cluster use the Neo4j service DNS address <release-name>.<namespace>.svc.<cluster domain>.

The default cluster domain is cluster.local and the default namespace is default. Generally, the Neo4j service DNS address is <release-name>.default.svc.cluster.local.

For example, if using the release name my-release in the default namespace, the cluster’s DNS address would be my-release.default.svc.cluster.local, and the bolt address for use with Neo4j drivers would be neo4j://my-release.default.svc.cluster.local:7687.

To allow for an application running inside Kubernetes to access the Neo4j cluster, you can also use the Neo4j headless service that is installed via the neo4j/neo4j-cluster-headless-service Helm Chart. For more information and a detailed example, see Access the Neo4j cluster using headless service.

2.2. Access Neo4j using K8s label selector

Alternatively, the Neo4j service (default) in Kubernetes can be located using Kubernetes service discovery by searching with the label selector: helm.neo4j.com/service=default/admin/internals,helm.neo4j.com/instance=<release-name>.

The following is an example of how to look up the installed services:

# Neo4j service:

kubectl get service -l helm.neo4j.com/service=default,helm.neo4j.com/instance=my-release

# Admin service:

kubectl get service -l helm.neo4j.com/service=admin,helm.neo4j.com/instance=my-release

# internals service:

kubectl get service -l helm.neo4j.com/service=internals,helm.neo4j.com/instance=my-release

2.3. Ad-hoc external access using kubectl port-forward

In most cases, it is possible to access the Neo4j service from a developer machine outside the Kubernetes cluster using kubectl port-forward. To access the Neo4j service for http(s) and neo4j/bolt from a developer machine, use the following command:

kubectl port-forward svc/<release-name> tcp-bolt tcp-http tcp-https

Neo4j is accessible via the Neo4j browser at http://localhost:7474.

3. Applications accessing Neo4j from outside Kubernetes

To access a Neo4j cluster from outside Kubernetes, you need to install the neo4j-cluster-loadbalancer service using the neo4j/neo4j-cluster-loadbalancer Helm Chart. For a detailed example, see Access the Neo4j cluster from outside Kubernetes.

4. Customizing Kubernetes Resources

The Neo4j Helm chart creates various Kubernetes resources. Some of them can be customized by adding extra configuration to the helm deployment values file.

Table 2. Supported K8s resources customizations
Customization values.yaml field Type

Setting a pod securityContext for the Neo4j Pod

securityContext

PodSecurityContext

Adding annotations to Services

services.neo4j.annotations

Annotations object for ClusterIP service.

services.admin.annotations

Annotations object for headless (DNS) service.

services.internal.annotations

Annotations object for internal service.

Adding annotations to Load Balancer Service

annotations

Annotations object for LoadBalancer service.

5. Accessing Neo4j for DBMS administration and monitoring

The Neo4j Helm chart creates the admin service for the purposes of Neo4j administration. The admin service is a “Headless” service in Kubernetes and does not depend on Neo4j health checks. Therefore, it permits connections to Neo4j even if Neo4j is not healthy. In general, that is not desirable for applications but can be useful for administration and debugging.

5.1. Access Neo4j using DNS

To access the admin service inside Kubernetes use the DNS address <release-name>-admin.<namespace>.svc.<cluster domain>.

For example, if using the release name my-release in the default namespace, the cluster’s DNS address would be my-release-admin.default.svc.cluster.local.

The admin service can be used to access a range of Neo4j interfaces:

  • Neo4j Bolt for Neo4j administration via Cypher commands

  • Neo4j Backup for taking database backups

  • Graphite for metrics collection

  • Prometheus for metrics collection

  • Java Management Extensions (JMX) for metrics collection and JVM administration

5.2. Access Neo4j using kubectl for troubleshooting

To get an interactive cypher-shell console for troubleshooting, use this command:

kubectl run -it --rm --image neo4j:4.4.8 cypher-shell -- cypher-shell -a bolt://my-release-admin.default.svc.cluster.local

Generally, the neo4j:// protocol is used for connecting to Neo4j. For troubleshooting, though, the direct bolt:// protocol is used because it allows a connection in some situations where a neo4j:// connection will not succeed.