Access a Neo4j standalone server

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

Supported Kubernetes services

The Neo4j Helm chart publishes three 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. 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.

  • External — a LoadBalancer service for application neo4j/bolt and http(s) connections originating from outside the Kubernetes cluster.

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

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

7687

Yes

Yes*

Yes

Neo4j Browser HTTP

7474

Yes

Yes*

Yes

Neo4j Browser HTTPS

7473

Yes

Yes*

Yes

Neo4j Cypher HTTP API

7474

Yes

Yes*

Yes

Neo4j Cypher HTTPS API

7473

Yes

Yes*

Yes

Neo4j Backup

6362

No

Yes

No but configurable

Graphite Monitoring

2003

No

Yes

No

Prometheus Metrics

2004

No

Yes

No

Java Management Extensions (JMX)

3637

No

No but configurable

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.

Applications accessing Neo4j from inside Kubernetes

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.

Access Neo4j using K8s label selector

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

For example:

# install neo4j
helm install "my-release" …
# lookup installed service
kubectl get service -l helm.neo4j.com/service=neo4j,helm.neo4j.com/instance=my-release

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.

Applications accessing Neo4j from outside Kubernetes

To access Neo4j from an application outside the Kubernetes cluster, use the IP address of the external service. The external IP(s) of the LoadBalancer can be found using kubectl:

  • Using with the service name <release-name>-external:

    kubectl get service <release-name>-external -ocustom-columns=ip:.status.loadBalancer.ingress[].ip

  • Using a label selector:

    kubectl get service -l helm.neo4j.com/service=external,helm.neo4j.com/name=<release-name> -ocustom-columns=ip:.status.loadBalancer.ingress[].ip

If the Kubernetes LoadBalancer implementation that you are using supports setting a static IP, the IP address of the LoadBalancer can be configured in the Neo4j Helm release by setting externalService.loadBalancerIP. If a static IP address is not explicitly set, then Kubernetes does not guarantee that a dynamically assigned IP address will not change.

When exposing a Neo4j database on the Internet, it is recommended to use a static IP and configure SSL on the exposed services. For more information, see Configure SSL.

If you have static IPs, you can associate DNS with them and obtain trusted certificates.

The ports that are exposed on the external service can be configured in the Helm release by changing the externalService object. The default values are:

externalService:
 annotations: { }
 loadBalancerIP: NULL

 ports:
   http:
     enabled: true
   https:
     enabled: true
   bolt:
     enabled: true
   backup:
     enabled: false

Disabling / enabling a port on the externalService object removes it from the load balancer but does not affect whether it is disabled/enabled in Neo4j.

Backup is not secure unless SSL-with-client-auth is enforced in the Neo4j configuration.

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

neo4jService.annotations

Annotations object for ClusterIP service.

adminService.annotations

Annotations object for headless (DNS) service.

externalService.annotations

Annotations object for LoadBalancer service.

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.

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

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.34 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.