Neo4j Enterprise Operator for Kubernetes

The Neo4j Kubernetes Operator automates the deployment and management of Neo4j Enterprise Edition.

The Operator deploys Neo4j EE v5.26+. It supports both clustered and standalone deployments for cloud-native graph database operations.

Warning

Alpha Software — Please Read Before Using

This project is in alpha stage and is maintained by a single maintainer in a personal capacity. Development is assisted by LLM-based tooling, which means the codebase may contain subtle bugs, incomplete features, or unexpected behavior despite best efforts.

• No production guarantees: This operator is not recommended for production workloads without thorough independent validation. Use at your own risk.
• No official Neo4j support: This project is not an official Neo4j product and is not supported by Neo4j, Inc. in any capacity. The maintainer is a Product Manager at Neo4j, but maintains this project in a personal capacity. Support is provided solely by the maintainer on a best-effort basis through GitHub Issues.
• Breaking changes: As an alpha project, APIs and behavior may change between releases without notice.

📑 Table of Contents

• Requirements
• Quick Start
  • Installation
  • Cleanup
  • Development Installation
• Database Management
• Property Sharding
• Backup and Restore
• Examples
• Authentication
• Documentation Structure
• Key Features
• Common Use Cases
• Recent Improvements
• Contributing
• Support

📋 Requirements

• Neo4j: Version 5.26.x (last semver LTS) or 2025.x.x+ (CalVer — the successor versioning scheme)
• Kubernetes: Version 1.21 or higher
• Go: Version 1.24+ (for development)
• cert-manager: Version 1.18+ (optional, only required for TLS-enabled Neo4j deployments)

🚀 Quick Start

Installation

Installation requires cloning from source:

1. Clone the repository and checkout the latest tag:

   # Clone the repository
   git clone https://github.com/neo4j-partners/neo4j-kubernetes-operator.git
   cd neo4j-kubernetes-operator
   
   # Checkout the latest release tag
   LATEST_TAG=$(git describe --tags --abbrev=0)
   git checkout $LATEST_TAG

2. Install the operator using Helm (recommended) or make targets:

   Helm Installation (Recommended):

   # Install using Helm chart (automatically handles RBAC)
   helm install neo4j-operator ./charts/neo4j-operator \
     --namespace neo4j-operator-system \
     --create-namespace

   # Install from GHCR OCI registry
   helm install neo4j-operator oci://ghcr.io/neo4j-partners/charts/neo4j-operator \
     --version <release-version> \
     --namespace neo4j-operator-system \
     --create-namespace

   Note: use the chart version without the v prefix (for example, 0.2.0).

   Make Targets:

   # Install CRDs into your cluster
   make install
   
   # Deploy the operator (choose based on your environment)
   make deploy-prod        # Production deployment (uses local neo4j-operator:latest image)
   make deploy-dev         # Development deployment (uses local neo4j-operator:dev image)
   
   # Registry-based deployment (requires cluster-admin permissions)
   make deploy-prod-registry  # Deploy from Docker Hub registry (auto-checks RBAC)
   make deploy-dev-registry   # Deploy dev overlay with registry image (auto-checks RBAC)
   
   # For users without cluster-admin permissions
   make deploy-namespace-scoped  # Deploy with namespace-only permissions (limited functionality)

   Note:

   • Helm chart automatically creates all necessary RBAC permissions
   • Registry deployments automatically check and help set up RBAC permissions
   • If you encounter permission errors, the operator will guide you through the setup process
   • RBAC scope: operatorMode=cluster and operatorMode=namespaces install ClusterRole/ClusterRoleBinding; operatorMode=namespace installs Role/RoleBinding in a single namespace (details: docs/user_guide/operator-modes.md)

3. Create admin credentials (Required for authentication):

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

   Important: The operator manages authentication through Kubernetes secrets. Do not set NEO4J_AUTH directly in environment variables.

4. Deploy your first Neo4j instance:

   For single-node development (non-clustered):

   kubectl apply -f examples/standalone/single-node-standalone.yaml

   For clustered deployment (production):

   kubectl apply -f examples/clusters/minimal-cluster.yaml

5. Access your Neo4j instance:

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

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

6. Verify your installation (Optional):

   # Run unit tests (fast, no cluster required)
   make test-unit
   
   # Run integration tests (automatically creates cluster and deploys operator)
   make test-integration
   
   # Or run tests step by step against an existing cluster
   make test-cluster             # Create test cluster
   make test-integration-ci      # Run essential tests (assumes cluster exists)
   make test-cluster-delete      # Clean up test cluster

