Go through all Kafka passwordless quickstart/migration-guide to make sure following them can work

[saragluna]

Context

With all Kafka passwordless-doc being finished, we should check the readability and correctness of those docs.

Goal

Go through the docs in the below PRs to make sure it is easy to understand and execute, and all the commands are correct and operational.

• migration: https://github.com/MicrosoftDocs/azure-dev-docs-pr/pull/3483
• quickstart: https://github.com/MicrosoftDocs/azure-dev-docs-pr/pull/3406

[chenrujun]

Information update:

1. Link to PR: https://github.com/MicrosoftDocs/azure-dev-docs-pr/pull/3583
2. Link to quick start: https://review.docs.microsoft.com/en-us/azure/developer/java/spring-framework/configure-spring-cloud-stream-binder-java-app-kafka-azure-event-hub?branch=pr-en-us-3583&tabs=passwordless
3. Link to migration-guide: https://review.docs.microsoft.com/en-us/azure/developer/java/spring-framework/migrate-kafka-to-passwordless-connection?branch=pr-en-us-3583&tabs=azure-portal-permission%2Csign-in-azure-cli%2Cjava-kafka%2Cservice-connector-portal%2Cservice-connector-cli%2Cassign-role-service-connector

[chenrujun]

Quick start feedback:

Link to quick start: https://review.docs.microsoft.com/en-us/azure/developer/java/spring-framework/configure-spring-cloud-stream-binder-java-app-kafka-azure-event-hub?branch=pr-en-us-3583&tabs=passwordless

1. Add link to Azure Active Directory (Azure AD) authentication and Shared Access Signatures (SAS) authentication.
   

1.1. Azure Active Directory (Azure AD) authentication
https://docs.microsoft.com/en-us/azure/event-hubs/authenticate-application or
https://docs.microsoft.com/en-us/azure/event-hubs/authenticate-managed-identity?tabs=latest
1.2. Shared Access Signatures (SAS) authentication
https://docs.microsoft.com/en-us/azure/event-hubs/authenticate-shared-access-signature

2. This sentence is not right:
   

Event Hubs provides an endpoint compatible with the Apache Kafka® producer and consumer APIs. This quick start is not using Apache Kafka.

My suggestion:

This article shows you how to develop a Spring Boot application that can send and receive messages in Azure Event Hubs for Kafka by spring-cloud-stream-binder-kafka.

3. Error in command:
   
   Lack / at the end of the first line.

4. Add links:
   

5. I faced path problem about git bash:
   

This problem has been solved by this:

export MSYS_NO_PATHCONV=1

Refs: https://github.com/git-for-windows/build-extra/blob/main/ReleaseNotes.md

We can write this down in the doc in case other reader face the same problem.

6. Change 4.3.0 to spring-cloud-azure-dependencies:4.3.0 (I prefer this one) or Spring Cloud Azure: 4.3.0
   

7. Delete implementation detail in the quick start guide. Move it to reference doc if necessary.
   

8. For version after -> Since. 4.4.0 -> spring-cloud-azure-dependencies:4.4.0. Delete unnecessary description.
   

[chenrujun]

Feedback of Migration guide

Link to migration-guide: https://review.docs.microsoft.com/en-us/azure/developer/java/spring-framework/migrate-kafka-to-passwordless-connection?branch=pr-en-us-3583&tabs=azure-portal-permission%2Csign-in-azure-cli%2Cjava-kafka%2Cservice-connector-portal%2Cservice-connector-cli%2Cassign-role-service-connector

1. after -> since.
   

BTW, why this feature is not written in the changelog? https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/spring/CHANGELOG.md

2. The support for passwordless connections is enabled -> The passwordless connections is supported. Before 4.3.0, this feature is not existed instead of not enabled.
   

3. source control -> source code
   

4. Uniform connection / connections. If there is no reason to plural, I suggest using connection in all places.
   

5. in the application, its configuration files, or in environment variables -> in application's configuration files or in environment variables
   

6. Azure Managed Identity and Role Based Access Control (RBAC) are not Azure services.
   

7. To make less confusing, add link to DefaultAzureCredential when it first appears in this document.
   

8, Change link from .net to java

Current link is about .net: https://review.docs.microsoft.com/en-us/dotnet/api/overview/azure/Identity-readme#defaultazurecredential
We should use link to java sdk: https://docs.microsoft.com/en-us/java/api/overview/azure/Identity-readme?view=azure-java-stable#defaultazurecredential

9. The content of Introducing passwordless connections is different from page to page.
   
   
   To avoid difference, I suggest writing this content in a standalone page, then add link to the page in other pages.

10. overview -> managed-identity overview, the link text should self-explained. documentation -> page. IMY, documentation consists of many pages. This link is just a page.
    

11. The following steps explain how to migrate an existing application to use passwordless connections instead of a SAS solution -> The following steps explain how to migrate an existing application from SAS solution to passwordless connections solution
    

12. To make it less confusing, it's better to provide the project before migraion, and the project after migration.
    
    

13...
Not finished yet, will continue soon.

[chenrujun]

