Neo4jEnterpriseCluster API Reference

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+)

For single-node deployments, use Neo4jEnterpriseStandalone instead.

Related Resources

Neo4jDatabase - Create databases within the cluster
Neo4jShardedDatabase - Create sharded databases for horizontal scaling
Neo4jPlugin - Install plugins (APOC, GDS, etc.)
Neo4jBackup - Schedule automated backups
Neo4jRestore - Restore from backups

Spec

The Neo4jEnterpriseClusterSpec defines the desired state of a Neo4j Enterprise cluster.

Core Configuration (Required)

Field	Type	Description
`image`	`ImageSpec`	The Neo4j Docker image configuration
`topology`	`TopologyConfiguration`	Cluster topology (number of servers)
`storage`	`StorageSpec`	Storage configuration for data persistence
`auth`	`AuthSpec`	Authentication configuration

Kubernetes Integration

Field	Type	Description
`resources`	`*corev1.ResourceRequirements`	CPU and memory resources
`env`	`[]corev1.EnvVar`	Environment variables for Neo4j pods
`nodeSelector`	`map[string]string`	Node selector constraints
`tolerations`	`[]corev1.Toleration`	Pod tolerations
`affinity`	`*corev1.Affinity`	Pod affinity rules
`securityContext`	`*SecurityContextSpec`	Pod/container security overrides

Neo4j Configuration

Field	Type	Description
`config`	`map[string]string`	Custom Neo4j configuration

Operations

Field	Type	Description
`restoreFrom`	`RestoreSpec`	Restore from backup configuration
`backups`	`BackupsSpec`	Backup configuration
`upgradeStrategy`	`UpgradeStrategySpec`	Upgrade strategy configuration

Networking

Field	Type	Description
`service`	`ServiceSpec`	Service configuration for external access

Extensions

Field	Type	Description
`tls`	`TLSSpec`	TLS configuration
`ui`	`UISpec`	Neo4j UI configuration
`mcp`	`MCPServerSpec`	MCP server deployment and exposure settings
`propertySharding`	`PropertyShardingSpec`	Property sharding configuration (Neo4j 2025.12+)
`queryMonitoring`	`QueryMonitoringSpec`	Query monitoring configuration
`auraFleetManagement`	`AuraFleetManagementSpec`	Aura Fleet Management integration (optional)

Type Definitions

ImageSpec

Field	Type	Description
`repo`	`string`	Image repository (default: `"neo4j"`)
`tag`	`string`	Image tag
`pullPolicy`	`string`	Pull policy: `"Always"`, `"IfNotPresent"`, `"Never"`
`pullSecrets`	`[]string`	Image pull secrets

TopologyConfiguration

Defines the cluster server topology and role constraints.

Field	Type	Description
`servers`	`int32`	Required. Number of Neo4j servers (minimum: 2, maximum: 20)
`serverModeConstraint`	`string`	Global server mode constraint: `"NONE"` (default), `"PRIMARY"`, `"SECONDARY"`
`serverRoles`	`[]ServerRoleHint`	Per-server role constraints (overrides global constraint)
`placement`	`*PlacementConfig`	Advanced placement and scheduling configuration
`availabilityZones`	`[]string`	Target availability zones for server distribution
`enforceDistribution`	`bool`	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)

ServerRoleHint

Specifies role constraints for individual servers.

Field	Type	Description
`serverIndex`	`int32`	Required. Server index (0-based, must be < servers count)
`modeConstraint`	`string`	Required. Role constraint: `"NONE"`, `"PRIMARY"`, `"SECONDARY"`

StorageSpec

Field	Type	Description
`className`	`string`	Storage class name
`size`	`string`	Storage size (e.g., `"10Gi"`)
`retentionPolicy`	`string`	PVC retention policy: `"Delete"` (default) or `"Retain"`
`backupStorage`	`*BackupStorageSpec`	Additional storage for backups

BackupStorageSpec

Field	Type	Description
`className`	`string`	Storage class name for backup volumes
`size`	`string`	Storage size for backup volumes