📊 Database Management

After deploying a Neo4j instance (standalone or cluster), you can create and manage databases using the Neo4jDatabase CRD.

Prerequisites: You must first deploy either a Neo4jEnterpriseStandalone or Neo4jEnterpriseCluster before creating databases.

Step 1: Deploy a Neo4j Instance

Choose one of the following deployment types:

Option A: Standalone Instance (Development/Testing)

kubectl apply -f examples/standalone/single-node-standalone.yaml

# Wait for deployment
kubectl get neo4jenterprisestandalone
kubectl wait --for=condition=Ready neo4jenterprisestandalone/standalone --timeout=300s

Option B: Cluster Instance (Production)

kubectl apply -f examples/clusters/minimal-cluster.yaml

# Wait for cluster formation
kubectl get neo4jenterprisecluster
kubectl wait --for=condition=Ready neo4jenterprisecluster/minimal-cluster --timeout=300s

Step 2: Create Databases

For cluster deployments:

# Create a database on your cluster
kubectl apply -f - <<EOF
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jDatabase
metadata:
  name: my-cluster-database
spec:
  clusterRef: minimal-cluster  # Reference to your Neo4jEnterpriseCluster
  name: appdb
  topology:
    primaries: 1
    secondaries: 1
  wait: true
  ifNotExists: true
EOF

For standalone deployments:

# Create a database on your standalone instance
kubectl apply -f - <<EOF
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jDatabase
metadata:
  name: my-standalone-database
spec:
  clusterRef: standalone  # Reference to your Neo4jEnterpriseStandalone
  name: devdb
  wait: true
  ifNotExists: true
EOF

More database examples:

• Database with custom topology
• Database for standalone instance
• Database from S3 backup
• Database from existing backup

🔄 Property Sharding (Infinigraph GA)

Property sharding (Infinigraph) was introduced and is GA as of Neo4j 2025.12. It keeps the graph shard (nodes/relationships) in a Raft group while distributing properties across property shards for horizontal scale.

Requirements

• Neo4j Version: 2025.12+ Enterprise (not available on Aura)
• Minimum Servers: 2 servers minimum (3+ recommended for HA graph shard primaries)
• Memory: 4Gi minimum, 8Gi+ recommended per server
• CPU: 2+ cores per server for cross-shard queries
• Authentication: Admin secret required
• Storage: Storage class must be specified
• Network: Low-latency networking for transaction log shipping
• Cypher: db.query.default_language=CYPHER_25 is required for sharded databases

Quick Start

1. Create admin secret (required):

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

2. Create a property sharding enabled cluster:

apiVersion: neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: sharding-cluster
spec:
  image:
    repo: neo4j
    tag: 2025.12-enterprise  # Requires 2025.12+ for property sharding
  auth:
    adminSecret: neo4j-admin-secret
  topology:
    servers: 3  # 3+ recommended for HA graph shard primaries
  storage:
    size: 10Gi
    className: standard
  resources:
    requests:
      memory: 8Gi
      cpu: 2000m
    limits:
      memory: 16Gi
      cpu: 4000m
  propertySharding:
    enabled: true
    config:
      internal.dbms.sharded_property_database.enabled: "true"
      internal.dbms.sharded_property_database.allow_external_shard_access: "false"
      db.query.default_language: "CYPHER_25"

3. Create a sharded database:

apiVersion: neo4j.com/v1alpha1
kind: Neo4jShardedDatabase
metadata:
  name: my-sharded-db
spec:
  clusterRef: sharding-cluster
  name: products
  defaultCypherLanguage: "25"  # Required for property sharding
  propertySharding:
    propertyShards: 2
    graphShard:
      primaries: 2
      secondaries: 1
    propertyShardTopology:
      replicas: 1

Examples

• Basic setup - Simple property sharded database
• Advanced configuration - Production setup with multiple shards
• Development setup - Minimal resources for testing
• With backup - Backup configuration for sharded databases

For complete documentation, see Property Sharding Guide. Note: backupConfig on Neo4jShardedDatabase is not orchestrated yet; use Neo4jBackup resources for shard backups.

💾 Backup and Restore

Setting up Backups

Simple PVC-based backup:

kubectl apply -f examples/backup-restore/backup-pvc-simple.yaml

S3-based backup with scheduling:

kubectl apply -f examples/backup-restore/backup-s3-basic.yaml

Scheduled daily backups:

kubectl apply -f examples/backup-restore/backup-scheduled-daily.yaml

Restoring from Backup

