DOC-2285: Warn against GCP node pool tags, document Dataplane settings UI method

[micheleRP]

Resolves https://redpandadata.atlassian.net/browse/DOC-2285

What changed

Following INC-2875 (customer added labels to GCP BYOC node pools with gcloud container node-pools update, GKE aggressively replaced all nodes, PVCs went pending, and a whole cluster recovery was required), this PR updates the "Manage custom resource labels and network tags" section for GCP BYOC:

• Adds a prominent CAUTION callout: never add labels or network tags directly to GCP node pools. GKE treats this as a node replacement and bypasses the controlled failover Redpanda requires.
• Documents the supported UI method (cluster > Dataplane settings page), including the 10-entry UI limit, case sensitivity, and the gcp.network-tag.<tag> key convention.
• Keeps the existing Control Plane API method under its own heading (16-entry limit), and standardizes naming to "Control Plane API".
• Updates the cluster-creation step in create-byoc-cluster-gcp.adoc to point to both methods.
• Removes the custom tags feature-flag note ("contact Support to unlock") from the GCP, AWS, and Azure partials, per cloudv2#27589, which removed the enable-custom-cloud-tags flags across the codebase.

The GCP section content lives in the shared partial custom-tags-gcp.adoc, so both create-byoc-cluster-gcp and vpc-byo-gcp pages get the update. The feature-flag removal also touches the pages that include the AWS and Azure partials.

Verification

• Safe-method mechanics confirmed against cloudv2 pkg/tags/gcp.go: Redpanda applies labels directly to GCE instances and disks, and network tags to instances, never to node pools.
• UI behavior (10-entry limit, network tag convention) verified on a live BYOC cluster.
• Local Antora build passes; all five including pages render correctly with proper list nesting.

Reviewer feedback resolved

• Feature-flag scope (was an open question): the enable-custom-cloud-tags flags were removed in cloudv2#27589, landing in production the week of July 13. Hold merge until that rollout completes so the docs do not drop the unlock note early.
• The UI copy claiming tags "cannot be edited later" is stale; Paul Zhang confirmed customers can update custom tags. The docs intentionally do not repeat that claim.
• CodeRabbit naming and accuracy findings addressed (network tags apply to instances only; "Control Plane API" naming).

Note: A screenshot of the Dataplane settings page was intentionally omitted; docs team screenshot standards are not finalized yet (see DOC-2285 ticket for the incident-thread screenshot).

Preview pages

• Create a BYOC Cluster on GCP (updated)
• Create a BYOVPC Cluster on GCP (updated via shared partial)
• Create a BYOC Cluster on AWS (feature-flag note removed)
• Create a BYOC Cluster on Azure (feature-flag note removed)
• Create a BYOVNet Cluster on Azure (feature-flag note removed)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for rp-cloud ready!

Name	Link
🔨 Latest commit	9a84571
🔍 Latest deploy log	https://app.netlify.com/projects/rp-cloud/deploys/6a4d5897c622ad00087bd38a
😎 Deploy Preview	https://deploy-preview-632--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]

📝 Walkthrough

Walkthrough

This PR updates GCP BYOC documentation describing custom resource labels and network tags. The advanced settings note in the cluster creation guide is reworded to clarify gcp.network-tag.<tag> behavior and post-creation options. The custom-tags-gcp partial is restructured to describe two management workflows—the Dataplane settings UI and the Control Plane API—each with distinct entry-count limits and prerequisites, and adds a caution against modifying node pools directly.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• redpanda-data/cloud-docs#624: Related BYOC centralized-egress documentation relies on the same GCP network-tag labeling behavior clarified in this PR.

Suggested reviewers: matteogaraventa

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly matches the main change: warning about GCP node pool tags and documenting the Dataplane settings UI method.
Description check	✅ Passed	It includes the issue reference, change summary, verification, and preview links; only the review deadline and checklist section are missing.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-2285-gcp-node-pool-tags-warning

---

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

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

modules/get-started/partials/custom-tags-gcp.adoc (1)

52-52: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use the Control Plane API term consistently.

"Cloud API" reads like leftover terminology here; the rest of this section uses "Control Plane API". Renaming this sentence will keep the workflow naming consistent.

♻️ Proposed fix

