Skip to content

Add DocumentDB guides #935

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tamalsaha wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add DocumentDB guides #935

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/examples/documentdb/autoscaler/compute/autoscaling-compute-object.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Base DocumentDB for COMPUTE autoscaling tests.
# Resources are deliberately LOW (cpu 500m / memory 1Gi) so a compute autoscaler
# with minAllowed above these values deterministically recommends a scale-UP to
# minAllowed (the recommendation floor), which creates a VerticalScaling ops request.
# local-path is fine for compute tests (no volume expansion involved).
Comment on lines +1 to +5

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

This example uses a storage/topology combination the PR already calls out as broken.

The PR notes that multi-replica DocumentDB clusters on local-path stay Ready=False, but this manifest sets replicas: 3 with storageClassName: local-path and even says that combination is fine. Because compute autoscaling needs a Ready database first, readers following this example will get stuck before any VerticalScaling OpsRequest is created.

Also applies to: 15-28

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/examples/documentdb/autoscaler/compute/autoscaling-compute-object.yaml`
around lines 1 - 5, The example in autoscaling-compute-object.yaml uses a broken
multi-replica DocumentDB setup with storageClassName set to local-path, which
prevents the database from reaching Ready before compute autoscaling can
trigger. Update the manifest and its surrounding comments in the DocumentDB
example to avoid the unsupported replicas/local-path combination, using a
storage/topology configuration that is known to become Ready, so the compute
autoscaler can proceed to create the VerticalScaling OpsRequest as intended.

apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: dcdb
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 3
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: 500m
memory: 1Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
33 changes: 33 additions & 0 deletions docs/examples/documentdb/autoscaler/compute/autoscaling-compute.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# COMPUTE (vertical) autoscaler for DocumentDB.
# The compute loop creates a VPA named after the DB's petset (= db name "dcdb"),
# polls VPA recommendations, and when the recommendation differs from the current
# request by more than resourceDiffPercentage (and the pod is older than
# podLifeTimeThreshold, OR the current request is outside the min/max band),
# it creates a VerticalScaling DocumentDBOpsRequest named dcops-dcdb-<rand>.
#
# Deterministic scale-UP: the base DB requests 500m/1Gi which is BELOW minAllowed
# (600m/1.5Gi) here, so the recommendation floor pushes it up to minAllowed.
apiVersion: autoscaling.kubedb.com/v1alpha1
kind: DocumentDBAutoscaler
metadata:
name: dcdb-compute-autoscaler
namespace: demo
spec:
databaseRef:
name: dcdb
opsRequestOptions:
timeout: 5m
apply: IfReady # IfReady | Always
compute:
documentdb:
trigger: "On" # "On" | "Off"
podLifeTimeThreshold: 1m
resourceDiffPercentage: 5
minAllowed:
cpu: 600m
memory: 1.5Gi
maxAllowed:
cpu: "2"
memory: 3Gi
controlledResources: ["cpu", "memory"]
containerControlledValues: "RequestsAndLimits" # RequestsAndLimits | RequestsOnly
33 changes: 33 additions & 0 deletions docs/examples/documentdb/autoscaler/storage/autoscaling-storage-object.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Base DocumentDB for STORAGE autoscaling tests.
# Storage autoscaling issues a VolumeExpansion ops request, which REQUIRES an
# expandable StorageClass (allowVolumeExpansion: true). local-path is NOT
# expandable, so use longhorn (installed in this cluster). Start small (2Gi) so
# the volume fills past usageThreshold quickly when you write data.
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: dcdb
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 3
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 1Gi
limits:
cpu: 500m
memory: 1Gi
storage:
storageClassName: "longhorn"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 2Gi
33 changes: 33 additions & 0 deletions docs/examples/documentdb/autoscaler/storage/autoscaling-storage.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# STORAGE autoscaler for DocumentDB.
# The storage loop reads PVC usage from the custom-metrics API (volume_used_percentage)
# for the DB's pods. When usage% > usageThreshold, it computes a new size from
# scalingRules and creates a VolumeExpansion DocumentDBOpsRequest (capped at upperBound)
# using expansionMode.
#
# IMPORTANT: the DocumentDB storage autoscaler computes the scaled size ONLY from
# `scalingRules[].threshold` (see GetVolumeForOpsReq) -- the simpler top-level
# `scalingThreshold` field is NOT read by this controller path. You MUST provide
# scalingRules or NO ops request is ever created. A single rule with empty
# appliesUpto applies to all sizes; threshold "50%" grows capacity by 50%.
Comment on lines +7 to +11

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Align the documented growth math with the captured output.

This example says threshold: 50% grows 2Gi to 3Gi, but the guide later shows the generated size as about 2.85Gi. Those two explanations can't both be true, so readers won't know what size to expect from this rule. Either fix the example/output pair or explain the actual sizing formula.

Also applies to: 29-31

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/examples/documentdb/autoscaler/storage/autoscaling-storage.yaml` around
lines 7 - 11, The autoscaling example in the storage DocumentDB YAML has
inconsistent growth math between the `scalingRules[].threshold` explanation and
the later generated-size output. Update the example and surrounding text to
match the actual sizing behavior used by `GetVolumeForOpsReq`, or explicitly
document the formula that converts a 50% threshold into the shown capacity, so
readers can trace the result from the `scalingRules` values.

