Accessing Neo4j

A Neo4j running on Kubernetes 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

Neo4j supports the following Kubernetes services:

  • Default 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 the Neo4j cluster.

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

The following is a list of the default Kubernetes services per Neo4j interface and deployment type:

Neo4j Interface Default Port Default Service Admin Service Neo4j 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
Neo4j Interface Default Port Default Service Admin Service Internal Service Neo4j 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

Cluster discovery management

5000

No

No

Yes

No

Cluster transaction

6000

No

No

Yes

No

Cluster RAFT

7000

No

No

Yes

No

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.

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.

To allow for an application running inside Kubernetes to access a 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.

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>

For example:

# install neo4j
helm install "my-release" …
# lookup installed service
kubectl get service -l helm.neo4j.com/service=default,helm.neo4j.com/instance=my-release
helm.neo4j.com/service=neo4j,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

Applications accessing Neo4j from outside Kubernetes

To access Neo4j from an application outside the Kubernetes cluster, you can use a LoadBalancer service or an Ingress controller.

Access Neo4j using a LoadBalancer

Neo4j Helm chart provides a LoadBalancer service for accessing Neo4j from outside the Kubernetes cluster. The LoadBalancer service is created by default when installing the Neo4j Helm chart. The LoadBalancer service is configured to expose the Neo4j ports 7687, 7474, 7473, and 6362 (backup) by default.

The external IP(s) of the LoadBalancer can be found using kubectl:

  • The service name is based on the value of the neo4j.name — <my-neo4j-name>-lb-neo4j:

    kubectl get service `<my-neo4j-name>-lb-neo4j` -ocustom-columns=ip:.status.loadBalancer.ingress[].ip

  • Using a label selector:

    kubectl get service -l helm.neo4j.com/service=neo4j,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 services.neo4j object. The default values are:

services:
  neo4j:
     annotations: { }
     loadBalancerIP: NULL
     ports:
       http:
         enabled: true
         # uncomment to publish http on port 80 (neo4j default is 7474)
         # port: 80
         # targetPort: 7474
         # name: http
       https:
         enabled: true
        # uncomment to publish http on port 443 (neo4j default is 7473)
        # port: 443
        # targetPort: 7473
        # name: https
       bolt:
         enabled: true
        # Uncomment to explicitly specify the port to publish Neo4j Bolt (7687 is the default)
        # port: 7687
        # targetPort: 7687
        # name: tcp-bolt
       backup:
         enabled: false
        # Uncomment to explicitly specify the port to publish Neo4j Backup (6362 is the default)
        # port: 6362
        # targetPort: 6362
        # name: tcp-backup

Disabling/enabling a port on the services.neo4j 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.

For a detailed example, see Access the Neo4j cluster from outside Kubernetes.

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.

The following is a list of the supported K8s resources customizations:

Customization values.yaml field Type

Setting a pod securityContext for the Neo4j Pod

securityContext

PodSecurityContext

Adding annotations to Services

services.default.annotations

Annotations object for ClusterIP service.

services.admin.annotations

Annotations object for headless (DNS) service.

services.neo4j.annotations

Annotations object for LoadBalancer service.
Customization values.yaml field Type

Setting a pod securityContext for the Neo4j Pod

securityContext

PodSecurityContext

Adding annotations to Services

services.default.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

services.neo4j.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:5.25.1 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.