Getting Started

This guide will walk you through the process of deploying your first Neo4j Enterprise instance on Kubernetes using the Neo4j Enterprise Operator. You can choose between clustered and standalone deployments based on your needs.

Prerequisites

• A Kubernetes cluster (v1.32+)
• kubectl installed and configured
• Neo4j Enterprise Edition — 5.26 LTS or any CalVer release (2025.x, 2026.x, …); evaluation license acceptable for testing. See Supported Neo4j Versions for the full support policy.
• cert-manager 1.20+ (optional, for TLS-enabled deployments)

Building from source additionally needs Go 1.27+ — see the Installation Guide for that path.

Neo4j version: the examples below use 5.26-enterprise, the 5.26 LTS line (it tracks the latest 5.26 patch), but every one works on a CalVer release too — just change the image tag (e.g. 2026.08.1-enterprise). The operator auto-detects CalVer (discovery mode, Cypher 25, etc.); nothing else in the manifest changes. For the CalVer-only default Cypher 25 language on a database, see examples/databases/database-2025x.yaml.

Installation

The recommended path is the Helm chart repository:

helm repo add neo4j-operator https://priyolahiri.github.io/neo4j-kubernetes-operator/charts
helm repo update

helm install neo4j-operator neo4j-operator/neo4j-operator \
  --namespace neo4j-operator-system \
  --create-namespace

The chart is also published to the OCI registry:

helm install neo4j-operator oci://ghcr.io/priyolahiri/charts/neo4j-operator \
  --version <release-version> \
  --namespace neo4j-operator-system \
  --create-namespace

For all installation methods (kubectl-apply bundle, source clone, make targets for contributor workflows), see the full Installation Guide.

Install the CLI at the same time

This operator has no admission webhooks, so a spec mistake is only reported after you apply. The kubectl-neo4j CLI closes that loop from your side:

kubectl neo4j validate -f my-cluster.yaml   # the manifest, against the operator's own validators
kubectl neo4j preflight -f my-cluster.yaml  # the cluster it is about to land in
kubectl apply -f my-cluster.yaml
kubectl neo4j status                        # what came up
kubectl neo4j diagnose                      # and why anything did not

It ships on the same release tag as the operator — see Installing the CLI.

Operator Modes

The Neo4j Operator supports two operational modes:

• Production Mode (default): Optimized for stability, security, and monitoring in production environments
• Development Mode: Optimized for rapid development, debugging, and local testing

For detailed information about modes, configuration options, and caching strategies, see the Operator Modes Guide.

Quick Mode Selection

The Helm install above runs in production mode by default; set developmentMode: true in your values for development mode. Contributors working from a clone of this repository can instead use the make deployment targets (make deploy-prod, make deploy-dev) — see the Makefile reference.

⚠️ Important: The operator must always run in-cluster, even for development. This ensures proper DNS resolution and cluster connectivity required for Neo4j cluster formation.

Choosing Your Deployment Type

The Neo4j Enterprise Operator supports two deployment types:

• Neo4jEnterpriseStandalone: Single-node deployments for development, testing, and simple production workloads
• Neo4jEnterpriseCluster: Clustered deployments (minimum 2 servers) for production with high availability and automatic failover

Deploying a Standalone Instance (Development)

For development, testing, or simple workloads that don't require high availability:

1. Create admin credentials:

   kubectl create secret generic neo4j-admin-secret \
     --from-literal=username=neo4j \
     --from-literal=password=your-secure-password
   

2. Deploy the standalone instance:

   kubectl apply -f https://raw.githubusercontent.com/priyolahiri/neo4j-kubernetes-operator/main/examples/standalone/single-node-standalone.yaml
   

3. Check deployment status:

   kubectl get neo4jenterprisestandalone
   kubectl get pods
   

4. Access Neo4j Browser:

   kubectl port-forward svc/standalone-neo4j-client 7474:7474 7687:7687
   

   Open http://localhost:7474 in your browser.

Deploying a Cluster (Production)

For production workloads requiring high availability and clustering:

Option 1: Minimal Cluster (Recommended for Testing)

1. Create admin credentials:

   kubectl create secret generic neo4j-admin-secret \
     --from-literal=username=neo4j \
     --from-literal=password=your-secure-password
   

2. Deploy the minimal cluster:

   kubectl apply -f https://raw.githubusercontent.com/priyolahiri/neo4j-kubernetes-operator/main/examples/clusters/minimal-cluster.yaml
   

3. Monitor deployment (2-3 minutes expected):

   kubectl get pods -l app.kubernetes.io/name=neo4j -w
   

Option 2: Multi-Server Cluster (Recommended for Production)

1. Create admin credentials:

   kubectl create secret generic neo4j-admin-secret \
     --from-literal=username=neo4j \
     --from-literal=password=your-secure-password
   

