DOC-1538 BYOC customer tags after cluster creation (#400)

* DOC-1538 BYOC customer tags after cluster creation

* edits + add to What's New

* incorporate coderabbit suggestions

* incorporate Paul's feedback

* fix what's new links

* incorporate review feedback + minor edits

* Update modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc

Co-authored-by: Joyce Fee <[email protected]>

* Update modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc

Co-authored-by: Joyce Fee <[email protected]>

* incorporate doc review feedback

---------

Co-authored-by: Joyce Fee <[email protected]>

Author: micheleRP

modules/get-started/pages/cluster-types/byoc/aws/create-byoc-cluster-aws.adoc

@@ -19,7 +19,7 @@ Before you deploy a BYOC cluster on AWS, check that the user creating the cluste
 ** `AWS_PROFILE` or
 ** `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`
 
-To verify access, you should be able to successfully run `aws sts get-caller-identity` for your region. See the https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/get-caller-identity.html[AWS CLI reference^].
+To verify access, you should be able to successfully run `aws sts get-caller-identity` for your region. For more information, see the https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/get-caller-identity.html[AWS CLI reference^].
 --
 
 == Create a BYOC cluster
@@ -33,8 +33,8 @@ To verify access, you should be able to successfully run `aws sts get-caller-ide
 * If you plan to create a private network in your own VPC, select the region where your VPC is located.
 * Three availability zones provide two backups in case one availability zone goes down.
 ====
-+ 
-Optionally, click *Advanced settings* to specify up to five key-value custom tags. After the cluster is created, the tags are applied to all AWS resources associated with this cluster. For more information, see the https://docs.aws.amazon.com/mediaconnect/latest/ug/tagging-restrictions.html[AWS documentation^].
++
+Optionally, click *Advanced settings* to specify up to five key-value custom tags. After the cluster is created, the tags are applied to all AWS resources associated with this cluster. For more information, see the https://docs.aws.amazon.com/mediaconnect/latest/ug/tagging-restrictions.html[AWS documentation^]. After the cluster is created, you can <<manage-custom-tags,specify more tags with the Cloud API>>.
 
 . Click *Next*.
 . On the Network page, enter the connection type: either *Public* or *Private*. For BYOC clusters, *Private* is best-practice.
@@ -50,6 +50,10 @@ As part of agent deployment:
 
 include::get-started:partial$no-access.adoc[]
 
+== Manage custom tags
+
+include::get-started:partial$custom-tags-aws.adoc[]
+
 == Next steps
 
 xref:networking:byoc/aws/index.adoc[Configure private networking]

modules/get-started/pages/cluster-types/byoc/aws/vpc-byo-aws.adoc

@@ -55,7 +55,7 @@ The https://github.com/redpanda-data/cloud-examples/blob/main/customer-managed/a
 
 == Configure Terraform
 
-NOTE: For simplicity, these instructions assume that Terraform is configured to use local state. You may want to configure https://developer.hashicorp.com/terraform/language/state/remote[remote state^]. 
+NOTE: For simplicity, the instructions are based on the assumption that Terraform is configured to use local state. You may want to configure https://developer.hashicorp.com/terraform/language/state/remote[remote state^]. 
 
 Define a JSON file called `byovnet.auto.tfvars.json` inside the Terraform directory that contains information about the VPC.
 
@@ -452,4 +452,8 @@ After that completes, run:
 rpk cloud byoc aws destroy --redpanda-id ${REDPANDA_ID}
 ```
 
-include::get-started:partial$no-access.adoc[]
+== Manage custom tags
+
+include::get-started:partial$custom-tags-aws.adoc[]
+
+NOTE: For BYOVPC clusters, custom tags are not applied to the customer-managed resources that are deployed by the customer.

modules/get-started/pages/cluster-types/byoc/azure/create-byoc-cluster-azure.adoc

@@ -87,9 +87,6 @@ Confirm that the Azure subscription has enough virtual CPUs (vCPUs) per instance
 
 See the https://learn.microsoft.com/en-us/azure/quotas/view-quotas[Microsoft documentation^].
 
-include::shared:partial$kafka-connect.adoc[]
-
-
 === Check Azure SKU restrictions
 
 Ensure your subscription has access to the required VM sizes in the region where you will use Redpanda. For example, using the Azure CLI or in the Azure Cloud Shell, run:
@@ -144,7 +141,7 @@ To create a Redpanda cluster in your Azure VNet, follow the <<prerequisites,prer
 * Multi-AZ is the default configuration. Three AZs provide two backups in case one availability zone goes down.
 ====
 + 
-Optionally, click *Advanced settings* to specify up to five key-value custom tags. After the cluster is created, the tags are applied to all Azure resources associated with this cluster. For details, see the https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/tag-resources[Microsoft documentation^].
+Optionally, click *Advanced settings* to specify up to five key-value custom tags. After the cluster is created, the tags are applied to all Azure resources associated with this cluster. For details, see the https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/tag-resources[Microsoft documentation^]. After the cluster is created, you can <<manage-custom-tags,specify more tags with the Cloud API>>. 
 
 . Click *Next*.
 . On the Network page, enter the connection type: either *Public* or *Private*. For BYOC clusters, *Private* using Azure Private Link is best-practice. 
@@ -155,8 +152,6 @@ Optionally, click *Advanced settings* to specify up to five key-value custom tag
 +
 As part of agent deployment, Redpanda assigns the permissions required to run the agent. For details about these permissions, see xref:security:authorization/cloud-iam-policies-azure.adoc[Azure IAM policies].
 
-== Next steps
+== Manage custom tags
 
-* xref:networking:azure-private-link.adoc[Configure Azure Private Link]
-* xref:security:authorization/cloud-iam-policies-azure.adoc[Review Azure IAM policies]
-* xref:reference:rpk/index.adoc[Learn about `rpk` commands]
+include::get-started:partial$custom-tags-azure.adoc[]

modules/get-started/pages/cluster-types/byoc/azure/vnet-azure.adoc

@@ -514,3 +514,15 @@ rpk cloud byoc azure destroy --redpanda-id ${REDPANDA_ID}
 ```
 
 include::get-started:partial$no-access.adoc[]
+
+== Manage custom tags
+
+include::get-started:partial$custom-tags-azure.adoc[]
+
+NOTE: For BYOVNet clusters, custom tags are not applied to the customer-managed resources that are deployed by the customer.
+
+== Next steps
+
+* xref:networking:azure-private-link.adoc[Configure Azure Private Link]
+* xref:security:authorization/cloud-iam-policies-azure.adoc[Review Azure IAM policies]
+* xref:reference:rpk/index.adoc[Learn about `rpk` commands]

modules/get-started/pages/cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc

@@ -20,9 +20,8 @@ Enter a cluster name, then select the resource group, provider (GCP), xref:refer
 * If you plan to create a private network in your own VPC, select the region where your VPC is located.
 * Three availability zones provide two backups in case one availability zone goes down.
 ====
-+ 
-Optionally, click *Advanced settings* to specify up to five key-value custom labels. After the cluster is created, the labels are applied to all GCP resources associated with this cluster. For more information, 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. If a label key starts with `gcp.network-tag.<tag>`, then the agent interprets it as a request to apply the `<tag>` https://cloud.google.com/vpc/docs/add-remove-network-tags[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 information, see the https://cloud.google.com/compute/docs/labeling-resources[GCP documentation^]. After the cluster is created, you can <<manage-custom-resource-labels-and-network-tags,specify more labels with the Cloud API>>. 
 . Click *Next*.
 . On the Network page, enter the connection type: either *Public* or *Private*. For BYOC clusters, *Private* is best-practice.
 ** Your network name is used to identify this network.
@@ -34,6 +33,10 @@ Note that `rpk` configures the permissions required by the agent to provision an
 
 include::get-started:partial$no-access.adoc[]
 
+== Manage custom resource labels and network tags
+
+include::get-started:partial$custom-tags-gcp.adoc[]
+
 == Next steps
 
 xref:networking:byoc/gcp/index.adoc[Configure private networking]

modules/get-started/pages/cluster-types/byoc/gcp/vpc-byo-gcp.adoc

@@ -738,6 +738,12 @@ You can delete the cluster in the Cloud UI.
 . Select your cluster.
 . Go to the **Cluster settings** page and click **Delete**, then confirm your deletion. 
 
+== Manage custom resource labels and network tags
+
+include::get-started:partial$custom-tags-gcp.adoc[]
+
+NOTE: For BYOVPC clusters, custom labels are not applied to the customer-managed resources that are deployed by the customer.
+
 == Next steps
 
 xref:networking:byoc/gcp/index.adoc[Configure private networking]

modules/get-started/pages/whats-new-cloud.adoc

@@ -8,6 +8,10 @@ This page lists new features added to Redpanda Cloud.
 
 == August 2025
 
+=== Manage custom resource tags in BYOC
+
+After cluster creation, you can manage custom cloud provider tags and labels on BYOC and BYOVPC/BYOVNet clusters for xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc#manage-custom-tags[AWS], xref:get-started:cluster-types/byoc/azure/create-byoc-cluster-azure.adoc#manage-custom-tags[Azure], and xref:get-started:cluster-types/byoc/gcp/create-byoc-cluster-gcp.adoc#manage-custom-resource-labels-and-network-tags[GCP] using the Cloud Control Plane API. This involves refreshing Redpanda agent permissions with `rpk cloud byoc` due to new IAM permissions. 
+
 === Iceberg topics with AWS Glue
 
 A new xref:manage:iceberg/iceberg-topics-aws-glue.adoc[integration with AWS Glue Data Catalog] allows you to add Redpanda topics as Iceberg tables in your data lakehouse. The AWS Glue catalog integration is available in BYOC clusters with Redpanda version 25.2 and later.

modules/get-started/partials/custom-tags-aws.adoc

@@ -0,0 +1,70 @@
+Your organization might require custom tags for cost allocation, audit compliance, or governance policies. After cluster creation, you can manage tags with the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API]. The Control Plane API allows up to 16 custom tags in AWS. 
+
+Make sure you have:
+
+* The cluster ID. You can find this in the Redpanda Cloud UI, in the **Details** section of the cluster overview.
+* A valid bearer token for the Cloud Control Plane API. For details, see link:/api/doc/cloud-controlplane/authentication[Authenticate to the API]. 
+
+include::shared:partial$feature-flag.adoc[]
+
+. To refresh agent permissions so the Redpanda agent can update tags, run:
++
+[,bash]
+----
+export CLUSTER_ID="<cluster-id>"
+
+rpk cloud byoc aws apply --redpanda-id="$CLUSTER_ID"
+----
++
+This step is required because tag management requires additional IAM permissions that may not have been granted during initial cluster creation:
++
+* `ec2:DescribeTags`
+* `ec2:DescribeVolumes`
+* `ec2:DescribeNetworkInterfaces`
+* `ec2:CreateTags`
+* `ec2:DeleteTags`
+* `iam:TagPolicy`
+* `iam:UntagPolicy`
+* `iam:TagInstanceProfile`
+* `iam:UntagInstanceProfile`
+
+. To update tags, invoke the Cloud API.
++
+First, set your authentication token:
++
+[,bash]
+----
+export AUTH_TOKEN="<your-bearer-token>"
+----
++
+The `PATCH` call sets the tags specified under `"cloud_provider_tags"`. It replaces the existing tags with the specified tags. Include all desired tags in the request. To remove a single entry, omit it from the map you send.
++
+[,bash]
+----
+cluster_patch_body=$(cat <<'JSON'
+{
+  "cloud_provider_tags": {
+    "Environment": "production",
+    "CostCenter": "engineering"
+  }
+}
+JSON
+)
+
+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"
+----
++
+To remove all tags, send an empty `cloud_provider_tags` object:
++
+[,bash]
+----
+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"
+----

modules/get-started/partials/custom-tags-azure.adoc

@@ -0,0 +1,64 @@
+Your organization might require custom tags for cost allocation, audit compliance, or governance policies. After cluster creation, you can manage tags with the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API]. The Control Plane API allows up to 16 custom tags in Azure. 
+
+Make sure you have:
+
+* The cluster ID. You can find this in the Redpanda Cloud UI, in the **Details** section of the cluster overview.
+* A valid bearer token for the Cloud Control Plane API. For details, see link:/api/doc/cloud-controlplane/authentication[Authenticate to the API]. 
+
+include::shared:partial$feature-flag.adoc[]
+
+. To refresh Redpanda agent permissions in the target subscription, run:
++
+[,bash]
+----
+export CLUSTER_ID="<cluster-id>"
+export SUBSCRIPTION_ID="<subscription-id>"
+
+rpk cloud byoc azure apply --redpanda-id="$CLUSTER_ID" --subscription-id="$SUBSCRIPTION_ID"
+----
+
+. To update tags, invoke the Cloud API.
++
+First, set your authentication token:
++
+[,bash]
+----
+export AUTH_TOKEN="<your-bearer-token>"
+----
++
+The `PATCH` call sets the tags specified under `"cloud_provider_tags"`. It replaces the existing tags with the specified tags. Include all desired tags in the request. To remove a single entry, omit it from the map you send.
++
+[,bash]
+----
+cluster_patch_body=$(cat <<'JSON'
+{
+  "cloud_provider_tags": {
+    "Environment": "production",
+    "CostCenter": "engineering"
+  }
+}
+JSON
+)
+
+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"
+----
++
+To remove all tags, send an empty `cloud_provider_tags` object:
++
+[,bash]
+----
+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"
+----
+
+=== Limitations
+
+* Nodepool Application Security Groups (ASG): Custom tags are set only when the cluster is created. Tags cannot be updated on these resources after cluster creation.
+* Private Link network interfaces (Kubernetes API server, Tiered Storage, and Private Link service): Custom tags are set only during cluster creation and cannot be changed later.

modules/get-started/partials/custom-tags-gcp.adoc

@@ -0,0 +1,68 @@
+Your organization might require custom resource labels and network tags for cost allocation, audit compliance, or governance policies. After cluster creation, you can manage this with the xref:manage:api/cloud-byoc-controlplane-api.adoc[Cloud Control Plane API]. The Control Plane API allows up to 16 custom resource labels and network tags in GCP.
+
+Make sure you have:
+
+* The cluster ID. You can find this in the Redpanda Cloud UI, in the **Details** section of the cluster overview.
+* A valid bearer token for the Cloud Control Plane API. For details, see link:/api/doc/cloud-controlplane/authentication[Authenticate to the API]. 
+
+include::shared:partial$feature-flag.adoc[]
+
+. To refresh agent permissions so the Redpanda agent can update labels and network tags, run:
++
+[,bash]
+----
+export CLUSTER_ID="<cluster-id>"
+export PROJECT_ID="<gcp-project-id>"
+
+rpk cloud byoc gcp apply --redpanda-id="$CLUSTER_ID" --project-id="$PROJECT_ID"
+----
++
+This step is required because label/tag management requires additional IAM permissions that may not have been granted during initial cluster creation:
++
+* `compute.disks.get`
+* `compute.disks.list`
+* `compute.disks.setLabels`
+* `compute.instances.setLabels`
+
+. To update labels and network tags, invoke the Cloud API.
++
+First, set your authentication token:
++
+[,bash]
+----
+export AUTH_TOKEN="<your-bearer-token>"
+----
++
+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.
++
+[,bash]
+----
+cluster_patch_body=$(cat <<'JSON'
+{
+  "cloud_provider_tags": {
+    "environment": "production",
+    "cost-center": "engineering",
+    "gcp.network-tag.web-servers": "true",
+    "gcp.network-tag.database-access": "true"
+  }
+}
+JSON
+)
+
+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"
+----
++
+To remove all labels and network tags, send an empty `cloud_provider_tags` object:
++
+[,bash]
+----
+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"
+----