The Neo4jEnterpriseCluster Custom Resource Definition (CRD) manages Neo4j Enterprise clusters with high availability, automatic failover, and horizontal scaling capabilities.
Enforce server distribution across topology domains
Server Role Management:
- Servers self-organize into primary/secondary roles at the database level
- Role constraints influence which databases a server can host:
- NONE: Server can host databases in any mode (default)
- PRIMARY: Server only hosts databases in primary mode
- SECONDARY: Server only hosts databases in secondary mode
- Use serverRoles for granular per-server control
Validation:
- Minimum 2 servers required for clustering
- Cannot configure all servers as SECONDARY (cluster needs primaries)
- Server indices in serverRoles must be within range (0 to servers-1)
Storage size (e.g., "10Gi"). Can be increased after creation — the operator automatically expands PVCs and recreates the StatefulSet with zero downtime. Cannot be decreased (PVC shrink is not supported by Kubernetes). Requires the StorageClass to have allowVolumeExpansion: true.
retentionPolicy
string
PVC retention policy: "Delete" (default) permanently removes PVCs on deletion; "Retain" preserves them. Use Retain for production to prevent data loss. See Storage and PVC Retention.
Schema-only. Defined on the API but the operator does not currently generate dbms.security.auth_minimum_password_length (and friends) from this. Set those keys via spec.config directly until implemented.
Schema-only. Defined on the API but the operator does not wire it to Neo4j config or mount the keytab. Use spec.config["dbms.security.kerberos.*"] plus spec.extraVolumes for the keytab Secret until full Kerberos support lands.
authCacheTTL
string
Auth cache TTL (e.g., "10m", "600s"). Maps to dbms.security.auth_cache_ttl
⚠️ All URI fields require https:// — Neo4j 2026.x rejects http:// for wellKnownDiscoveryURI, authEndpoint, tokenEndpoint, jwksURI, userInfoURI, and issuer at config-parse time, and the cluster fails to start. There is no insecure-mode override. Self-hosted IDPs without TLS need a TLS-terminating proxy plus the proxy's CA in spec.trustedCASecrets.
Field
Type
Description
displayName
string
Display name on login screen
wellKnownDiscoveryURI
string
OIDC discovery endpoint (auto-configures other endpoints). HTTPS only.
Used by the legacy singular spec.auth.trustStore field. New configurations
should prefer the plural TrustedCASecret list at
spec.trustedCASecrets; both fields are merged at reconcile time so
backward compatibility is preserved.
Field
Type
Description
name
string
Required. Name of Secret containing CA certificate (PEM format)
key
string
Key in the Secret containing the CA cert (default: "ca.crt")
References a Secret containing a PEM-encoded CA certificate to add to Neo4j's
JVM truststore. Used by spec.trustedCASecrets.
Field
Type
Description
name
string
Required. Name of the Secret. Doubles as the keytool alias inside the JKS, so names must be unique across the list.
key
string
Key within the Secret. Defaults to "ca.crt" — the layout cert-manager-issued Secrets use.
The operator merges every entry into a JKS truststore at
/truststore/truststore.jks (password changeit) using a truststore-init
init container, then sets -Djavax.net.ssl.trustStore on the JVM. The JDK's
default cacerts is used as the seed, so adding internal CAs does not
remove trust in public CAs.
Example with cert-manager:
apiVersion:cert-manager.io/v1kind:Certificatemetadata:{ name:oidc-tls}spec:secretName:oidc-tls# ← name to reference belowissuerRef:{ name:corp-ca, kind:ClusterIssuer}commonName:idp.corp.example.comdnsNames:[idp.corp.example.com]---apiVersion:neo4j.neo4j.com/v1beta1kind:Neo4jEnterpriseClusterspec:trustedCASecrets:-name:oidc-tls# default key "ca.crt" matches cert-manager
For the less common case where a Neo4j SSL policy needs a CA at a specific
filesystem path (e.g. dbms.ssl.policy.<name>.truststore_path), use
spec.extraVolumes + spec.extraVolumeMounts instead — the operator does
not parse policy config to wire up filesystem mounts automatically.
Schema-only — not wired by the operator yet. See the
auth.kerberos row in AuthSpec for the recommended workaround
(spec.config["dbms.security.kerberos.*"] + spec.extraVolumes for the
keytab) until full support lands.
Secret containing a trusted CA certificate (key: ca.crt) for verifying Neo4j TLS connections. When omitted, the operator auto-discovers the CA from the cert-manager-generated Secret.
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")
Examples:
# Standard cert-manager ClusterIssuer (default)issuerRef:name:ca-cluster-issuerkind:ClusterIssuer# Namespace-scoped IssuerissuerRef:name:my-issuerkind:Issuer# AWS Private CA (external issuer)issuerRef:name:aws-pca-issuerkind:AWSPCAClusterIssuergroup:awspca.cert-manager.io# HashiCorp VaultissuerRef:name:vault-issuerkind:VaultIssuergroup:cert.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).
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):
propertySharding:enabled:trueconfig:# Transaction log retention (critical for shard sync)db.tx_log.rotation.retention_policy:"14days"# Property synchronization intervalinternal.dbms.sharded_property_database.property_pull_interval:"10ms"# Memory optimizationserver.memory.heap.max_size:"12G"server.memory.pagecache.size:"6G"# Connection pooling for cross-shard queriesserver.bolt.thread_pool_min_size:"10"server.bolt.thread_pool_max_size:"100"
Resource Recommendations:
Development:
resources:requests:memory:4Gi# Absolute minimum for dev/testcpu:2000m# 2 cores for cross-shard querieslimits:memory:8Gi# Recommended for productioncpu:2000m
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.
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)
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.
Service endpoints and connection information populated by the controller on
every status update. Schema is shared between Neo4jEnterpriseCluster and
Neo4jEnterpriseStandalone; the cluster controller resolves URLs against
the {cluster}-client ClusterIP, the standalone controller against the
{name}-service ClusterIP.
Field
Type
Description
bolt
string
Bolt protocol endpoint (e.g. bolt+s://<service>:7687 when TLS is enabled, bolt://... when disabled)
Connection-string snippets generated from spec.service.type and the
LoadBalancer-assigned external IP (when applicable). On a LoadBalancer
service the external IP is filled in once the cloud provider's controller
has assigned one; until then a <external-ip> placeholder is substituted.
For NodePort the bolt port and HTTPS port appear as <bolt-node-port> /
<http-node-port> placeholders since those are dynamically assigned and
visible via kubectl get svc.
Field
Type
Description
portForward
string
kubectl port-forward command (always available)
browserURL
string
Neo4j Browser URL
boltURI
string
Bolt connection URI (uses bolt+ssc:// when TLS is enabled, since cert-manager-issued certs typically aren't trusted by external clients)
Live diagnostics collected from SHOW SERVERS and SHOW DATABASES when spec.monitoring.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.
apiVersion:neo4j.neo4j.com/v1beta1kind: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
apiVersion:neo4j.neo4j.com/v1beta1kind: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
# Note: Backups are now managed via Neo4jBackup CRDapiVersion:neo4j.neo4j.com/v1beta1kind:Neo4jBackupmetadata:name:daily-cluster-backupspec:target:kind:Clustername:monitored-clusterstorage:type:s3bucket:neo4j-backupspath:daily/schedule:"02***"# Daily at 2 AMretention:maxAge:"30d"maxCount:30options:compress:truebackupType:FULL
# Create a clusterkubectlapply-fcluster.yaml
# List clusterskubectlgetneo4jenterprisecluster
# Get cluster detailskubectldescribeneo4jenterpriseclustermy-cluster
# Check cluster statuskubectlgetneo4jenterpriseclustermy-cluster-oyaml
# Port forward for local accesskubectlport-forwardsvc/my-cluster-client7474:74747687:7687
# Development cluster (minimal resources)apiVersion:neo4j.neo4j.com/v1beta1kind:Neo4jEnterpriseClustermetadata:name:dev-clusterspec:topology:servers:2# Minimum for clusteringstorage:className:standardsize:10Giresources:requests:cpu:200mmemory:1Gilimits:cpu:1memory:2Gitls:mode:disabled---# Property Sharding cluster (Neo4j 2025.12+)apiVersion:neo4j.neo4j.com/v1beta1kind:Neo4jEnterpriseClustermetadata:name:sharding-clusterspec:image:repo:neo4jtag:2025.12-enterprisetopology:servers:7# Sufficient for property sharding workloadsstorage:className:fast-ssdsize:100Giresources:requests:cpu:2memory:8Gilimits:cpu:4memory:16GipropertySharding:enabled:trueconfig:db.tx_log.rotation.retention_policy:"14days"internal.dbms.sharded_property_database.property_pull_interval:"5ms"server.memory.heap.max_size:"12G"server.memory.pagecache.size:"6G"tls:mode:cert-managerissuerRef:name:ca-cluster-issuerkind:ClusterIssuer---# Production cluster (high availability)apiVersion:neo4j.neo4j.com/v1beta1kind:Neo4jEnterpriseClustermetadata:name:prod-clusterspec:topology:servers:5placement:topologySpread:enabled:truetopologyKey:topology.kubernetes.io/zonemaxSkew:1antiAffinity:enabled:truetype:requiredavailabilityZones:[us-east-1a,us-east-1b,us-east-1c]enforceDistribution:truestorage:className:fast-ssdsize:100Giresources:requests:cpu:2memory:8Gilimits:cpu:4memory:16Gitls:mode:cert-managerissuerRef:name:ca-cluster-issuerkind:ClusterIssuerauth:# NOTE: spec.auth.passwordPolicy is schema-only and currently ignored# by the operator. Set the equivalent Neo4j config keys via spec.config# (e.g. dbms.security.auth_minimum_password_length=12) until typed-field# support lands.adminSecret:neo4j-admin-secret
# Check resource version conflictskubectlgetevents--field-selectorreason=UpdateConflict
# Force reconciliation with a no-op annotation changekubectlannotateneo4jenterpriseclustermy-cluster\troubleshooting.neo4j.com/reconcile="$(date+%s)"--overwrite