AWS msk documentation change
Summary
Updated SASL/SCRAM client connection documentation with clearer instructions, added troubleshooting section for memory errors, and fixed path references
Security assessment
The changes primarily improve existing security documentation for SASL/SCRAM authentication but don't address specific vulnerabilities. The troubleshooting section addresses performance issues (Java heap memory) rather than security weaknesses. Security documentation addition is marked true as SASL/SCRAM is a security feature, but no concrete evidence of addressing a security vulnerability exists in the diff.
Diff
diff --git a/msk/latest/developerguide/msk-password-tutorial-connect.md b/msk/latest/developerguide/msk-password-tutorial-connect.md index db33a0f0c..f39ff1bce 100644 --- a//msk/latest/developerguide/msk-password-tutorial-connect.md +++ b//msk/latest/developerguide/msk-password-tutorial-connect.md @@ -4,0 +5,2 @@ +Connecting a client to cluster using SASL/SCRAM authenticationTroubleshooting connection issues + @@ -7 +9,8 @@ -After you create a secret and associate it with your cluster, you can connect your client to the cluster. The following example steps demonstrate how to connect a client to a cluster that uses SASL/SCRAM authentication, and how to produce to and consume from an example topic. +After you create a secret and associate it with your cluster, you can connect your client to the cluster. The following procedure demonstrates how to connect a client to a cluster that uses SASL/SCRAM authentication. It also shows how to produce to and consume from an example topic. + +###### Topics + + * Connecting a client to cluster using SASL/SCRAM authentication + + * Troubleshooting connection issues + @@ -9 +18,5 @@ After you create a secret and associate it with your cluster, you can connect yo - 1. Run the following command on a machine that has the AWS CLI installed, replacing `clusterARN` with the ARN of your cluster. + + +## Connecting a client to cluster using SASL/SCRAM authentication + + 1. Run the following command on a machine that has AWS CLI installed. Replace `clusterARN` with the ARN of your cluster. @@ -12,0 +26,2 @@ After you create a secret and associate it with your cluster, you can connect yo +From the JSON result of this command, save the value associated with the string named `BootstrapBrokerStringSaslScram`. You'll use this value in later steps. + @@ -25 +40 @@ After you create a secret and associate it with your cluster, you can connect yo - 4. Create a file named `kafka.client.truststore.jks` in a `./tmp` directory. + 4. Create a file named `kafka.client.truststore.jks` in a `/tmp` directory. @@ -36 +51 @@ After you create a secret and associate it with your cluster, you can connect yo - 7. To create an example topic, run the following command, replacing `BootstrapServerString` with one of the broker endpoints that you obtained in the previous step. + 7. To create an example topic, run the following command. Replace `BootstrapBrokerStringSaslScram` with the bootstrap broker string that you obtained in step 1 of this topic. @@ -38 +53 @@ After you create a secret and associate it with your cluster, you can connect yo - <path-to-your-kafka-installation>/bin/kafka-topics.sh --create --bootstrap-server BootstrapBrokerStringSaslScram --command-config client_sasl.properties --replication-factor 3 --partitions 1 --topic ExampleTopicName + <path-to-your-kafka-installation>/bin/kafka-topics.sh --create --bootstrap-server BootstrapBrokerStringSaslScram --command-config <path-to-client-properties>/client_sasl.properties --replication-factor 3 --partitions 1 --topic ExampleTopicName @@ -40 +55 @@ After you create a secret and associate it with your cluster, you can connect yo - 8. Retrieve your bootstrap brokers string with the following command. Replace `ClusterArn` with the Amazon Resource Name (ARN) of your cluster: + 8. To produce to the example topic that you created, run the following command on your client machine. Replace `BootstrapBrokerStringSaslScram` with the bootstrap broker string that you retrieved in step 1 of this topic. @@ -42 +57 @@ After you create a secret and associate it with your cluster, you can connect yo - aws kafka get-bootstrap-brokers --cluster-arn ClusterArn + <path-to-your-kafka-installation>/bin/kafka-console-producer.sh --broker-list BootstrapBrokerStringSaslScram --topic ExampleTopicName --producer.config client_sasl.properties @@ -44 +59 @@ After you create a secret and associate it with your cluster, you can connect yo -From the JSON result of the command, save the value associated with the string named `BootstrapBrokerStringSaslScram`. + 9. To consume from the topic you created, run the following command on your client machine. Replace `BootstrapBrokerStringSaslScram` with the bootstrap broker string that you obtained in step 1 of this topic. @@ -46 +61 @@ From the JSON result of the command, save the value associated with the string n - 9. To produce to the example topic that you created, run the following command on your client machine. Replace `BootstrapBrokerStringSaslScram` with the value that you retrieved in the previous step. + <path-to-your-kafka-installation>/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --from-beginning --consumer.config client_sasl.properties @@ -48 +62,0 @@ From the JSON result of the command, save the value associated with the string n - <path-to-your-kafka-installation>/bin/kafka-console-producer.sh --broker-list BootstrapBrokerStringSaslScram --topic ExampleTopicName --producer.config client_sasl.properties @@ -50 +63,0 @@ From the JSON result of the command, save the value associated with the string n - 10. To consume from the topic you created, run the following command on your client machine. Replace `BootstrapBrokerStringSaslScram` with the value that you obtained previously. @@ -52 +64,0 @@ From the JSON result of the command, save the value associated with the string n - <path-to-your-kafka-installation>/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --from-beginning --consumer.config client_sasl.properties @@ -53,0 +66,12 @@ From the JSON result of the command, save the value associated with the string n +## Troubleshooting connection issues + +When running Kafka client commands, you might encounter Java heap memory errors, especially when working with large topics or datasets. These errors occur because Kafka tools run as Java applications with default memory settings that might be insufficient for your workload. + +To resolve `Out of Memory Java Heap` errors, you can increase the Java heap size by modifying the `KAFKA_OPTS` environment variable to include memory settings. + +The following example sets the maximum heap size to 1GB (`-Xmx1G`). You can adjust this value based on your available system memory and requirements. + + + export KAFKA_OPTS="-Djava.security.auth.login.config=<path-to-jaas-file>/users_jaas.conf -Xmx1G" + +For consuming large topics, consider using time-based or offset-based parameters instead of `--from-beginning` to limit memory usage: @@ -55,0 +80 @@ From the JSON result of the command, save the value associated with the string n + <path-to-your-kafka-installation>/bin/kafka-console-consumer.sh --bootstrap-server BootstrapBrokerStringSaslScram --topic ExampleTopicName --max-messages 1000 --consumer.config client_sasl.properties