Merge pull request #256451 from enkrumah/patch-53

Update kafka-output.md

Author: v-shils

articles/stream-analytics/kafka-output.md

@@ -5,20 +5,20 @@ author: enkrumah
 ms.author: ebnkruma
 ms.service: stream-analytics
 ms.topic: conceptual
-ms.date: 10/23/2023
+ms.date: 10/27/2023
 ---
 
 # Kafka output from Azure Stream Analytics (Preview)
 
-Azure Stream Analytics allows you to connect directly to Kafka clusters as a producer to output data. The solution is low code and entirely managed by the Azure Stream Analytics team at Microsoft, allowing it to meet business compliance standards. The Kafka Adapters are backward compatible and support all versions with the latest client release starting from version 0.10. Users can connect to Kafka clusters inside a VNET and Kafka clusters with a public endpoint, depending on the configurations. The configuration relies on existing Kafka configuration conventions.
+Azure Stream Analytics allows you to connect directly to Kafka clusters as a producer to output data. The solution is low code and entirely managed by the Azure Stream Analytics team at Microsoft, allowing it to meet business compliance standards. The ASA Kafka output is backward compatible and supports all versions with the latest client release starting from version 0.10. Users can connect to Kafka clusters inside a VNET and Kafka clusters with a public endpoint, depending on the configurations. The configuration relies on existing Kafka configuration conventions.
 Supported compression types are None, Gzip, Snappy, LZ4, and Zstd.
 
 ## Configuration
 The following table lists the property names and their description for creating a Kafka output: 
 
 | Property name                | Description                                                                                                             |
 |------------------------------|-------------------------------------------------------------------------------------------------------------------------|
-| Input/Output Alias            | A friendly name used in queries to reference your input or output                                                      |
+| Output Alias            | A friendly name used in queries to reference your output                                                      |
 | Bootstrap server addresses   | A list of host/port pairs to establish the connection to the Kafka cluster.                                  |
 | Kafka topic                  | A unit of your Kafka cluster you want to write events to.                                                               |
 | Security Protocol            | How you want to connect to your Kafka cluster. Azure Stream Analytics supports mTLS, SASL_SSL, SASL_PLAINTEXT or None. |
@@ -44,8 +44,8 @@ You can use four types of security protocols to connect to your Kafka clusters:
 
 ### Connect to Confluent Cloud using API key
 
