Aura Fleet Management Integration¶

Neo4j Aura Fleet Management lets you monitor all your Neo4j deployments — both Aura-managed and self-managed — from a single Aura console view. The operator integrates with Fleet Management natively: it installs the plugin automatically and handles token registration once your cluster is ready.

How it works¶

The fleet-management plugin jar is pre-bundled in every Neo4j Enterprise image at /var/lib/neo4j/products/. When you enable Fleet Management in the operator:

The operator merges "fleet-management" into the existing NEO4J_PLUGINS list on the StatefulSet. This is additive — any plugins already installed via Neo4jPlugin CRDs are preserved. At pod startup, the Docker entrypoint copies the bundled jar to /plugins/ — no internet access required.
The required procedure security settings (dbms.security.procedures.unrestricted=fleetManagement.* and dbms.security.procedures.allowlist=fleetManagement.*) are added to neo4j.conf automatically.
Once the cluster reaches Ready phase and the plugin is loaded, the operator reads the Aura registration token from a Kubernetes Secret and calls CALL fleetManagement.registerToken($token) via Bolt. This is idempotent — re-registering on reconcile loops is harmless.

Two-phase reconciliation¶

Plugin installation (step 1) happens on every reconcile when enabled: true. Token registration (step 2–3) is gated on status.phase == "Ready" and skips if status.auraFleetManagement.registered == true. This ensures the pod restart triggered by the plugin load completes before registration is attempted.

Plugin coexistence¶

Fleet Management works alongside any Neo4jPlugin CRDs you apply to the same deployment. For example, if APOC is installed via a Neo4jPlugin resource, the NEO4J_PLUGINS list on the StatefulSet will contain both:

["apoc","fleet-management"]

The operator uses an additive merge strategy — neither controller overwrites the other's entries.

Prerequisites¶

A Neo4j Aura account with Fleet Management enabled.
A registration token from the Aura console wizard (see Generate a token) — or Aura API credentials, and let the operator mint the token itself (see Operator-managed onboarding).
Neo4j Enterprise 5.26+ or 2025.x+. All supported enterprise images bundle the fleet-management plugin.

Generate a token¶

In the Aura console:

Navigate to Instances → Self-managed → Add deployment
Select Monitor deployment
Follow the wizard — skip the "Install the plugin" step (the operator handles it)
Generate a token with your preferred expiry and note whether you want auto-rotation enabled (the plugin will renew it automatically before expiry)
Copy the token value

Configure the operator¶

Step 1 — Store the token in a Kubernetes Secret¶

kubectl create secret generic aura-fleet-token \
  --from-literal=token='<paste-token-here>' \
  -n <your-namespace>

Step 2 — Enable Fleet Management in the cluster spec¶

Add the auraFleetManagement field to your Neo4jEnterpriseCluster or Neo4jEnterpriseStandalone:

apiVersion: neo4j.neo4j.com/v1beta1
kind: Neo4jEnterpriseCluster
metadata:
  name: my-cluster
spec:
  acceptLicenseAgreement: "eval"
  image:
    repo: neo4j
    tag: 2025.12-enterprise
  topology:
    servers: 3
  storage:
    size: 10Gi
  auth:
    adminSecret: neo4j-admin-secret

  auraFleetManagement:
    enabled: true
    tokenSecretRef:
      name: aura-fleet-token   # the Secret created above
      key: token               # defaults to "token" if omitted

The operator will:

Merge "fleet-management" into NEO4J_PLUGINS on the next reconcile (causes a rolling pod restart to load the jar)
Register the token once the cluster reaches Ready phase

Verify registration¶

# Check status
kubectl get neo4jenterprisecluster my-cluster -o jsonpath='{.status.auraFleetManagement}'

# Example output:
# {"registered":true,"lastRegistrationTime":"2025-12-01T10:00:00Z","message":"Registered with Aura Fleet Management"}

# Check events
kubectl get events --field-selector reason=AuraFleetManagementRegistered

After a few minutes you should see the deployment appear in the Aura console under Instances → Self-managed.

Standalone deployment¶

Works identically for Neo4jEnterpriseStandalone:

apiVersion: neo4j.neo4j.com/v1beta1
kind: Neo4jEnterpriseStandalone
metadata:
  name: my-standalone