# Restore from a previous backup
kubectl apply -f examples/backup-restore/restore-from-backup.yaml

Advanced backup features:

• Point-in-time recovery setup
• Incremental backups
• Backup with specific types

Cleanup

To remove the operator from your cluster:

# Remove operator deployment (choose your deployment mode)
make undeploy-prod  # or undeploy-dev

# Remove CRDs (this will also remove all Neo4j instances)
make uninstall

Development Installation

For development work with locally built images:

# Create development cluster
make dev-cluster

# Deploy operator (uses local images by default)
make deploy-dev   # Deploy to dev namespace with local neo4j-operator:dev image
# or
make deploy-prod  # Deploy to prod namespace with local neo4j-operator:latest image

# Alternative: Use automated setup (detects available clusters)
make operator-setup

# Note: Production deployment now uses local images by default

For additional deployment options, see the Installation section above.

💡 Examples

After cloning the repository, ready-to-use configurations are available in the examples/ directory:

Standalone Deployments (Single-Node, Non-Clustered)

• Single-node standalone - Development and testing
• LoadBalancer standalone - External access with LoadBalancer
• NodePort standalone - External access with NodePort

Clustered Deployments (Enterprise Server Architecture)

• Minimal cluster - 2 servers (minimum cluster topology)
• Multi-server cluster - Production with high availability (5+ servers)
• Three-node cluster - 3 servers with TLS for fault tolerance
• Topology placement - Multi-zone deployment with topology constraints
• LoadBalancer cluster - External access with cloud load balancer
• Ingress cluster - HTTPS access via Ingress controller

Plugin Management (NEW!)

• Cluster plugin example - Install APOC on a Neo4jEnterpriseCluster
• Standalone plugin example - Install Graph Data Science on standalone
• Plugin documentation - Complete guide to plugin management

Property Sharding (Infinigraph GA - Neo4j 2025.12+)

• Basic property sharding - Simple property sharded database setup
• Advanced property sharding - Production configuration with multiple shards
• Development property sharding - Development setup with minimal resources
• Property sharding with backup - Backup configuration for sharded databases
• Property sharding documentation - Complete guide to property sharding

Quick Example Deployment

# After cloning and installing the operator:
kubectl apply -f examples/standalone/single-node-standalone.yaml

# Check status
kubectl get neo4jenterprisestandalone
kubectl get pods

# Access Neo4j Browser
kubectl port-forward svc/standalone-neo4j-service 7474:7474

See the examples directory for complete documentation and additional configurations.

🔐 Authentication

The operator manages Neo4j authentication through Kubernetes secrets:

1. Secret-based Authentication: Create a secret with username and password keys
2. Automatic Configuration: The operator automatically configures NEO4J_AUTH from the secret
3. Managed Variables: NEO4J_AUTH and NEO4J_ACCEPT_LICENSE_AGREEMENT are managed by the operator

Authentication Configuration

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

# Reference in your cluster specification
spec:
  auth:
    provider: native  # Options: native, ldap, kerberos, jwt
    adminSecret: neo4j-admin-secret

Important Notes:

• Do not set NEO4J_AUTH in the env section - it will be ignored
• NEO4J_ACCEPT_LICENSE_AGREEMENT is automatically set for Enterprise edition
• For production, consider using external secret management solutions

See authentication example for complete configuration.

📚 Documentation Structure

👥 User Guides

• Getting Started - Installation and first cluster
• Installation - All installation methods
• Configuration - Complete configuration reference
• Clustering - High availability setup
• Security Guide - Authentication, TLS, and RBAC
• Backup & Restore - Data protection strategies
• Performance Tuning - Optimization techniques
• Monitoring - Observability and alerting
• Upgrades - Neo4j version upgrades

🔧 Developer & Contributor Guides

• Architecture Overview - System design and components
• Development Setup - Local development environment
• Testing Guide - Test strategy and execution
• Contributing - How to contribute code

📖 API Reference

Complete CRD documentation for all custom resources:

• Neo4jEnterpriseCluster - Clustered deployments
• Neo4jEnterpriseStandalone - Single-node deployments
• Neo4jBackup & Neo4jRestore
• Neo4jDatabase
• Neo4jShardedDatabase - Property sharded databases (Infinigraph, GA in 2025.12+)
• Neo4jPlugin

✨ Key Features

🏗️ Core Capabilities

