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.30+)
• kubectl installed and configured
• Neo4j Enterprise Edition (evaluation license acceptable for testing)
• Go 1.26+ (for building from source)
• cert-manager 1.20+ (optional, for TLS-enabled deployments)

Installation

The recommended path is the Helm chart repository (available from v1.8.0 onwards):

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

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

For pre-v1.8.0 releases, the chart is also published to the OCI registry:

helm install neo4j-operator oci://ghcr.io/neo4j-partners/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.

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

# Production deployment (uses local image by default)
make deploy-prod

# Development deployment (uses local image by default)
make deploy-dev

# Alternative: Registry-based deployment
make deploy-prod-registry  # Requires ghcr.io access
make deploy-dev-registry   # Requires registry access for dev image

⚠️ 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 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-service 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 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:

   # For production (with TLS)
   kubectl apply -f examples/clusters/multi-server-cluster.yaml
   
   # For testing (TLS disabled)
   kubectl apply -f examples/clusters/three-node-cluster.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 will now create several Kubernetes resources to bring your cluster to life:

• A StatefulSet to manage the Neo4j pods.
• PersistentVolumeClaims for storing data and logs.
• A headless Service for StatefulSet pod identity.
• A discovery Service for Kubernetes-based cluster formation.
• A client-facing Service for applications to connect to.
• A ConfigMap with your Neo4j configuration.

Cluster Formation Process

For multi-server clusters, all pods start simultaneously using ParallelPodManagement:

Minimal Cluster (2 servers): 1. All server pods: Start simultaneously (ParallelPodManagement) 2. Cluster formation: Servers discover each other and self-organize (1-2 minutes) 3. Ready state: All servers join the cluster automatically

Multi-Server Cluster (3+ servers): 1. All server pods: Start simultaneously for optimal formation 2. Self-organization: Servers automatically assign roles based on database topology requirements 3. Database hosting: Servers can host databases as primaries or secondaries as needed

Total deployment time: 2-3 minutes for minimal clusters, 3-5 minutes for multi-server clusters.

You can monitor the progress with 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-service 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
kubectl port-forward service/multi-server-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

Property Sharding for Large Datasets

For large datasets that require horizontal scaling, you can enable property sharding (Neo4j 2025.12+):

# Create a property sharding enabled cluster
kubectl apply -f examples/property_sharding/basic-property-sharding.yaml

# Create a sharded database with property distribution
kubectl apply -f - <<EOF
apiVersion: neo4j.neo4j.com/v1beta1
kind: Neo4jShardedDatabase
metadata:
  name: large-dataset-db
spec:
  clusterRef: basic-sharding-cluster
  name: largedata
  defaultCypherLanguage: "25"  # Cypher language version: "5" or "25". Cypher 25 requires Neo4j 2025.x or later.
  propertySharding:
    propertyShards: 4
    graphShard:
      primaries: 3
      secondaries: 0
    propertyShardTopology:
      replicas: 1
  wait: true
EOF

For detailed database management, see: - Neo4jDatabase API Reference - Property Sharding Guide - Database Seed URI Guide - Database Examples - Property Sharding 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

For more advanced topics, see: - Configuration Guide - Advanced configuration options - Security Guide - Authentication, TLS, and security best practices - Performance Guide - Optimization and scaling strategies - Migration Guide - Migrating from previous versions