Add DatadogPodAutoscaler manifest reference

[clamoriniere]

What does this PR do? What is the motivation?

Adds a new sub-page, DatadogPodAutoscaler manifest reference, documenting DatadogPodAutoscaler (DPA) configuration options that are only available by editing the manifest and were not previously covered in the docs. It also makes targeted updates to the Kubernetes Autoscaling overview so the two pages stay consistent and correct.

Changes

New page containers/autoscaling/manifest.md:

• Manifest anatomy (annotated skeleton with per-field required/optional markers), supported target workloads, and how to choose a scaling mode.
• Container constraints: controlledResources (CPU and memory rightsizing, with the memory-only default when combined with horizontal scaling), controlledValues (RequestsAndLimits / RequestsOnly), minAllowed / maxAllowed, enabled, and "*" wildcard non-merge semantics.
• Burstable mode (options.burstable), OOMKill bump tuning (options.outOfMemory.bumpUpRatio), sidecars (including native sidecars), vertical rollout timing (resizePendingPeriod / rolloutFallbackDelay), and ContainerResource / AbsoluteValue / CustomQuery (including ApmMetrics) objectives, plus telemetry tagging.
• Links back to the overview instead of duplicating setup and prerequisite content.

Updates to containers/autoscaling/_index.md:

• Corrected the in-place vertical scaling enablement field to inPlaceVerticalScaling (Operator and Helm) and added a dedicated In-place vertical scaling section.
• Documented that in-place vertical scaling is supported on Kubernetes 1.33+, and that in-place resizes are not observed by applications that read resources only at startup or via the downward API.
• Added a note that vertical recommendations reach new pods through the Admission Controller mutating webhook.
• Clarified that the OOMKill memory bump is re-applied until the workload stabilizes and is configurable.
• Added pointers from Path B (GitOps) and the example-configurations section to the new manifest reference.

Navigation:

• Added a Manifest reference entry to the English left navigation under Autoscaling.

Review feedback addressed:

• Human reviewers: removed feature-status labels (all content is GA), marked each skeleton field required/optional, clarified that objectives also feeds multidimensional scaling, emphasized that autoscaled containers must not be excluded from Agent collection (with a link to Container Discovery Management), corrected the scale-down comment, marked custom-query-with-vertical-scaling as not supported, documented in-place support at Kubernetes 1.33+ with the startup/downward-API caveat, and clarified that an OOMKill raises the memory limit and potentially the request.
• Automated /review suggestions: promoted the remaining inline external URLs in the in-place section to reference-style links, renumbered the manifest reference list sequentially, reconciled the vertical-only instruction with the "Choose a scaling mode" table, broke the dense Kubernetes-limitations sentence into a nested bullet list, made the API-version sentence clearer, capitalized the Note sentence, and made hyphenation of rightsizing consistent.

Testing / validation

• Verified Hugo shortcode balance (tabs/tab) and fenced code blocks in both changed pages.
• Verified that all internal anchor links resolve to real headings, and that reference definitions and usages match.
• Confirmed no em dashes or en dashes remain in the changed files.
• Reviewed the changed content against the Datadog Vale substitution list (American English, no flagged terms). Vale is not installed in this environment, so this was a manual review of the diff.

Merge readiness

• Ready for merge

For Datadog employees:

• ⚠️ Your branch name MUST follow the <name>/<description> convention and include the forward slash (/). If you've already created your PR with an incorrect branch name, please rename your branch and open a fresh PR.
• 🤖 New: Comment with /review to run an automated check that catches common issues before a Documentation team member reviews your PR.

AI assistance

Drafted with Bits Code (Claude Code): converted a source reference document into the new page, applied Datadog documentation style, made the consistency edits to the overview, and addressed reviewer feedback (human and automated). Reviewed by the author.

Additional notes

No Jira ticket is associated with this change. StatefulSet is documented as a fully supported target workload per maintainer guidance. The ArgoCD and Terraform guides were intentionally left unchanged.

---

PR by Bits - View session in Datadog

Comment @DataDog to request changes

[datadog-prod-us1-6]

View session in Datadog

Bits Code status: ✅ Done

CI Auto-fix: Failed (reached max 5 attempts) | Disable

Comment @DataDog to request changes

[datadog-official]

I can only run on private repositories.

[github-actions]

Preview links (active after the build_preview check completes)

New or renamed files

• https://docs-staging.datadoghq.com/dd/cedric.lamoriniere/dpa-manifest-reference/containers/autoscaling/manifest

Modified Files

• https://docs-staging.datadoghq.com/dd/cedric.lamoriniere/dpa-manifest-reference/containers/autoscaling/

[clamoriniere]

few requires change needed for the content

[domalessi]

Created DOCS-15498 for editorial review.

[domalessi]

/review

[github-actions]

🤖 Automated review by Claude. AI-generated; verify before acting.

Overall this is a well-structured, high-quality PR that adds a much-needed manifest reference and cleanly refactors the in-place vertical scaling coverage in _index.md. A few minor style-level nits below.

_{Reviewed c93aa6618ac75bd78b94fa8e2737a60fd1bf3daa — workflow run}

[github-actions]

Style: The reference-link numbering skips [4], [5], and [6] (goes 1, 2, 3, 7, 8, 9, 10). Looks like it was copied from _index.md. Renumber sequentially so the definitions match the in-text references:

Suggested change

	[10]: /containers/guide/container-discovery-management/
	[1]: https://app.datadoghq.com/orchestration/scaling/workload
	[2]: /containers/autoscaling/
	[3]: /containers/autoscaling/#in-place-vertical-scaling
	[4]: https://kubernetes.io/docs/concepts/workloads/pods/sidecar-containers/
	[5]: /integrations/datadog-cluster-agent/#metrics
	[6]: /help/
	[7]: /containers/guide/container-discovery-management/

(You'll also need to update the in-text references [7], [8], [9], [10] accordingly.)

[AlexanderYastrebov]

I think users will benefit if we also add these details to the DPA CRD such that they are discoverable by agents via kubectl explain.

[clamoriniere]

hi @AlexanderYastrebov

I think users will benefit if we also add these details to the DPA CRD such that they are discoverable by agents via kubectl explain.

it is a good idea, I will open a follow-up PR on datadog-operator repo to add more comment on the CRD definition https://github.com/DataDog/datadog-operator/blob/main/api/datadoghq/v1alpha1/datadogpodautoscaler_types.go

[clamoriniere]

/review

[github-actions]

🤖 Automated review by Claude. AI-generated; verify before acting.

Nice restructuring: hoisting in-place vertical scaling into its own top-level section and pulling manifest details into a dedicated reference page reads well. A few small nits on hyphenation consistency and one clarity question on the OOMKill + RequestsOnly interaction.

_{Reviewed 0ed0e06c5c0816aaf5ee3d4c400d0a0bcde1c4ca — workflow run}