Use this resource to update the security settings of a cluster.
URI
/v1/clusters/clusterArn/security
HTTP methods
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
PATCH
Operation ID: UpdateSecurity
Updates security settings of the specified cluster.
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 UpdateSecurityResponse (p. 101)200 response
400 Error (p. 101) The request isn't valid because
the input is incorrect. Correct your input and then submit it again.
401 Error (p. 101) The request is not authorized.
The provided credentials couldn't be validated.
403 Error (p. 101) Access forbidden. Check your
credentials and then retry your request.
404 Error (p. 101) The resource could not be found
due to incorrect input. Correct the input, then retry the request.
429 Error (p. 101) 429 response
500 Error (p. 101) There was an unexpected
internal server error. Retrying your request might resolve the issue.
503 Error (p. 101) 503 response
Schemas
Request bodies
PATCH schema
{
"encryptionInfo": {
"encryptionInTransit": { "inCluster": boolean, "clientBroker": enum },
"encryptionAtRest": {
"dataVolumeKMSKeyId": "string"
}
}, "clientAuthentication": { "sasl": {
"unauthenticated": { "enabled": boolean
}, "tls": {
"certificateAuthorityArnList": [ "string"
],
"enabled": boolean }
}, "currentVersion": "string"
}
Response bodies
UpdateSecurityResponse schema
{
"clusterArn": "string",
"clusterOperationArn": "string"
}
Error schema
{ "message": "string",
"invalidParameter": "string"
}
Properties
ClientAuthentication
Includes all client authentication information.
sasl
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.
Type: Sasl (p. 103) Required: False
unauthenticated
Details for ClientAuthentication using no authentication.
Type: Unauthenticated (p. 104) Required: False
tls
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.
Type: Tls (p. 104) Required: False
ClientBroker
Client-broker encryption in transit setting.
TLS
TLS_PLAINTEXT PLAINTEXT
EncryptionAtRest
The data-volume encryption details.
dataVolumeKMSKeyId
The ARN of the Amazon KMS key for encrypting data at rest. If you don't specify a KMS key, MSK creates one for you and uses it.
Type: string Required: True
EncryptionInTransit
The settings for encrypting data in transit.
inCluster
When set to true, it indicates that data communication among the broker nodes of the cluster is encrypted. When set to false, the communication happens in plaintext.
The default value is true.
Type: boolean Required: False
clientBroker
Indicates the encryption setting for data in transit between clients and brokers. You must set it to one of the following values.
TLS means that client-broker communication is enabled with TLS only.
TLS_PLAINTEXT means that client-broker communication is enabled for both TLS-encrypted, as well as plaintext data.
PLAINTEXT means that client-broker communication is enabled in plaintext only.
The default value is TLS.
Type: ClientBroker (p. 102) Required: False
EncryptionInfo
Includes encryption-related information, such as the Amazon KMS key used for encrypting data at rest and whether you want MSK to encrypt your data in transit.
encryptionInTransit
The details for encryption in transit.
Type: EncryptionInTransit (p. 102) Required: False
encryptionAtRest
The data-volume encryption details.
Type: EncryptionAtRest (p. 102) Required: False
Error
Returns information about an error.
message
The description of the error.
Type: string Required: False
invalidParameter
The parameter that caused the error.
Type: string Required: False
IAM
Details for SASL/IAM client authentication.
enabled
SASL/IAM authentication is enabled or not.
Type: boolean Required: False
Sasl
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.
iam
Details for ClientAuthentication using IAM.
Type: IAM (p. 103) Required: False
scram
Details for SASL/SCRAM client authentication.
Type: Scram (p. 104) Required: False
Scram
Details for SASL/SCRAM client authentication.
enabled
SASL/SCRAM authentication is enabled or not.
Type: boolean Required: False
Tls
Details for client authentication using TLS.
certificateAuthorityArnList
List of ACM Certificate Authority ARNs.
Type: Array of type string Required: False
enabled
TLS authentication is enabled or not.
Type: boolean Required: False
Unauthenticated
Details for allowing no client authentication.
enabled
Unauthenticated is enabled or not.
Type: boolean Required: False
UpdateSecurityRequest
Request body for UpdateSecurity.
encryptionInfo
The encryption info details.
Type: EncryptionInfo (p. 103) Required: False
clientAuthentication
The client authentication info details.
Type: ClientAuthentication (p. 101) Required: False
currentVersion
Current cluster version.Type: string Required: True
UpdateSecurityResponse
Response body for UpdateSecurity.
clusterArn
The Amazon Resource Name (ARN) of the cluster.
Type: string Required: False
clusterOperationArn
The Amazon Resource Name (ARN) of the cluster operation.
Type: string Required: False
See also
For more information about using this API in one of the language-specific AWS SDKs and references, see the following:
UpdateSecurity
• AWS Command Line Interface
• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java V2
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V3
Clusters
Use this resource to create an Amazon MSK cluster and to get a list of existing clusters.
URI
/v1/clusters
HTTP methods
GET
Operation ID: ListClusters Returns a list of all the MSK clusters.
Query parameters
Name Type Required Description
nextToken String False The paginated results
marker. When the result of the operation is truncated, the call returns NextToken in the response. To get the next batch, provide this token in your next request.
clusterNameFilter String False Specify a prefix of the
name of the clusters that you want to list.
The service lists all the clusters whose names start with this prefix.
maxResults String False The maximum number
of results to return in the response. If there are more results, the response includes a NextToken parameter.
Responses
Status code Response model Description
200 ListClustersResponse (p. 110)Successful response.
400 Error (p. 112) The request isn't valid because
the input is incorrect. Correct your input and then submit it again.
401 Error (p. 112) The request is not authorized.
The provided credentials couldn't be validated.
403 Error (p. 112) Access forbidden. Check your
credentials and then retry your request.
404 Error (p. 112) The resource could not be found
due to incorrect input. Correct the input, then retry the request.
429 Error (p. 112) 429 response
500 Error (p. 112) There was an unexpected
internal server error. Retrying your request might resolve the issue.
503 Error (p. 112) 503 response
POST
Operation ID: CreateCluster
Creates a new MSK cluster. The following Python 3.6 examples shows how you can create a cluster that's distributed over two Availability Zones. Before you run this Python script, replace the example subnet and security-group IDs with the IDs of your subnets and security group. When you create an MSK cluster, its brokers get evenly distributed over a number of Availability Zones that's equal to the number of subnets that you specify in the BrokerNodeGroupInfo parameter. In this example, you can add a third subnet to get a cluster that's distributed over three Availability Zones.
import boto3
client = boto3.client('kafka') response = client.create_cluster(
BrokerNodeGroupInfo={
'BrokerAZDistribution': 'DEFAULT',
ClusterName='SalesCluster',
EncryptionInfo={
EnhancedMonitoring='PER_TOPIC_PER_BROKER', KafkaVersion='2.2.1',
NumberOfBrokerNodes=2 )
print(response)
Responses
Status code Response model Description
200 CreateClusterResponse (p. 112)Successful response.
400 Error (p. 112) The request isn't valid because
the input is incorrect. Correct your input and then submit it again.
401 Error (p. 112) The request is not authorized.
The provided credentials couldn't be validated.
403 Error (p. 112) Access forbidden. Check your
credentials and then retry your request.
404 Error (p. 112) The resource could not be found
due to incorrect input. Correct the input, then retry the request.
409 Error (p. 112) This cluster name already exists.
Retry your request using another name.
429 Error (p. 112) 429 response
500 Error (p. 112) There was an unexpected
internal server error. Retrying your request might resolve the issue.
503 Error (p. 112) 503 response
OPTIONS
Enable CORS by returning the correct headers.
Responses
Status code Response model Description
200 None The default response for a CORS
method.
Schemas
Request bodies
POST schema
{ "encryptionInfo": {
"encryptionInTransit": { "inCluster": boolean, "clientBroker": enum },
"encryptionAtRest": {
"dataVolumeKMSKeyId": "string"
} },
"numberOfBrokerNodes": integer, "configurationInfo": {
"arn": "string", "revision": integer },
"enhancedMonitoring": enum, "storageMode": enum, "clusterName": "string", "kafkaVersion": "string", "clientAuthentication": { "sasl": {
"unauthenticated": { "enabled": boolean },
"tls": {
"certificateAuthorityArnList": [ "string"
"brokerNodeGroupInfo": { "clientSubnets": [
"string"
],
"instanceType": "string", "connectivityInfo": { "publicAccess": { "type": "string"
} },
"securityGroups": [ "string"
],
"brokerAZDistribution": enum, "storageInfo": {
"nextToken": "string", "clusterInfoList": [ {
"zookeeperConnectString": "string", "creationTime": "string",
"zookeeperConnectStringTls": "string", "loggingInfo": {
"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": {
} },
"currentBrokerSoftwareInfo": { "configurationRevision": integer, "kafkaVersion": "string",
"configurationArn": "string"
} } ] }
CreateClusterResponse schema
{
"clusterArn": "string", "clusterName": "string", "state": enum
}
Error schema
{ "message": "string",
"invalidParameter": "string"
}
Properties
BrokerAZDistribution
This parameter is currently not in use.
DEFAULT
BrokerLogs
The broker logs configuration for this MSK cluster.
s3
Details of the Amazon S3 destination for broker logs.
Type: S3 (p. 126) Required: False
firehose
Details of the Kinesis Data Firehose delivery stream that is the destination for broker logs.
Type: Firehose (p. 123) Required: False
cloudWatchLogs
Details of the CloudWatch Logs destination for broker logs.
Type: CloudWatchLogs (p. 115) Required: False
BrokerNodeGroupInfo
Describes the setup to be used for the broker nodes in the cluster.
clientSubnets
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.
Specify exactly two subnets if you are using the US West (N. California) Region. 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 be in Availability Zone us-east-1e.
Type: Array of type string Required: True
instanceType
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.
Type: string Required: True MinLength: 5 MaxLength: 32
connectivityInfo
Information about the cluster's connectivity setting.
Type: ConnectivityInfo (p. 119) Required: False
securityGroups
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.
Type: Array of type string Required: False
brokerAZDistribution
This parameter is currently not in use.
Type: BrokerAZDistribution (p. 112) Required: False
storageInfo
Contains information about storage volumes attached to MSK broker nodes.
Type: StorageInfo (p. 127) Required: False
BrokerSoftwareInfo
Information about the current software installed on the cluster.
configurationRevision
The revision of the configuration to use. This field isn't visible in this preview release.
Type: integer Required: False Format: int64
kafkaVersion
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.
Type: string Required: False
configurationArn
The Amazon Resource Name (ARN) of the configuration used for the cluster. This field isn't visible in this preview release.
Type: string Required: False
ClientAuthentication
Includes all client authentication information.
sasl
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.
Type: Sasl (p. 127) Required: False
unauthenticated
Details for ClientAuthentication using no authentication.
Type: Unauthenticated (p. 128) Required: False
tls
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.
Type: Tls (p. 128) Required: False
ClientBroker
Client-broker encryption in transit setting.
TLSTLS_PLAINTEXT PLAINTEXT
CloudWatchLogs
Details of the CloudWatch Logs destination for broker logs.
logGroup
The CloudWatch log group that is the destination for broker logs.
Type: string Required: False
enabled
Specifies whether broker logs get sent to the specified CloudWatch Logs destination.
Type: boolean Required: True
ClusterInfo
Returns information about a cluster.
encryptionInfo
Includes all encryption-related information.
Type: EncryptionInfo (p. 122) Required: False
zookeeperConnectString
The connection string to use to connect to zookeeper cluster on plaintext port.
Type: string Required: False
creationTime
The time when the cluster was created.
Type: string Required: False
zookeeperConnectStringTls
The connection string to use to connect to the Apache ZooKeeper cluster on a TLS port.
Type: string Required: False
loggingInfo
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.
Type: LoggingInfo (p. 124) Required: False
currentVersion
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.
Type: string Required: False
tags
Tags attached to the cluster.
Type: object Required: False
numberOfBrokerNodes
The number of broker nodes in the cluster.
Type: integer Required: False
clusterArn
The Amazon Resource Name (ARN) that uniquely identifies the cluster.
Type: string Required: False
activeOperationArn
Arn of active cluster operation.
Type: string Required: False
enhancedMonitoring
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.
Type: EnhancedMonitoring (p. 122) Required: False
storageMode
This controls storage mode for supported storage tiers.
Type: StorageMode (p. 128) Required: False
clusterName
The name of the cluster.
Type: string Required: False
stateInfo
Includes information of the cluster state.
Type: StateInfo (p. 127) Required: False
clientAuthentication
Includes all client authentication information.
Type: ClientAuthentication (p. 114) Required: False
state
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.
Type: ClusterState (p. 118) Required: False
brokerNodeGroupInfo
Information about the broker nodes.
Type: BrokerNodeGroupInfo (p. 113) Required: False
openMonitoring
Settings for open monitoring using Prometheus.
Type: OpenMonitoring (p. 125) Required: False
currentBrokerSoftwareInfo
Information about the version of software currently deployed on the brokers in the cluster.
Type: BrokerSoftwareInfo (p. 114) Required: False
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
ConfigurationInfo
Specifies the configuration to use for the brokers.
arn
ARN of the configuration to use.
Type: string Required: True
revision
The revision of the configuration to use.
Type: integer Required: True Format: int64 Minimum: 1
ConnectivityInfo
Broker access controls.
publicAccess
Access control settings for the cluster's brokers.
Type: PublicAccess (p. 126) Required: False
CreateClusterRequest
Creates a cluster.
encryptionInfo
Includes all encryption-related information.
Type: EncryptionInfo (p. 122) Required: False
numberOfBrokerNodes
The number of broker nodes in the cluster.
Type: integer Required: True
configurationInfo
Represents the configuration that you want MSK to use for the cluster.
Type: ConfigurationInfo (p. 118) Required: False
enhancedMonitoring
Specifies the level of monitoring for the MSK cluster. The possible values are DEFAULT, PER_BROKER, and PER_TOPIC_PER_BROKER.
Type: EnhancedMonitoring (p. 122) Required: False
storageMode
This controls storage mode for supported storage tiers.
Type: StorageMode (p. 128) Required: False
clusterName
The name of the cluster.
Type: string Required: True MinLength: 1 MaxLength: 64
kafkaVersion
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.
Type: string Required: True MinLength: 1 MaxLength: 128
clientAuthentication
Includes all client authentication related information.
Type: ClientAuthentication (p. 114) Required: False