You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Neo4jEnterpriseCluster Custom Resource Definition (CRD) manages Neo4j Enterprise clusters with high availability, automatic failover, and horizontal scaling capabilities.
Overview
API Version: neo4j.neo4j.com/v1alpha1
Kind: Neo4jEnterpriseCluster
Supported Neo4j Versions: 5.26.x (last semver LTS) and 2025.01.0+ (CalVer)
Architecture: Server-based deployment with unified StatefulSet
Minimum Servers: 2 (required for clustering)
Maximum Servers: 20 (validated limit)
Architecture
Server-Based Architecture: Neo4jEnterpriseCluster uses a unified server-based architecture introduced in Neo4j 5.26.x:
Single StatefulSet: {cluster-name}-server with configurable replica count
Server Pods: Named {cluster-name}-server-0, {cluster-name}-server-1, etc.
Self-Organization: Servers automatically organize into primary/secondary roles for databases
Centralized Backup: Optional {cluster-name}-backup-0 pod for centralized backup operations
Role Flexibility: Servers can host multiple databases with different roles
When to Use:
Production workloads requiring high availability
Multi-database deployments with different topology requirements
Workloads needing horizontal read scaling
Enterprise features like advanced backup, security, and monitoring
Large datasets requiring property sharding (Neo4j 2025.12+)
Issuer resource kind. Default: "ClusterIssuer". Use "Issuer" for namespace-scoped issuers, or any external issuer kind (e.g. "AWSPCAClusterIssuer", "VaultIssuer", "GoogleCASClusterIssuer")
group
string
API group of the issuer. Default: cert-manager.io. Set to the external issuer's API group when using third-party issuers (e.g. "awspca.cert-manager.io")
Enables integration with Neo4j Aura Fleet Management for monitoring this cluster from the Aura console. The fleet-management plugin is pre-bundled in all Neo4j Enterprise images (no internet access required).
Required. Name of the Kubernetes Secret containing the registration token
key
string
Key within the Secret (default: "token")
PropertyShardingSpec
Configures property sharding for horizontal scaling of large datasets. Property sharding separates graph structure from properties, distributing properties across multiple databases for better scalability. Available in Neo4j 2025.12+ Enterprise.
Field
Type
Description
enabled
bool
Enable property sharding for this cluster (default: false)
config
map[string]string
Advanced property sharding configuration
System Requirements (validated by operator):
Neo4j Version: 2025.12+ Enterprise
Minimum Servers: 2 servers (3+ recommended for HA graph shard primaries)
Memory: 4GB minimum, 8GB+ recommended per server
CPU: 1+ core minimum, 2+ cores recommended per server
Authentication: Admin secret required
Storage: Persistent storage class required
Required Configuration (automatically applied when enabled):
Optional MCP server deployment for the cluster using the official mcp/neo4j image (github.com/neo4j/mcp). Requires the APOC plugin for the get-schema tool.
HTTP transport (default): no credentials stored in the pod — each client request carries a Basic Auth or Bearer token Authorization header. A Service is created at <name>-mcp:8080; the endpoint path is /mcp (fixed).
STDIO transport: NEO4J_USERNAME and NEO4J_PASSWORD are injected from the admin secret (or a custom secret via spec.mcp.auth). No Service is created.
Override Neo4j credentials for STDIO transport. Ignored in HTTP mode (credentials come per-request from the client).
replicas
*int32
Number of MCP pod replicas (default: 1). Only meaningful for HTTP.
resources
*corev1.ResourceRequirements
Resource requirements for MCP pods
env
[]corev1.EnvVar
Extra environment variables. Operator-managed vars (NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_TRANSPORT_MODE, NEO4J_MCP_HTTP_*, etc.) are silently ignored.
Kubernetes Service and Ingress/Route exposure settings
MCPTLSSpec
Enables container-level TLS on the mcp/neo4j HTTP server by mounting a Kubernetes TLS secret and injecting NEO4J_MCP_HTTP_TLS_ENABLED=true with the cert/key file paths. For most deployments, Ingress-level TLS termination is simpler.
Field
Type
Description
secretName
string
Required. Name of a Kubernetes TLS secret (type: kubernetes.io/tls) containing the certificate and private key.
certKey
string
Key in the secret for the certificate file (default: tls.crt)
keyKey
string
Key in the secret for the private key file (default: tls.key)
MCPServiceSpec
Field
Type
Description
type
string
Service type: "ClusterIP" (default), "NodePort", "LoadBalancer"
annotations
map[string]string
Service annotations
loadBalancerIP
string
Static LoadBalancer IP
loadBalancerSourceRanges
[]string
Allowed source ranges
externalTrafficPolicy
string
External traffic policy: "Cluster" or "Local"
port
int32
Service port for MCP HTTP (default: same as container port)
Overrides the Neo4j credentials injected into the MCP pod. Only effective for STDIO transport. In HTTP mode the server authenticates per-request using the client's Authorization header.
Field
Type
Description
secretName
string
Secret containing username/password keys. Defaults to the cluster admin secret when unset.
Live diagnostics collected from SHOW SERVERS and SHOW DATABASES when spec.queryMonitoring.enabled=true and the cluster is in Ready phase. Updated on every reconcile cycle.
Field
Type
Description
servers
[]ServerDiagnostic
SHOW SERVERS results. Each entry has name, address, state, health, hostingDatabases.
servers[].name
string
Server display name.
servers[].address
string
Bolt address of the server.
servers[].state
string
Lifecycle state: Enabled, Cordoned, Deallocating.
servers[].health
string
Health status: Available or Unavailable.
servers[].hostingDatabases
int
Number of databases currently hosted on this server.
databases
[]DatabaseDiagnostic
SHOW DATABASES results. Each entry has name, status, requestedStatus, role, default.
databases[].name
string
Database name.
databases[].status
string
Current status: online, offline, quarantined.
databases[].requestedStatus
string
Desired status as requested by the operator.
databases[].role
string
Role on the last-contacted server: primary, secondary.
databases[].default
bool
Whether this is the cluster's default database.
lastCollected
string (RFC3339)
Timestamp of the most recent successful collection.
collectionError
string
Error message from the last failed collection; empty on success.
Conditions
The operator maintains the following condition types on status.conditions (standard metav1.Condition):
Condition Type
True when
False when
Unknown when
ServersHealthy
All servers are state=Enabledandhealth=Available
Any server is Cordoned, Deallocating, or Unavailable
Diagnostics cannot be collected (cluster not Ready or Bolt unreachable)
DatabasesHealthy
All user databases have status=online
Any database has requestedStatus=online but status≠online
Diagnostics cannot be collected (cluster not Ready or Bolt unreachable)
Note: The system database is excluded from the DatabasesHealthy check because it has special internal lifecycle behavior.
Examples
Basic Cluster
apiVersion: neo4j.neo4j.com/v1alpha1kind: Neo4jEnterpriseClustermetadata:
name: basic-clusterspec:
image:
repo: neo4j # Note: field name is 'repo', not 'repository'tag: "5.26.0-enterprise"topology:
servers: 3# Creates StatefulSet basic-cluster-server with 3 replicasstorage:
className: standardsize: 10Giauth:
adminSecret: neo4j-admin-secret # Note: field name is 'adminSecret'resources:
requests:
cpu: "1"memory: 4Gilimits:
cpu: "2"memory: 8Gi
Cluster with Server Role Constraints
apiVersion: neo4j.neo4j.com/v1alpha1kind: Neo4jEnterpriseClustermetadata:
name: role-constrained-clusterspec:
image:
repo: neo4jtag: "5.26.0-enterprise"topology:
servers: 5# Global constraint: all servers default to any roleserverModeConstraint: NONE# Per-server role hints (overrides global constraint)serverRoles:
- serverIndex: 0modeConstraint: PRIMARY # Server-0: only primary databases
- serverIndex: 1modeConstraint: PRIMARY # Server-1: only primary databases
- serverIndex: 2modeConstraint: SECONDARY # Server-2: only secondary databases
- serverIndex: 3modeConstraint: SECONDARY # Server-3: only secondary databases
- serverIndex: 4modeConstraint: NONE # Server-4: any database mode# Advanced placement for high availabilityplacement:
topologySpread:
enabled: truetopologyKey: topology.kubernetes.io/zonemaxSkew: 1whenUnsatisfiable: DoNotScheduleantiAffinity:
enabled: truetopologyKey: kubernetes.io/hostnametype: requiredavailabilityZones:
- us-east-1a
- us-east-1b
- us-east-1cenforceDistribution: truestorage:
className: fast-ssdsize: 50Giauth:
adminSecret: neo4j-admin-secret
# Create a cluster
kubectl apply -f cluster.yaml
# List clusters
kubectl get neo4jenterprisecluster
# Get cluster details
kubectl describe neo4jenterprisecluster my-cluster
# Check cluster status
kubectl get neo4jenterprisecluster my-cluster -o yaml
# Port forward for local access
kubectl port-forward svc/my-cluster-client 7474:7474 7687:7687
Cluster Operations
# Scale cluster (change server count)
kubectl patch neo4jenterprisecluster my-cluster -p '{"spec":{"topology":{"servers":5}}}'# Update Neo4j version
kubectl patch neo4jenterprisecluster my-cluster -p '{"spec":{"image":{"tag":"2025.01.0-enterprise"}}}'# Check cluster health
kubectl exec my-cluster-server-0 -- cypher-shell -u neo4j -p password "SHOW SERVERS"# Monitor server pods
kubectl get pods -l neo4j.com/cluster=my-cluster
kubectl logs my-cluster-server-0 -c neo4j