- To update labels and network tags, invoke the Cloud API.
+ To update labels and network tags, invoke the Control Plane API.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@modules/get-started/partials/custom-tags-gcp.adoc` at line 52, The
terminology in this sentence is inconsistent with the rest of the section:
replace “Cloud API” with “Control Plane API” in the custom-tags-gcp content.
Update the wording in the relevant sentence so the workflow description matches
the surrounding references and keeps naming consistent.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@modules/get-started/partials/custom-tags-gcp.adoc`:
- Line 7: Clarify the GCP resource targeting in this sentence so labels and
network tags are not grouped together incorrectly. In the custom-tags-gcp.adoc
text, update the wording to state that labels are applied to both GCE instances
and disks, while network tags are applied only to GCE instances, keeping the
distinction consistent with the rest of the PR and the Dataplane settings page /
Control Plane API behavior.

---

Outside diff comments:
In `@modules/get-started/partials/custom-tags-gcp.adoc`:
- Line 52: The terminology in this sentence is inconsistent with the rest of the
section: replace “Cloud API” with “Control Plane API” in the custom-tags-gcp
content. Update the wording in the relevant sentence so the workflow description
matches the surrounding references and keeps naming consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 143dc145-af6d-4664-b594-1b063dff0a96

📥 Commits

Reviewing files that changed from the base of the PR and between 9896712 and 29827a0.

⛔ Files ignored due to path filters (1)

• modules/shared/images/dataplane-settings-tags-gcp.png is excluded by !**/*.png

📒 Files selected for processing (2)

• modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
• modules/get-started/partials/custom-tags-gcp.adoc

[paulzhang97]

The feature-flag note ("contact Support to unlock") now sits above both methods. Confirm whether the flag gates the Dataplane settings UI as well as the API, or the API only.

The feature flags on custom tags were just removed by PR. The changes will land on Production the next week.

The UI copy says entries "cannot be edited later", which contradicts the documented API PATCH behavior. This claim is intentionally not repeated in the docs pending confirmation.

Customers can update custom tags.

[micheleRP]

Thanks @paulzhang97. Applied in 9a84571: removed the feature-flag note from the GCP partial, and since cloudv2#27589 removes the flags codebase-wide, also removed it from the AWS and Azure custom tags partials. We'll hold the merge until the rollout lands in production next week so the unlock note doesn't disappear early. Also confirmed the docs don't repeat the UI's "cannot be edited later" wording, since tags are updatable.

[Feediver1]

lgtm

[Feediver1]

Final-pass review (docs-team-standards)

Overall: Accurate, well-verified incident-response doc with a strong warning callout. No content defects found — the one open item is ticket-scope: the DOC-2285 acceptance criteria require a screenshot that was deliberately removed mid-PR.

Jira ticket alignment

DOC-2285 (Bug, customer-escalation, INC-2875): prominent warning ✅ and safe-method steps ✅ fully meet two of three acceptance criteria. Gap: the AC explicitly requires a screenshot of the Dataplane Settings UI, which a66fa8b removed "pending screenshot standards." Defensible deferral, but the ticket can't close as-written — either restore the screenshot or annotate the ticket with the deferral decision and a follow-up.

Verification performed

• Both GCP consumer pages checked (create-byoc-cluster-gcp.adoc:62, vpc-byo-gcp.adoc:745): the partial is included under a == heading in each, so the new === subsections nest correctly in both, and the <<use-the-control-plane-api>> / <<manage-custom-resource-labels-and-network-tags>> anchors resolve. All 5 consumer pages across the three partials accounted for.
• Information-loss audit of the flag-note removal: the removed IMPORTANT block only said "contact Support to unlock"; API prerequisites, the 16-entry limit, and all steps are preserved. Removal justified by cloudv2#27589.
• CodeRabbit findings: both already addressed and verified in the final text (labels vs. network tags resource targets in b244caf; "Cloud API" → "Control Plane API" in 9a84571).

Suggestions

1. [custom-tags-aws.adoc:7, custom-tags-azure.adoc:7] Naming standardization stopped at GCP — both partials (already touched in this PR) still say "Cloud Control Plane API" in the bearer-token bullet. Apply the same trim while they're in the diff.
2. [modules/shared/partials/feature-flag.adoc] Orphaned after this PR removes its last three includes (verified by grep — zero references remain). Consider deleting it here, or noting the orphan for a follow-up, so a "contact Support to unlock" note for a removed flag can't be accidentally reused.

What works well

• Warning tone is exactly right for a sev-2 postmortem doc: direct imperatives, causal verbs ("bypasses the failover process"), concrete consequences — no softeners.
• Claims verified at the source (cloudv2 pkg/tags/gcp.go) and on a live cluster, and the final labels/tags targeting text matches that verification.
• Clear UI-vs-API split with cross-referenced limits (10 UI / 16 API).

🤖 Automated final-pass review via docs-team-standards pr-review.