AuthSpec

Field	Type	Description
`provider`	`string`	Auth provider: `"native"`, `"ldap"`, `"jwt"`, `"kerberos"` (default: `"native"`)
`adminSecret`	`string`	Secret containing admin username and password
`secretRef`	`string`	Secret containing provider-specific configuration
`externalSecrets`	`*ExternalSecretsConfig`	External secrets configuration
`passwordPolicy`	`*PasswordPolicySpec`	Password policy configuration
`jwt`	`*JWTAuthSpec`	JWT authentication configuration
`ldap`	`*LDAPAuthSpec`	LDAP authentication configuration
`kerberos`	`*KerberosAuthSpec`	Kerberos authentication configuration

JWTAuthSpec

Field	Type	Description
`validation`	`*JWTValidationSpec`	JWT validation settings
`claimsMapping`	`map[string]string`	Claims mapping

JWTValidationSpec

Field	Type	Description
`jwksUrl`	`string`	JWKS endpoint URL
`issuer`	`string`	JWT issuer
`audience`	`[]string`	JWT audience

LDAPAuthSpec

Field	Type	Description
`server`	`*LDAPServerSpec`	LDAP server settings
`userSearch`	`*LDAPSearchSpec`	User search settings
`groupSearch`	`*LDAPSearchSpec`	Group search settings

LDAPServerSpec

Field	Type	Description
`urls`	`[]string`	LDAP server URLs
`tls`	`bool`	Enable TLS for LDAP connection
`insecureSkipVerify`	`bool`	Skip TLS certificate verification

LDAPSearchSpec

Field	Type	Description
`baseDN`	`string`	Search base DN
`filter`	`string`	Search filter
`scope`	`string`	Search scope: `"base"`, `"one"`, `"sub"`

KerberosAuthSpec

Field	Type	Description
`realm`	`string`	Kerberos realm
`servicePrincipal`	`string`	Service principal
`keytab`	`*KerberosKeytabSpec`	Keytab configuration

KerberosKeytabSpec

Field	Type	Description
`secretRef`	`string`	Secret containing keytab file
`key`	`string`	Key in secret containing keytab (default: `"keytab"`)

SecurityContextSpec

Field	Type	Description
`podSecurityContext`	`*corev1.PodSecurityContext`	Pod-level security settings
`containerSecurityContext`	`*corev1.SecurityContext`	Container-level security settings

TLSSpec

Field	Type	Description
`mode`	`string`	TLS mode: `"cert-manager"` (default) or `"disabled"`
`issuerRef`	`*IssuerRef`	cert-manager issuer reference
`certificateSecret`	`string`	TLS secret name (manual certificates)
`externalSecrets`	`*ExternalSecretsConfig`	External Secrets configuration
`duration`	`*string`	Certificate duration (e.g., `"2160h"`)
`renewBefore`	`*string`	Renewal window before expiry (e.g., `"360h"`)
`subject`	`*CertificateSubject`	Certificate subject fields
`usages`	`[]string`	Certificate usages

IssuerRef

Field	Type	Description
`name`	`string`	Required. Issuer resource name
`kind`	`string`	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-issuer
  kind: ClusterIssuer

# Namespace-scoped Issuer
issuerRef:
  name: my-issuer
  kind: Issuer

# AWS Private CA (external issuer)
issuerRef:
  name: aws-pca-issuer
  kind: AWSPCAClusterIssuer
  group: awspca.cert-manager.io

# HashiCorp Vault
issuerRef:
  name: vault-issuer
  kind: VaultIssuer
  group: cert.cert-manager.io

CertificateSubject

Field	Type	Description
`organizations`	`[]string`	Organization names
`countries`	`[]string`	Country codes
`organizationalUnits`	`[]string`	Organizational units
`localities`	`[]string`	Localities
`provinces`	`[]string`	Provinces/States

ExternalSecretsConfig

Field	Type	Description
`enabled`	`bool`	Enable External Secrets integration
`secretStoreRef`	`*SecretStoreRef`	SecretStore or ClusterSecretStore reference
`refreshInterval`	`string`	Refresh interval (e.g., `"1h"`)
`data`	`[]ExternalSecretData`	External secret data mappings

