Important

These cluster management APIs are currently available on Confluent Cloud in an Early Access Program to a very limited set of early adopters. An early access feature is a component of Confluent Cloud introduced to gain feedback. This feature should be used only for evaluation and non-production testing purposes or to provide feedback to Confluent, particularly as it becomes more widely available in follow-on preview editions. If you would like to participate in the Early Access Program, email ccloud-api-access+v2-early-access@confluent.io.

Early Access Program features are intended for evaluation use in development and testing environments only, and not for production use. The warranty, SLA, and Support Services provisions of your agreement with Confluent do not apply to Early Access Program features. Early Access Program features are considered to be a Proof of Concept as defined in the Confluent Cloud Terms of Service. Confluent may discontinue providing preview releases of the Early Access Program features at any time in Confluent’s sole discretion.

Confluent Cloud Cluster Management APIs (Early Access)

In addition to managing Apache Kafka® clusters with the Confluent Cloud UI, you can use a collection of REST APIs to perform operations on Standard and Basic Kafka clusters. Like other Confluent Cloud APIs, the APIs have predictable resource-oriented URLs, transport data using JSON, and use standard HTTP verbs, response codes, authentication, and design principles.

You can perform the following operations with this API:

Base URL

The base URL for all cluster management calls is:

https://api.confluent.cloud/

Object model

All Confluent objects share a set of common properties:

  • api_version: Indicates the API version for the object.
  • kind: Indicates what kind of object it is.
  • id: An identifier for the object.

For more about the object model, see Confluent Cloud APIs.

Authentication

Each request to the cluster endpoint must include an Authorization: Basic {key} header that contains a Confluent Cloud API key. For more detail on creating or accessing your Confluent Cloud API keys, see Confluent Cloud API keys. API requests without a correct authentication header will fail. A key grants access to a single Confluent cluster.

An API key is owned by a User or Service Account and inherits the permissions granted to the owner. API keys grant many privileges and should not be shared publicly to GitHub, in client-side code, and so forth.

HTTP Basic authorization requires the key to be colon-separated and base-64 encoded.

For example, if your API Key is abcp7DEFGH123456789 and the corresponding Secret is XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO, generate a base-64 encoded header with the following command on MacOS or Linux:

echo -n "abcp7DEFGH123456789:XNCIW93I2L1SQPJSJ823K1LS902KLDFMCZPWEO" | base64

The resulting authorization header will be:

Authorization: Basic QUJDREVGR0gxMjM0NTY3ODk6WE5DSVc5M0kyTDFTUVBKU0o4MjNLMUxTOTAyS0xERk1DWlBXRU8=

Alternatively, if testing using a tool such as Postman, specify the API Key as the Username and the API Secret as the password and Postman will provide the encoding.

List clusters

If you have operator or admin access to an environment, you can list all of the Basic or Standard Kafka clusters with a GET call to the cluster endpoint. In the request, you specify the environment ID. This call does not require a payload.

GET /cmk/v2/clusters?environment={environment_id}

Input parameters

environment_id The ID for the environment that contains the clusters to list

Return values

A successful call returns an HTTP 200 OK and a JSON payload that contains a list of clusters for the environment. The response describes each cluster including the following information:

  • The type of cluster
  • The cloud provider and region for the cluster
  • The cluster status
  • Info about the environment that contains the list of clusters

Note that the returned list of clusters are sorted by created-at field value by default.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "api_version":"cmk/v2",
    "kind": "KafkaCluster",
    "data":[
     {
         "id":"lkc-8abcde",
         "metadata":{
             "created_at":"2021-05-06T16:33:31.897453Z",
             "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1/kafka=lkc-8abcde",
             "self":"https://api.confluent.cloud/cmk/v2/clusters/lkc-8abcde",
             "updated_at":"2021-05-06T16:33:31.897453Z"
         },
         "spec":{
             "availability":"SINGLE_ZONE",
             "cluster_type":"BASIC",
             "display_name":"cluster_basic",
             "environment":{
                 "api_version":"v2",
                 "id":"env-test1",
                 "kind":"Environment",
                 "related":"https://api.confluent.cloud/v2/environments/env-test1",
                 "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1"
             },
             "http_endpoint":"https://abcp7-0wg55.us-central1.gcp.api.confluent.cloud/:443",
             "kafka_bootstrap_endpoint":"SASL_SSL://abcp7-0wg55.us-central1.gcp.api.confluent.cloud:9092",
             "placement":{
                 "cloud":"GCP",
                 "kind":"Location",
                 "region":"us-central1"
             }
         },
         "status":{
             "phase":"PROVISIONED"
         }
     },
     {
         "id":"lkc-w1234j",
         "metadata":{
             "created_at":"2021-05-06T16:33:55.22847Z",
             "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1/kafka=lkc-w1234j",
             "self":"https://api.confluent.cloud/cmk/v2/clusters/lkc-w1234j",
             "updated_at":"2021-05-06T16:33:55.22847Z"
         },
         "spec":{
             "availability":"SINGLE_ZONE",
             "cluster_type":"STANDARD",
             "display_name":"cluster_standard",
             "environment":{
                 "api_version":"v2",
                 "id":"env-test1",
                 "kind":"Environment",
                 "related":"https://api.confluent.cloud/v2/environments/env-test1",
                 "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1"
             },
             "http_endpoint":"https://abcp7-0wg55.us-central1.gcp.confluent.cloud:443",
             "kafka_bootstrap_endpoint":"SASL_SSL://abcp7-0wg55.us-central1.gcp.confluent.cloud:9092",
             "placement":{
                 "cloud":"GCP",
                 "kind":"Location",
                 "region":"us-central1"
             }
         },
         "status":{
             "phase":"PROVISIONED"
         }
     }
     ]
 }

