feat: add IOUring opt-in feature gate for PostgreSQL async I/O

[xgerman]

What

Adds an IOUring opt-in feature gate so customers can enable PostgreSQL 18
io_method = io_uring asynchronous I/O on a DocumentDB cluster with a single
flag — disabled by default for security.

apiVersion: db.microsoft.com/preview
kind: DocumentDB
spec:
  featureGates:
    IOUring: true

When the gate is enabled the operator does both things io_uring requires,
natively — no external Kyverno policy needed:

1. Sets io_method=io_uring as a protected PG parameter (mirrors the
   existing ChangeStreams → wal_level pattern in ProtectedParameters).
2. Relaxes the postgres container seccomp profile through CNPG's native
   Cluster.Spec.SeccompProfile. The runtime's RuntimeDefault profile strips
   io_uring_setup/enter/register, which otherwise causes
   FATAL: could not setup io_uring queue: Operation not permitted at startup.

Why

This is the productized outcome of the io_uring benchmark spike (previously
PR #406, now closed). Instead of requiring a Kyverno policy to relax seccomp,
the operator handles it natively behind an opt-in gate.

Seccomp configuration (operator-level)

Seccomp behavior is a cluster-wide node decision, so it is operator-level
config exposed as Helm values (not per-DocumentDB):

Helm value	Default	Effect
operator.ioUring.seccompMode	"" → localhost	localhost (hardened curated profile) or unconfined
operator.ioUring.seccompProfile	"" → profiles/documentdb-iouring.json	Localhost profile path

Wired through DOCUMENTDB_IOURING_SECCOMP_MODE /
DOCUMENTDB_IOURING_SECCOMP_PROFILE env vars.

Note: The kernel must also have io_uring_disabled=0 on the nodes.

What's included

• Feature gate: IOUring constant, CEL allowlist entry, and default in
  featureGateDefaults (the documented 3-step add-a-gate procedure).
• Operator behavior: io_method protected param + applyIOUringSeccomp
  helper (single clean helper, no duplication).
• Helm: first-class operator.ioUring.* values + template env vars +
  helm-unittest coverage.
• Playground: documentdb-playground/io-uring-feature/ — modeled on the
  upstream cnpg-playground seccomp approach (kind extraMount + a DaemonSet
  installer for real clusters). No Kyverno required.
• Docs: docs/operator-public-documentation/io-uring.md + mkdocs nav.
• Tests: gate default/true/false, io_method presence, and the seccomp
  nil/Localhost-default/Localhost-custom/Unconfined branches.

Validation

• gofmt clean · go build ./... · go vet ./... · go test ./internal/cnpg/... ./api/preview/... pass
• helm unittest . — 85/85 pass
• make manifests generate produces no drift; CRDs in sync (config + helm)

Notes

• No new CRD struct fields (map-based gate), so zz_generated.deepcopy.go is
  unchanged — correct.
• The seccomp profile JSON is intentionally vendored into the playground so it
  is self-contained/standalone.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Adds an opt-in IOUring feature gate to the DocumentDB operator so a DocumentDB cluster can enable PostgreSQL 18 async I/O (io_method=io_uring) while the operator also applies the required seccomp relaxation via CNPG’s Cluster.Spec.SeccompProfile. This fits the operator’s existing “feature gates drive protected Postgres parameters” approach (e.g., ChangeStreams → wal_level) and productizes the previous benchmark spike by removing the need for external Kyverno mutation.

Changes:

• Introduces IOUring as a supported feature gate (API constant, default map entry, and CRD/CEL allowlist updates).
• Operator now (a) enforces io_method=io_uring as a protected PG parameter and (b) applies a seccomp profile override when the gate is enabled (Localhost profile by default; optionally Unconfined).
• Adds Helm values + templates + helm-unittest coverage for operator-level seccomp configuration, plus docs and a self-contained playground demonstrating node profile installation.

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
operator/src/internal/utils/constants.go	Adds env var constants and default profile path for IOUring seccomp configuration.
operator/src/internal/cnpg/pg_defaults.go	Forces io_method=io_uring as a protected parameter when the IOUring gate is enabled.
operator/src/internal/cnpg/pg_defaults_test.go	Tests IOUring-protected parameter behavior.
operator/src/internal/cnpg/cnpg_cluster.go	Applies operator-configured seccomp profile to CNPG ClusterSpec when IOUring is enabled.
operator/src/internal/cnpg/cnpg_cluster_test.go	Covers IOUring seccomp nil/default/custom/unconfined branches and ensures io_method presence.
operator/src/config/crd/bases/documentdb.io_dbs.yaml	Updates CRD validation allowlist to permit IOUring in spec.featureGates.
operator/src/api/preview/documentdb_types.go	Adds FeatureGateIOUring constant and updates XValidation allowlist annotation.
operator/src/api/preview/documentdb_funcs.go	Adds IOUring default value entry to featureGateDefaults.
operator/src/api/preview/documentdb_funcs_test.go	Adds IOUring default/explicit true/explicit false tests.
operator/documentdb-helm-chart/values.yaml	Adds operator.ioUring.{seccompMode,seccompProfile} Helm values and documentation.
operator/documentdb-helm-chart/tests/09_operator_deployment_test.yaml	Helm unit tests for IOUring env var templating (set/omit behaviors).
operator/documentdb-helm-chart/templates/09_documentdb_operator.yaml	Templates DOCUMENTDB_IOURING_SECCOMP_MODE/PROFILE env vars into operator deployment when configured.
operator/documentdb-helm-chart/crds/documentdb.io_dbs.yaml	Keeps Helm-packaged CRD in sync with IOUring feature gate allowlist.
mkdocs.yml	Adds documentation nav entry for the io_uring feature gate page.
documentdb-playground/io-uring-feature/seccomp/kustomization.yaml	Adds kustomize bundle to install IOUring Localhost seccomp profile via ConfigMap + DaemonSet.
documentdb-playground/io-uring-feature/seccomp/documentdb-iouring.json	Adds curated seccomp profile JSON (RuntimeDefault + io_uring syscalls) for Localhost mode.
documentdb-playground/io-uring-feature/seccomp/deploy-seccomp-daemonset.yaml	Adds node installer DaemonSet that writes the profile into /var/lib/kubelet/seccomp.
documentdb-playground/io-uring-feature/README.md	Adds end-to-end playground guide for enabling IOUring and validating io_uring + seccomp.
documentdb-playground/io-uring-feature/operator-values/unconfined-patch.yaml	Adds patch snippet to configure operator for Unconfined mode on existing installs.
documentdb-playground/io-uring-feature/operator-values/localhost-patch.yaml	Adds patch snippet to configure operator for Localhost mode/profile on existing installs.
documentdb-playground/io-uring-feature/manifests/documentdb-iouring.yaml	Adds demo namespace/secret/DocumentDB manifest enabling featureGates.IOUring: true.
documentdb-playground/io-uring-feature/kind/kind-cluster.yaml	Adds kind config to mount the Localhost seccomp profile into kind nodes.
docs/operator-public-documentation/io-uring.md	Adds user-facing documentation for IOUring gate, prerequisites, operator config, verification, and troubleshooting.
CHANGELOG.md	Records the new IOUring feature gate and the new playground in release notes.

[documentdb-triage-tool]

🤖 Auto-triaged by documentdb-triage-tool.

Applied: ecosystem, go, documentation, test, enhancement
Project fields suggested: Component playground · Priority P2 · Effort XL · Status Needs Review
Confidence: 0.85 (mixed)

Reasoning

component from path globs (playground, controllers, docs, api, test, manifests); effort from diff stats (1617+5 LOC, 24 files); LLM: Multi-component feature gate implementation (operator logic, Helm values, docs, playground, tests) adding opt-in PostgreSQL 18 io_uring async I/O support with seccomp profile handling.

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.