SecretStoreRef

Field	Type	Description
`name`	`string`	SecretStore name
`kind`	`string`	`"SecretStore"` or `"ClusterSecretStore"`

ExternalSecretData

Field	Type	Description
`secretKey`	`string`	Target secret key
`remoteRef`	`*ExternalSecretRemoteRef`	Remote secret reference

ExternalSecretRemoteRef

Field	Type	Description
`key`	`string`	External secret key
`property`	`string`	Property within the secret
`version`	`string`	Secret version

AuraFleetManagementSpec

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).

Field	Type	Description
`enabled`	`bool`	Enable Aura Fleet Management integration (default: `false`)
`tokenSecretRef`	`*AuraTokenSecretRef`	Reference to the Kubernetes Secret holding the Aura registration token (optional; registration deferred if omitted)

Status fields (read-only, set by the operator):

Field	Description
`status.auraFleetManagement.registered`	`true` once `fleetManagement.registerToken` succeeded
`status.auraFleetManagement.lastRegistrationTime`	Timestamp of last successful registration
`status.auraFleetManagement.message`	Human-readable status or error detail

Example:

auraFleetManagement:
  enabled: true
  tokenSecretRef:
    name: aura-fleet-token  # kubectl create secret generic aura-fleet-token --from-literal=token='<token>'
    key: token              # defaults to "token"

See Aura Fleet Management Guide for full setup instructions.

AuraTokenSecretRef

Field	Type	Description
`name`	`string`	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):

internal.dbms.sharded_property_database.enabled: "true"
db.query.default_language: "CYPHER_25"
internal.dbms.sharded_property_database.allow_external_shard_access: "false"

Performance Tuning Options:

propertySharding:
  enabled: true
  config:
    # Transaction log retention (critical for shard sync)
    db.tx_log.rotation.retention_policy: "14 days"

    # Property synchronization interval
    internal.dbms.sharded_property_database.property_pull_interval: "10ms"

    # Memory optimization
    server.memory.heap.max_size: "12G"
    server.memory.pagecache.size: "6G"

    # Connection pooling for cross-shard queries
    server.bolt.thread_pool_min_size: "10"
    server.bolt.thread_pool_max_size: "100"

Resource Recommendations:

Development:

resources:
  requests:
    memory: 4Gi    # Absolute minimum for dev/test
    cpu: 2000m     # 2 cores for cross-shard queries
  limits:
    memory: 8Gi    # Recommended for production
    cpu: 2000m

Production:

resources:
  requests:
    memory: 4Gi    # Minimum requirement
    cpu: 2000m     # Cross-shard performance
  limits:
    memory: 8Gi    # Recommended for production
    cpu: 4000m     # Handle peak loads

Validation Errors:

Error	Cause	Resolution
`property sharding requires Neo4j 2025.12+`	Old Neo4j version	Upgrade to 2025.12+ Enterprise
`spec.topology.servers in body should be greater than or equal to 2`	Invalid server count	Increase server count to 2+ (3+ recommended for HA)
`property sharding requires minimum 4GB memory`	Insufficient memory	Increase memory to 8GB+ (recommended)
`property sharding requires minimum 1 CPU core`	Insufficient CPU	Increase CPU to 2+ cores (recommended)

For detailed configuration, see the Property Sharding Guide.

BackupsSpec

Field	Type	Description
`defaultStorage`	`*StorageLocation`	Default storage location for backups
`cloud`	`*CloudBlock`	Cloud provider configuration (credentials/identity)

StorageLocation

Field	Type	Description
`type`	`string`	Storage type: `"s3"`, `"gcs"`, `"azure"`, `"pvc"`
`bucket`	`string`	Bucket name (for cloud storage)
`path`	`string`	Path within bucket or PVC
`pvc`	`*PVCSpec`	PVC configuration (for `pvc` type)
`cloud`	`*CloudBlock`	Cloud provider configuration

