Use the Control Plane API
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 cloud environment outside of the Redpanda Cloud UI. You can call the API endpoints directly, or use tools like Terraform or Python scripts to automate cluster management.
For the full Cloud API reference documentation, see Redpanda Cloud API Reference.
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 endpoints:
Long-running operations
Some endpoints do not directly return the resource itself, but instead return an operation. The following is an example response of Create Network (POST /networks
):
"operation": {
"id": "cl5nlt1c1scg01plkoe0",
"metadata": {
"@type": "type.googleapis.com/redpanda.api.controlplane.v1beta2.CreateNetworkMetadata",
"network_id": "cl5o0td1dafe70i7460g"
},
"state": "STATE_IN_PROGRESS",
"started_at": "2023-11-08T12:35:01.957Z",
"finished_at": null
}
The response object represents the long-running operation of creating a network. Network creation is an example of an operation that can take a longer period of time to complete.
Check operation state
To check the progress of an operation, make a request to the GET /operations/{id}
endpoint using the operation ID as a parameter:
curl https://api.redpanda.com/v1beta2/operations/<operation-id>
The response contains the current state of the operation: IN_PROGRESS
, COMPLETED
, or FAILED
.
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, logical partitions, 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 API reference.
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 by making a POST request to the /v1beta2/resource-groups
endpoint. Pass a name for your resource group in the request body.
curl -H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
"name": "<resource-group-name>"
}' -X POST https://api.redpanda.com/v1beta2/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 by making a request to POST /v1beta2/networks
.
Choose a CIDR range that does not overlap with your existing VPCs or your Redpanda network.
curl -d \
'{
"cidr_block": "10.0.0.0/20",
"cloud_provider": "CLOUD_PROVIDER_GCP",
"cluster_type": "TYPE_DEDICATED",
"name": "<network-name>",
"resource_group_id": "<resource-group-id>",
"region": "us-west1"
}' -X POST https://api.redpanda.com/v1beta2/networks
This endpoint returns a long-running operation.
Create a new cluster
After the network is created, make a request to the POST /v1beta2/clusters
with the resource group ID and network ID in the request body.
curl -d \
'{
"cloud_provider": "CLOUD_PROVIDER_GCP",
"connection_type": "CONNECTION_TYPE_PUBLIC",
"name": "my-new-cluster",
"resource_group_id": "<resource-group-id>",
"network_id": "<network-id>",
"region": "us-west1",
"throughput_tier": "tier-1-gcp-um4g",
"type": "TYPE_DEDICATED",
"zones": [
"us-west1-a",
"us-west1-b",
"us-west1-c"
]
}' -X POST https://api.redpanda.com/v1beta2/clusters
The Create Cluster endpoint returns a long-running operation. When the operation is completed, you can retrieve cluster details by calling GET /v1beta2/clusters/{id}
, passing the cluster ID as a parameter.
Additional steps to create a BYOC cluster
-
Ensure that you have installed
rpk
. -
After making a Create Cluster request, run
rpk cloud byoc
. Passmetadata.cluster_id
from the Create Cluster response:-
GCP
-
AWS
rpk cloud byoc gcp apply --redpanda-id=<metadata.cluster_id> --project-id=<gcp-project-id>
rpk cloud byoc aws apply --redpanda-id=<metadata.cluster_id>
-
Delete a cluster
To delete a cluster, make a request to the DELETE /v1beta2/clusters/{id}
endpoint, passing the cluster ID as a parameter. This is a long-running operation.
curl -X DELETE https://api.redpanda.com/v1beta2/clusters/<cluster_id>
Additional steps to delete a BYOC cluster
-
Make a request to
GET /v1beta2/clusters/{id}
to check the state of the cluster. Wait until the state isSTATE_DELETING_AGENT
. -
After the state changes to
STATE_DELETING_AGENT
, runrpk cloud byoc
to destroy the agent.-
GCP
-
AWS
rpk cloud byoc gcp destroy --redpanda-id=<cluster-id> --project-id=<gcp-project-id>
rpk cloud byoc aws destroy --redpanda-id=<cluster-id>
-
-
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/v1beta2/networks/{id}
endpoint to delete the network. This is a long running operation. -
Optional: After the network is deleted, make a request to
DELETE /v1beta2/resource-groups/{id}
to delete the resource group.