• Dual Deployment Modes: Choose between clustered (Neo4jEnterpriseCluster) or standalone (Neo4jEnterpriseStandalone) deployments
• Server-Based Architecture: Enterprise clusters use unified server StatefulSets where servers self-organize into database primary/secondary roles
• Flexible Topology: Specify total server count and let Neo4j automatically assign database hosting roles based on requirements
• Property Sharding: Neo4j property sharding (Infinigraph, GA in 2025.12+) for massive scale graph databases
• High Availability: Multi-server clusters with automatic leader election and V2_ONLY discovery
• Persistent Storage: Configurable storage classes and volume management
• Rolling Updates: Zero-downtime Neo4j version upgrades
• OpenShift Route Support: Optional OpenShift Routes via spec.service.route for cluster and standalone services

🔐 Security & Authentication

• TLS/SSL: Configurable TLS encryption for client and cluster communications
• Authentication: Support for native, LDAP, Kerberos, and JWT authentication
• Automatic RBAC: Operator automatically creates all necessary RBAC resources for backups
• Network Policies: Pod-to-pod communication security

🚀 Operations & Automation

• Automated Backups: Scheduled backups with centralized backup StatefulSet (resource-efficient)
• Point-in-Time Recovery: Restore clusters to specific timestamps with --restore-until
• Database Management: Create databases with topology constraints, seed URIs, and point-in-time recovery
• Version-Aware Operations: Automatic detection and adaptation for Neo4j 5.26.x and 2025.x
• Plugin Management: Smart plugin installation with automatic configuration (APOC, GDS, Bloom, GenAI, N10s, GraphQL)
• Split-Brain Detection: Automatic detection and repair of split-brain scenarios in clusters

⚡ Performance & Efficiency

• Optimized Reconciliation: Intelligent rate limiting reduces API calls by 99.8% (18,000+ to ~34 per minute)
• Smart Status Updates: Status updates only when cluster state actually changes
• ConfigMap Debouncing: 2-minute debounce prevents restart loops from configuration changes
• Resource Validation: Automatic validation ensures optimal Neo4j memory settings
• Prometheus Metrics: Neo4j built-in metrics endpoint exposed via spec.monitoring

🔧 Deployment Management

Manage your Neo4j deployments using standard kubectl commands:

# For clustered deployments
kubectl get neo4jenterprisecluster
kubectl describe neo4jenterprisecluster my-cluster

# For standalone deployments
kubectl get neo4jenterprisestandalone
kubectl describe neo4jenterprisestandalone my-standalone

# Operator logs
kubectl logs -l app.kubernetes.io/name=neo4j-operator

🏃‍♂️ Common Use Cases

Development & Testing

• Standalone deployments for development environments (single-node, non-clustered)
• Minimal clusters for integration testing (2 servers self-organizing)
• Ephemeral deployments for CI/CD pipelines
• Sample data loading for testing scenarios with seed URIs

Production Deployments

• High-availability clusters across multiple availability zones with topology placement
• Server pools that automatically assign database hosting based on requirements
• Automated backup strategies with off-site storage and automatic RBAC
• Performance monitoring and alerting integration
• Blue-green deployments for zero-downtime upgrades

Enterprise Features

• LDAP/AD integration for centralized authentication
• Plugin ecosystem with Neo4j 5.26+ compatibility:
  • APOC & APOC Extended: Environment variable configuration (Neo4j 5.26+ compatible)
  • Graph Data Science (GDS): Automatic security configuration and license support
  • Bloom: Complete setup with web interface and security settings
  • GenAI: AI provider integrations (OpenAI, Vertex AI, Azure OpenAI, Bedrock)
  • Neo Semantics (N10s): RDF and semantic web support
• Smart Plugin Configuration: Automatic detection of plugin type and appropriate configuration method
• Compliance-ready logging and auditing
• Resource quotas and governance controls

Note: "Compliance-ready logging and auditing" means the operator exposes Neo4j logging/audit controls via spec.config and emits Kubernetes Events for key actions; you still need to enable the desired Neo4j log settings and ship/retain logs per your compliance requirements.

🎯 Recent Improvements

Latest Version Enhancements

• Property Sharding Support (GA): Neo4j property sharding (Infinigraph, introduced in 2025.12)
  • Automatic Configuration: Applies required sharding settings (CYPHER_25 default language, sharded database enablement)
  • Version Validation: Ensures Neo4j 2025.12+ for property sharding compatibility
  • Topology Requirements: Validates minimum 2 servers for property sharding clusters (3+ recommended for HA)
  • Neo4jShardedDatabase CRD: CRD for creating and managing property-sharded databases