PVCSpec

Field	Type	Description
`name`	`string`	Name of existing PVC to use
`storageClassName`	`string`	Storage class name
`size`	`string`	Size for new PVC (e.g., `"100Gi"`)

CloudBlock

Field	Type	Description
`provider`	`string`	Cloud provider: `"aws"`, `"gcp"`, `"azure"`
`identity`	`*CloudIdentity`	Cloud identity configuration

CloudIdentity

Field	Type	Description
`provider`	`string`	Identity provider: `"aws"`, `"gcp"`, `"azure"`
`serviceAccount`	`string`	Service account name for cloud identity
`autoCreate`	`*AutoCreateSpec`	Auto-create service account and annotations

AutoCreateSpec

Field	Type	Description
`enabled`	`bool`	Enable auto-creation of service account (default: `true`)
`annotations`	`map[string]string`	Annotations to apply to auto-created service account

QueryMonitoringSpec

Query performance monitoring and analytics configuration.

Field	Type	Description
`enabled`	`bool`	Enable query monitoring (default: `true`)
`slowQueryThreshold`	`string`	Slow query threshold (default: `"5s"`)
`explainPlan`	`bool`	Enable query plan explanation (default: `true`)
`indexRecommendations`	`bool`	Enable index recommendations (default: `true`)
`sampling`	`*QuerySamplingConfig`	Query sampling configuration
`metricsExport`	`*QueryMetricsExportConfig`	Metrics export configuration

QuerySamplingConfig

Query sampling configuration for performance monitoring.

Field	Type	Description
`rate`	`string`	Sampling rate (0.0 to 1.0)
`maxQueriesPerSecond`	`int32`	Maximum queries to sample per second

QueryMetricsExportConfig

Metrics export configuration for query monitoring.

Field	Type	Description
`prometheus`	`bool`	Export to Prometheus
`customEndpoint`	`string`	Export to custom endpoint
`interval`	`string`	Export interval

PlacementConfig

Advanced placement and scheduling configuration.

Field	Type	Description
`topologySpread`	`*TopologySpreadConfig`	Topology spread constraints
`antiAffinity`	`*PodAntiAffinityConfig`	Pod anti-affinity rules
`nodeSelector`	`map[string]string`	Node selection constraints
`requiredDuringScheduling`	`bool`	Hard placement requirements

TopologySpreadConfig

Controls how servers are distributed across cluster topology.

Field	Type	Description
`enabled`	`bool`	Enable topology spread constraints
`topologyKey`	`string`	Topology domain (e.g., `"topology.kubernetes.io/zone"`)
`maxSkew`	`int32`	Maximum allowed imbalance between domains
`whenUnsatisfiable`	`string`	Action when constraints can't be satisfied
`minDomains`	`*int32`	Minimum number of eligible domains

PodAntiAffinityConfig

Prevents servers from being scheduled on the same nodes/zones.

Field	Type	Description
`enabled`	`bool`	Enable anti-affinity rules
`topologyKey`	`string`	Anti-affinity topology domain
`type`	`string`	Constraint type: `"required"` or `"preferred"`

ServiceSpec

Configures how Neo4j is exposed outside the Kubernetes cluster.

Field	Type	Description
`type`	`string`	Service type: `"ClusterIP"`, `"NodePort"`, `"LoadBalancer"` (default: `"ClusterIP"`)
`annotations`	`map[string]string`	Service annotations (e.g., for cloud load balancer configuration)
`loadBalancerIP`	`string`	Static IP for LoadBalancer service (cloud provider specific)
`loadBalancerSourceRanges`	`[]string`	IP ranges allowed to access LoadBalancer
`externalTrafficPolicy`	`string`	External traffic policy: `"Cluster"` or `"Local"`
`ingress`	`IngressSpec`	Ingress configuration
`route`	`RouteSpec`	OpenShift Route configuration

IngressSpec

Configures an Ingress resource for HTTP(S) access to Neo4j Browser.

