URI HTTP methods Schemas Properties See also

Cluster

Represents an Amazon MSK cluster.

URI

/v1/clusters/clusterArn

HTTP methods

GET

Operation ID: DescribeCluster

Returns a description of the MSK cluster whose Amazon Resource Name (ARN) is specified in the request. The following is a Python 3.6 example of how to use this operation. Before you run this Python script, replace the example cluster Amazon Resource Name (ARN) with the ARN of the cluster you want to describe. If you don't know the ARN of the cluster, you can use the ListClusters operation to list all the clusters and see their ARNs and full descriptions.


import boto3

client = boto3.client('kafka')

response = client.describe_cluster(
    ClusterArn='arn:aws:kafka:us-east-1:0123456789019:cluster/SalesCluster/abcd1234-abcd-cafe-abab-9876543210ab-4'
)

print(response)

Note that the response to this operation only includes the ZookeeperConnectStringTls node in clusters created with Apache Kafka version 2.5.1 and later.

Path parameters
Name	Type	Required	Description
`clusterArn`	String	True	The Amazon Resource Name (ARN) that uniquely identifies the cluster.

Responses
Status code	Response model	Description
`200`	`DescribeClusterResponse`	Successful response.
`400`	`Error`	The request isn't valid because the input is incorrect. Correct your input and then submit it again.
`401`	`Error`	The request is not authorized. The provided credentials couldn't be validated.
`403`	`Error`	Access forbidden. Check your credentials and then retry your request.
`404`	`Error`	The resource could not be found due to incorrect input. Correct the input, then retry the request.
`429`	`Error`	429 response
`500`	`Error`	There was an unexpected internal server error. Retrying your request might resolve the issue.
`503`	`Error`	503 response

DELETE

Operation ID: DeleteCluster

Deletes the MSK cluster specified by the Amazon Resource Name (ARN) in the request, and all its revisions.

Path parameters
Name	Type	Required	Description
`clusterArn`	String	True	The Amazon Resource Name (ARN) that uniquely identifies the cluster.

Query parameters
Name	Type	Required	Description
`currentVersion`	String	False	The current version of the MSK cluster.

Responses
Status code	Response model	Description
`200`	`DeleteClusterResponse`	Successful response.
`400`	`Error`	The request isn't valid because the input is incorrect. Correct your input and then submit it again.
`401`	`Error`	The request is not authorized. The provided credentials couldn't be validated.
`403`	`Error`	Access forbidden. Check your credentials and then retry your request.
`404`	`Error`	The resource could not be found due to incorrect input. Correct the input, then retry the request.
`429`	`Error`	429 response
`500`	`Error`	There was an unexpected internal server error. Retrying your request might resolve the issue.
`503`	`Error`	503 response

OPTIONS

Enable CORS by returning the correct headers.

Path parameters
Name	Type	Required	Description
`clusterArn`	String	True	The Amazon Resource Name (ARN) that uniquely identifies the cluster.

Responses
Status code	Response model	Description
`200`	None	Default response for CORS method

Schemas

Response bodies


{
  "clusterInfo": {
    "encryptionInfo": {
      "encryptionInTransit": {
        "inCluster": boolean,
        "clientBroker": enum
      },
      "encryptionAtRest": {
        "dataVolumeKMSKeyId": "string"
      }
    },
    "zookeeperConnectString": "string",
    "creationTime": "string",
    "customerActionStatus": enum,
    "zookeeperConnectStringTls": "string",
    "loggingInfo": {
      "brokerLogs": {
        "s3": {
          "bucket": "string",
          "prefix": "string",
          "enabled": boolean
        },
        "firehose": {
          "deliveryStream": "string",
          "enabled": boolean
        },
        "cloudWatchLogs": {
          "logGroup": "string",
          "enabled": boolean
        }
      },
      "authorizerLogs": {
        "s3": {
          "bucket": "string",
          "prefix": "string",
          "enabled": boolean
        },
        "firehose": {
          "deliveryStream": "string",
          "enabled": boolean
        },
        "cloudWatchLogs": {
          "logGroup": "string",
          "enabled": boolean
        }
      }
    },
    "currentVersion": "string",
    "tags": {
    },
    "numberOfBrokerNodes": integer,
    "clusterArn": "string",
    "activeOperationArn": "string",
    "enhancedMonitoring": enum,
    "storageMode": enum,
    "clusterName": "string",
    "stateInfo": {
      "code": "string",
      "message": "string"
    },
    "clientAuthentication": {
      "sasl": {
        "iam": {
          "enabled": boolean
        },
        "scram": {
          "enabled": boolean
        }
      },
      "unauthenticated": {
        "enabled": boolean
      },
      "tls": {
        "certificateAuthorityArnList": [
          "string"
        ],
        "enabled": boolean
      }
    },
    "state": enum,
    "brokerNodeGroupInfo": {
      "clientSubnets": [
        "string"
      ],
      "zoneIds": [
        "string"
      ],
      "instanceType": "string",
      "connectivityInfo": {
        "vpcConnectivity": {
          "clientAuthentication": {
            "sasl": {
              "iam": {
                "enabled": boolean
              },
              "scram": {
                "enabled": boolean
              }
            },
            "tls": {
              "enabled": boolean
            }
          }
        },
        "publicAccess": {
          "type": "string"
        },
        "networkType": "string"
      },
      "securityGroups": [
        "string"
      ],
      "brokerAZDistribution": enum,
      "storageInfo": {
        "ebsStorageInfo": {
          "provisionedThroughput": {
            "volumeThroughput": integer,
            "enabled": boolean
          },
          "volumeSize": integer
        }
      }
    },
    "openMonitoring": {
      "prometheus": {
        "nodeExporter": {
          "enabledInBroker": boolean
        },
        "jmxExporter": {
          "enabledInBroker": boolean
        }
      }
    },
    "rebalancing": {
      "status": enum
    },
    "currentBrokerSoftwareInfo": {
      "configurationRevision": integer,
      "kafkaVersion": "string",
      "configurationArn": "string"
    }
  }
}