For details on the types of responses you can expect when a call fails, see Failures.

Create a cluster

If you have operator or admin access to an environment, you can create a Basic or Standard Kafka cluster with a POST call to the cluster endpoint.

POST /cmk/v2/clusters

You include a JSON payload that contains a spec object with the following:

  • display_name: The display name of the cluster.
  • availability: The cluster availability: SINGLE_ZONE or MULTI_ZONE.
  • A placement object that contains:
    • kind: Location
    • cloud: GCP, AZURE or AWS
    • region: A valid region for the cloud provider. See Cloud Providers and Regions for a full list.
  • cluster_type: BASIC or STANDARD
  • environment object that contains:
    • id: The ID of the environment that contains the cluster

The following example demonstrates the request format:

POST /cmk/v2/clusters HTTP/1.1
Host: api.confluent.cloud

{
 "spec": {
     "display_name": "cluster_gcp",
     "availability": "SINGLE_ZONE",
     "placement": {
       "kind": "Location",
       "cloud": "GCP",
       "region": "us-central1"
     },
     "cluster_type": "BASIC",
     "environment": {
       "id": "{{environment_id}}"
     }
   }
}

Return values

Success returns an HTTP 202 ACCEPTED with a JSON payload that describes the cluster. The cluster description includes the following:

  • The type of cluster
  • The cloud provider and region for the cluster
  • The cluster status
  • Info about the environment that contains the cluster
HTTP/1.1 202 ACCEPTED
Content-Type: application/json

 {
 "api_version":"cmk/v2",
 "id":"lkc-r123v4",
 "kind":"KafkaCluster",
 "metadata":{
     "created_at":"2021-05-26T17:56:22.862Z",
     "resource_name":"crn://confluent.cloud/organization=12345/environment=env-abcp7/kafka=lkc-r123v4",
     "self":"https://api.confluent.cloud/cmk/v2/clusters/lkc-r123v4",
     "updated_at":"2021-05-26T17:56:22.862Z"
 },
 "spec":{
     "availability":"SINGLE_ZONE",
     "cluster_type":"BASIC",
     "display_name":"cluster_gcp",
     "environment":{
         "api_version":"v2",
         "id":"env-abcp7",
         "kind":"Environment",
         "related":"https://api.confluent.cloud/v2/environments/env-abcp7",
         "resource_name":"crn://confluent.cloud/organization=98955/environment=env-abcp7"
     },
     "http_endpoint":"https://abcp7-0wg55.us-central1.gcp.confluent.cloud:443",
     "kafka_bootstrap_endpoint":"SASL_SSL://abcp7-0wg55.us-central1.gcp.confluent.cloud:9092",
     "placement":{
         "cloud":"GCP",
         "kind":"Location",
         "region":"us-central1"
     }
 },
 "status":{
     "phase":"PROVISIONING"
  }
 }

For details on the types of responses you can expect when a call fails, see Failures.

Read a cluster

If you have operator or admin access to an environment, you can make a GET call to the cluster endpoint to retrieve details about a specified cluster. You specify the environment and cluster IDs in the request. This call does not require a payload.

GET /cmk/v2/clusters/{cluster_id}?environment={environment_id}

Input parameters

environment_id The ID for the environment that contains the cluster to read.
cluster_id The ID for the cluster to read.

Return values

Success returns an HTTP 200 OK and the following JSON payload that describes the cluster, including the following:

  • The type of cluster
  • The cloud provider and region for the cluster
  • The cluster status
  • Info about the environment that contains the cluster