#
# REQUIRES: an expandable StorageClass (provision the DB with autoscaling-storage-object.yaml)
# AND the custom.metrics.k8s.io API (storage-metrics-apiserver) -- metrics-server
# alone is NOT enough. The autoscaler ServiceAccount also needs get/list on
# custom.metrics.k8s.io (added to ClusterRole kubedb-kubedb-autoscaler).
apiVersion: autoscaling.kubedb.com/v1alpha1
kind: DocumentDBAutoscaler
metadata:
name: dcdb-storage-autoscaler
namespace: demo
spec:
databaseRef:
name: dcdb
storage:
documentdb:
trigger: "On" # "On" | "Off"
usageThreshold: 60 # scale when PVC usage% is > 60
scalingRules: # REQUIRED: drives the new size (scalingThreshold is ignored here)
- appliesUpto: "" # empty = applies to all current sizes
threshold: 50% # grow capacity by 50% (e.g. 2Gi -> 3Gi)
expansionMode: "Online" # Online | Offline (Online needs online-resize-capable CSI)
upperBound: 10Gi # never grow past this
27 changes: 27 additions & 0 deletions docs/examples/documentdb/configuration/cluster-config-secret.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-cls-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 3
configuration:
secretName: documentdb-custom-config
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
Comment on lines +1 to +27

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🔴 Critical | 🏗️ Heavy lift

DocumentDB CR specifies PostgreSQL version string pg17-0.109.0.

DocumentDB is a MongoDB-compatible database; the version should reflect a MongoDB/DocumentDB version (e.g., 4.0.0 or a KubeDB-specific DocumentDB version string), not a PostgreSQL version. This pg17-0.109.0 value is clearly carried over from the Postgres guides and will prevent proper cluster provisioning.

🛠️ Suggested correction 
-  version: 'pg17-0.109.0'
+  version: '5.1.0'  # or appropriate KubeDB DocumentDB version
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-cls-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 3
configuration:
secretName: documentdb-custom-config
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-cls-sample
namespace: demo
spec:
version: '5.1.0' # or appropriate KubeDB DocumentDB version
storageType: Durable
deletionPolicy: Delete
replicas: 3
configuration:
secretName: documentdb-custom-config
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/examples/documentdb/configuration/cluster-config-secret.yaml` around
lines 1 - 27, The DocumentDB sample is using a PostgreSQL-style version value in
the DocumentDB manifest, so update the spec.version in the DocumentDB example to
a valid MongoDB/DocumentDB version string instead of the copied pg17-0.109.0
value. Use the DocumentDB sample resource in the cluster-config-secret example
and replace the version with the correct KubeDB-supported DocumentDB version
that matches the rest of the guide.

9 changes: 9 additions & 0 deletions docs/examples/documentdb/configuration/documentdb-custom-config-secret.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
apiVersion: v1
kind: Secret
metadata:
name: documentdb-custom-config
namespace: demo
stringData:
user.conf: |
max_connections=250
work_mem=8MB
Comment on lines +1 to +9

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🔴 Critical | 🏗️ Heavy lift

DocumentDB config Secret contains PostgreSQL settings, not DocumentDB/MongoDB settings.

The user.conf key holds max_connections=250 and work_mem=8MB, which are PostgreSQL parameters. DocumentDB (MongoDB-compatible) uses an entirely different configuration surface (e.g., net.maxIncomingConnections, storage.wiredTiger.engineConfig.cacheSizeGB, operationProfiling.slowOpThresholdMs). Users applying this Secret will have invalid configuration or no effect.

This appears to be a copy-paste carryover from the Postgres guides that was not adapted for DocumentDB.

🛠️ Proposed fix (illustrative DocumentDB parameters) 
stringData:
  user.conf: |
    net.maxIncomingConnections=250
    storage.wiredTiger.engineConfig.cacheSizeGB=0.5
    operationProfiling.slowOpThresholdMs=100
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/examples/documentdb/configuration/documentdb-custom-config-secret.yaml`
around lines 1 - 9, The Secret example in documentdb-custom-config-secret.yaml
is using PostgreSQL-only settings in user.conf, so update the DocumentDB example
to use MongoDB-compatible DocumentDB parameters instead. Replace the current
max_connections and work_mem entries with valid DocumentDB-style options in the
Secret manifest, keeping the change localized to the user.conf block so the
documentdb-custom-config example matches the rest of the DocumentDB guides.

