fix(DOC-1958): add lifecycle ignore_changes guidance and prose cleanup

[mfernest]

Summary

Terraform throughput tier ignore:

• Documents the lifecycle { ignore_changes = [throughput_tier] } pattern as a complement to allow_deletion = false, protecting clusters from accidental replacement when Redpanda Support upgrades a throughput tier
• Rewrites opening sentence to remove weak verbs
• Cuts throat-clearing prose throughout (~234 net word reduction)
• Fixes passive voice, future tense, e.g./etc., and Title Case violations
• Tightens callout <1> from 9 sentences to 3
• Replaces "your-secret-password" placeholder with "schema-registry-password"

Resolves DOC-1958.

Preview pages

• Redpanda Terraform Provider (updated)

Test plan

• Build passes locally
• Limitations section renders correctly with new lifecycle code block
• Deploy preview renders correctly

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for rp-cloud ready!

Name	Link
🔨 Latest commit	ab478ee
🔍 Latest deploy log	https://app.netlify.com/projects/rp-cloud/deploys/6a108080912f350008aab7f1
😎 Deploy Preview	https://deploy-preview-533--rp-cloud.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ae5e4350-b8e3-4a8d-9916-54191f219653

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This pull request updates the Terraform provider documentation file with refined phrasing, improved capitalization consistency, and clarified technical content. Changes include replacing placeholder credentials with more generic equivalents, expanding the throughput_tier warning with a Terraform lifecycle workaround example, refining installation instructions, and reworded descriptions for various examples and Terraform concepts.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• docs: add notice about the terraform provider #382: Updates Windows/WSL guidance for running the Terraform provider in the same documentation file.
• DOC-323 GA Terraform provider #233: Modifies provider version guidance and refines BYOC/BYOVPC limitations and related Terraform examples in the same documentation file.

Suggested reviewers