Field	Type	Description
`enabled`	`bool`	Enable Ingress creation
`className`	`string`	Ingress class name (e.g., `"nginx"`)
`annotations`	`map[string]string`	Ingress annotations
`host`	`string`	Hostname for the Ingress
`tlsSecretName`	`string`	TLS secret name for Ingress

RouteSpec

Field	Type	Description
`enabled`	`bool`	Enable OpenShift Route creation
`host`	`string`	Hostname for the Route (optional)
`path`	`string`	Path for the Route (default: `"/"`)
`annotations`	`map[string]string`	Route annotations
`tls`	`*RouteTLSSpec`	TLS settings for the Route
`targetPort`	`int32`	Target service port (default: `7474`)

RouteTLSSpec

Field	Type	Description
`termination`	`string`	TLS termination: `"edge"`, `"reencrypt"`, `"passthrough"`
`insecureEdgeTerminationPolicy`	`string`	`"None"`, `"Allow"`, `"Redirect"`
`secretName`	`string`	Secret containing certificate (reencrypt/passthrough)

MCPServerSpec

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.

For client configuration, see the MCP Client Setup Guide.

Field	Type	Description
`enabled`	`bool`	Enable MCP server deployment (default: `false`)
`image`	`*ImageSpec`	MCP server image. Defaults to `mcp/neo4j:latest`. Pin a version with `image.tag`.
`transport`	`string`	Transport mode: `"http"` (default) or `"stdio"`
`readOnly`	`bool`	Disable the `write-cypher` tool when `true` (default: `true`)
`database`	`string`	Default Neo4j database for MCP queries
`schemaSampleSize`	`*int32`	Schema sampling size for `get-schema`. Use `-1` to sample entire graph.
`telemetry`	`*bool`	Enable anonymous usage telemetry sent to Neo4j. When unset, uses the server default (`true`). Set to `false` to opt out.
`logLevel`	`string`	Log verbosity: `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`
`logFormat`	`string`	Log output format: `text` (default) or `json`
`http`	`*MCPHTTPConfig`	HTTP transport configuration (only used when `transport: http`)
`auth`	`*MCPAuthSpec`	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.
`securityContext`	`*SecurityContextSpec`	Pod/container security context overrides

MCPHTTPConfig

HTTP transport configuration. Only applied when spec.mcp.transport: http.

Field	Type	Description
`host`	`string`	HTTP bind host (default: `0.0.0.0`)
`port`	`int32`	HTTP bind port. Default: `8080` without TLS, `8443` with TLS.
`tls`	`*MCPTLSSpec`	Optional container-level TLS. When unset, handle TLS at the Ingress layer instead.
`authHeaderName`	`string`	Name of the HTTP header carrying credentials (default: `Authorization`). Override when a proxy rewrites the standard header.
`service`	`*MCPServiceSpec`	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)
`ingress`	`*IngressSpec`	Ingress configuration. Path is always `/mcp` (fixed by the official image).
`route`	`*RouteSpec`	OpenShift Route configuration

MCPAuthSpec

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.
`usernameKey`	`string`	Username key name (default: `username`)
`passwordKey`	`string`	Password key name (default: `password`)

UISpec

Field	Type	Description
`enabled`	`bool`	Enable Neo4j UI deployment
`ingress`	`*IngressSpec`	UI ingress configuration
`resources`	`*corev1.ResourceRequirements`	Resource requirements for UI pods
`pathType`	`string`	Path type: `"Prefix"`, `"Exact"`, `"ImplementationSpecific"`
`tlsEnabled`	`bool`	Enable TLS on the Ingress
`tlsSecretName`	`string`	TLS certificate secret name
`annotations`	`map[string]string`	Ingress annotations

Status

The Neo4jEnterpriseClusterStatus represents the observed state of the cluster.