• Neo4j 5.26+ Plugin Compatibility: Complete rework of plugin system for Neo4j 5.26+ compatibility
  • APOC Environment Variables: APOC configuration now uses environment variables (no longer supported in neo4j.conf)
  • Automatic Security Settings: Plugin-specific procedure security applied automatically
  • Plugin Type Detection: Smart configuration based on plugin requirements
  • Dependency Management: Automatic resolution and installation of plugin dependencies
• Enhanced External Access: Full support for LoadBalancer, NodePort services and Ingress resources with automatic connection string generation in status
• Cloud Provider Integration: Automatic detection of AWS, GCP, and Azure with optimal LoadBalancer configurations
• Improved Service Configuration: Support for static IPs, source ranges, external traffic policies, and custom annotations
• Automatic RBAC for Backups: The operator now automatically creates all necessary RBAC resources (ServiceAccounts, Roles, RoleBindings) for backup operations - no manual configuration required
• Enhanced Test Stability: Improved integration test cleanup with automatic finalizer removal prevents namespace termination issues
• Better Error Handling: Fixed nil pointer dereferences and improved error messages for better troubleshooting
• Improved TLS Cluster Formation: Enhanced stability for TLS-enabled clusters during initial formation

Observability & GitOps (February 2026)

• Live Cluster Diagnostics: SHOW SERVERS and SHOW DATABASES results surfaced in status.diagnostics — no more kubectl exec for cluster health
• Structured Kubernetes Events: All state transitions emit typed events (ClusterFormationStarted, BackupCompleted, SplitBrainDetected, etc.) consumable by monitoring pipelines — see the Events Reference
• Custom Prometheus Metrics: Per-server health gauge, cluster phase gauge, backup counters, reconcile histograms — all with cluster/namespace labels
• ArgoCD/Flux Health Checks: Native ArgoCD Lua scripts for all 7 CRDs; Flux detects readiness via standard Ready condition automatically
• Standardized Status Conditions: All CRDs now emit Ready, ServersHealthy, and DatabasesHealthy conditions with consistent Reason and Message fields
• Multi-Registry Support: spec.image.pullSecrets wired into StatefulSet imagePullSecrets for ECR/GCR/ACR/private registry support

Developer Experience

• Simplified Testing: New test cleanup patterns and helpers make integration testing more reliable
• Better Documentation: Updated troubleshooting guides with common issues and solutions
• CI/CD Ready: GitHub workflows automatically handle RBAC generation and deployment

🤝 Contributing

We welcome contributions from both Kubernetes beginners and experts!

⚠️ IMPORTANT: Kind Required for Development This project exclusively uses Kind (Kubernetes in Docker) for all development workflows, testing, and CI emulation. You must install Kind before contributing.

Prerequisites for Contributors

Required Tools:

• Go 1.24+
• Docker
• kubectl
• Kind (Kubernetes in Docker) - MANDATORY
• make

Quick Kind Installation:

# macOS (Homebrew)
brew install kind

# Linux (binary download)
curl -Lo ./kind https://kind.sigs.k8s.io/dl/latest/kind-linux-amd64
chmod +x ./kind && sudo mv ./kind /usr/local/bin/kind

# Verify installation
kind version

For detailed installation instructions, see our Contributing Guide.

Quick Contribution Setup

# Clone and setup development environment
git clone https://github.com/neo4j-partners/neo4j-kubernetes-operator.git
cd neo4j-kubernetes-operator

# Create local Kind cluster for development
make dev-cluster

# Run tests to verify setup
make test-unit          # Unit tests (fast, no cluster required)
make test-integration   # Integration tests (auto-creates cluster, deploys operator)
make test-ci-local      # Emulate CI workflow with debug logging (Added 2025-08-22)

# Deploy operator for development
make operator-setup

Available Make Targets

Development & Testing:

• make dev-cluster - Create development Kind cluster
• make operator-setup - Deploy operator in-cluster (recommended)
• make test-unit - Run unit tests (fast, no cluster required)
• make test-integration - Run integration tests (auto-creates cluster, deploys operator)
• make test-ci-local - Emulate CI workflow with debug logging

Operator Installation:

• make install - Install CRDs
• make deploy-prod - Deploy with production config
• make deploy-dev - Deploy with development config
• make undeploy-prod/undeploy-dev - Remove operator deployment
• make uninstall - Remove CRDs

Code Quality:

• make fmt - Format code
• make lint - Run linter
• make vet - Run go vet
• make test-coverage - Generate coverage report

See the Contributing Guide for detailed instructions.

📞 Support

• Documentation: docs/
• GitHub Issues: https://github.com/neo4j-partners/neo4j-kubernetes-operator/issues