13. Now there is only code after migration. It's better to keep the code before migration at the same time.
    
    

Here is code before migration created by myself:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.azure.spring.password.less.migration.kafka.java</groupId>
  <artifactId>before-migration</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.apache.kafka</groupId>
      <artifactId>kafka-clients</artifactId>
      <version>3.2.3</version>
    </dependency>
  </dependencies>

</project>

import org.apache.kafka.clients.CommonClientConfigs;
import org.apache.kafka.clients.producer.KafkaProducer;
import org.apache.kafka.clients.producer.Producer;
import org.apache.kafka.clients.producer.ProducerConfig;
import org.apache.kafka.clients.producer.ProducerRecord;
import org.apache.kafka.clients.producer.RecordMetadata;
import org.apache.kafka.common.config.SaslConfigs;
import org.apache.kafka.common.serialization.StringSerializer;

import java.util.Properties;
import java.util.concurrent.Future;

public class BeforeMigrationApplication {

    public static void main(String[] args) {
        try (Producer<String, String> producer = createProducer()) {
            ProducerRecord<String, String> record = new ProducerRecord<>("sample-topic", "sample-key", "sample-value");
            Future<RecordMetadata> future = producer.send(record);
            RecordMetadata metadata = future.get();
            System.out.println(metadata.toString());
        } catch (Exception e) {
            e.printStackTrace();
            System.out.println("Error happened when produce message. " + e);
        }
    }

    private static Producer<String, String> createProducer() {
        String hostName = System.getProperty("hostName");
        String connectionString = System.getProperty("connectionString");

        Properties properties = new Properties();
        properties.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, String.format("%s:9093", hostName));
        properties.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_SSL");
        properties.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        properties.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        properties.put(SaslConfigs.SASL_MECHANISM, "PLAIN");
        properties.put(SaslConfigs.SASL_JAAS_CONFIG,
                String.format("org.apache.kafka.common.security.plain.PlainLoginModule required username=\"$ConnectionString\" password=\"%s\";", connectionString));

        return new KafkaProducer<>(properties);
    }
}

[chenrujun]

14. In current Java tab, it's using org.apache.kafka:kafka-clients. We should add some description about azure-messaging-eventhubs. It's official client to connect to Azure Event Hubs.
    14.1. Can azure-messaging-eventhubs be used to connect to Azure Event Hubs Kafka?
    14,2. If azure-messaging-eventhubs can be used to connect to Azure Event Hubs Kafka, is migration guide necessary here?

[chenrujun]

15. It's better not use master branch. Because master branch may change. Use git tag instead.
    

[chenrujun]

16. Use constant value instead of raw string
    

Here is the code in my localhost:

More context:
pom file:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <groupId>com.azure.spring.password.less.migration.kafka.java</groupId>
  <artifactId>after-migration</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.apache.kafka</groupId>
      <artifactId>kafka-clients</artifactId>
      <version>3.2.3</version>
    </dependency>
<!--    <dependency>-->
<!--      <groupId>org.apache.kafka</groupId>-->
<!--      <artifactId>kafka_2.12</artifactId>-->
<!--      <version>2.3.1</version>-->
<!--    </dependency>-->
    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>azure-client-authentication</artifactId>
      <version>1.6.15</version>
    </dependency>
  </dependencies>

</project>

java code:

import org.apache.kafka.clients.CommonClientConfigs;
import org.apache.kafka.clients.producer.KafkaProducer;
import org.apache.kafka.clients.producer.Producer;
import org.apache.kafka.clients.producer.ProducerRecord;
import org.apache.kafka.clients.producer.RecordMetadata;
import org.apache.kafka.common.config.SaslConfigs;

import java.util.Properties;
import java.util.concurrent.Future;

public class AfterMigrationApplication {

    public static void main(String[] args) {
        try (Producer<String, String> producer = createProducer()) {
            ProducerRecord<String, String> record = new ProducerRecord<>("after-migration-topic", "after-migration--key", "after-migration--value");
            Future<RecordMetadata> future = producer.send(record);
            RecordMetadata metadata = future.get();
            System.out.println(metadata.toString());
        } catch (Exception e) {
            e.printStackTrace();
            System.out.println("Error happened when produce message. " + e);
        }
    }

    private static Producer<String, String> createProducer() {
        String hostName = System.getProperty("hostName");

        Properties properties = new Properties();
        properties.put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, String.format("%s:9093", hostName));
        properties.put(CommonClientConfigs.SECURITY_PROTOCOL_CONFIG, "SASL_SSL");
        properties.put(SaslConfigs.SASL_MECHANISM, "OAUTHBEARER");
        properties.put(SaslConfigs.SASL_JAAS_CONFIG, "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required");
        properties.put(SaslConfigs.SASL_LOGIN_CALLBACK_HANDLER_CLASS, "CustomAuthenticateCallbackHandler");
        return new KafkaProducer<>(properties);
    }
}

[chenrujun]

17. Problem: Missing required configuration "key.serializer" which has no default value.
    

Fixed by adding the 2 properties:

        properties.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        properties.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());