Field	Type	Description
`phase`	`string`	Cluster phase: `"Initializing"`, `"Running"`, `"Failed"`, `"Upgrading"`, `"Scaling"`
`ready`	`bool`	Whether the cluster is ready
`message`	`string`	Human-readable status message
`conditions`	`[]metav1.Condition`	Cluster conditions
`replicas`	`map[string]ReplicaStatus`	Status of each replica
`clusterID`	`string`	Neo4j cluster ID
`endpoints`	`EndpointStatus`	Service endpoints
`version`	`string`	Current Neo4j version
`upgradeStatus`	`*UpgradeStatus`	Upgrade status
`lastBackup`	`*metav1.Time`	Last backup timestamp
`observedGeneration`	`int64`	Last observed generation

EndpointStatus

Service endpoints and connection information.

Field	Type	Description
`boltURL`	`string`	Bolt protocol endpoint
`httpURL`	`string`	HTTP endpoint for Neo4j Browser
`httpsURL`	`string`	HTTPS endpoint for Neo4j Browser
`internalURL`	`string`	Internal cluster communication endpoint
`connectionExamples`	`ConnectionExamples`	Example connection strings

ConnectionExamples

Example connection strings for various scenarios.

Field	Type	Description
`portForward`	`string`	kubectl port-forward command
`browserURL`	`string`	Neo4j Browser URL
`boltURI`	`string`	Bolt connection URI
`neo4jURI`	`string`	Neo4j driver URI
`pythonExample`	`string`	Python driver connection example
`javaExample`	`string`	Java driver connection example

UpgradeStatus

Detailed upgrade progress tracking.

Field	Type	Description
`phase`	`string`	Upgrade phase: `"Pending"`, `"InProgress"`, `"Paused"`, `"Completed"`, `"Failed"`
`startTime`	`*metav1.Time`	When the upgrade started
`completionTime`	`*metav1.Time`	When the upgrade completed
`currentStep`	`string`	Current upgrade step description
`previousVersion`	`string`	Version before upgrade
`targetVersion`	`string`	Version being upgraded to
`progress`	`*UpgradeProgress`	Upgrade progress statistics
`message`	`string`	Additional upgrade details
`lastError`	`string`	Last error encountered during upgrade

UpgradeProgress

Upgrade progress across servers.

Field	Type	Description
`total`	`int32`	Total number of servers to upgrade
`upgraded`	`int32`	Number of servers successfully upgraded
`inProgress`	`int32`	Number of servers currently being upgraded
`pending`	`int32`	Number of servers pending upgrade
`servers`	`*NodeUpgradeProgress`	Server upgrade details

NodeUpgradeProgress

Server-specific upgrade progress.

Field	Type	Description
`total`	`int32`	Total number of servers
`upgraded`	`int32`	Number of servers successfully upgraded
`inProgress`	`int32`	Number of servers currently being upgraded
`pending`	`int32`	Number of servers pending upgrade
`currentLeader`	`string`	Current leader server

Examples

Basic Cluster

apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: basic-cluster
spec:
  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 replicas
  storage:
    className: standard
    size: 10Gi
  auth:
    adminSecret: neo4j-admin-secret  # Note: field name is 'adminSecret'
  resources:
    requests:
      cpu: "1"
      memory: 4Gi
    limits:
      cpu: "2"
      memory: 8Gi

Cluster with Server Role Constraints

apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: role-constrained-cluster
spec:
  image:
    repo: neo4j
    tag: "5.26.0-enterprise"
  topology:
    servers: 5
    # Global constraint: all servers default to any role
    serverModeConstraint: NONE
    # Per-server role hints (overrides global constraint)
    serverRoles:
      - serverIndex: 0
        modeConstraint: PRIMARY    # Server-0: only primary databases
      - serverIndex: 1
        modeConstraint: PRIMARY    # Server-1: only primary databases
      - serverIndex: 2
        modeConstraint: SECONDARY  # Server-2: only secondary databases
      - serverIndex: 3
        modeConstraint: SECONDARY  # Server-3: only secondary databases
      - serverIndex: 4
        modeConstraint: NONE       # Server-4: any database mode
    # Advanced placement for high availability
    placement:
      topologySpread:
        enabled: true
        topologyKey: topology.kubernetes.io/zone
        maxSkew: 1
        whenUnsatisfiable: DoNotSchedule
      antiAffinity:
        enabled: true
        topologyKey: kubernetes.io/hostname
        type: required
    availabilityZones:
      - us-east-1a
      - us-east-1b
      - us-east-1c
    enforceDistribution: true
  storage:
    className: fast-ssd
    size: 50Gi
  auth:
    adminSecret: neo4j-admin-secret

