# Use the Control Plane API with BYOC > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt) --- title: Use the Control Plane API with BYOC latest-operator-version: v26.1.4 latest-console-tag: v3.7.3 latest-connect-version: 4.93.0 latest-redpanda-tag: v26.1.9 docname: api/cloud-byoc-controlplane-api page-component-name: cloud-data-platform page-version: master page-component-version: master page-component-title: Cloud page-relative-src-path: api/cloud-byoc-controlplane-api.adoc page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/manage/pages/api/cloud-byoc-controlplane-api.adoc description: Use the Control Plane API to manage resources in your Redpanda Cloud BYOC environment. page-git-created-date: "2024-08-01" page-git-modified-date: "2025-03-20" --- The Redpanda Cloud API is a collection of REST APIs that allow you to interact with different parts of Redpanda Cloud. The Control Plane API enables you to programmatically manage your organization’s Redpanda infrastructure outside of the Cloud UI. You can call the API endpoints directly, or use tools like Terraform or Python scripts to automate cluster management. See [Control Plane API](https://docs.redpanda.com/api/doc/cloud-controlplane/) for the full API reference documentation. ## [](#control-plane-api)Control Plane API The Control Plane API is one central API that allows you to provision clusters, networks, and resource groups. The Control Plane API consists of the following endpoint groups: - [Clusters](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-clusters) - [Networks](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-networks) - [Operations](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-operations) - [Resource Groups](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-resource-groups) - [Control Plane Role Bindings](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-control-plane-role-bindings) - [Control Plane Users](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-control-plane-users) - [Control Plane Service Accounts](https://docs.redpanda.com/api/doc/cloud-controlplane/group/endpoint-control-plane-service-accounts) ## [](#lro)Long-running operations Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of [`POST /clusters`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster): ```bash { "operation": { "id": "cqfc6vdmvio001r4vu4", "metadata": { "@type": "type.googleapis.com/redpanda.api.controlplane.v1.CreateClusterMetadata", "cluster_id": "cqg168balf4e4pm8ptu" }, "state": "STATE_IN_PROGRESS", "started_at": "2024-07-23T20:31:29.948Z", "type": "TYPE_CREATE_CLUSTER", "resource_id": "cqg168balf4e4pm8ptu" } } ``` The response object represents the long-running operation of creating a cluster. Cluster creation is an example of an operation that can take a longer period of time to complete. ### [](#check-operation-state)Check operation state To check the progress of an operation, make a request to the [`GET /operations/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation) endpoint using the operation ID as a parameter: ```bash curl -H "Authorization: Bearer " https://api.redpanda.com/v1/operations/ ``` > 💡 **TIP** > > When using a shell substitution variable for the token, use double quotes to wrap the header value. The response contains the current state of the operation: `IN_PROGRESS`, `COMPLETED`, or `FAILED`. ## [](#cluster-tiers)Cluster tiers When you create a BYOC or Dedicated cluster, you select a usage tier. Each tier provides tested and guaranteed workload configurations for throughput, partitions (pre-replication), and connections. Availability depends on the region and the cluster type. See the full list of regions, zones, and tiers available with each provider in the [Control Plane API reference](https://docs.redpanda.com/api/doc/cloud-controlplane/topic/topic-regions-and-usage-tiers). ## [](#create-a-cluster)Create a cluster To create a new cluster, first create a resource group and network, if you have not already done so. ### [](#create-a-resource-group)Create a resource group Create a resource group by making a POST request to the [`/v1/resource-groups`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-resourcegroupservice_createresourcegroup) endpoint. Pass a name for your resource group in the request body. ```bash curl -H 'Content-Type: application/json' \ -H "Authorization: Bearer " \ -d '{ "resource_group": { "name": "" } }' -X POST https://api.redpanda.com/v1/resource-groups ``` A resource group ID is returned. Pass this ID later when you call the Create Cluster endpoint. ### [](#create-a-network)Create a network Create a network by making a request to [`POST /v1/networks`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-networkservice_createnetwork). Choose a [CIDR range](https://docs.redpanda.com/cloud-data-platform/networking/cidr-ranges/) that does not overlap with your existing VPCs or your Redpanda network. ```bash curl -d \ '{ "network": { "cidr_block": "10.0.0.0/20", "cloud_provider": "CLOUD_PROVIDER_GCP", "cluster_type": "TYPE_BYOC", "name": "", "resource_group_id": "", "region": "us-west1" } }' -H "Content-Type: application/json" \ -H "Authorization: Bearer " -X POST https://api.redpanda.com/v1/networks ``` This endpoint returns a [long-running operation](#lro). ### [](#create-a-new-cluster)Create a new cluster After the network is created, make a request to the [`POST /v1/clusters`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster) with the resource group ID and network ID in the request body. ```bash curl -d \ '{ "cluster": { "cloud_provider": "CLOUD_PROVIDER_GCP", "connection_type": "CONNECTION_TYPE_PUBLIC", "name": "my-new-cluster", "resource_group_id": "", "network_id": "", "region": "us-west1", "throughput_tier": "tier-1-gcp-um4g", "type": "TYPE_BYOC", "zones": [ "us-west1-a", "us-west1-b", "us-west1-c" ], "cluster_configuration": { "custom_properties": { "audit_enabled":true } } } }' -H "Content-Type: application/json" \ -H "Authorization: Bearer " -X POST https://api.redpanda.com/v1/clusters ``` The Create Cluster endpoint returns a [long-running operation](#lro). When the operation completes, you can retrieve cluster details by calling [`GET /v1/clusters/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster), and passing the cluster ID as a parameter. #### [](#additional-steps-to-create-a-byoc-cluster)Additional steps to create a BYOC cluster 1. Ensure that you have installed `rpk`. 2. After making a Create Cluster request, run `rpk cloud byoc`. Pass `metadata.cluster_id` from the Create Cluster response: ##### AWS ```bash rpk cloud byoc aws apply --redpanda-id= ``` ##### Azure ```bash rpk cloud byoc azure apply --redpanda-id= --subscription-id= ``` ##### GCP ```bash rpk cloud byoc gcp apply --redpanda-id= --project-id= ``` ## [](#update-cluster-configuration)Update cluster configuration To update your cluster configuration properties, make a request to the [`PATCH /v1/clusters/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster) endpoint, passing the cluster ID as a parameter. Include the properties to update in the request body. ```bash curl -H "Authorization: Bearer " \ -H 'accept: application/json'\ -H 'content-type: application/json' \ -d '{ "cluster_configuration": { "custom_properties": { "iceberg_enabled":true, "iceberg_catalog_type":"rest" } } }' -X PATCH "https://api.cloud.redpanda.com/v1/clusters/" ``` The Update Cluster endpoint returns a [long-running operation](#lro). [Check the operation state](#check-operation-state) to verify that the update is complete. ## [](#delete-a-cluster)Delete a cluster To delete a cluster, make a request to the [`DELETE /v1/clusters/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_deletecluster) endpoint, passing the cluster ID as a parameter. This is a [long-running operation](#lro). ```bash curl -H "Authorization: Bearer " -X DELETE https://api.redpanda.com/v1/clusters/ ``` ### [](#additional-steps-to-delete-a-byoc-cluster)Additional steps to delete a BYOC cluster 1. Make a request to [`GET /v1/clusters/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-clusterservice_getcluster) to check the state of the cluster. Wait until the state is `STATE_DELETING_AGENT`. 2. After the state changes to `STATE_DELETING_AGENT`, run `rpk cloud byoc` to destroy the agent. #### AWS ```bash rpk cloud byoc aws destroy --redpanda-id= ``` #### Azure ```bash rpk cloud byoc azure destroy --redpanda-id= ``` #### GCP ```bash rpk cloud byoc gcp destroy --redpanda-id= --project-id= ``` 3. When the cluster is deleted, the delete operation’s state changes to `STATE_COMPLETED`. At this point, you may make a DELETE request to the [`/v1/networks/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-networkservice_deletenetwork) endpoint to delete the network. This is a long running operation. 4. Optional: After the network is deleted, make a request to [`DELETE /v1/resource-groups/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-resourcegroupservice_deleteresourcegroup) to delete the resource group. ## [](#manage-rbac)Manage RBAC You can also use the Control Plane API to manage [RBAC configurations](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/rbac/). ### [](#list-role-bindings)List role bindings To see role assignments for IAM user and service accounts, make a GET request to the [`/v1/role-bindings`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-rolebindingservice_listrolebindings) endpoint. ```bash curl https://api.redpanda.com/v1/role-bindings?filter.role_name=&filter.scope.resource_type=SCOPE_RESOURCE_TYPE_CLUSTER \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` ### [](#get-role-binding)Get role binding To see roles assignments for a specific IAM account, make a GET request to the [`/v1/role-bindings/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-rolebindingservice_getrolebinding) endpoint, passing the role binding ID as a parameter. ```bash curl "https://api.redpanda.com/v1/role-bindings/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` ### [](#get-user)Get user To see details of an IAM user account, make a GET request to the [`/v1/users/{id}`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-userservice_getuser) endpoint, passing the user account ID as a parameter. ```bash curl "https://api.redpanda.com/v1/users/ \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` ### [](#create-role-binding)Create role binding To assign a role to an IAM user or service account, make a POST request to the [`/v1/role-bindings`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-rolebindingservice_createrolebinding) endpoint. Specify the role and scope, which includes the specific resource ID and an optional resource type, in the request body. ```bash curl -X POST "https://api.redpanda.com/v1/role-bindings" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "role_name": "", "account_id": "", "scope": { "resource_type": "SCOPE_RESOURCE_TYPE_CLUSTER", "resource_id": "" } }' ``` For ``, use one of roles listed in [Predefined roles](https://docs.redpanda.com/cloud-data-platform/security/authorization/rbac/rbac/#predefined-roles) (`Reader`, `Writer`, `Admin`). ### [](#create-service-account)Create service account > 📝 **NOTE** > > Service accounts are assigned the Admin role for all resources in the organization. To create a new service account, make a POST request to the [`/v1/service-accounts`](https://docs.redpanda.com/api/doc/cloud-controlplane/operation/operation-serviceaccountservice_createserviceaccount) endpoint, with a service account name and optional description in the request body. ```bash curl -X POST "https://api.redpanda.com/v1/service-accounts" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "service_account": { "name": "", "description": "" } }' ``` ## [](#next-steps)Next steps - [Use the Data Plane APIs](https://docs.redpanda.com/cloud-data-platform/manage/api/cloud-dataplane-api/)