Merge pull request #289261 from jlian/main

Fix inaccurate content

Author: prmerger-automator[bot]

articles/iot-operations/connect-to-cloud/howto-configure-mqtt-endpoint.md

@@ -23,7 +23,7 @@ MQTT dataflow endpoints are used for MQTT sources and destinations. You can conf
 - An instance of [Azure IoT Operations Preview](../deploy-iot-ops/howto-deploy-iot-operations.md)
 - A [configured dataflow profile](howto-configure-dataflow-profile.md)
 
-## Azure IoT Operations Local MQTT broker
+## Azure IoT Operations local MQTT broker
 
 ### Default endpoint
 

articles/iot-operations/connect-to-cloud/tutorial-mqtt-bridge.md

@@ -92,7 +92,7 @@ Using Azure CLI, find the principal ID for the Azure IoT Operations Arc extensio
 ```azurecli
 export PRINCIPAL_ID=$(az k8s-extension list \
   --resource-group $RESOURCE_GROUP \
-  --cluster-name <CLUSTER-NAME> \
+  --cluster-name $CLUSTER_NAME \
   --cluster-type connectedClusters \
   --query "[?extensionType=='microsoft.iotoperations'].identity.principalId | [0]" -o tsv)
 echo $PRINCIPAL_ID
@@ -145,77 +145,34 @@ Take note of the output value for `topicSpacesConfiguration.hostname` that is a
 example.region-1.ts.eventgrid.azure.net
 ```
 
-## Create an Azure IoT Operations MQTT broker dataflow endpoint
+## Understand the default Azure IoT Operations MQTT broker dataflow endpoint
 