Cluster with Centralized Backup

apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: monitored-cluster
spec:
  image:
    repo: neo4j
    tag: "5.26.0-enterprise"
  topology:
    servers: 3  # Creates monitored-cluster-server StatefulSet
  storage:
    className: fast-ssd
    size: 50Gi
  auth:
    adminSecret: neo4j-admin-secret
  # Centralized backup configuration
  backups:
    defaultStorage:
      type: s3
      bucket: neo4j-backups
      path: production/
    cloud:
      provider: aws
      identity:
        provider: aws
        serviceAccount: neo4j-backup-sa  # Uses IAM roles for pods
  # Enhanced query monitoring
  queryMonitoring:
    enabled: true
    slowQueryThreshold: "1s"
    explainPlan: true
    indexRecommendations: true
    sampling:
      rate: "0.1"
      maxQueriesPerSecond: 100
    metricsExport:
      prometheus: true
      interval: "30s"

Create Scheduled Backup (Separate Resource)

# Note: Backups are now managed via Neo4jBackup CRD
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jBackup
metadata:
  name: daily-cluster-backup
spec:
  target:
    kind: Cluster
    name: monitored-cluster
  storage:
    type: s3
    bucket: neo4j-backups
    path: daily/
  schedule: "0 2 * * *"  # Daily at 2 AM
  retention:
    maxAge: "30d"
    maxCount: 30
  options:
    compress: true
    backupType: FULL

Cluster with LoadBalancer Service

apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: public-cluster
spec:
  image:
    repo: neo4j
    tag: "5.26.0-enterprise"
  topology:
    servers: 5  # Creates public-cluster-server StatefulSet with 5 replicas
  storage:
    className: standard
    size: 20Gi
  auth:
    adminSecret: neo4j-admin-secret
  # LoadBalancer service configuration
  service:
    type: LoadBalancer
    annotations:
      # AWS NLB example
      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
      service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled: "true"
    loadBalancerSourceRanges:
      - "10.0.0.0/8"      # Corporate network
      - "172.16.0.0/12"   # VPN range
    externalTrafficPolicy: Local  # Preserve client IPs

Cluster with Ingress

apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: ingress-cluster
spec:
  image:
    repo: neo4j
    tag: "5.26.0-enterprise"
  topology:
    servers: 3  # Creates ingress-cluster-server StatefulSet
  storage:
    className: fast-ssd
    size: 20Gi
  auth:
    adminSecret: neo4j-admin-secret
  # TLS configuration
  tls:
    mode: cert-manager
    issuerRef:
      name: letsencrypt-prod
      kind: ClusterIssuer
  # Ingress configuration
  service:
    ingress:
      enabled: true
      className: nginx
      host: neo4j.example.com
      tlsSecretName: neo4j-tls
      annotations:
        cert-manager.io/cluster-issuer: letsencrypt-prod
        nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

Management Commands

Basic Operations

# 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

Usage Patterns

Multi-Database Architecture

# 1. Create cluster with role-optimized servers
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: multi-db-cluster
spec:
  topology:
    servers: 6
    serverRoles:
      - serverIndex: 0
        modeConstraint: PRIMARY    # Dedicated for write workloads
      - serverIndex: 1
        modeConstraint: PRIMARY
      - serverIndex: 2
        modeConstraint: SECONDARY  # Dedicated for read workloads
      - serverIndex: 3
        modeConstraint: SECONDARY
      - serverIndex: 4
        modeConstraint: NONE       # Mixed workloads
      - serverIndex: 5
        modeConstraint: NONE
  # ... other configuration

---
# 2. Create databases with specific topologies
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jDatabase
metadata:
  name: user-database
