Skip to content

AuraCustomerManagedKey API Reference

⛔ UNPROVEN — never exercised against the live Aura API. Every other Aura CRD has been driven end-to-end against a real account; this one has not, because it needs a real cloud KMS key (AWS KMS / GCP Cloud KMS / Azure Key Vault) with IAM grants to Aura, which cannot be created disposably. Its shape comes from the published v1 OpenAPI spec — and on this API, spec-derived contracts have repeatedly proven wrong. Verify in a non-production project before relying on it. See Verification status.

Adoption: the v1 CMK list endpoint returns only id, name and tenant_id, so adoption narrows on name and then confirms with a per-key GET — a key can never be matched on keyId/region/cloudProvider from a list entry.

The AuraCustomerManagedKey Custom Resource Definition (CRD) registers a customer-managed encryption key (CMK) with Neo4j Aura for use by dedicated-tier instances. The key material lives in the customer's own cloud KMS; Aura stores only a reference to it.

Overview

  • API Version: neo4j.neo4j.com/v1beta1
  • Kind: AuraCustomerManagedKey
  • Scope: Namespaced
  • Short name: auracmk
  • Purpose: Register a customer-managed encryption key (CMK) for dedicated-tier AuraInstance encryption.
  • Guide: Aura Orchestration Guide

Once the key reaches status Ready, its Aura-assigned ID (status.customerManagedKeyId) is referenced from an AuraInstance's spec.customerManagedKeyId. Every placement field is immutable: a CMK is permanently bound to one cloud provider, region, instance type, and KMS key — to change any of them, create a new CMK.

Spec

Set exactly one of providerConfigRef or credentialsSecretRef for API access.

Field Type Description
providerConfigRef object References an AuraProviderConfig ({name}, a core LocalObjectReference) in the same namespace. Mutually exclusive with credentialsSecretRef.
credentialsSecretRef object Inline single-account shortcut when no AuraProviderConfig is used. See AuraCredentialsSecretRef. Mutually exclusive with providerConfigRef.
projectId string Aura project (the API tenant_id) the key is scoped to. Immutable once set. Falls back to the provider config's defaultProjectId when empty.
name string CMK display name in Aura (max 30 chars). Defaults to metadata.name.
cloudProvider string Enum aws / gcp / azure. Must match the instances that will use it. Required. Immutable.
region string Region the key applies to, e.g. europe-west1. Required. Immutable.
instanceType string Enum enterprise-db / enterprise-ds — CMKs are supported for the dedicated tiers only. Required. Immutable.
keyId string The cloud KMS key resource identifier Aura will use: an AWS KMS key ARN, a GCP KMS key resource name, or an Azure Key Vault key URL. The customer must grant Aura access to this key out of band. Required. Immutable.
deletionPolicy string Enum Orphan / Delete. Default Orphan (leave the key registered in Aura on CR delete). Delete deregisters it — fails while any instance still uses it.
managementPolicies []string Items enum Observe / Create / Update / Delete / *. Default ["*"] (full management).

Status

Field Type Description
customerManagedKeyId string Aura-assigned key ID. Reference this value from an AuraInstance's spec.customerManagedKeyId.
phase string Mirrors the Aura key status: Pending, Ready, Deleting, Error.
conditions []metav1.Condition Ready (key usable) and Synced (operator reconciled spec).
observedGeneration int64 The .metadata.generation last reconciled.
lastSyncedTime *metav1.Time When the key was last observed from the Aura API.

Deletion note

A key still bound to an instance cannot be deleted — Aura returns encryption-key-is-active. The CR then sets Synced=False with reason KeyInUse and keeps its finalizer until the key is no longer referenced by any instance.

Example

apiVersion: neo4j.neo4j.com/v1beta1
kind: AuraCustomerManagedKey
metadata:
  name: prod-cmk
  namespace: neo4j
spec:
  providerConfigRef:
    name: aura-account
  cloudProvider: aws
  region: eu-west-1
  instanceType: enterprise-db
  keyId: arn:aws:kms:eu-west-1:123456789012:key/abcd1234-...

Then reference the resulting key from an instance:

spec:
  type: enterprise-db
  customerManagedKeyId: <status.customerManagedKeyId of prod-cmk>