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 documentDBImage and gatewayImage. Individual image fields take precedence over this version. |
||
documentDBImage string |
DocumentDBImage is the container image to use for DocumentDB. Changing this is not recommended for most users. If not specified, defaults based on documentDBVersion or operator defaults. |
||
gatewayImage string |
GatewayImage is the container image to use for the DocumentDB Gateway sidecar. Changing this is not recommended for most users. If not specified, defaults to a version that matches the DocumentDB operator version. |
||
postgresImage string |
PostgresImage is the container image to use for the PostgreSQL server. If not specified, defaults to the last stable PostgreSQL version compatible with DocumentDB. Must use trixie (Debian 13) base to match the extension's GLIBC requirements. |
ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie | 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. |
||
clusterReplication ClusterReplication |
ClusterReplication configures cross-cluster replication for DocumentDB. | ||
sidecarInjectorPluginName string |
SidecarInjectorPluginName is the name of the sidecar injector plugin to use. | ||
walReplicaPluginName string |
WalReplicaPluginName is the name of the wal replica plugin to use. | ||
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: {} |
|
affinity AffinityConfiguration |
Affinity/Anti-affinity rules for Pods (cnpg passthrough) | 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. | Enum: [Disabled 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
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. |
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 |
PostgresTLS¶
PostgresTLS acts as a placeholder for future Postgres TLS settings.
Appears in: - TLSConfiguration
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"). | ||
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 |