DOC-1538 BYOC customer tags after cluster creation #400
Conversation
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughAdds a new "Manage custom resource tags" section to BYOC create docs for AWS, Azure, and GCP. Documents post-creation tag/label management via the Cloud Control Plane API (PATCH /clusters/{id} with Sequence Diagram(s)sequenceDiagram
autonumber
actor User
participant CLI as rpk CLI (optional)
participant CCP as Cloud Control Plane API
participant Agent as BYOC Agent
participant CSP as Cloud Provider APIs
rect rgb(235,245,255)
note over User,CCP: Update cluster tags via Cloud API
User->>CCP: PATCH /clusters/{cluster_id} { "cloud_provider_tags": { ... } }<br/>Authorization: Bearer <token>
CCP-->>User: 200 OK (updated spec)
end
rect rgb(240,255,240)
note over User,CLI: (provider-specific) Refresh agent permissions
User->>CLI: rpk cloud byoc <provider> apply --redpanda-id=<cluster_id>
CLI->>Agent: Trigger permissions refresh
Agent-->>CLI: Result
end
rect rgb(255,250,235)
note over Agent,CSP: Reconcile tags on provider resources
CCP-)Agent: Desired cloud_provider_tags
Agent->>CSP: Create/Update/Delete tags/labels on resources
CSP-->>Agent: Success / Error
Agent-->>CCP: Status
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Assessment against linked issues
Assessment against linked issues: Out-of-scope changes
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (11)
modules/get-started/pages/whats-new-cloud.adoc (1)
11-14: Link anchors look correct; tighten wording and remove trailing space.
- Cross-refs resolve to sections that exist and generate stable anchors.
- Minor copy nit: trailing space at end of Line 13.
-After cluster creation, you can manage custom cloud provider tags and labels for xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc#manage-custom-resource-tags[AWS], xref:get-started:cluster-types/byoc/azure/create-byoc-cluster-azure.adoc#manage-custom-resource-tags[Azure], and xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc#manage-custom-resource-tags[GCP] using the Cloud Control Plane API +After cluster creation, you can manage custom cloud provider tags and labels for xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc#manage-custom-resource-tags[AWS], xref:get-started:cluster-types/byoc/azure/create-byoc-cluster-azure.adoc#manage-custom-resource-tags[Azure], and xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc#manage-custom-resource-tags[GCP] using the Cloud Control Plane API.modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc (4)
53-61: Clarify “tags vs. labels” terminology for AWS (tags only).AWS resources only use “tags”. Consider dropping “labels” here to avoid cross-provider confusion.
-After cluster creation, you may need to update resource tags for compliance or organizational requirements. You can manage custom cloud provider tags and labels using the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API]. +After cluster creation, you may need to update resource tags for compliance or organizational requirements. You can manage custom cloud provider tags using the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API].
64-82: rpk command and IAM permissions: standardize flags; verify missing IAM tag actions.
- rpk flags elsewhere use kebab-case; keep consistent across providers (dash over underscore).
- Consider whether iam:TagRole/iam:UntagRole are also needed for Redpanda-managed IAM roles.
-rpk cloud byoc aws apply --redpanda-id=$cluster_id +# Standardize env var naming in samples: +# export CLUSTER_ID=<cluster id> +rpk cloud byoc aws apply --redpanda-id="$CLUSTER_ID"Action items to verify:
- Do we also require:
iam:TagRole,iam:UntagRole?- Any region/account scoping flags needed on
rpk cloud byoc aws applyfor multi-account setups?
105-115: Minor curl formatting and consistency.
- Keep the same variable style here and consistent line continuation.
-cluster_patch_body='{"cloud_provider_tags": {}}' - -curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}"\ +cluster_patch_body='{"cloud_provider_tags": {}}' + +curl -X PATCH "https://api.redpanda.com/v1/clusters/$CLUSTER_ID" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $AUTH_TOKEN" \ -d "$cluster_patch_body" \
83-103: Unify variable usage and clarify full‐replacement semanticsTo keep the example consistent with earlier snippets (which use
$cluster_id), replace the literal{cluster.id}placeholder with the same environment variable. Also, add a prominent note that this PATCH call replaces the entire tag set—omitting any tag in your payload will remove it. If your API implementation supports RFC 7396 (JSON Merge Patch), you can switch theContent-Typetoapplication/merge-patch+json; otherwise, keepapplication/json.• Define and export the cluster ID before invoking the API:
export cluster_id="<your-cluster-id>"• Add a NOTE immediately above the
curlinvocation to warn about full replacement.
• Update thecurlURL to use$cluster_idinstead of{cluster.id}.
• (Optional) If you confirm support for JSON Merge Patch, change:-H "Content-Type: application/json" \ +H "Content-Type: application/merge-patch+json" \Revised snippet:
+ // Ensure you’ve set your cluster ID from the UI + export cluster_id="<your-cluster-id>" [,bash] ---- cluster_patch_body=$(cat <<'JSON' { "cloud_provider_tags": { "custom-label-1": "true", "custom-label-2": "123" } } JSON ) + NOTE: This call replaces the entire tag set on supported resources. Omitted tags in the payload will be removed. curl -X PATCH "https://api.redpanda.com/v1/clusters/$cluster_id" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer \$AUTH_TOKEN" \ -d "\$cluster_patch_body" ----modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc (3)
158-166: Azure: keep provider terminology (“tags”), not “labels”; add note on system-managed tags.
- Azure uses “tags”. Suggest removing “labels”.
- Recommend noting that Redpanda system tags (if any) are immutable to prevent accidental removal.
-After cluster creation, you may need to update resource tags for compliance or organizational requirements. You can manage custom cloud provider tags and labels using the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API]. +After cluster creation, you may need to update resource tags for compliance or organizational requirements. You can manage custom cloud provider tags using the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API]. + +NOTE: System-managed tags used by Redpanda may be immutable and are not editable via the API.
169-175: rpk command: standardize variable names and quoting; confirm required flags.
- Use consistent variable names across docs ($CLUSTER_ID, $SUBSCRIPTION_ID).
- Quote expansions.
-rpk cloud byoc azure apply --redpanda-id=$cluster_id --subscription-id=$subscription_id +export CLUSTER_ID=<cluster id> +export SUBSCRIPTION_ID=<subscription id> +rpk cloud byoc azure apply --redpanda-id="$CLUSTER_ID" --subscription-id="$SUBSCRIPTION_ID"
210-214: Limitations: add quick rationale to reduce support tickets.Briefly explain why ASG and Private Link NIC tags aren’t mutable (provider constraints vs design), or link to upstream docs.
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc (3)
23-23: Creation-time limit vs post-creation limit: clarify 5 vs 16 for GCP.You state “up to five” labels at creation, and later “up to 16” total. Add a note that the UI allows 5 at creation but you can add more post-creation (up to 16).
-. Optionally, click *Advanced settings* to specify up to five key-value custom GCP labels. If a label key starts with `gcp.network-tag.<tag>`, the agent interprets it as a request to apply the `<tag>` network tag to GCE instances in the cluster. Use labels for organization/metadata; use network tags to target firewall rules and routes. After the cluster is created, labels are applied to applicable GCP resources (for example, instances and disks), and network tags are applied to instances. For more details on labels, see the https://cloud.google.com/compute/docs/labeling-resources[GCP documentation^]. +. Optionally, click *Advanced settings* to specify up to five key-value custom GCP labels. NOTE: You can add more after creation (up to the overall limit below). If a label key starts with `gcp.network-tag.<tag>`, the agent interprets it as a request to apply the `<tag>` network tag to GCE instances in the cluster. Use labels for organization/metadata; use network tags to target firewall rules and routes. After the cluster is created, labels are applied to applicable GCP resources (for example, instances and disks), and network tags are applied to instances. For more details on labels, see the https://cloud.google.com/compute/docs/labeling-resources[GCP documentation^].
39-45: Confirm the 16-labels/tags product limit and scope.Is “16” a Redpanda product cap (not a GCP platform limit)? If so, explicitly say “Redpanda Cloud allows up to 16…” and clarify whether the 16 is the combined total of labels + network tags.
-Redpanda Cloud allows up to 16 custom labels and network tags in GCP. +Redpanda Cloud allows up to 16 total custom entries (labels + network tags) per cluster in GCP.
86-96: Consistency for “remove all tags” example.Use same variable style and line continuation.
-curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \ +curl -X PATCH "https://api.redpanda.com/v1/clusters/$CLUSTER_ID" \
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc(2 hunks)modules/get-started/pages/whats-new-cloud.adoc(1 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-07T16:36:45.111Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.
Applied to files:
modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adocmodules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc (2)
48-56: Good fix: rpk CLI flag style (kebab-case) and variable quoting.The switch to
--project-idand quoting the env vars look correct and consistent with our rpk style elsewhere.
60-64: Missing IAM permission for network tags (compute.instances.setTags).Without
compute.instances.setTags, the agent cannot assign network tags to GCE instances. Add it to the list and call it out explicitly.Apply:
* `compute.disks.get` * `compute.disks.list` * `compute.disks.setLabels` * `compute.instances.setLabels` +* `compute.instances.setTags`Optional note to reduce support tickets:
+NOTE: Assigning network tags on GCE instances requires the `compute.instances.setTags` permission in addition to label permissions.
🧹 Nitpick comments (5)
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc (5)
23-23: Clarify label vs network tag behavior; avoid implying invalid GCP label keys with dots.Keys like
gcp.network-tag.<tag>contain dots, which are not valid in GCP label keys. Please make it explicit that such keys are not applied as GCP labels and are only interpreted to apply GCE network tags, to prevent confusion about label constraints.Proposed reword (keeps current intent, removes ambiguity):
- . Optionally, click *Advanced settings* to specify up to five key-value custom GCP labels. If a label key starts with `gcp.network-tag.<tag>`, the agent interprets it as a request to apply the `<tag>` network tag to GCE instances in the cluster. Use labels for organization/metadata; use network tags to target firewall rules and routes. After the cluster is created, labels are applied to applicable GCP resources (for example, instances and disks), and network tags are applied to instances. For more details on labels, see the https://cloud.google.com/compute/docs/labeling-resources[GCP documentation^]. + . Optionally, click *Advanced settings* to specify up to five key-value custom GCP labels. To request GCE network tags, add entries whose keys start with `gcp.network-tag.<tag>`. These `gcp.network-tag.*` entries are used only to apply the `<tag>` network tag to instances and are not applied as GCP labels. Use labels for organization/metadata; use network tags to target firewall rules and routes. After the cluster is created, valid labels are applied to applicable GCP resources (for example, instances and disks), and network tags are applied to instances. For more details on labels, see the https://cloud.google.com/compute/docs/labeling-resources[GCP documentation^].If the agent currently also attempts to set these as labels, please confirm and we can adjust the guidance accordingly.
74-75: Elevate destructive-replace warning with an admonition.You already explain replacement semantics. Surface it more clearly with a CAUTION block to prevent accidental tag loss.
-The `PATCH` call sets the labels and network tags specified under `"cloud_provider_tags"`. It replaces the existing labels and tags with the specified labels and tags. Include all desired labels and tags in the request. To remove a single entry, omit it from the map you send. +[CAUTION] +==== +The `PATCH` call replaces the entire set of labels and network tags managed by Redpanda for this cluster. Include all desired labels and tags in the request; any omitted keys are removed. To remove a single entry, omit it from the map you send. +====
78-86: Confirm semantics ofgcp.network-tag.*values and label constraints in the example.If values for
gcp.network-tag.*entries are ignored (e.g.,"true"is just a placeholder), add a brief note after the example. Also, ensure those keys are not applied as labels (see comment on Line 23).Suggested note to insert immediately after the example block:
+NOTE: Keys prefixed with `gcp.network-tag.` are used only to apply network tags to instances; their values are ignored. These keys are not applied as GCP labels.
90-94: Optional: make curl examples a bit safer and more consistent.Add
-sSfor quieter output with errors and declareAcceptto emphasize JSON responses.-curl -X PATCH "https://api.redpanda.com/v1/clusters/$CLUSTER_ID" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $AUTH_TOKEN" \ - -d "$cluster_patch_body" +curl -sS -X PATCH "https://api.redpanda.com/v1/clusters/$CLUSTER_ID" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -d "$cluster_patch_body"Apply the same to the “remove all” example below.
Also applies to: 102-106
65-72: Auth token step looks good. Consider linking the specific API reference anchor.Minor enhancement: include a link to the specific PATCH operation anchor for quick lookup (consistent with other pages).
-First, set your authentication token: +First, set your authentication token. For the API reference, see xref:manage:api/cloud-byoc-controlplane-api.adoc#patch-/v1/clusters/-cluster.id-[PATCH /v1/clusters/{cluster.id}].
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc(1 hunks)modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc(2 hunks)modules/get-started/pages/whats-new-cloud.adoc(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- modules/get-started/pages/whats-new-cloud.adoc
- modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc
- modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-08-07T16:36:45.111Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#377
File: modules/networking/pages/dedicated/gcp/configure-psc-in-ui.adoc:35-71
Timestamp: 2025-08-07T16:36:45.111Z
Learning: In Redpanda Cloud documentation, NAT subnet and firewall rule creation commands for GCP Private Service Connect are producer-side infrastructure steps that only BYOC (Bring Your Own Cloud) customers need to perform, since they manage their own VPC. Dedicated cluster customers don't need these steps because Redpanda manages the infrastructure for them. The ifdef::env-byoc[] guard correctly hides these commands from Dedicated users.
Applied to files:
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
📚 Learning: 2025-06-18T21:02:38.074Z
Learnt from: micheleRP
PR: redpanda-data/cloud-docs#334
File: modules/networking/partials/psc-api2.adoc:15-16
Timestamp: 2025-06-18T21:02:38.074Z
Learning: In the Redpanda Cloud documentation system, cross-reference anchors using the format `#patch-/v1/clusters/-cluster.id-` work correctly for referencing API endpoints, even with dashes instead of curly braces around parameter names.
Applied to files:
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
🔇 Additional comments (1)
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc (1)
39-39: Clarify Redpanda-specific 16-entry limit (combined labels + tags)GCP itself allows up to 64 labels per resource and 64 network tags per VM; the “16” limit here is a Redpanda Cloud restriction and applies to the combined total of custom labels and
gcp.network-tag.*entries.• File: modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Line 39-Redpanda Cloud allows up to 16 custom labels and network tags in GCP. +Redpanda Cloud allows up to 16 total custom entries in GCP (combined count across GCP resource labels and `gcp.network-tag.*` entries).
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc
Outdated
Show resolved
Hide resolved
modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc
Outdated
Show resolved
Hide resolved
Co-authored-by: Joyce Fee <[email protected]>
…luster-gcp.adoc Co-authored-by: Joyce Fee <[email protected]>
micheleRP
deleted the
DOC-1538-Document-feature-BYOC-support-adding-and-removing-of-customer-tags-after-cluster-creation
branch
Description
This pull request adds documentation for managing custom cloud provider tags and labels on existing BYOC clusters across AWS, Azure, and GCP. It adds instructions for using the Cloud Control Plane API to update, replace, or remove tags/labels after cluster creation, and clarifies required IAM permissions and update limitations for each provider.
Resolves https://redpandadata.atlassian.net/browse/DOC-1538
Review deadline:
Page previews
What's New
Create BYOC on AWS
Create BYOVPC on AWS
Create BYOC on Azure
Create BYOVNet on Azure
Create BYOC on GCP
Create BYOVPC on GCP
Checks