Add warning to CSI Driver docs on upgrading to Datadog Operator 1.28.0

[mrdoggopat]

What does this PR do? What is the motivation?

This PR is in motivation to document a workaround for users upgrading the Datadog Operator to 1.28.0+ if they run into reconciliation issues with the DatadogCSIDriver.

Merge readiness

• Ready for merge

AI assistance

Checked grammar and placement with Claude.

[github-actions]

Preview links (active after the build_preview check completes)

Modified Files

• https://docs-staging.datadoghq.com/patrickliang/add-warning-on-upgrading-datadog-operator-1.28/containers/kubernetes/csi_driver

[mrdoggopat]

/review

[github-actions]

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

One small addition — a warning block for a version-specific upgrade issue. A few style/clarity nits inline; no blockers.

_{Reviewed 528d2cc6b5a242349609571d46fc3af3e4066cb8 — workflow run}

[github-actions]

Issue: "If previously running" is a dangling modifier (no subject). Also, "Remediate by deleting the object once" is awkward — the "once" is ambiguous (one time? or the style-guide-flagged "after"?). Rephrase for clarity and to match the direct/imperative voice used elsewhere on this page.

Suggested change

	<p>If previously running <code>v1.26.0</code> or <code>v1.27.0</code>, upgrading to Datadog Operator <code>v1.28.0</code> or later can leave the existing <code>k8s.csi.datadoghq.com</code> CSIDriver object in a state that the Operator cannot reconcile. Remediate by deleting the object once:</p>
	<p>If you previously ran <code>v1.26.0</code> or <code>v1.27.0</code>, upgrading to Datadog Operator <code>v1.28.0</code> or later can leave the existing <code>k8s.csi.datadoghq.com</code> CSIDriver object in a state that the Operator cannot reconcile. To resolve, delete the object:</p>

[buraizu]

Thanks for the PR, I've left a couple of suggestions.

Additionally, the new warning div sits directly alongside an existing warning div (screenshot):

This creates a visually jarring experience, and users might miss important information. One potential resolution would be to add a sub-heading before the new warning div, possible something like:
#### Upgrade and migration notes.

Let me know if that works. If not, it may be more expedient to create a card on the DOCS board to have someone from the team investigate the best presentation for this information.

Also feel free to let me know if you have any questions.

[mrdoggopat]

Thanks for the PR, I've left a couple of suggestions.

Additionally, the new warning div sits directly alongside an existing warning div (screenshot):

This creates a visually jarring experience, and users might miss important information. One potential resolution would be to add a sub-heading before the new warning div, possible something like: #### Upgrade and migration notes.

Let me know if that works. If not, it may be more expedient to create a card on the DOCS board to have someone from the team investigate the best presentation for this information.

Also feel free to let me know if you have any questions.

Hey @buraizu
Thanks for the feedback!
I've made a commit to add a sub-heading, let me know if that works or need me to adjust anything else!

[buraizu]

Thanks for applying that feedback @mrdoggopat. Taking another look, I think there's a bit of additional room for improvement for both human readers and AI retrieval alike. Here's the rationale:

1. The two blocks aren't the same severity. The upgrade block is a genuine caution — if you don't act, the Operator can't reconcile — so it should stay as a warning callout. The Helm migration block is guidance, not danger (one of its paths is literally "No action is required"), so styling it as a red warning overstates it. That mismatch is the real source of the visual friction: two identical red blocks where only one is actually a warning.

   As such, I'm suggesting to give each topic its own #### heading, keep the upgrade known-issue as the single warning callout, and present the Helm migration as plain prose with a bulleted list. That leaves one red block instead of two, and the prose treatment matches how the rest of the page handles substantial procedural content.

2. Because each block now has its own heading, both sections get anchor links. You can point users (or other docs) directly to the upgrade workaround or the Helm migration steps, which isn't possible while they're anonymous divs.

I built this locally to check the rendering, and attached a screenshot below, along with the updated markdown content.

Since I'm not able to make a suggestion on the "Migrating from Helm-based CSI Driver installation" div, you'll have to change that as well in your feature branch if you decide to apply this update. If you'd prefer, I can also make this commit directly to your branch — just let me know how you'd like to proceed.

Thanks again for following up, and let me know if you have any questions!

[mrdoggopat]

Thanks for applying that feedback @mrdoggopat. Taking another look, I think there's a bit of additional room for improvement for both human readers and AI retrieval alike. Here's the rationale:

1. The two blocks aren't the same severity. The upgrade block is a genuine caution — if you don't act, the Operator can't reconcile — so it should stay as a warning callout. The Helm migration block is guidance, not danger (one of its paths is literally "No action is required"), so styling it as a red warning overstates it. That mismatch is the real source of the visual friction: two identical red blocks where only one is actually a warning.
   As such, I'm suggesting to give each topic its own #### heading, keep the upgrade known-issue as the single warning callout, and present the Helm migration as plain prose with a bulleted list. That leaves one red block instead of two, and the prose treatment matches how the rest of the page handles substantial procedural content.
2. Because each block now has its own heading, both sections get anchor links. You can point users (or other docs) directly to the upgrade workaround or the Helm migration steps, which isn't possible while they're anonymous divs.

I built this locally to check the rendering, and attached a screenshot below, along with the updated markdown content.

Since I'm not able to make a suggestion on the "Migrating from Helm-based CSI Driver installation" div, you'll have to change that as well in your feature branch if you decide to apply this update. If you'd prefer, I can also make this commit directly to your branch — just let me know how you'd like to proceed.

Thanks again for following up, and let me know if you have any questions!

I think that's fine! As my change is more of a warning anyway.