HTTP/1.1 200 OK
Content-Type: application/json

 {
     "api_version":"cmk/v2",
     "id":"abcp7-12345",
     "kind":"KafkaCluster",
     "metadata":{
         "created_at":"2021-05-26T18:30:58.028057Z",
         "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1/kafka=abcp7-12345",
         "self":"https://api.confluent.cloud/cmk/v2/clusters/abcp7-12345",
         "updated_at":"2021-05-26T18:31:12.471683461Z"
     },
     "spec":{
         "availability":"SINGLE_ZONE",
         "cluster_type":"STANDARD",
         "display_name":"update_name",
         "environment":{
             "api_version":"v2",
             "id":"env-test1",
             "kind":"Environment",
             "related":"https://api.confluent.cloud/v2/environments/env-test1",
             "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1"
     },
     "http_endpoint":"https://abcp7-0wg55.us-central1.gcp.confluent.cloud:443",
     "kafka_bootstrap_endpoint":"SASL_SSL://abcp7-0wg55.us-central1.gcp.confluent.cloud:9092",
     "placement":{
         "cloud":"GCP",
         "kind":"Location",
         "region":"us-central1"
      }
     },
     "status":{
       "phase":"PROVISIONED"
     }
 }

For details on the types of responses you can expect when a call fails, see Failures.

Update a cluster name or type

If you have operator or admin access to an environment, you can update the cluster type or change the name of a Basic or Standard Kafka cluster with an HTTP PATCH call to the cluster endpoint. You specify the environment and cluster IDs in the request, and include a payload that contains details of the change. You can specify one change in the request; either change the cluster type or update the name, but not both.

PATCH /cmk/v2/clusters/{cluster_id}?environment={environment_id}

Input parameters

environment_id The ID for the environment that contains the cluster to update.
cluster_id The ID for the cluster to update.

The JSON payload contains:

  • display_name or cluster_type and the new value.

The following example demonstrates the request format:

PATCH /cmk/v2/clusters/abcp7-12345?environment=env-test1 HTTP/1.1
Host: api.confluent.cloud

 {
   "spec": {
         "display_name": "updated_name",
         "environment": {
             "id": "string"
         }
   }
 }

Return values

Success returns a 200 OK and JSON payload that describes the updated cluster. Similiar to the other calls, the payload describes:

  • The type of cluster
  • The cloud provider and region for the cluster
  • The cluster status
  • Info about the environment that contains the cluster
HTTP/1.1 200 OK
Content-Type: application/json

 {
     "api_version":"cmk/v2",
     "id":"abcp7-12345",
     "kind":"KafkaCluster",
     "metadata":{
         "created_at":"2021-05-26T18:30:58.028057Z",
         "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1/kafka=abcp7-12345",
         "self":"https://api.confluent.cloud/cmk/v2/clusters/abcp7-12345",
         "updated_at":"2021-05-26T18:31:12.471683461Z"
     },
     "spec":{
         "availability":"SINGLE_ZONE",
         "cluster_type":"STANDARD",
         "display_name":"updated_name",
         "environment":{
             "api_version":"v2",
             "id":"env-test1",
             "kind":"Environment",
             "related":"https://api.confluent.cloud/v2/environments/env-test1",
             "resource_name":"crn://confluent.cloud/organization=123456/environment=env-test1"
     },
     "http_endpoint":"https://abcp7-0wg55.us-central1.gcp.confluent.cloud:443",
     "kafka_bootstrap_endpoint":"SASL_SSL://abcp7-0wg55.us-central1.gcp.confluent.cloud:9092",
     "placement":{
         "cloud":"GCP",
         "kind":"Location",
         "region":"us-central1"
      }
     },
     "status":{
         "phase":"PROVISIONED"
     }
 }

For details on the types of responses you can expect when a call fails, see Failures.

Delete a cluster

If you have operator or admin access to an environment, you can delete the name of a Basic or Standard Kafka cluster with a DELETE call to the cluster endpoint. You specify the environment and cluster IDs in the request, and the call does not require a payload.

DELETE /cmk/v2/clusters/{cluster_id}?environment={environment_id}

Input parameters

environment_id The ID for the environment that contains the cluster to delete.
cluster_id The ID for the cluster to delete.

Return values

Success returns an HTTP 204 No Content.

For details on the types of responses you can expect when a call fails, see Failures.

Failures

When a failure occurs, you could receive one of the following statuses:

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 429 Rate Limit Exceeded
  • 500 Oops something went wrong

The failure message body will provide more detail about the failure reason and an ID to use with Confluent support if you need help solving the problem. The following example shows a 400 Bad Request error with details about why the call failed.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json

{
    "errors": [
      {
           "id": "c9cb03c2878ca172bbd0072bd99a9aaa",
            "status": "400",
            "code": "parameter_missing",
            "detail": "Missing Parameter",
            "source": {
               "parameter": "environment"
             }
      }
   ]
 }