Agent IAM Policies in GCP
When you run rpk cloud byoc gcp apply to create a BYOC cluster, you grant these permissions to the Redpanda Cloud agent service account. The agent uses them to call the GCP API and manage cluster resources on your behalf. The permissions follow the principle of least privilege. They are not required by Redpanda Cloud end users, and your GCP account does not need them for the initial Terraform bootstrap.
|
This page covers the permissions the Redpanda agent service account uses to manage BYOC cluster resources. It does not apply to BYOVPC clusters. |
|
These permissions are granted to the Redpanda agent service account within the Redpanda-managed GCP project. Two capabilities are granted as predefined roles rather than individual permissions: Kubernetes Engine Admin (full management of the GKE cluster) and Storage Object Admin (object access, scoped to the cluster management bucket). The agent service account also carries two transitional predefined role bindings, |
How to read this page
The agent’s permissions are granted through a single custom role, plus the predefined roles noted above. The custom role’s permissions are organized into functional groups (compute, networking, storage, identity, secrets, service enablement, and monitoring). Each group lists the permissions it includes and why they are needed. The full role definition appears in a collapsible Terraform block at the end of this page.
| Access level | Meaning |
|---|---|
Read |
|
Write |
Creates, updates, or uses resources. |
Delete |
Removes resources. |
Compute and Kubernetes
Manages the Compute Engine instances, instance groups and templates, autoscalers, and disks that run the Redpanda data plane, plus the operations and zone/region metadata needed to provision them. Kubernetes cluster management is granted through the Kubernetes Engine Admin role.
| Permission | Access | Why it is needed |
|---|---|---|
|
Read |
Required to read autoscaler configuration so Redpanda Cloud can safely scale the compute backing your cluster. |
|
Read |
Required to enumerate autoscalers when managing the compute that runs your Redpanda cluster. |
|
Read |
Required to read details of the persistent disks attached to your cluster’s brokers (used when applying labels and validating storage). |
|
Read |
Required to enumerate the persistent disks belonging to your cluster. |
|
Write |
Required to apply Redpanda-managed labels to your cluster’s persistent disks for identification, cost tracking, and lifecycle management. |
|
Read |
Required to check the status of long-running GCP operations initiated on your cluster’s behalf. |
|
Read |
Required to inspect long-running GCP operations so Redpanda Cloud can detect quota exhaustion, capacity stockouts, and other provisioning errors affecting your cluster. |
|
Write |
Required to create the managed instance groups that run the compute nodes of your Redpanda cluster. |
|
Delete |
Required to delete managed instance groups when nodes or the cluster are being removed. |
|
Read |
Required to read managed instance group configuration to validate and reconcile the state of your cluster’s compute. |
|
Read |
Required to enumerate managed instance groups belonging to your Redpanda cluster. |
|
Write |
Required to update managed instance groups when scaling, upgrading, or reconfiguring your cluster. |
|
Write |
Required to create the instance groups that back your Redpanda cluster’s compute. |
|
Delete |
Required to delete instance groups during cluster changes or teardown. |
|
Read |
Required to read instance group details when managing your cluster’s compute. |
|
Write |
Required to update instance groups as your cluster is scaled or reconfigured. |
|
Write |
Required to create the instance templates that define how your Redpanda cluster’s nodes are provisioned. |
|
Delete |
Required to delete obsolete instance templates during upgrades and teardown. |
|
Read |
Required to read instance template details when validating and provisioning your cluster. |
|
Write |
Required to provision the compute instances (VMs) that host your Redpanda cluster’s brokers and supporting workloads. |
|
Delete |
Required to deprovision compute instances when nodes are replaced, scaled down, or the cluster is torn down. |
|
Read |
Required to read instance details for health checks, validation, and reconciliation of your cluster’s compute. |
|
Read |
Required to enumerate the instances that make up your Redpanda cluster. |
|
Write |
Required to reset (hard-reboot) an instance during recovery when a node becomes unresponsive. |
|
Write |
Required to apply deletion protection to cluster instances so they cannot be accidentally destroyed. |
|
Write |
Required to apply Redpanda-managed labels to your cluster’s instances for identification, cost tracking, and lifecycle management. |
|
Write |
Required to update instance configuration as part of scaling, upgrades, or reconfiguration of your cluster. |
|
Write |
Required so Redpanda Cloud can attach instances to networking resources (such as Private Service Connect network endpoint groups) that provide connectivity to your cluster. |
|
Read |
Required to read basic GCP project metadata (such as default network settings) needed to provision resources for your cluster. |
|
Read |
Required to check the status of regional operations initiated on your cluster’s behalf (including Private Service Connect operations). |
|
Read |
Required to list regional operations so Redpanda Cloud can monitor asynchronous provisioning and Private Service Connect changes and detect failures. |
|
Read |
Required to read region metadata when provisioning resources for your cluster. |
|
Read |
Required to enumerate available regions when placing and validating your cluster. |
|
Read |
Required to check the status of zonal operations so Redpanda Cloud can detect quota exhaustion, capacity stockouts, and other provisioning errors affecting your cluster. |
|
Read |
Required to inspect zonal operations for detecting quota and capacity issues that affect your cluster’s health. |
|
Read |
Required to read zone metadata when placing your cluster’s compute resources. |
|
Read |
Required to enumerate available zones when provisioning and validating your cluster. |
Networking and connectivity
Manages the VPC network, firewall rules, forwarding rules and Private Service Connect endpoints, backend services, network endpoint groups, service attachments, subnetworks, and Cloud DNS zones and records.
| Permission | Access | Why it is needed |
|---|---|---|
|
Read |
Required to read static IP address details when provisioning and managing the network endpoints used by your Redpanda cluster. |
|
Write |
Required so Redpanda Cloud can create the firewall rules that protect your cluster’s network and allow only intended traffic. |
|
Delete |
Required so Redpanda Cloud can remove firewall rules it created when they are no longer needed (for example, cluster changes or teardown). |
|
Read |
Required to inspect existing firewall rules to validate cluster networking and detect drift from the expected configuration. |
|
Write |
Required so Redpanda Cloud can update firewall rules as your cluster’s networking requirements change. |
|
Write |
Required to create the forwarding rules that establish Private Service Connect (PSC) endpoints so you can privately reach your Redpanda cluster. |
|
Delete |
Required to remove PSC forwarding rules when endpoints or the cluster are torn down. |
|
Read |
Required to read PSC forwarding rule details when validating and reconciling private connectivity to your cluster. |
|
Write |
Required to create Private Service Connect forwarding rules that let you privately reach your Redpanda cluster. |
|
Delete |
Required to delete Private Service Connect forwarding rules when private connectivity is being removed. |
|
Write |
Required to apply Redpanda-managed labels to PSC forwarding rules for identification, cost tracking, and lifecycle management. |
|
Write |
Required to configure the target of PSC forwarding rules so private connections resolve to your Redpanda cluster. |
|
Write |
Required to update PSC forwarding rules as your private connectivity configuration changes. |
|
Write |
Required to apply Redpanda-managed labels to forwarding rules for identification, cost tracking, and lifecycle management. |
|
Write |
Required to configure forwarding rule targets so traffic is directed to the correct components of your Redpanda cluster. |
|
Write |
Required so Redpanda Cloud can attach forwarding rules to your cluster’s networking resources. |
|
Write |
Required to create the VPC network resources that carry your Redpanda cluster’s traffic (when Redpanda Cloud manages the network). |
|
Delete |
Required to remove VPC network resources that Redpanda Cloud created when they are no longer needed. |
|
Read |
Required to inspect the effective firewall rules on your VPC so Redpanda Cloud can validate that cluster networking is correctly configured. |
|
Write |
Required to update VPC network configuration on networks that Redpanda Cloud manages for your cluster. |
|
Write |
Required to update network-level policies applied to the VPC hosting your cluster. |
|
Write |
Required so Redpanda Cloud can attach your cluster’s resources (instances, service attachments, endpoints) to the VPC network. |
|
Write |
Required to create the regional backend services that route Private Service Connect traffic to your Redpanda cluster. |
|
Delete |
Required to delete regional backend services when PSC connectivity or the cluster is being torn down. |
|
Read |
Required to read regional backend service details when validating and reconciling private connectivity. |
|
Write |
Required so Redpanda Cloud can attach backend services to forwarding rules and service attachments serving your cluster. |
|
Write |
Required to attach your cluster’s broker instances to the network endpoint groups that back Private Service Connect. |
|
Write |
Required to create the network endpoint groups that expose your cluster’s brokers through Private Service Connect. |
|
Delete |
Required to delete network endpoint groups when PSC connectivity or the cluster is being torn down. |
|
Write |
Required to detach broker instances from network endpoint groups during scaling, replacement, or teardown. |
|
Read |
Required to read network endpoint group details when validating and reconciling PSC connectivity. |
|
Write |
Required so Redpanda Cloud can attach network endpoint groups to the backend services and forwarding rules serving your cluster. |
|
Read |
Required to read Cloud Router configuration when validating VPC networking used by your cluster. |
|
Write |
Required to create the Private Service Connect service attachments that publish your Redpanda cluster for private consumption. |
|
Delete |
Required to delete PSC service attachments when private connectivity or the cluster is being torn down. |
|
Read |
Required to read PSC service attachment details when validating and reconciling private connectivity. |
|
Read |
Required to enumerate PSC service attachments belonging to your cluster. |
|
Write |
Required to update PSC service attachments as private connectivity settings (such as allow-lists) change. |
|
Read |
Required to read subnetwork details when validating and placing your cluster’s resources on the correct subnets. |
|
Write |
Required so Redpanda Cloud can place your cluster’s instances and endpoints in the appropriate subnets. |
|
Write |
Required to publish DNS record changes so clients can resolve the endpoints of your Redpanda cluster (including external-DNS updates from the underlying GKE cluster). |
|
Read |
Required to check the status of pending DNS record changes for your cluster’s endpoints. |
|
Read |
Required to enumerate DNS record changes when reconciling the DNS state for your cluster. |
|
Write |
Required to create the managed DNS zones that host your Redpanda cluster’s endpoint records. |
|
Delete |
Required to delete managed DNS zones created by Redpanda Cloud when they are no longer needed. |
|
Read |
Required to read managed DNS zone details when reconciling your cluster’s DNS configuration. |
|
Read |
Required to enumerate managed DNS zones associated with your cluster (used by external-DNS and by Redpanda’s validation). |
|
Write |
Required to update managed DNS zone configuration as your cluster’s DNS needs change. |
|
Read |
Required to read Cloud DNS project settings when managing DNS for your cluster. |
|
Write |
Required to create DNS records so clients can resolve your Redpanda cluster’s endpoints (used by external-DNS). |
|
Delete |
Required to remove DNS records when endpoints are decommissioned or the cluster is torn down. |
|
Read |
Required to read DNS record details when reconciling your cluster’s DNS state. |
|
Read |
Required to enumerate DNS records associated with your cluster. |
|
Write |
Required to update DNS records as your cluster’s endpoints change. |
Storage
Reads bucket metadata and manages the IAM policy on the Tiered Storage bucket. Object-level access is granted through the Storage Object Admin role, scoped to the cluster management bucket.
| Permission | Access | Why it is needed |
|---|---|---|
|
Read |
Required to read storage bucket details for the buckets used by your cluster (for example, Tiered Storage). |
|
Read |
Required to inspect IAM bindings on your cluster’s storage buckets to validate access is correctly configured. |
|
Write |
Required to grant your cluster’s service accounts access to the storage buckets it uses (for example, Tiered Storage). |
Identity and access
Creates and manages the custom role, service accounts, and project-level IAM bindings the cluster components need.
| Permission | Access | Why it is needed |
|---|---|---|
|
Write |
Required to create the custom IAM roles that grant Redpanda Cloud components least-privilege access needed to operate your cluster. |
|
Delete |
Required to delete custom IAM roles created by Redpanda Cloud when they are no longer needed. |
|
Read |
Required to read custom IAM role definitions to validate that the correct permissions are in place for your cluster. |
|
Read |
Required to enumerate IAM roles when validating and reconciling the permissions granted for your cluster. |
|
Write |
Required to restore an accidentally deleted custom IAM role so your cluster’s operation is not disrupted. |
|
Write |
Required to update custom IAM role definitions as Redpanda Cloud’s required permissions evolve. |
|
Write |
Required to attach Redpanda-managed service accounts to the GCP resources that run your cluster workloads, so those resources run with the service account’s identity. |
|
Write |
Required to create the service accounts used by the various components that run your Redpanda cluster. |
|
Delete |
Required to delete service accounts created by Redpanda Cloud when they are no longer needed. |
|
Read |
Required to read service account details to validate that your cluster’s components have the correct identities. |
|
Read |
Required to inspect service account IAM bindings when validating and reconciling permissions for your cluster. |
|
Write |
Required to grant the necessary IAM bindings on service accounts so cluster components can act on their behalf. |
|
Write |
Required to update service account configuration as your cluster evolves. |
|
Read |
Required to read basic project metadata used by all Redpanda Cloud components (cluster provisioning, connectors, and application services) that run in your project. |
|
Read |
Required to inspect your project’s IAM policy to validate that the necessary bindings for Redpanda Cloud are correctly in place. |
|
Write |
Required to grant the project-level IAM bindings needed for Redpanda Cloud to operate your cluster. |
Secrets management
Lists and deletes the Secret Manager secrets Redpanda creates for your cluster.
| Permission | Access | Why it is needed |
|---|---|---|
|
Delete |
Required to remove Redpanda-managed secret resources associated with your cluster during reconfiguration or teardown. |
|
Read |
Required to find Redpanda-managed secret resources during reconciliation and cleanup. This permission does not grant access to secret values. |
Service enablement
Enables and reads the state of the GCP APIs (services) that your cluster depends on.
| Permission | Access | Why it is needed |
|---|---|---|
|
Write |
Required to enable the Google Cloud APIs used to provision and operate your cluster. |
|
Read |
Required to verify that the Google Cloud APIs needed by your cluster are enabled. |
|
Read |
Required to list the Google Cloud APIs enabled in your project when reconciling the services your cluster depends on. |
Monitoring
Writes log entries for the agent and cluster components.
| Permission | Access | Why it is needed |
|---|---|---|
|
Write |
Required so your Redpanda cluster and the underlying GKE cluster can write operational logs to Cloud Logging in your project. |
Optional feature permissions
|
The following permissions support Redpanda SQL. They are granted through a separate custom role (internally named for |
Manage Redpanda SQL storage buckets
Creates and manages the Cloud Storage bucket that holds Redpanda SQL metadata.
| Permission | Access | Why it is needed |
|---|---|---|
|
Write |
Required to create the Cloud Storage buckets used by Redpanda SQL. |
|
Delete |
Required to remove Redpanda SQL buckets when the feature or cluster is decommissioned. |
|
Write |
Required to configure security, lifecycle, and other settings on the Cloud Storage buckets used by Redpanda SQL. |
|
Delete |
Required to remove Redpanda SQL objects during lifecycle operations or before deleting a bucket. |
|
Read |
Required to enumerate Redpanda SQL objects during reconciliation and cleanup. |
Full role definition
The complete set of permissions in the Redpanda agent custom role:
Terraform
permissions = [
"compute.addresses.get",
"compute.autoscalers.get",
"compute.autoscalers.list",
"compute.firewalls.create",
"compute.firewalls.delete",
"compute.firewalls.get",
"compute.firewalls.update",
"compute.forwardingRules.use",
"compute.globalOperations.get",
"compute.globalOperations.list",
"compute.instanceGroupManagers.create",
"compute.instanceGroupManagers.delete",
"compute.instanceGroupManagers.get",
"compute.instanceGroupManagers.list",
"compute.instanceGroupManagers.update",
"compute.instanceGroups.create",
"compute.instanceGroups.delete",
"compute.instanceGroups.get",
"compute.instanceGroups.update",
"compute.instances.create",
"compute.instances.delete",
"compute.instances.get",
"compute.instances.list",
"compute.instances.reset",
"compute.instances.setDeletionProtection",
"compute.instances.update",
"compute.instanceTemplates.create",
"compute.instanceTemplates.delete",
"compute.instanceTemplates.get",
"compute.instances.setLabels",
"compute.disks.get",
"compute.disks.list",
"compute.disks.setLabels",
"compute.networks.create",
"compute.networks.delete",
"compute.networks.getEffectiveFirewalls",
"compute.networks.update",
"compute.networks.updatePolicy",
"compute.projects.get",
"compute.regionOperations.get",
"compute.regionOperations.list",
"compute.regions.get",
"compute.regions.list",
"compute.routers.get",
"compute.serviceAttachments.create",
"compute.serviceAttachments.delete",
"compute.serviceAttachments.get",
"compute.serviceAttachments.list",
"compute.serviceAttachments.update",
"compute.subnetworks.get",
"compute.subnetworks.use",
"compute.zoneOperations.get",
"compute.zoneOperations.list",
"compute.zones.get",
"compute.zones.list",
"dns.changes.create",
"dns.changes.get",
"dns.changes.list",
"dns.managedZones.create",
"dns.managedZones.delete",
"dns.managedZones.get",
"dns.managedZones.list",
"dns.managedZones.update",
"dns.projects.get",
"dns.resourceRecordSets.create",
"dns.resourceRecordSets.delete",
"dns.resourceRecordSets.get",
"dns.resourceRecordSets.list",
"dns.resourceRecordSets.update",
"iam.roles.create",
"iam.roles.delete",
"iam.roles.get",
"iam.roles.list",
"iam.roles.undelete",
"iam.roles.update",
"iam.serviceAccounts.actAs",
"iam.serviceAccounts.create",
"iam.serviceAccounts.delete",
"iam.serviceAccounts.get",
"iam.serviceAccounts.getIamPolicy",
"iam.serviceAccounts.setIamPolicy",
"iam.serviceAccounts.update",
"logging.logEntries.create",
"resourcemanager.projects.get",
"resourcemanager.projects.getIamPolicy",
"resourcemanager.projects.setIamPolicy",
"storage.buckets.get",
"storage.buckets.getIamPolicy",
"storage.buckets.setIamPolicy",
"compute.forwardingRules.create",
"compute.forwardingRules.delete",
"compute.forwardingRules.get",
"compute.forwardingRules.setLabels",
"compute.forwardingRules.setTarget",
"compute.forwardingRules.pscCreate",
"compute.forwardingRules.pscDelete",
"compute.forwardingRules.pscSetLabels",
"compute.forwardingRules.pscSetTarget",
"compute.forwardingRules.pscUpdate",
"compute.instances.use",
"compute.networks.use",
"compute.regionBackendServices.create",
"compute.regionBackendServices.delete",
"compute.regionBackendServices.get",
"compute.regionBackendServices.use",
"compute.regionNetworkEndpointGroups.attachNetworkEndpoints",
"compute.regionNetworkEndpointGroups.create",
"compute.regionNetworkEndpointGroups.delete",
"compute.regionNetworkEndpointGroups.detachNetworkEndpoints",
"compute.regionNetworkEndpointGroups.get",
"compute.regionNetworkEndpointGroups.use",
"secretmanager.secrets.list",
"secretmanager.secrets.delete",
"serviceusage.services.enable",
"serviceusage.services.get",
"serviceusage.services.list",
]Service account credential rotation
To rotate service account credentials for your BYOC cluster, contact Redpanda Support with your cluster ID, the service accounts that require rotation, and your target timeline.
|
GCP service account credential rotation for BYOC clusters is not self-service. Rotating these credentials without coordinating with Redpanda can disrupt agent connectivity, monitoring, and Tiered Storage uploads, and can leave the cluster stuck and unable to complete future operations. |