{
  "clusterArn": "string",
  "state": enum
}


{
  "message": "string",
  "invalidParameter": "string"
}

Properties

AuthorizerLogs

Authorizer Logs details for cluster.

Property	Type	Required	Description
`cloudWatchLogs`	CloudWatchLogs	False	CloudWatch Log destination details.
`firehose`	Firehose	False	Firehose Log destination details.
`s3`	S3	False	S3 Log destination details.

BrokerAZDistribution

This parameter is currently not in use.

DEFAULT

BrokerLogs

The broker logs configuration for this MSK cluster.

Property	Type	Required	Description
`cloudWatchLogs`	CloudWatchLogs	False	Details of the CloudWatch Logs destination for broker logs.
`firehose`	Firehose	False	Details of the Kinesis Data Firehose delivery stream that is the destination for broker logs.
`s3`	S3	False	Details of the Amazon S3 destination for broker logs.

BrokerNodeGroupInfo

Describes the setup to be used for the broker nodes in the cluster.

Property	Type	Required	Description
`brokerAZDistribution`	BrokerAZDistribution	False	This parameter is currently not in use.
`clientSubnets`	Array of type string	True	The list of subnets to connect to in the client virtual private cloud (VPC). Amazon creates elastic network interfaces inside these subnets. Client applications use elastic network interfaces to produce and consume data. If you use the US West (N. California) Region, specify exactly two subnets. For other Regions where Amazon MSK is available, you can specify either two or three subnets. The subnets that you specify must be in distinct Availability Zones. When you create a cluster, Amazon MSK distributes the broker nodes evenly across the subnets that you specify. Client subnets can't occupy the Availability Zone with ID `use1-az3`.
`connectivityInfo`	ConnectivityInfo	False	Information about the cluster's connectivity setting.
`instanceType`	string MinLength: 5 MaxLength: 32	True	The type of Amazon EC2 instances to use for brokers. The following instance types are allowed: kafka.m5.large, kafka.m5.xlarge, kafka.m5.2xlarge, kafka.m5.4xlarge, kafka.m5.8xlarge, kafka.m5.12xlarge, kafka.m5.16xlarge, and kafka.m5.24xlarge.
`securityGroups`	Array of type string	False	The security groups to associate with the elastic network interfaces in order to specify who can connect to and communicate with the Amazon MSK cluster. If you don't specify a security group, Amazon MSK uses the default security group associated with the VPC. If you specify security groups that were shared with you, you must ensure that you have permissions to them. Specifically, you need the `ec2:DescribeSecurityGroups` permission.
`storageInfo`	StorageInfo	False	Contains information about storage volumes attached to Amazon MSK broker nodes.
`zoneIds`	Array of type string	False	The zoneIds for brokers in customer account.

BrokerSoftwareInfo

Information about the current software installed on the cluster.

Property Type Required Description

Property	Type	Required	Description
`configurationArn`	string	False	The Amazon Resource Name (ARN) of the configuration used for the cluster. This field isn't visible in this preview release.
`configurationRevision`	integer Format: int64	False	The revision of the configuration to use. This field isn't visible in this preview release.
`kafkaVersion`	string	False	The version of Apache Kafka. You can use Amazon MSK to create clusters that use Apache Kafka versions 1.1.1 and 2.2.1. See Apache Kafka Versions.

configurationArn

string

False

The Amazon Resource Name (ARN) of the configuration used for the cluster. This field isn't visible in this preview release.

configurationRevision

integer

Format: int64

False

The revision of the configuration to use. This field isn't visible in this preview release.

kafkaVersion

string

False

The version of Apache Kafka. You can use Amazon MSK to create clusters that use Apache Kafka versions 1.1.1 and 2.2.1. See Apache Kafka Versions.

ClientAuthentication

Includes all client authentication information.

