API Reference¶
Packages¶
documentdb.io/preview¶
Package preview contains API Schema definitions for the db preview API group.
Resource Types¶
Backup¶
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
documentdb.io/preview |
||
kind string |
Backup |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec BackupSpec |
BackupConfiguration¶
BackupConfiguration defines backup settings for DocumentDB.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
retentionDays integer |
RetentionDays specifies how many days backups should be retained. If not specified, the default retention period is 30 days. |
30 | Maximum: 365 Minimum: 1 Optional: {} |
BackupSpec¶
BackupSpec defines the desired state of Backup.
Appears in: - Backup
| Field | Description | Default | Validation |
|---|---|---|---|
cluster LocalObjectReference |
Cluster specifies the DocumentDB cluster to backup. The cluster must exist in the same namespace as the Backup resource. |
Required: {} |
|
retentionDays integer |
RetentionDays specifies how many days the backup should be retained. If not specified, the default retention period from the cluster's backup retention policy will be used. |
Optional: {} |
BootstrapConfiguration¶
BootstrapConfiguration defines how to bootstrap a DocumentDB cluster.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
recovery RecoveryConfiguration |
Recovery configures recovery from a backup. | Optional: {} |
CertManagerTLS¶
CertManagerTLS holds parameters for cert-manager driven certificates.
Appears in: - GatewayTLS
| Field | Description | Default | Validation |
|---|---|---|---|
issuerRef IssuerRef |
|||
dnsNames string array |
DNSNames for the certificate SANs. If empty, operator will add Service DNS names. | ||
secretName string |
SecretName optional explicit name for the target secret. If empty a default is chosen. |
ClusterReplication¶
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
crossCloudNetworkingStrategy string |
CrossCloudNetworking determines which type of networking mechanics for the replication | Enum: [AzureFleet Istio None] |
|
primary string |
Primary is the name of the primary cluster for replication. | ||
clusterList MemberCluster array |
ClusterList is the list of clusters participating in replication. | ||
highAvailability boolean |
Whether or not to have replicas on the primary cluster. |
DocumentDB¶
DocumentDB is the Schema for the dbs API.
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
documentdb.io/preview |
||
kind string |
DocumentDB |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec DocumentDBSpec |
DocumentDBSpec¶
DocumentDBSpec defines the desired state of DocumentDB.
Appears in: - DocumentDB
| Field | Description | Default | Validation |
|---|---|---|---|
nodeCount integer |
NodeCount is the number of nodes in the DocumentDB cluster. Must be 1. | Maximum: 1 Minimum: 1 |
|
instancesPerNode integer |
InstancesPerNode is the number of DocumentDB instances per node. Range: 1-3. | Maximum: 3 Minimum: 1 |
|
resource Resource |
Resource specifies the storage resources for DocumentDB. | ||
documentDBVersion string |
DocumentDBVersion specifies the version for all DocumentDB components (engine, gateway). When set, this overrides the default versions for image.documentDB and image.gateway. Individual image fields under spec.image take precedence over this version. |
||
image ImageSpec |
Image groups container image settings for the DocumentDB stack (extension image, gateway image, PostgreSQL image). All fields are optional; sensible defaults are applied when omitted. |
Optional: {} |
|
imagePullSecrets LocalObjectReference array |
ImagePullSecrets is an optional list of references to secrets in the same namespace to use for pulling any of the images used by this cluster. Passed through to the underlying CloudNative-PG cluster. |
Optional: {} |
|
documentDbCredentialSecret string |
DocumentDbCredentialSecret is the name of the Kubernetes Secret containing credentials for the DocumentDB gateway (expects keys username and password). If omitted,a default secret name documentdb-credentials is used.NOTE: Immutable today; will be relaxed in a future release to support credential rotation. |
||
clusterReplication ClusterReplication |
ClusterReplication configures cross-cluster replication for DocumentDB. | ||
postgres PostgresSpec |
Postgres groups PostgreSQL process-level tuning (UID/GID, custom post-init SQL). All fields are optional; defaults are preserved when omitted. |
Optional: {} |
|
plugins PluginsSpec |
Plugins groups CNPG plugin configuration (sidecar injector name, WAL replica name). All fields are optional; defaults are preserved when omitted. |
Optional: {} |
|
exposeViaService ExposeViaService |
ExposeViaService configures how to expose DocumentDB via a Kubernetes service. This can be a LoadBalancer or ClusterIP service. |
||
environment string |
Environment specifies the cloud environment for deployment This determines cloud-specific service annotations for LoadBalancer services |
Enum: [eks aks gke] |
|
timeouts Timeouts |
|||
tls TLSConfiguration |
TLS configures certificate management for DocumentDB components. | ||
logLevel string |
Overrides default log level for the DocumentDB cluster. | ||
bootstrap BootstrapConfiguration |
Bootstrap configures the initialization of the DocumentDB cluster. | Optional: {} |
|
backup BackupConfiguration |
Backup configures backup settings for DocumentDB. | Optional: {} |
|
featureGates object (keys:string, values:boolean) |
FeatureGates enables or disables optional DocumentDB features. Keys are PascalCase feature names following the Kubernetes feature gate convention. Example: {"ChangeStreams": true} IMPORTANT: When adding a new feature gate, update ALL of the following: 1. Add a new FeatureGate* constant in documentdb_types.go 2. Add the key name to the XValidation CEL rule's allowed list below 3. Add a default entry in the featureGateDefaults map in documentdb_types.go |
Optional: {} |
|
schemaVersion string |
SchemaVersion controls the desired schema version for the DocumentDB extension. The operator never changes your database schema unless you ask: - Set schemaVersion → updates the database schema (irreversible) - Set schemaVersion: "auto" → schema auto-updates with binary Once the schema has been updated, the operator blocks image rollback below the installed schema version to prevent running an untested binary/schema combination. Values: - "" (empty, default): Two-phase mode. Image upgrades happen automatically, but ALTER EXTENSION UPDATE does NOT run. Users must explicitly set this field to finalize the schema upgrade. This is the safest option for production as it allows rollback by reverting the image before committing the schema change. - "auto": Schema automatically updates to match the binary version whenever the binary is upgraded. This is the simplest mode but provides no rollback safety window. Only recommended for single-region clusters. - " Must be <= the binary version. |
Pattern: ^(auto\|[0-9]+\.[0-9]+\.[0-9]+)?$ Optional: {} |
|
affinity AffinityConfiguration |
Affinity/Anti-affinity rules for Pods (cnpg passthrough) | Optional: {} |
|
monitoring MonitoringSpec |
Monitoring configures observability via an OTel Collector sidecar. | Optional: {} |
ExporterSpec¶
ExporterSpec configures metric export destinations.
Appears in: - MonitoringSpec
| Field | Description | Default | Validation |
|---|---|---|---|
otlp OTLPExporterSpec |
OTLP configures the OpenTelemetry Protocol exporter. | Optional: {} |
|
prometheus PrometheusExporterSpec |
Prometheus configures a Prometheus scrape endpoint on the OTel Collector sidecar. | Optional: {} |
ExposeViaService¶
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
serviceType string |
ServiceType determines the type of service to expose for DocumentDB. | Enum: [LoadBalancer ClusterIP] |
GatewayTLS¶
GatewayTLS defines TLS configuration for the gateway sidecar (Phase 1: certificate provisioning only)
Appears in: - TLSConfiguration
| Field | Description | Default | Validation |
|---|---|---|---|
mode string |
Mode selects the TLS management strategy. Defaults to SelfSigned if not specified. |
SelfSigned | Enum: [SelfSigned CertManager Provided] |
certManager CertManagerTLS |
CertManager config when Mode=CertManager. | ||
provided ProvidedTLS |
Provided secret reference when Mode=Provided. |
GlobalEndpointsTLS¶
GlobalEndpointsTLS acts as a placeholder for future global endpoint TLS settings.
Appears in: - TLSConfiguration
ImageSpec¶
ImageSpec groups container image settings for the DocumentDB stack. All fields are optional; the operator falls back to documentDBVersion, environment variables, and built-in defaults in that order.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
documentDB string |
DocumentDB is the container image for the DocumentDB extension layer. This image is mounted into the PostgreSQL container via CNPG's ImageVolumeSource so that the extension files are available alongside an upstream PostgreSQL image. |
Optional: {} |
|
gateway string |
Gateway is the container image for the DocumentDB Gateway sidecar. | Optional: {} |
|
postgres string |
Postgres is the container image for the PostgreSQL server. Must be an upstream CNPG-compatible PostgreSQL image (the operator adds the DocumentDB extension via an ImageVolume mount), and must use trixie (Debian 13) base to match the extension's GLIBC requirements. |
ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie | Optional: {} |
IssuerRef¶
IssuerRef references a cert-manager Issuer or ClusterIssuer.
Appears in: - CertManagerTLS
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
|||
kind string |
Kind of issuer (Issuer or ClusterIssuer). Defaults to Issuer. | ||
group string |
Group defaults to cert-manager.io |
MemberCluster¶
Appears in: - ClusterReplication
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the member cluster. | ||
environment string |
EnvironmentOverride is the cloud environment of the member cluster. Will default to the global setting |
Enum: [eks aks gke] |
|
storageClass string |
StorageClassOverride specifies the storage class for DocumentDB persistent volumes in this member cluster. |
MonitoringSpec¶
MonitoringSpec configures observability via an OTel Collector sidecar.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
enabled boolean |
Enabled turns on the OTel Collector sidecar for metrics collection. | ||
exporter ExporterSpec |
Exporter configures where metrics are sent. | Optional: {} |
OTLPExporterSpec¶
OTLPExporterSpec configures the OTLP exporter.
Appears in: - ExporterSpec
| Field | Description | Default | Validation |
|---|---|---|---|
endpoint string |
Endpoint is the OTLP gRPC endpoint (e.g., "otel-collector.monitoring:4317"). |
PVRecoveryConfiguration¶
PVRecoveryConfiguration defines settings for recovering from a retained PersistentVolume.
Appears in: - RecoveryConfiguration
| Field | Description | Default | Validation |
|---|---|---|---|
name string |
Name is the name of the PersistentVolume to recover from. The PV must exist and be in Available or Released state. |
MinLength: 1 |
PluginsSpec¶
PluginsSpec groups CNPG plugin configuration.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
sidecarInjectorName string |
SidecarInjectorName is the name of the CNPG sidecar injector plugin to use for the gateway and other sidecars. Immutable. |
Optional: {} |
|
walReplicaName string |
WalReplicaName is the name of the WAL replica plugin to use for cross-cluster replication. |
Optional: {} |
PostgresSpec¶
PostgresSpec groups PostgreSQL process-level tuning. All fields are optional.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
uid integer |
UID is the numeric user ID under which the PostgreSQL server process runs. When set, GID must also be set. |
Optional: {} |
|
gid integer |
GID is the numeric group ID under which the PostgreSQL server process runs. When set, UID must also be set. |
Optional: {} |
|
postInitSQL string array |
PostInitSQL is an ordered list of SQL statements executed after the cluster is initialized. These statements run AFTER the operator's mandatory bootstrap (CREATE EXTENSION documentdb, CREATE ROLE documentdb, ALTER ROLE documentdb), so they can safely reference the documentdb extension and role. |
Optional: {} |
PostgresTLS¶
PostgresTLS acts as a placeholder for future Postgres TLS settings.
Appears in: - TLSConfiguration
PrometheusExporterSpec¶
PrometheusExporterSpec configures the Prometheus scrape endpoint exporter.
Appears in: - ExporterSpec
| Field | Description | Default | Validation |
|---|---|---|---|
port integer |
Port for the Prometheus scrape endpoint. Defaults to 8888. | 8888 | Maximum: 65535 Minimum: 1024 Optional: {} |
ProvidedTLS¶
ProvidedTLS references an existing secret that contains tls.crt/tls.key (and optional ca.crt).
Appears in: - GatewayTLS
| Field | Description | Default | Validation |
|---|---|---|---|
secretName string |
RecoveryConfiguration¶
RecoveryConfiguration defines recovery settings for bootstrapping a DocumentDB cluster.
Appears in: - BootstrapConfiguration
| Field | Description | Default | Validation |
|---|---|---|---|
backup LocalObjectReference |
Backup specifies the source backup to restore from. | Optional: {} |
|
persistentVolume PVRecoveryConfiguration |
PersistentVolume specifies the PV to restore from. The operator will create a temporary PVC bound to this PV, use it for CNPG recovery, and delete the temporary PVC after the cluster is healthy. Cannot be used together with Backup. |
Optional: {} |
Resource¶
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
storage StorageConfiguration |
Storage configuration for DocumentDB persistent volumes. |
ScheduledBackup¶
| Field | Description | Default | Validation |
|---|---|---|---|
apiVersion string |
documentdb.io/preview |
||
kind string |
ScheduledBackup |
||
metadata ObjectMeta |
Refer to Kubernetes API documentation for fields of metadata. |
||
spec ScheduledBackupSpec |
ScheduledBackupSpec¶
ScheduledBackupSpec defines the desired state of ScheduledBackup
Appears in: - ScheduledBackup
| Field | Description | Default | Validation |
|---|---|---|---|
cluster LocalObjectReference |
Cluster specifies the DocumentDB cluster to backup. The cluster must exist in the same namespace as the ScheduledBackup resource. |
Required: {} |
|
schedule string |
Schedule defines when backups should be created using cron expression format. See https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format |
Required: {} |
|
retentionDays integer |
RetentionDays specifies how many days the backups should be retained. If not specified, the default retention period from the cluster's backup retention policy will be used. |
Optional: {} |
StorageConfiguration¶
Appears in: - Resource
| Field | Description | Default | Validation |
|---|---|---|---|
pvcSize string |
PvcSize is the size of the persistent volume claim for DocumentDB storage (e.g., "10Gi"). | MinLength: 1 |
|
storageClass string |
StorageClass specifies the storage class for DocumentDB persistent volumes. If not specified, the cluster's default storage class will be used. |
||
persistentVolumeReclaimPolicy string |
PersistentVolumeReclaimPolicy controls what happens to the PersistentVolume when the DocumentDB cluster is deleted. When a DocumentDB cluster is deleted, the following chain of deletions occurs: DocumentDB deletion → CNPG Cluster deletion → PVC deletion → PV deletion (based on this policy) Options: - Retain (default): The PV is preserved after cluster deletion, allowing manual data recovery or forensic analysis. Use for production workloads where data safety is critical. Orphaned PVs must be manually deleted when no longer needed. - Delete: The PV is automatically deleted when the PVC is deleted. Use for development, testing, or ephemeral environments where data persistence is not required. WARNING: Setting this to "Delete" means all data will be permanently lost when the DocumentDB cluster is deleted. This cannot be undone. |
Retain | Enum: [Retain Delete] Optional: {} |
TLSConfiguration¶
TLSConfiguration aggregates TLS settings across DocumentDB components.
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
gateway GatewayTLS |
Gateway configures TLS for the gateway sidecar (Phase 1: certificate provisioning only). | ||
postgres PostgresTLS |
Postgres configures TLS for the Postgres server (placeholder for future phases). | ||
globalEndpoints GlobalEndpointsTLS |
GlobalEndpoints configures TLS for global endpoints (placeholder for future phases). |
Timeouts¶
Appears in: - DocumentDBSpec
| Field | Description | Default | Validation |
|---|---|---|---|
stopDelay integer |
Maximum: 1800 Minimum: 0 |