spec:
  acceptLicenseAgreement: "eval"
  image:
    repo: neo4j
    tag: 5.26-enterprise
  storage:
    size: 10Gi
  auth:
    adminSecret: neo4j-admin-secret

  auraFleetManagement:
    enabled: true
    tokenSecretRef:
      name: aura-fleet-token

Plugin only, no token (monitoring-ready mode)¶

You can enable the plugin without providing a token yet. The plugin will be installed and the security settings applied, but registration is deferred until a tokenSecretRef is added.

auraFleetManagement:
  enabled: true
  # tokenSecretRef omitted — plugin installed, registration deferred

This is useful if you want to pre-install the plugin before setting up Aura access.

Operator-managed onboarding (mint the token automatically)¶

Everything above requires a human to run the console wizard and paste a token into a Secret. If you give the operator Aura API credentials instead, it can register the Fleet Manager deployment and mint the token itself — no wizard, no copy-paste.

Verified against a live Aura account (2026-07-31)

The whole provisioning path — deployment registration, token minting, rotation and cleanup — has been driven end-to-end against a real Aura organization. See Aura Orchestration → Verification status.

Set spec.auraFleetManagement.provision instead of tokenSecretRef (the two are mutually exclusive):

apiVersion: neo4j.neo4j.com/v1beta1
kind: Neo4jEnterpriseCluster
metadata:
  name: my-cluster
spec:
  auraFleetManagement:
    enabled: true
    provision:
      providerConfigRef:
        name: aura-prod          # AuraProviderConfig with API credentials
      # organizationId / projectId default to the provider config's values
      collectTelemetry: true     # mirror Aura's view into status (optional)

The operator then:

