Consolidate and document default-value conventions for DocumentDBSpec (images, plugin names, replication GUCs)

[xgerman]

Summary

Follow-up from review of #374. Several review questions about how and where default values are surfaced were left unanswered when the PR was approved. This issue consolidates them so the team can make a consistent, deliberate decision about defaults across the DocumentDBSpec API.

The common theme: some defaults live in the CRD schema (default:), some are applied in code at runtime, and some GUCs are hardcoded. We should decide on a consistent convention and document the rationale.

Open questions

1. Image defaults: only postgres has a CRD default

Raised in this review comment:

So, we have default image only for postgres but not for documentDB and gateway?

In the image stanza, only image.postgres has a CRD-level default: (ghcr.io/cloudnative-pg/postgresql:18-minimal-trixie). image.documentDB and image.gateway have no schema default.

This is likely intentional — the documentDB/gateway images follow the separate database version track and are defaulted in code (internal/utils/constants.go, cnpg-plugins/sidecar-injector/.../config.go) rather than in the CRD schema. The action here is probably to document the rationale (and confirm the two version tracks are the reason), not necessarily to add CRD defaults.

2. Plugin names: fixed defaults not expressed as CRD defaults

Raised in this review comment:

We have a default value for this which will never change in ideal case. Do we want to include it like other default values?

spec.plugins.sidecarInjectorName / spec.plugins.walReplicaName have well-known default names that are applied in code but not declared as CRD default: values. Decide whether to surface these as schema defaults for consistency with image.postgres.

3. Replication GUCs hardcoded to 10

Raised in this review comment:

Should we expose these with default value 10?

In operator/src/internal/cnpg/cnpg_cluster.go (buildPostgresConfiguration), max_replication_slots and max_wal_senders are hardcoded:

params := map[string]string{
    "cron.database_name":    "postgres",
    "max_replication_slots": "10",
    "max_wal_senders":       "10",
}

Decide whether to expose these as user-configurable GUCs with a default of 10.

Note: this overlaps with the PostgreSQL parameter tuning work in #307, which introduces spec.postgresParameters for user-overridable GUCs (with cron.database_name, max_replication_slots, max_wal_senders, max_prepared_transactions listed as protected and non-overridable). Any change here should be reconciled with that design.

Proposed outcome

• Agree on a convention for where defaults live (CRD schema vs in-code fallback) and document it.
• Decide per-field for images (1), plugin names (2), and replication GUCs (3).
• Reconcile (3) with the postgresParameters design from feat: add PostgreSQL parameter tuning with memory-aware defaults #307.
• Update the CRD types / API reference docs to reflect the decision.

References

• PR: feat(api)!: domain-grouped DocumentDBSpec with image/postgres/plugins stanzas + imagePullSecrets #374
• Related PR: feat: add PostgreSQL parameter tuning with memory-aware defaults #307 (PostgreSQL parameter tuning)
• Code: operator/src/internal/cnpg/cnpg_cluster.go — buildPostgresConfiguration; operator/src/api/preview/documentdb_types.go (image, plugins stanzas)

[documentdb-triage-tool]

🤖 Auto-triaged by documentdb-triage-tool.

Applied: go
Project fields suggested: Component api · Priority P3 · Effort M · Status In Progress
Confidence: 0.82 (llm)

Reasoning

LLM: Follow-up housekeeping issue to standardize default-value conventions across DocumentDBSpec (CRD schema defaults vs. code defaults), touching API types, CRD manifests, and internal constants — no functional regression, purely polish/consistency.

If a label is wrong, remove it manually and ping @patty-chow so the rules can be tuned. The bot will not re-label items that already have component labels.