Property	Type	Required	Description
`sasl`	Sasl	False	Details for client authentication using SASL. To turn on SASL, you must also turn on `EncryptionInTransit` by setting `inCluster` to true. You must set `clientBroker` to either `TLS` or `TLS_PLAINTEXT`. If you choose `TLS_PLAINTEXT`, then you must also set `unauthenticated` to true.
`tls`	Tls	False	Details for ClientAuthentication using TLS. To turn on TLS access control, you must also turn on `EncryptionInTransit` by setting `inCluster` to true and `clientBroker` to `TLS`.
`unauthenticated`	Unauthenticated	False	Details for ClientAuthentication using no authentication.

ClientBroker

Client-broker encryption in transit setting.

TLS
TLS_PLAINTEXT
PLAINTEXT

CloudWatchLogs

Details of the CloudWatch Logs destination for broker logs.

Property	Type	Required	Description
`enabled`	boolean	True	Specifies whether broker logs get sent to the specified CloudWatch Logs destination.
`logGroup`	string	False	The CloudWatch log group that is the destination for broker logs.

ClusterInfo

Returns information about a cluster.

Property	Type	Required	Description
`activeOperationArn`	string	False	Arn of active cluster operation.
`brokerNodeGroupInfo`	BrokerNodeGroupInfo	False	Information about the broker nodes.
`clientAuthentication`	ClientAuthentication	False	Includes all client authentication information.
`clusterArn`	string	False	The Amazon Resource Name (ARN) that uniquely identifies the cluster.
`clusterName`	string	False	The name of the cluster.
`creationTime`	string	False	The time when the cluster was created.
`currentBrokerSoftwareInfo`	BrokerSoftwareInfo	False	Information about the version of software currently deployed on the brokers in the cluster.
`currentVersion`	string	False	The current version of the MSK cluster. Cluster versions aren't simple integers. You can obtain the current version by describing the cluster. An example version is `KTVPDKIKX0DER`.
`customerActionStatus`	CustomerActionStatus	False	Determines if there is an action required from the customer.
`encryptionInfo`	EncryptionInfo	False	Includes all encryption-related information.
`enhancedMonitoring`	EnhancedMonitoring	False	Specifies which Apache Kafka metrics Amazon MSK gathers and sends to Amazon CloudWatch for this cluster. This property has three possible values: `DEFAULT`, `PER_BROKER`, and `PER_TOPIC_PER_BROKER`. For a list of the metrics associated with each of these three levels of monitoring, see Monitoring.
`loggingInfo`	LoggingInfo	False	You can configure your MSK cluster to send broker logs to different destination types. This is a container for the configuration details related to broker logs.
`numberOfBrokerNodes`	integer	False	The number of broker nodes in the cluster.
`openMonitoring`	OpenMonitoring	False	Settings for open monitoring using Prometheus.
`rebalancing`	Rebalancing	False	Specifies if intelligent rebalancing is turned on for your MSK Provisioned cluster with Express brokers. For all new Express-based clusters that you create, intelligent rebalancing is turned on by default.
`state`	ClusterState	False	The state of the cluster. Amazon MSK automatically renews certificates on clusters every 13 months. It sets the state of the cluster to `MAINTENANCE` when it starts the certificate-update operation. It sets it back to `ACTIVE` when the update is done. While a cluster is in the `MAINTENANCE` state, you can continue to produce and consume data, but you can't perform any update operations on it. You can perform update operations on a cluster when it is in the `ACTIVE` state.
`stateInfo`	StateInfo	False	Includes information of the cluster state.
`storageMode`	StorageMode	False	This controls storage mode for supported storage tiers.
`tags`	object	False	Tags attached to the cluster.
`zookeeperConnectString`	string	False	The connection string to use to connect to zookeeper cluster on plaintext port.
`zookeeperConnectStringTls`	string	False	The connection string to use to connect to the Apache ZooKeeper cluster on a TLS port.

ClusterState

The state of the cluster. Amazon MSK automatically renews certificates on clusters every 13 months. It sets the state of the cluster to MAINTENANCE when it starts the certificate-update operation. It sets it back to ACTIVE when the update is done. While a cluster is in the MAINTENANCE state, you can continue to produce and consume data, but you can't perform any update operations on it. You can perform update operations on a cluster when it is in the ACTIVE state.

ACTIVE
CREATING
UPDATING
DELETING
FAILED
MAINTENANCE
REBOOTING_BROKER
HEALING

ConnectivityInfo

Broker access controls.

Property Type Required Description

Property	Type	Required	Description
`networkType`	string MinLength: 4 MaxLength: 4	False	The network type of the cluster, which is IPv4 or DUAL. The DUAL network type uses both IPv4 and IPv6 addresses for your cluster and its resources. By default, a cluster uses the IPv4 network type.
`publicAccess`	PublicAccess	False	Access control settings for the cluster's brokers.

networkType

string

MinLength: 4

MaxLength: 4

False

The network type of the cluster, which is IPv4 or DUAL. The DUAL network type uses both IPv4 and IPv6 addresses for your cluster and its resources. By default, a cluster uses the IPv4 network type.

publicAccess

PublicAccess

False

Access control settings for the cluster's brokers.