Registers a deployment named <namespace>-<name> (capped at 30 characters — the Aura API's limit). Override with provision.deploymentName.
Mints a registration token and stores it in <name>-aura-fleet-token (override with provision.tokenSecretName). The Secret is owned by the CR, so it is garbage-collected with it.
Registers that token over Bolt exactly as the manual flow does — reading it back out of the Secret from step 2.

The Aura deployment ID is pinned to the CR in the neo4j.com/external-fleet-deployment-id annotation. Do not remove it — it is what stops a second deployment being registered on the next reconcile.

The one-shot token rule¶

Aura returns a deployment token exactly once. It cannot be read back later. That shapes the recovery behaviour when the token Secret is deleted:

`provision.tokenPolicy`	Behaviour when the Secret is missing
`CreateIfMissing` (default)	Mints a token only if the Aura deployment has none. If the deployment already has a registered token, the operator refuses to rotate and explains why in `status.auraFleetManagement.message` — rotating would invalidate a working registration to fix a missing file.
`Rotate`	Always rotates to obtain a fresh token. This invalidates the existing registration, so the operator clears `status.auraFleetManagement.registered` before rotating and the DBMS re-registers with the new token.

If you hit the refusal, either restore the Secret from backup or opt into tokenPolicy: Rotate deliberately.

Cleanup¶

provision.deletionPolicy defaults to Orphan — deleting the CR leaves the deployment registered in Aura, so monitoring history survives a redeploy. Set it to Delete to revoke the token and unregister the deployment on CR deletion.

Aura's view of the deployment¶

With provision.collectTelemetry: true, the operator mirrors what Aura's fleet plugin reports into status.auraFleetManagement.servers / .databases: server versions, JVM/OS, license state and mode constraint, plus per-database role/writer, last committed transaction, replication lag, and graph/property shards.

Database detail is fetched per server — Aura only exposes role, writer, transaction and shard data on its per-server endpoint, not on the deployment-level database list — so each row carries a serverId identifying which server reported it. Several servers reporting the same database therefore produce one row each, with different roles.

This is deliberately separate from status.diagnostics, which is the operator's own Bolt-derived view. The two can legitimately disagree (different source, different moment), and merging them would hide which one said what. Both lists are capped at 20 entries; serverCount / databaseCount report the true totals, and telemetryError records a collection failure — telemetry never fails a reconcile.

Token rotation¶

If you enable auto-rotation in the Aura wizard, the plugin handles renewal automatically — no operator changes needed. If you rotate manually (generate a new token in Aura), update the Kubernetes Secret:

kubectl create secret generic aura-fleet-token \
  --from-literal=token='<new-token>' \
  --dry-run=client -o yaml | kubectl apply -f -

The operator will detect that status.auraFleetManagement.registered is true and skip re-registration. To force re-registration with the new token, patch the cluster status:

kubectl patch neo4jenterprisecluster my-cluster \
  --type=merge --subresource=status \
  -p '{"status":{"auraFleetManagement":{"registered":false}}}'

The operator will then call registerToken with the new token on the next reconcile.

Security¶

The token Secret is read at registration time — it is never stored in the cluster spec or status.
Fleet Management uses outbound-only connections from your deployment to Aura — no inbound ports are opened.
The plugin does not read database data; it only reports metrics and topology. See Fleet Management Data Transparency for the full list of transmitted data.

Status fields¶

Field	Type	Description
`status.auraFleetManagement.registered`	bool	`true` once `registerToken` succeeded
`status.auraFleetManagement.lastRegistrationTime`	time	Timestamp of last successful registration
`status.auraFleetManagement.message`	string	Human-readable status or error message
`status.auraFleetManagement.provisioned`	bool	`true` once the operator has registered a deployment and stored a token (operator-managed onboarding only)
`status.auraFleetManagement.deploymentId`	string	Aura-assigned Fleet Manager deployment ID
`status.auraFleetManagement.deploymentName`	string	Name the deployment is registered under in Aura
`status.auraFleetManagement.tokenSecretName`	string	Secret holding the minted token
`status.auraFleetManagement.tokenCreationTime`	time	When Aura created the current token
`status.auraFleetManagement.tokenExpiryTime`	time	When the current token expires
`status.auraFleetManagement.tokenAutoRotate`	bool	Whether Aura auto-renews the token on expiry
`status.auraFleetManagement.servers` / `.databases`	list	Aura's view of the deployment (`collectTelemetry: true`), capped at 20
`status.auraFleetManagement.serverCount` / `.databaseCount`	int	Untruncated totals
`status.auraFleetManagement.telemetryError`	string	Why the last telemetry collection failed (non-fatal)

Troubleshooting¶

Registration not happening after enabling

The operator only attempts registration when status.phase == "Ready". Check that all pods are healthy:

kubectl get pods
kubectl describe neo4jenterprisecluster my-cluster

fleetManagement.registerToken procedure not found

The plugin jar may not have been copied yet. This happens if pods are still restarting after NEO4J_PLUGINS was updated. Wait for the rolling update to complete, or check:

kubectl exec my-cluster-server-0 -- cypher-shell -u neo4j -p <password> \
  "SHOW PROCEDURES YIELD name WHERE name STARTS WITH 'fleetManagement' RETURN name"

Registration failing (registered: false with a message)

Registration failures are recorded in status.auraFleetManagement.message, and each new failure also raises an AuraFleetManagementFailed warning event:

kubectl get neo4jenterprisecluster my-cluster -o jsonpath='{.status.auraFleetManagement.message}'

Common causes:

Token Secret not found in the correct namespace (cannot read token secret …)
Incorrect key name in the Secret (default is token) (key "token" not found in secret …)
Token has expired — generate a new one in the Aura console, update the Secret, and reset registered as described under Token rotation

The event is raised when a failure first appears or its message changes, not on every retry, so a registration that keeps failing the same way produces one event rather than a stream. The message in status.auraFleetManagement.message is always the current one:

kubectl get events --field-selector reason=AuraFleetManagementFailed

A failure to patch the plugin onto the StatefulSet is reported separately, as AuraFleetManagementPluginPatchFailed.

Other plugins disappear after enabling Fleet Management

This should not happen (the additive merge strategy prevents it). If you observe it, check:

# Inspect the full NEO4J_PLUGINS value
kubectl get statefulset my-cluster-server \
  -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="NEO4J_PLUGINS")].value}'
# Should show all plugins, e.g. ["apoc","fleet-management"]

Manually verify the plugin

kubectl exec my-cluster-server-0 -- cypher-shell -u neo4j -p <password> \
  "CALL fleetManagement.status()"