30 changes: 30 additions & 0 deletions docs/examples/documentdb/configuration/standalone-config-inline.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-sa-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 1
configuration:
inline:
user.conf: |
max_connections=300
work_mem=16MB
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
27 changes: 27 additions & 0 deletions docs/examples/documentdb/configuration/standalone-config-secret.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-sa-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 1
configuration:
secretName: documentdb-custom-config
Comment on lines +7 to +12

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🩺 Stability & Availability | 🟠 Major | ⚡ Quick win

Standalone bootstrap issue noted in PR objectives.

The PR objectives explicitly state "standalone (replicas: 1) DocumentDB does not bootstrap on this build." Including this example may mislead users into thinking it works. Consider adding a prominent warning or omitting this example until the operator issue is resolved.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/examples/documentdb/configuration/standalone-config-secret.yaml` around
lines 7 - 12, The standalone DocumentDB example in this config is misleading
because the PR notes that replicas: 1 does not bootstrap on this build. Update
the example to avoid implying it works as-is by either removing the
standalone-config-secret.yaml example or adding a prominent warning in the
example/docs near the configuration block that explicitly states standalone
bootstrap is currently broken. Make sure the guidance is tied to this DocumentDB
standalone configuration example so users don’t treat it as a supported setup.

podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
31 changes: 31 additions & 0 deletions docs/examples/documentdb/configuration/standalone-config-tuning.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-sa-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 1
configuration:
tuning:
profile: oltp # web | oltp | dw | mixed | desktop
storageType: ssd # ssd | hdd | san
maxConnections: 200
disableAutoTune: false
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
11 changes: 11 additions & 0 deletions docs/examples/documentdb/reconfigure/cluster-reconfigure-remove.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: DocumentDBOpsRequest
metadata:
name: documentdb-cls-reconfigure-remove
namespace: demo
spec:
type: Reconfigure
databaseRef:
name: documentdb-cls-sample
configuration:
removeCustomConfig: true
13 changes: 13 additions & 0 deletions docs/examples/documentdb/reconfigure/cluster-reconfigure.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: DocumentDBOpsRequest
metadata:
name: documentdb-cls-reconfigure
namespace: demo
spec:
type: Reconfigure
databaseRef:
name: documentdb-cls-sample
configuration:
applyConfig:
user.conf: |
max_connections=250
13 changes: 13 additions & 0 deletions docs/examples/documentdb/reconfigure/standalone-reconfigure.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: DocumentDBOpsRequest
metadata:
name: documentdb-sa-reconfigure
namespace: demo
spec:
type: Reconfigure
databaseRef:
name: documentdb-sa-sample
configuration:
applyConfig:
user.conf: |
max_connections=250
25 changes: 25 additions & 0 deletions docs/examples/documentdb/restart/cluster-longhorn.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-cls-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 3
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "longhorn"
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
9 changes: 9 additions & 0 deletions docs/examples/documentdb/restart/cluster-restart.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: DocumentDBOpsRequest
metadata:
name: documentdb-cls-restart
namespace: demo
spec:
type: Restart
databaseRef:
name: documentdb-cls-sample
25 changes: 25 additions & 0 deletions docs/examples/documentdb/restart/cluster.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
apiVersion: kubedb.com/v1alpha2
kind: DocumentDB
metadata:
name: documentdb-cls-sample
namespace: demo
spec:
version: 'pg17-0.109.0'
storageType: Durable
deletionPolicy: Delete
replicas: 3
podTemplate:
spec:
containers:
- name: documentdb
resources:
requests:
cpu: 500m
memory: 2Gi
storage:
storageClassName: "local-path"
Comment on lines +10 to +20

@coderabbitai coderabbitai Bot Jun 30, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Don't use local-path for the default multi-replica restart example.

The PR notes that multi-replica DocumentDB clusters on local-path stay Ready=False on this build, so this manifest won't reach the tutorial's prerequisite state. Point the runnable example at the working storage class (cluster-longhorn.yaml) or mark this manifest unsupported for now.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/examples/documentdb/restart/cluster.yaml` around lines 10 - 20, The
multi-replica restart example is using a storage class that leaves DocumentDB
pods stuck not ready, so the manifest is not runnable as written. Update the
cluster restart example to use the working storage configuration referenced by
cluster-longhorn.yaml, or explicitly mark this manifest unsupported until
local-path is fixed. Check the storage section in the cluster YAML and the
restart example naming so the default tutorial path points to a Ready=True
setup.

accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
9 changes: 9 additions & 0 deletions docs/examples/documentdb/restart/standalone-restart.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
apiVersion: ops.kubedb.com/v1alpha1
kind: DocumentDBOpsRequest
metadata:
name: documentdb-sa-restart
namespace: demo
spec:
type: Restart
databaseRef:
name: documentdb-sa-sample
Loading
Loading