-# [Bicep](#tab/bicep)
-
-The dataflow and dataflow endpoints for MQTT broker and Azure Event Grid can be deployed as standard Azure resources since they have Azure Resource Provider (RPs) implementations. This Bicep template file from [Bicep File for MQTT-bridge dataflow Tutorial](https://github.com/Azure-Samples/explore-iot-operations/blob/main/samples/quickstarts/dataflow.bicep) deploys the necessary dataflow and dataflow endpoints.
-
-Download the file to your local, and make sure to replace the values for `customLocationName`, `aioInstanceName`, `eventGridHostName` with yours.
+By default, Azure IoT Operations deploys an MQTT broker as well as an MQTT broker dataflow endpoint. The MQTT broker dataflow endpoint is used to connect to the MQTT broker. The default configuration uses the built-in service account token for authentication. The endpoint is named `default` and is available in the same namespace as Azure IoT Operations. The endpoint is used as the source for the dataflows you create in the next steps.
 
-Next, execute the following command in your terminal:
+To learn more about the default MQTT broker dataflow endpoint, see [Azure IoT Operations local MQTT broker default endpoint](../connect-to-cloud/howto-configure-mqtt-endpoint.md#default-endpoint).
 
-```azurecli
-az stack group create --name MyDeploymentStack --resource-group $RESOURCE_GROUP --template-file /workspaces/explore-iot-operations/mqtt-bridge.bicep --action-on-unmanage 'deleteResources' --deny-settings-mode 'none' --yes
-```
-This endpoint is the source for the dataflow that sends messages to Azure Event Grid.
-
-```bicep
-resource MqttBrokerDataflowEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-08-15-preview' = {
-  parent: aioInstance
-  name: 'aiomq'
-  extendedLocation: {
-    name: customLocation.id
-    type: 'CustomLocation'
-  }
-  properties: {
-    endpointType: 'Mqtt'
-    mqttSettings: {
-      authentication: {
-        method: 'ServiceAccountToken'
-        serviceAccountTokenSettings: {
-          audience: 'aio-internal'
-        }
-      }
-      host: 'aio-broker:18883'
-      tls: {
-        mode: 'Enabled'
-        trustedCaCertificateConfigMapRef: 'azure-iot-operations-aio-ca-trust-bundle'
-      }
-    }
-  }
-}
-```
-
-# [Kubernetes](#tab/kubernetes)
-
-Create dataflow endpoint for the Azure IoT Operations built-in MQTT broker. This endpoint is the source for the dataflow that sends messages to Azure Event Grid.
+## Create an Azure Event Grid dataflow endpoint
 
-```yaml
-apiVersion: connectivity.iotoperations.azure.com/v1beta1
-kind: DataflowEndpoint
-metadata:
-  name: mq
-  namespace: azure-iot-operations
-spec:
-  endpointType: Mqtt
-  mqttSettings:
-    authentication:
-      method: ServiceAccountToken
-      serviceAccountTokenSettings: {}
-```
+Create dataflow endpoint for the Azure Event Grid. This endpoint is the destination for the dataflow that sends messages to Azure Event Grid. Replace `<EVENT_GRID_HOSTNAME>` with the MQTT hostname you got from the previous step. Include the port number `8883`.
 
----
+# [Bicep](#tab/bicep)
 
-This is the default configuration for the Azure IoT Operations MQTT broker endpoint. The authentication method is set to `ServiceAccountToken` to use the built-in service account token for authentication.
+The dataflow and dataflow endpoints Azure Event Grid can be deployed as standard Azure resources since they have Azure Resource Provider (RPs) implementations. This Bicep template file from [Bicep File for MQTT-bridge dataflow Tutorial](https://github.com/Azure-Samples/explore-iot-operations/blob/main/samples/quickstarts/dataflow.bicep) deploys the necessary dataflow and dataflow endpoints.
 
-## Create an Azure Event Grid dataflow endpoint
+Download the file to your local, and make sure to replace the values for `customLocationName`, `aioInstanceName`, `eventGridHostName` with yours. 
 
-# [Bicep](#tab/bicep)
+```bicep
+param customLocationName string = '<CUSTOM_LOCATION_NAME>'
+param aioInstanceName string = '<AIO_INSTANCE_NAME>'
+param eventGridHostName string = '<EVENT_GRID_HOSTNAME>:8883'
 
-Since you already deployed the resources in the previous section, there's no additional deployment needed. However, this endpoint is the destination for the dataflow that sends messages to Azure Event Grid. Replace `<EVENT-GRID-HOSTNAME>` with the hostname you got from the previous step. Include the port number `8883`.
+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
+  name: customLocationName
+}
 
-```bicep
+resource aioInstance 'Microsoft.IoTOperations/instances@2024-08-15-preview' existing = {
+  name: aioInstanceName
+}
 resource remoteMqttBrokerDataflowEndpoint 'Microsoft.IoTOperations/instances/dataflowEndpoints@2024-08-15-preview' = {
   parent: aioInstance
   name: 'eventgrid'
@@ -230,7 +187,7 @@ resource remoteMqttBrokerDataflowEndpoint 'Microsoft.IoTOperations/instances/dat
         method: 'SystemAssignedManagedIdentity'
         systemAssignedManagedIdentitySettings: {}
       }
-      host: '<NAMESPACE>.<REGION>-1.ts.eventgrid.azure.net:8883'
+      host: eventGridHostName
       tls: {
         mode: 'Enabled'
       }
@@ -239,9 +196,13 @@ resource remoteMqttBrokerDataflowEndpoint 'Microsoft.IoTOperations/instances/dat
 }
 ```
 
-# [Kubernetes](#tab/kubernetes)
+Next, execute the following command in your terminal. Replace `<FILE>` with the name of the Bicep file you downloaded.
 
-Create dataflow endpoint for the Azure Event Grid. This endpoint is the destination for the dataflow that sends messages to Azure Event Grid. Replace `<EVENT-GRID-HOSTNAME>` with the hostname you got from the previous step. Include the port number `8883`.
+```azurecli
+az stack group create --name DeployDataflowEndpoint --resource-group $RESOURCE_GROUP --template-file <FILE>.bicep --action-on-unmanage 'deleteResources' --deny-settings-mode 'none' --yes
+```
+
+# [Kubernetes](#tab/kubernetes)
 
 ```yaml
 apiVersion: connectivity.iotoperations.azure.com/v1beta1
@@ -252,7 +213,7 @@ metadata:
 spec:
   endpointType: Mqtt
   mqttSettings:
-    host: <EVENT-GRID-HOSTNAME>:8883
+    host: <EVENT_GRID_HOSTNAME>:8883
     authentication:
       method: SystemAssignedManagedIdentity
       systemAssignedManagedIdentitySettings: {}
@@ -268,11 +229,24 @@ Since the Event Grid MQTT broker requires TLS, the `tls` setting is enabled. No
 
 ## Create dataflows
 
-# [Bicep](#tab/bicep)
+Create two dataflows with the Azure IoT Operations MQTT broker endpoint as the source and the Azure Event Grid endpoint as the destination, and vice versa. No need to configure transformation.
 
-In this example, there are two dataflows with the Azure IoT Operations MQTT broker endpoint as the source and the Azure Event Grid endpoint as the destination, and vice versa. No need to configure transformation.
+# [Bicep](#tab/bicep)
 
 ```bicep
+param customLocationName string = '<CUSTOM_LOCATION_NAME>'
+param aioInstanceName string = '<AIO_INSTANCE_NAME>'
+
+resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
+  name: customLocationName
+}
+resource aioInstance 'Microsoft.IoTOperations/instances@2024-08-15-preview' existing = {
+  name: aioInstanceName
+}
+resource defaultDataflowProfile 'Microsoft.IoTOperations/instances/dataflowProfiles@2024-08-15-preview' existing = {
+  parent: aioInstance
+  name: 'default'
+}
 resource dataflow_1 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflows@2024-08-15-preview' = {
   parent: defaultDataflowProfile
   name: 'local-to-remote'
@@ -286,15 +260,15 @@ resource dataflow_1 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflow
       {
         operationType: 'Source'
         sourceSettings: {
-          endpointRef: MqttBrokerDataflowEndpoint.name
+          endpointRef: 'default'
           dataSources: array('tutorial/local')
         }
       }
       {
         operationType: 'Destination'
         destinationSettings: {
           endpointRef: remoteMqttBrokerDataflowEndpoint.name
-          dataDestination: 'telemetry/iot-mq'
+          dataDestination: 'telemetry/aio'
         }
       }
     ]
@@ -323,7 +297,7 @@ resource dataflow_2 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflow
       {
         operationType: 'Destination'
         destinationSettings: {
-          endpointRef: MqttBrokerDataflowEndpoint.name
+          endpointRef: 'default'
           dataDestination: 'tutorial/cloud'
         }
       }
@@ -332,9 +306,14 @@ resource dataflow_2 'Microsoft.IoTOperations/instances/dataflowProfiles/dataflow
 } 
 ```
 
+Like the dataflow endpoint, execute the following command in your terminal:
+
+```azurecli
+az stack group create --name DeployDataflows --resource-group $RESOURCE_GROUP --template-file <FILE>.bicep --action-on-unmanage 'deleteResources' --deny-settings-mode 'none' --yes
+```
+
 # [Kubernetes](#tab/kubernetes)
 
-Create two dataflows with the Azure IoT Operations MQTT broker endpoint as the source and the Azure Event Grid endpoint as the destination, and vice versa. No need to configure transformation.
 
 ```yaml
 apiVersion: connectivity.iotoperations.azure.com/v1beta1
@@ -347,13 +326,13 @@ spec:
   operations:
   - operationType: Source
     sourceSettings:
-      endpointRef: mq
+      endpointRef: default
       dataSources:
         - tutorial/local
   - operationType: Destination
     destinationSettings:
       endpointRef: eventgrid
-      dataDestination: telemetry/iot-mq
+      dataDestination: telemetry/aio
 ---
 apiVersion: connectivity.iotoperations.azure.com/v1beta1
 kind: Dataflow
@@ -370,7 +349,7 @@ spec:
         - telemetry/#
   - operationType: Destination
     destinationSettings:
-      endpointRef: mq
+      endpointRef: default
       dataDestination: tutorial/cloud
 ```
 
@@ -383,10 +362,10 @@ Together, the two dataflows form an MQTT bridge, where you:
 * Use TLS for both remote and local brokers
 * Use system-assigned managed identity for authentication to the remote broker
 * Use Kubernetes service account for authentication to the local broker
-* Use the topic map to map the `tutorial/local` topic to the `telemetry/iot-mq` topic on the remote broker
+* Use the topic map to map the `tutorial/local` topic to the `telemetry/aio` topic on the remote broker
 * Use the topic map to map the `telemetry/#` topic on the remote broker to the `tutorial/cloud` topic on the local broker
 
-When you publish to the `tutorial/local` topic on the local Azure IoT Operations MQTT broker, the message is bridged to the `telemetry/iot-mq` topic on the remote Event Grid MQTT broker. Then, the message is bridged back to the `tutorial/cloud` topic (because the `telemetry/#` wildcard topic captures it) on the local Azure IoT Operations MQTT broker. Similarly, when you publish to the `telemetry/iot-mq` topic on the remote Event Grid MQTT broker, the message is bridged to the `tutorial/cloud` topic on the local Azure IoT Operations MQTT broker.
+When you publish to the `tutorial/local` topic on the local Azure IoT Operations MQTT broker, the message is bridged to the `telemetry/aio` topic on the remote Event Grid MQTT broker. Then, the message is bridged back to the `tutorial/cloud` topic (because the `telemetry/#` wildcard topic captures it) on the local Azure IoT Operations MQTT broker. Similarly, when you publish to the `telemetry/aio` topic on the remote Event Grid MQTT broker, the message is bridged to the `tutorial/cloud` topic on the local Azure IoT Operations MQTT broker.
 
 ## Deploy MQTT client
 
@@ -404,14 +383,20 @@ Currently, bicep doesn't apply to deploy MQTT client.
 
 ```yaml
 apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: mqtt-client
+  namespace: azure-iot-operations
+---
+apiVersion: v1
 kind: Pod
 metadata:
   name: mqtt-client
   # Namespace must match MQTT broker BrokerListener's namespace
   # Otherwise use the long hostname: aio-broker.azure-iot-operations.svc.cluster.local
   namespace: azure-iot-operations
 spec:
-  # Use the "mqtt-client" service account which comes with default deployment
+  # Use the "mqtt-client" service account from above
   # Otherwise create it with `kubectl create serviceaccount mqtt-client -n azure-iot-operations`
   serviceAccountName: mqtt-client
   containers:
@@ -435,7 +420,7 @@ spec:
           expirationSeconds: 86400
   - name: trust-bundle
     configMap:
-      name: aio-ca-trust-bundle-test-only # Default root CA cert
+      name: azure-iot-operations-aio-ca-trust-bundle # Default root CA cert
 ```
 
 Apply the deployment file with kubectl.

articles/iot-operations/create-edge-apps/howto-develop-dapr-apps.md

@@ -113,7 +113,7 @@ The following definition components might require customization to your specific
           # Certificate chain for Dapr to validate the MQTT broker
           - name: aio-ca-trust-bundle
             configMap:
-              name: aio-ca-trust-bundle-test-only
+              name: azure-iot-operations-aio-ca-trust-bundle
 
           containers:
           # Container for the Dapr application 

articles/iot-operations/create-edge-apps/howto-develop-mqttnet-apps.md

@@ -100,7 +100,7 @@ spec:
   # Certificate chain for the application to validate the MQTT broker              
   - name: aio-ca-trust-bundle
     configMap:
-      name: aio-ca-trust-bundle-test-only
+      name: azure-iot-operations-aio-ca-trust-bundle
 
   containers:
   - name: mqtt-client-dotnet

articles/iot-operations/create-edge-apps/tutorial-event-driven-with-dapr.md

@@ -91,7 +91,7 @@ To start, create a yaml file that uses the following definitions:
           # Certificate chain for Dapr to validate the MQTT broker
           - name: aio-ca-trust-bundle
             configMap:
-              name: aio-ca-trust-bundle-test-only
+              name: azure-iot-operations-aio-ca-trust-bundle
 
           containers:
           - name: mq-event-driven-dapr
@@ -189,7 +189,7 @@ To verify the MQTT bridge is working, deploy an MQTT client to the cluster.
               expirationSeconds: 86400
       - name: aio-ca-trust-bundle
         configMap:
-          name: aio-ca-trust-bundle-test-only
+          name: azure-iot-operations-aio-ca-trust-bundle
     ```
 
 1. Apply the deployment file with kubectl:

articles/iot-operations/manage-mqtt-broker/howto-test-connection.md

@@ -41,14 +41,20 @@ The first option is to connect from within the cluster. This option uses the def
 
     ```yaml
     apiVersion: v1
+    kind: ServiceAccount
+    metadata:
+      name: mqtt-client
+      namespace: azure-iot-operations
+    ---
+    apiVersion: v1
     kind: Pod
     metadata:
       name: mqtt-client
       # Namespace must match MQTT broker BrokerListener's namespace
       # Otherwise use the long hostname: aio-broker.azure-iot-operations.svc.cluster.local
       namespace: azure-iot-operations
     spec:
-      # Use the "mqtt-client" service account which comes with default deployment
+      # Use the "mqtt-client" service account created from above
       # Otherwise create it with `kubectl create serviceaccount mqtt-client -n azure-iot-operations`
       serviceAccountName: mqtt-client
       containers:
@@ -128,10 +134,10 @@ The first option is to connect from within the cluster. This option uses the def
 
 Since the broker uses TLS, the client must trust the broker's TLS certificate chain. You need to configure the client to trust the root CA certificate used by the broker.
 
-To use the default root CA certificate, download it from the `aio-ca-trust-bundle-test-only` ConfigMap:
+To use the default root CA certificate, download it from the `azure-iot-operations-aio-ca-trust-bundle` ConfigMap:
 
 ```bash
-kubectl get configmap aio-ca-trust-bundle-test-only -n azure-iot-operations -o jsonpath='{.data.ca\.crt}' > ca.crt
+kubectl get configmap azure-iot-operations-aio-ca-trust-bundle -n azure-iot-operations -o jsonpath='{.data.ca\.crt}' > ca.crt
 ```
 
 Use the downloaded `ca.crt` file to configure your client to trust the broker's TLS certificate chain.