• micheleRP
• david-yu
• paulohtb6

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main changes: documenting a Terraform lifecycle pattern and performing prose cleanup, aligning with the primary objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	The PR description includes all required template sections: issue reference (DOC-1958), page preview link, and applicable checkboxes marked.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/doc-1958-terraform-ignore-changes

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@modules/manage/pages/terraform-provider.adoc`:
- Line 660: Update the NOTE that currently reads "Terraform deletes a cluster
that depends on a network after it deletes the network" to correctly state
deletion order for dependent resources: the dependent resource (cluster) is
destroyed first, then its dependency (network). Locate the note text string
"NOTE: Terraform deletes dependent resources in the correct order. For example,
Terraform removes a cluster that depends on a network after it deletes the
network." and rephrase it so the example reads that Terraform removes the
cluster first and then the network.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: e2a15053-62d3-4632-a437-bf3a32c50aa7

📥 Commits

Reviewing files that changed from the base of the PR and between d122be8 and cc47d06.

📒 Files selected for processing (1)

• modules/manage/pages/terraform-provider.adoc

[Feediver1]

@mfernest Please add the SME reviewer!

[Feediver1]

PR Review: fix(DOC-1958): add lifecycle ignore_changes guidance and prose cleanup (#533)

Files reviewed: 1 .adoc file (44 additions / 30 deletions in the original PR; +1 follow-up commit for review feedback)
Overall assessment: Addresses DOC-1958 exactly as the ticket asks, plus delivers solid prose cleanup. Both review findings have been addressed in commit b5906ec.

What this PR does

Adds a new WARNING block in modules/manage/pages/terraform-provider.adoc documenting the lifecycle { ignore_changes = [throughput_tier] } Terraform pattern as a complement to allow_deletion = false, protecting BYOC/Dedicated clusters from accidental replacement when Redpanda Support upgrades a cluster's throughput tier. The same PR does a broader prose cleanup of the file: future-tense fixes, e.g./etc. removal, weak-verb rewrites, callout tightening, more semantic placeholders.

Jira ticket alignment

Ticket: DOC-1958 — Document the complementary lifecycle { ignore_changes = [throughput_tier] } pattern for preventing cluster replacement on Redpanda Support tier upgrades.

Status: ✅ Satisfies the ticket completely. The lifecycle block in the PR matches the snippet in the ticket; the Redpanda-Support-upgrade scenario is called out explicitly with the consequence ("the next terraform apply triggers replacement").

Critical issues — resolved

1. [terraform-provider.adoc:757] Dependency-deletion-order NOTE was backwards. CodeRabbit flagged this on 2026-03-19. The original prose had the bug; the PR's rewrite preserved it. Fixed in commit b5906ec: after → before ("Terraform removes a cluster that depends on a network before it deletes the network"). Terraform destroys the dependent resource (cluster) first, then the dependency (network).

Suggestions — resolved

1. [terraform-provider.adoc:113] [source,terraform] was the only block in this file using that language tag. Every other code block in the file uses [source,hcl]. Fixed in commit b5906ec: changed to [source,hcl] for consistency.

2. PR description references "Title Case violations" (plural). Audited every H2+ heading on the page; all are now sentence-case (or correctly preserve proper nouns like "Schema Registry"). No further title-case fixes needed.

Impact on other files

• No new pages added → no nav.adoc / index page / What's New updates needed.
• Cross-references unchanged → no broken xrefs.
• The terraform-provider.adoc is cloud-only (not single-sourced from redpanda-data/docs) → no cross-repo concerns.

CodeRabbit findings worth considering

1. [terraform-provider.adoc:757] Deletion-order NOTE — resolved in commit b5906ec. CodeRabbit's only actionable comment, and it was a correct catch.

What works well

• Hits the DOC-1958 spec exactly. The lifecycle code block, the complementary framing, and the Redpanda-Support-upgrade narrative all match the ticket description.
• Significant prose tightening (~234-word reduction) without losing information. Callout <1> going from 9 sentences to 3 is a real readability win; the new version preserves the technical content ("Terraform internal name vs. Cloud-facing name") in fewer words.
• Style-guide-compliant fixes throughout: future-tense → present, e.g., → such as, etc. → and others, passive → active where possible, weak-verb removal in the opening sentence, Version Control → Version control.
• More semantic placeholder: "your-secret-password" → "schema-registry-password" (matches the variable name in the surrounding example).
• Tightens the prerequisites list ("Install at least version 1.0.0" → "Install Terraform 1.0.0 or later") and the Windows-support note.
• Drops a vestigial introductory sentence before "Set up the provider" without losing user-relevant information.
• PR description is exemplary — explicit scope, links to the ticket, includes a test plan with checked items, distinguishes the DOC-1958 fix from the bonus cleanup.

---

Final-pass review via /docs-team-standards:pr-review. Critical fix and the source-block-tag suggestion applied in commit b5906ec (pushed to this branch).

[Feediver1]

Additional review feedback applied (commit ab478ee)

A follow-up review pass found three items my earlier docs-team-standards:pr-review missed. All three are real and have been addressed on the branch in commit ab478ee:

1. "Manage an existing cluster" — restored the cluster_api_url explanation

The rewrite had dropped the sentence explaining the cluster_api_url attribute on the data source, which is the actual mechanism the code block below depends on. Without it, readers had to reverse-engineer the data-resource role from the HCL.

Restored sentence:

The data source exposes a cluster_api_url attribute that other resources (such as redpanda_topic) reference to connect to the cluster.

2. "Create a schema" and "Manage Schema Registry ACLs" — restored explicit resource-name mentions

Section intros are where readers scan for "what resource do I use to do X?". The rewrite removed those anchors:

• "Create a schema" no longer named redpanda_schema.
• "Manage Schema Registry ACLs" no longer named redpanda_schema_registry_acl.

Restored as opening sentences in both subsections, so the resource name lands before the reader hits the HCL block.

3. Limitations WARNING — allows → causes

If allow_deletion is set to true, modifying throughput_tier allows causes Terraform to destroy and replace the existing cluster, causing data loss.

"Allows Terraform to destroy" reads conditional/optional, which softens the actual semantics: the next terraform apply will trigger replacement unconditionally. The two follow-up bullets ("Set allow_deletion to false" / "Add a lifecycle block") are the conditional part — they need a stark consequence above them to motivate them. "Causes Terraform to destroy and replace" gives the WARNING the right urgency.

Why I missed these

My earlier review checked the PR for DOC-1958 alignment, style-guide compliance, bugs (the deletion-order NOTE), cross-page consistency, and build impact. What it didn't do is audit the diff for information loss — specifically, what the old prose carried that the new prose dropped. For a PR whose explicit value is "~234 net word reduction," that audit is the central thing to do, and I skipped it. The teammate's pass filled that gap. I've saved a memory rule for myself so future prose-cleanup PR reviews include both an information-loss audit and a warning-tone scrutiny pass.