-The ASA Kafka adapter is a librdkafka-based client, and to connect to confluent cloud, you will need TLS certificates that confluent cloud uses for server auth.
-Confluent uses TLS certificates from Let’s Encrypt, an open certificate authority (CA)
+The ASA Kafka output is a librdkafka-based client, and to connect to confluent cloud, you need TLS certificates that confluent cloud uses for server auth.
+Confluent uses TLS certificates from Let’s Encrypt, an open certificate authority (CA) You can download the ISRG Root X1 certificate in PEM format on the site of [LetsEncrypt](https://letsencrypt.org/certificates/).
 
 To authenticate using the API Key confluent offers, you must use the SASL_SSL protocol and complete the configuration as follows:
 
@@ -54,7 +54,7 @@ To authenticate using the API Key confluent offers, you must use the SASL_SSL pr
  | Username | Key/ Username from API Key |
  | Password | Secret/ Password from API key |
  | KeyVault | Name of Azure Key vault with Uploaded certificate from Let’s Encrypt |
- | Certificate | Certificate uploaded to KeyVault downloaded from Let’s Encrypt (You can download the ISRG Root X1 Self-sign cert in PEM format) |
+ | Certificate | Certificate uploaded to KeyVault downloaded from Let’s Encrypt (Download the ISRG Root X1 certificate in PEM format) |
 
 
 ## Key vault integration
@@ -64,16 +64,73 @@ To authenticate using the API Key confluent offers, you must use the SASL_SSL pr
 >
 
 Azure Stream Analytics integrates seamlessly with Azure Key vault to access stored secrets needed for authentication and encryption when using mTLS or SASL_SSL security protocols. Your Azure Stream Analytics job connects to your Azure Key vault using managed identity to ensure a secure connection and avoid the exfiltration of secrets.
-
 Certificates are stored as secrets in the key vault and must be in PEM format.
 
-The following command can upload the certificate as a secret to your key vault. You need "Administrator" access to your Key vault for this command to work properly.
+### Configure Key vault with permissions
+
+You can create a key vault resource by following the documentation [Quickstart: Create a key vault using the Azure portal](../key-vault/general/quick-create-portal.md)
+To be able to upload certificates, you must have "**Key Vault Administrator**"  access to your Key vault. Follow the following to grant admin access.
+
+> [!NOTE]
+> You must have "**Owner**" permissions to grant other key vault permissions.
+
+1. Select **Access control (IAM)**.
+
+1. Select **Add** > **Add role assignment** to open the **Add role assignment** page.
+
+1. Assign the role using the following configuration:
+
+ | Setting | Value |
+ | --- | --- |
+ | Role | Key Vault Administrator |
+ | Assign access to | User, group, or service principal |
+ | Members | \<Your account information or email> |
+
+
+### Upload Certificate to Key vault
+
+You can use Azure CLI to upload certificates as secrets to your key vault or use the Azure portal to upload the certificate as a secret.
+> [!IMPORTANT]
+> You must have "**Key Vault Administrator**" permissions access to your Key vault for this command to work properly
+> You must upload the certificate as a secret.
+> Your Azure Stream Analytics job will fail when the certificate used for authentication expires. To resolve this, you must update/replace the certificate in your key vault and restart your Azure Stream Analytics job.
+
+#### Option One - Upload certificate via Azure CLI
+
+The following command can upload the certificate as a secret to your key vault.
 
 ```azurecli-interactive
 az keyvault secret set --vault-name <your key vault> --name <name of the secret> --file <file path to secret>
 
 ```
 
+#### Option Two - Upload certificate via the Azure portal
+Use the following steps to upload a certificate as a secret using the Azure portal in your key vault:
+1. Select **Secrets**.
+
+1. Select **Generate/Import** > **Add role assignment** to open the **Add role assignment** page.
+
+1. Complete the following configuration for creating a secret:
+
+ | Setting | Value |
+ | --- | --- |
+ | Upload Options | Certificate |
+ | Upload certificate | \<select the certificate to upload> |
+ | Name | \<Name you want to give your secret> |
+ | activation date | (optional) |
+ | expiration date | (optional) |
+
+### Configure Managed identity
+Azure Stream Analytics requires you to configure managed identity to access key vault.
+You can configure your ASA job to use managed identity by navigating to the **Managed Identity** tab on the left side under **Configure**.
+
+   ![Configure Stream Analytics managed identity](./media/common/stream-analytics-enable-managed-identity-new.png)
+
+1.	Click on the **managed identity tab** under **configure**.
+2.	Select **Switch Identity** and select the identity to use with the job: system-assigned identity or user-assigned identity.
+3.	For user-assigned identity, select the subscription where your user-assigned identity is located and select the name of your identity.
+4.	Review and **save**.
+
 ### Grant the Stream Analytics job permissions to access the certificate in the key vault
 For your Azure Stream Analytics job to access the certificate in your key vault and read the secret for authentication using managed identity, the service principal you created when you configured managed identity for your Azure Stream Analytics job must have special permissions to the key vault. 
 
@@ -85,22 +142,24 @@ For your Azure Stream Analytics job to access the certificate in your key vault
 
  | Setting | Value |
  | --- | --- |
- | Role | Key vault secret reader |
- | Assign access to | User, group, or service principal |
- | Members | \<Name of your Stream Analytics job> |
-
+ | Role | Key vault secrets user |
+ | Managed identity | Stream Analytics job for System-assigned managed identity or User-assigned managed identity |
+ | Members | \<Name of your Stream Analytics job> or \<name of user-assigned identity> |
 
+   
 ### VNET integration
-When configuring your Azure Stream Analytics job to connect to your Kafka clusters, depending on your configuration, you might have to configure your job to access your Kafka clusters, which are behind a firewall or inside a virtual network. You can visit the Azure Stream Analytics VNET documentation to learn more about configuring private endpoints to access resources inside a virtual network or behind a firewall.           
+
+If your Kafka is inside a virtual network (VNET) or behind a firewall, you must configure your Azure Stream Analytics job to access your Kafka topic.
+Visit the [Run your Azure Stream Analytics job in an Azure Virtual Network documentation](../stream-analytics/run-job-in-virtual-network.md) for more information.       
 
 
 ### Limitations
-* When configuring your Azure Stream Analytics jobs to use VNET/SWIFT, your job must be configured with at least six (6) streaming units. 
+* When configuring your Azure Stream Analytics jobs to use VNET/SWIFT, your job must be configured with at least six (6) streaming units or one (1) V2 streaming unit. 
 * When using mTLS or SASL_SSL with Azure Key vault, you must convert your Java Key Store to PEM format. 
 * The minimum version of Kafka you can configure Azure Stream Analytics to connect to is version 0.10.
 
 > [!NOTE]
-> For direct help with using the Azure Stream Analytics Kafka adapter, please reach out to [[email protected]](mailto:[email protected]).
+> For direct help with using the Azure Stream Analytics Kafka output, please reach out to [[email protected]](mailto:[email protected]).
 >