2. Deploy the cluster:

   # Five-server production cluster (TLS via cert-manager)
   kubectl apply -f https://raw.githubusercontent.com/priyolahiri/neo4j-kubernetes-operator/main/examples/clusters/multi-server-cluster.yaml
   
   # Three-server cluster, no TLS (simplest for local testing)
   kubectl apply -f https://raw.githubusercontent.com/priyolahiri/neo4j-kubernetes-operator/main/examples/clusters/three-node-simple.yaml
   

3. Monitor deployment (3-5 minutes expected):

   kubectl get pods -l app.kubernetes.io/name=neo4j -w
   

Option 3: Custom Configuration

If you need a custom configuration, create your own manifest based on our examples:

1. Browse the examples directory:
2. Minimal cluster - 2 servers (minimum cluster topology)
3. Multi-server cluster - Production HA with TLS
4. Three-node cluster - Three servers with TLS

5. Production optimized cluster - Production with advanced features

6. Copy and customize an example:

   cp examples/clusters/minimal-cluster.yaml my-cluster.yaml
   # Edit my-cluster.yaml to customize settings
   kubectl apply -f my-cluster.yaml
   

See the Examples README for detailed customization guidance.

What Happens Next?

The operator creates a StatefulSet, per-pod PersistentVolumeClaims, headless + client Services, and a ConfigMap with the rendered Neo4j configuration. All Pods start in parallel; cluster formation typically takes 2-3 minutes for a 2-server cluster, 3-5 minutes for larger topologies.

kubectl get pods -w

Accessing Your Deployment

Once the pods are in the Running state, you can access your deployment using kubectl port-forward:

For Standalone Deployments

# For standalone deployment
kubectl port-forward service/standalone-neo4j-client 7474:7474 7687:7687

For Cluster Deployments

# For minimal cluster
kubectl port-forward service/minimal-cluster-client 7474:7474 7687:7687

# For multi-server cluster (multi-server-cluster.yaml deploys a CR named "multi-primary-cluster")
kubectl port-forward service/multi-primary-cluster-client 7474:7474 7687:7687

# For your custom cluster (replace with your cluster name)
kubectl port-forward service/YOUR-CLUSTER-NAME-client 7474:7474 7687:7687

You can then access the Neo4j Browser at http://localhost:7474.

Creating Databases

Once your cluster is running, you can create and manage databases using the Neo4jDatabase CRD:

Basic Database Creation

# Create a simple database
kubectl apply -f - <<EOF
apiVersion: neo4j.neo4j.com/v1beta1
kind: Neo4jDatabase
metadata:
  name: my-database
spec:
  clusterRef: minimal-cluster  # or your cluster name
  name: mydb
  wait: true
  ifNotExists: true
EOF

Database from Existing Backup (Seed URI)

If you have existing Neo4j backups in cloud storage, you can create databases directly from them:

# Create database from S3 backup
kubectl apply -f - <<EOF
apiVersion: neo4j.neo4j.com/v1beta1
kind: Neo4jDatabase
metadata:
  name: restored-database
spec:
  clusterRef: minimal-cluster
  name: restored-db
  seedURI: "s3://my-backups/database.backup"
  topology:
    primaries: 1
    secondaries: 1
  wait: true
  ifNotExists: true
EOF

For large datasets that need horizontal scaling, see the Property Sharding guide (Neo4j 2025.12+, via Neo4jShardedDatabase).

See also:

• Neo4jDatabase API Reference
• Database Seed URI Guide
• Database Examples

Next Steps

Now that you have Neo4j running on Kubernetes:

1. Explore the Neo4j Browser - Create some sample data and run queries
2. Create databases - Use the Neo4jDatabase CRD to create and manage databases
3. Connect your applications - Use the Bolt endpoint (port 7687) for programmatic access
4. Configure monitoring - Set up monitoring and alerting for your deployment
5. Plan backups - Implement backup strategies for data protection
6. Scale your deployment - For clusters, you can scale up/down based on your needs

Browse the examples

Ready-to-apply YAML manifests for every CRD live under examples/:

Directory	What's in it
standalone/	Single-node Neo4jEnterpriseStandalone examples
clusters/	Neo4jEnterpriseCluster topologies (minimal, prod, TLS, fleet-managed)
databases/	Neo4jDatabase examples (basic, seed URI, custom topology)
users-roles/	Neo4jUser, Neo4jRole, Neo4jRoleBinding, Neo4jAuthRule
plugins/	Neo4jPlugin examples (APOC, GDS, Bloom, GenAI, …)
backup-restore/	Neo4jBackup, Neo4jRestore (PVC, S3, GCS, Azure, PITR)
property_sharding/	Neo4jShardedDatabase setups
cross-cluster-replication/	Neo4jReplicaDatabase, Neo4jReplicaPromotion, Neo4jDatabaseAlias — DR replication across two Kubernetes clusters
security/	NetworkPolicy + Kyverno conformance policies

For more advanced topics, see:

• Configuration Guide - Advanced configuration options
• Security Guide - Authentication, TLS, and security best practices
• Performance Guide - Optimization and scaling strategies
• Upgrade Guide - Upgrading between releases