spec:
  clusterRef: multi-db-cluster
  name: users
  topology:
    primaries: 2    # Uses servers 0-1 (PRIMARY constraint)
    secondaries: 2  # Uses servers 2-3 (SECONDARY constraint)

---
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jDatabase
metadata:
  name: analytics-database
spec:
  clusterRef: multi-db-cluster
  name: analytics
  topology:
    primaries: 1    # Uses server 4 or 5 (NONE constraint)
    secondaries: 3  # Uses remaining servers

Development vs Production

# Development cluster (minimal resources)
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: dev-cluster
spec:
  topology:
    servers: 2  # Minimum for clustering
  storage:
    className: standard
    size: 10Gi
  resources:
    requests:
      cpu: 200m
      memory: 1Gi
    limits:
      cpu: 1
      memory: 2Gi
  tls:
    mode: disabled

---
# Property Sharding cluster (Neo4j 2025.12+)
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: sharding-cluster
spec:
  image:
    repo: neo4j
    tag: 2025.12-enterprise
  topology:
    servers: 7  # Sufficient for property sharding workloads
  storage:
    className: fast-ssd
    size: 100Gi
  resources:
    requests:
      cpu: 2
      memory: 8Gi
    limits:
      cpu: 4
      memory: 16Gi
  propertySharding:
    enabled: true
    config:
      db.tx_log.rotation.retention_policy: "14 days"
      internal.dbms.sharded_property_database.property_pull_interval: "5ms"
      server.memory.heap.max_size: "12G"
      server.memory.pagecache.size: "6G"
  tls:
    mode: cert-manager
    issuerRef:
      name: ca-cluster-issuer
      kind: ClusterIssuer

---
# Production cluster (high availability)
apiVersion: neo4j.neo4j.com/v1alpha1
kind: Neo4jEnterpriseCluster
metadata:
  name: prod-cluster
spec:
  topology:
    servers: 5
    placement:
      topologySpread:
        enabled: true
        topologyKey: topology.kubernetes.io/zone
        maxSkew: 1
      antiAffinity:
        enabled: true
        type: required
    availabilityZones: [us-east-1a, us-east-1b, us-east-1c]
    enforceDistribution: true
  storage:
    className: fast-ssd
    size: 100Gi
  resources:
    requests:
      cpu: 2
      memory: 8Gi
    limits:
      cpu: 4
      memory: 16Gi
  tls:
    mode: cert-manager
    issuerRef:
      name: ca-cluster-issuer
      kind: ClusterIssuer
  auth:
    passwordPolicy:
      minLength: 12
      requireSpecialChars: true

Best Practices

Resource Planning: Allocate sufficient memory (≥4Gi) and CPU for Neo4j Enterprise workloads
High Availability: Use odd number of servers (3, 5) and distribute across availability zones
Server Role Optimization: Use role constraints to optimize server usage for specific workload patterns
Storage: Use fast SSD storage classes (fast-ssd, premium-ssd) for production workloads
Security: Always enable TLS and use strong password policies in production
Monitoring: Enable query monitoring and centralized logging for performance insights
Backup Strategy: Use centralized backup with appropriate retention policies
Scaling: Plan for growth - scaling up is easier than scaling down

Troubleshooting

Common Issues

# Check cluster formation
kubectl exec my-cluster-server-0 -- cypher-shell -u neo4j -p password "SHOW SERVERS"

# Check pod status
kubectl get pods -l neo4j.com/cluster=my-cluster
kubectl describe pod my-cluster-server-0

# Check operator logs
kubectl logs -n neo4j-operator deployment/neo4j-operator-controller-manager

# Verify split-brain detection
kubectl get events --field-selector reason=SplitBrainDetected

Resource Conflicts

# Check resource version conflicts
kubectl get events --field-selector reason=UpdateConflict

# Force reconciliation with a no-op annotation change
kubectl annotate neo4jenterprisecluster my-cluster \
  troubleshooting.neo4j.com/reconcile="$(date +%s)" --overwrite

For more information:

FilesExpand file tree

neo4jenterprisecluster.md

Latest commit

History