Merge pull request #283921 from ryanwinterms/main

AIO Dapr updates for improved troubleshooting and simpler deployment

Author: JamesJBarnett

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

@@ -20,7 +20,7 @@ Azure IoT Operations supports two of these building blocks, powered by [MQTT bro
 - Publish and subscribe
 - State management
 
-To use the Dapr pluggable components, define the component spec for each of the APIs and then [register this to the cluster](https://docs.dapr.io/operations/components/pluggable-components-registration/). The Dapr components listen to a Unix domain socket placed on the shared volume. The Dapr runtime connects with each socket and discovers all services from a given building block API that the component implements.
+To use the Dapr pluggable components, define the component spec for each of the APIs and then [register with the cluster](https://docs.dapr.io/operations/components/pluggable-components-registration/). The Dapr components listen to a Unix domain socket placed on the shared volume. The Dapr runtime connects with each socket and discovers all services from a given building block API that the component implements.
 
 ## Install Dapr runtime
 
@@ -44,15 +44,15 @@ To create the yaml file, use the following component definitions:
 > [!div class="mx-tdBreakAll"]
 > | Component | Description |
 > |-|-|
-> | `metadata.name` | The component name is important and is how a Dapr application references the component. |
-> | `metadata.annotations` | Component annotations used by Dapr sidecar injector, defining the image location and required volume mounts
-> | `spec.type` | [The type of the component](https://docs.dapr.io/operations/components/pluggable-components-registration/#define-the-component), which needs to be declared exactly as shown |
-> | `spec.metadata.keyPrefix` | Defines the key prefix used when communicating to the statestore backend. See the [Dapr documentation](https://docs.dapr.io/developing-applications/building-blocks/state-management/howto-share-state) for more information |
-> | `spec.metadata.hostname` | The MQTT broker hostname. Defaults to `aio-mq-dmqtt-frontend` |
-> | `spec.metadata.tcpPort` | The MQTT broker port number. Default is `8883` |
-> | `spec.metadata.useTls` |  Define if TLS is used by the MQTT broker. Defaults to `true` |
-> | `spec.metadata.caFile` | The certificate chain path for validating the MQTT broker. Required if `useTls` is `true`. This file must be mounted in the pod with the specified volume name |
-> | `spec.metadata.satAuthFile ` | The Service Account Token (SAT) file is used to authenticate the Dapr components with the MQTT broker.  This file must be mounted in the pod with the specified volume name |
+> | `metadata:name` | The component name is important and is how a Dapr application references the component. |
+> | `metadata:annotations:dapr.io/component-container` | Component annotations used by Dapr sidecar injector, defining the image location, volume mounts and logging configuration |
+> | `spec:type` | [The type of the component](https://docs.dapr.io/operations/components/pluggable-components-registration/#define-the-component), which needs to be declared exactly as shown |
+> | `spec:metadata:keyPrefix` | Defines the key prefix used when communicating to the statestore backend. See more information, see [Dapr documentation](https://docs.dapr.io/developing-applications/building-blocks/state-management/howto-share-state) for more information |
+> | `spec:metadata:hostname` | The MQTT broker hostname. Default is `aio-mq-dmqtt-frontend` |
+> | `spec:metadata:tcpPort` | The MQTT broker port number. Default is `8883` |
+> | `spec:metadata:useTls` |  Define if TLS is used by the MQTT broker. Default is `true` |
+> | `spec:metadata:caFile` | The certificate chain path for validating the MQTT broker. Required if `useTls` is `true`. This file must be mounted in the pod with the specified volume name |
+> | `spec:metadata:satAuthFile ` | The Service Account Token (SAT) file is used to authenticate the Dapr components with the MQTT broker.  This file must be mounted in the pod with the specified volume name |
 
 1. Save the following yaml, which contains the Azure IoT Operations component definitions, to a file named `components.yaml`:
 
@@ -70,6 +70,10 @@ To create the yaml file, use the following component definitions:
             "volumeMounts": [
               { "name": "mqtt-client-token", "mountPath": "/var/run/secrets/tokens" },
               { "name": "aio-ca-trust-bundle", "mountPath": "/var/run/certs/aio-mq-ca-cert" }
+            ],
+            "env": [
+                { "name": "pubSubLogLevel", "value": "Information" },
+                { "name": "stateStoreLogLevel", "value": "Information" }
             ]
           }
     spec:
@@ -163,4 +167,4 @@ To configure authorization policies to MQTT broker, first you create a [BrokerAu
 
 ## Next steps
 
-Now that you have deployed the Dapr components, you can [Use Dapr to develop distributed applications](howto-develop-dapr-apps.md).
+Now that the Dapr components are deployed to the cluster, you can [Use Dapr to develop distributed applications](howto-develop-dapr-apps.md).

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

@@ -36,7 +36,7 @@ The first step is to write an application that uses a Dapr SDK to publish/subscr
 
 After you finish writing the Dapr application, build the container:
 
-1. To package the application into a container, run the following command:
+1. Package the application into a container with the following command:
 
     ```bash
     docker build . -t my-dapr-app
@@ -50,17 +50,20 @@ After you finish writing the Dapr application, build the container:
 
 ## Deploy a Dapr application
 
-The following [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) definition contains the volumes required to deploy the application along with the required containers. This deployment utilizes the Dapr sidecar injector to automatically add the pluggable component pod.
+The following [Deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) definition contains volumes for SAT authentication and TLS certificate chain, and utilizes Dapr sidecar injection to automatically add the pluggable components to the Pod.
 
-The yaml contains both a ServiceAccount, used to generate SATs for authentication with MQTT broker and the Dapr application Deployment.
-
-To create the yaml file, use the following definitions:
+The following definition components might require customization to your specific application:
 
 > | Component | Description |
 > |-|-|
-> | `volumes.mqtt-client-token` | The System Authentication Token used for authenticating the Dapr pluggable components with the MQTT broker |
-> | `volumes.aio-ca-trust-bundle` | The chain of trust to validate the MQTT broker TLS cert. This defaults to the test certificate deployed with Azure IoT Operations |
-> | `containers.mq-dapr-app` | The Dapr application container you want to deploy |
+> | `template:metadata:annotations:dapr.io/inject-pluggable-components` | Allows the IoT Operations pluggable components to be [automatically injected](https://docs.dapr.io/operations/components/pluggable-components-registration/) into the pod |
+> | `template:metadata:annotations:dapr.io/app-port` | Tells Dapr which port your application is listening on. If your application us not using this feature (such as a pubsub subscription), then remove this line |
+> | `volumes:mqtt-client-token` | The System Authentication Token used for authenticating the Dapr pluggable components with the MQTT broker |
+> | `volumes:aio-ca-trust-bundle` | The chain of trust to validate the MQTT broker TLS cert. This defaults to the test certificate deployed with Azure IoT Operations |
+> | `containers:mq-dapr-app` | The Dapr application container you want to deploy |
+
+> [!CAUTION]
+> If your Dapr application is not listening for traffic from the Dapr sidecar, then remove the `dapr.io/app-port` and `dapr.io/app-protocol` [annotations](https://docs.dapr.io/reference/arguments-annotations-overview/) otherwise the Dapr sidecar will fail to initialize.
 
 1. Save the following yaml to a file named `dapr-app.yaml`:
 
@@ -76,21 +79,20 @@ To create the yaml file, use the following definitions:
     apiVersion: apps/v1
     kind: Deployment
     metadata:
-      name: mq-dapr-app
+      name: my-dapr-app
       namespace: azure-iot-operations
     spec:
-      replicas: 1
       selector:
         matchLabels:
-          app: mq-dapr-app
+          app: my-dapr-app
       template:
         metadata:
           labels:
-            app: mq-dapr-app
+            app: my-dapr-app
           annotations:
             dapr.io/enabled: "true"
             dapr.io/inject-pluggable-components: "true"
-            dapr.io/app-id: "mq-dapr-app"
+            dapr.io/app-id: "my-dapr-app"
             dapr.io/app-port: "6001"
             dapr.io/app-protocol: "grpc"
         spec:
@@ -124,23 +126,22 @@ To create the yaml file, use the following definitions:
     kubectl get pods -w
     ```
 
-    The workload pod should report all pods running after a short interval, as shown in the following example output:
+    The pod should report three containers running after a short interval, as shown in the following example output:
 
     ```output
-    pod/dapr-workload created
     NAME                          READY   STATUS              RESTARTS   AGE
     ...
-    dapr-workload                 3/3     Running             0          30s
+    my-dapr-app                   3/3     Running             0          30s
     ```
 
 ## Troubleshooting
 
-If the application doesn't start or you see the pods in `CrashLoopBackoff`, the logs for `daprd` are most helpful. The `daprd` is a container that automatically deploys with your Dapr application.
+If the application doesn't start or you see the containers in `CrashLoopBackoff` state, the log for the `daprd` container often contains useful information.
 
-Run the following command to view the logs:
+Run the following command to view the logs for the daprd component:
 
 ```bash
-kubectl logs dapr-workload daprd
+kubectl logs -l app=my-dapr-app -c daprd
 ```
 
 ## Next steps

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

@@ -16,52 +16,45 @@ ms.date: 07/02/2024
 
 [!INCLUDE [public-preview-note](../includes/public-preview-note.md)]
 
-[MQTTnet](https://dotnet.github.io/MQTTnet/) is an open-source, high performance .NET library for MQTT based communication. This article uses a Kubernetes service account token and MQTTnet to connect to MQTT broker. You should use service account tokens to connect to in-cluster clients.
+[MQTTnet](https://dotnet.github.io/MQTTnet/) is an open-source, high performance .NET library for MQTT based communication. This article uses a Kubernetes service account token and MQTTnet to connect to MQTT broker. You should use service account tokens to connect in-cluster applications.
 
 ## Sample code
 
 The [sample code](https://github.com/Azure-Samples/explore-iot-operations/tree/main/samples/mqtt-client-dotnet/Program.cs) performs the following steps:
 
-1. Creates an MQTT client using the `MQTTFactory` class:
+1. Creates an MQTT client using the `MqttFactory` class:
 
     ```csharp
     var mqttFactory = new MqttFactory();
     var mqttClient = mqttFactory.CreateMqttClient();
     ```
 
-1. The following Kubernetes pod specification mounts the service account token to the specified path on the container file system. The mounted token is used as the password with well-known username `K8S-SAT`:
+1. The [Kubernetes pod specification](#pod-specification) mounts the service account on the container file system. The contents of the file are read:
+##3. The mounted token is used as the password with well-known username `K8S-SAT`:
 
     ```csharp
-    string token_path = "/var/run/secrets/tokens/mqtt-client-token";
+    static string sat_auth_file = "/var/run/secrets/tokens/mqtt-client-token";
     ...
-
-    static async Task<int> MainAsync()
-    {
-        ...
-
-        // Read SAT Token
-        var satToken = File.ReadAllText(token_path);
+    var satToken = File.ReadAllBytes(sat_auth_file);
     ```
 
-1. All options for the MQTT client are bundled in the class named `MqttClientOptions`. It's possible to fill options manually in code via the properties but you should use the `MqttClientOptionsBuilder` as advised in the [client](https://github.com/dotnet/MQTTnet/wiki/Client) documentation. The following code shows how to use the builder with the following options:
+1. The MQTT client options are configured using the `MqttClientOptions` class. Using the `MqttClientOptionsBuilder` as advised in the [client](https://github.com/dotnet/MQTTnet/wiki/Client) documentation is the advised way of setting the options:
 
     ```csharp
-    # Create TCP based options using the builder amd connect to broker
     var mqttClientOptions = new MqttClientOptionsBuilder()
-        .WithTcpServer(broker, 1883)
+        .WithTcpServer(hostname, tcp_port)
         .WithProtocolVersion(MqttProtocolVersion.V500)
-        .WithClientId("sampleid")
-        .WithCredentials("K8S-SAT", satToken)
-        .Build();
+        .WithClientId("mqtt-client-dotnet")
+        .WithAuthentication("K8S-SAT", satToken);
     ```
 
-1. After setting up the MQTT client options, a connection can be established. The following code shows how to connect with a server. You can replace the *CancellationToken.None* with a valid *CancellationToken*, if needed.
+5. After setting up the MQTT client options, a connection can be established. The following code shows how to connect with a server. You can replace the `CancellationToken.None` with a valid CancellationToken if needed.
 
     ```csharp
-    var response = await mqttClient.ConnectAsync(mqttClientOptions, CancellationToken.None);
+    var response = await mqttClient.ConnectAsync(mqttClientOptions.Build(), CancellationToken.None);
     ```
 
-1. MQTT messages can be created using the properties directly or via using `MqttApplicationMessageBuilder`. This class has some useful overloads that allow dealing with different payload formats. The API of the builder is a fluent API. The following code shows how to compose an application message and publish them to a topic called *sampletopic*:
+6. MQTT messages can be created using the properties directly or using `MqttApplicationMessageBuilder`. This class has overloads that allow dealing with different payload formats. The API of the builder is a fluent API. The following code shows how to compose an application message and publish them to an article called *sampletopic*:
 
     ```csharp
     var applicationMessage = new MqttApplicationMessageBuilder()
@@ -70,61 +63,68 @@ The [sample code](https://github.com/Azure-Samples/explore-iot-operations/tree/m
         .Build();
 
     await mqttClient.PublishAsync(applicationMessage, CancellationToken.None);
-    Console.WriteLine("The MQTT client published a message.");
     ```
 
 ## Pod specification
 
-The `serviceAccountName` field in the pod configuration must match the service account associated with the token being used. Also, note the `serviceAccountToken.expirationSeconds` is set to **86400 seconds**, and once it expires, you need to reload the token from disk. This logic isn't currently implemented in the sample.
+The `serviceAccountName` field in the pod configuration must match the service account associated with the token being used. Also, note the `serviceAccountToken.expirationSeconds` is set to **86400 seconds**, and once it expires, you need to reload the token from disk. This logic isn't implemented in this sample.
 
 ```yaml
 apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: mqtt-client
+  namespace: azure-iot-operations
+
+---
+apiVersion: v1
 kind: Pod
 metadata:
   name: mqtt-client-dotnet
-  labels:
-    app: publisher
+  namespace: azure-iot-operations
 spec:
   serviceAccountName: mqtt-client
 
-  volumes: 
-    # SAT token used to authenticate between the application and the MQTT broker
-    - name: mqtt-client-token
-      projected:
-        sources:
-          - serviceAccountToken:
-              path: mqtt-client-token
-              audience: aio-mq-dmqtt
-              expirationSeconds: 86400
-    
-    # Certificate chain for the application to validate the MQTT broker    
-    - name: aio-mq-ca-cert-chain
-      configMap:
-        name: aio-mq-ca-cert-chain
+  volumes:
+
+  # SAT token used to authenticate between the application and the MQTT broker  
+  - name: mqtt-client-token
+    projected:
+      sources:
+      - serviceAccountToken:
+          path: mqtt-client-token
+          audience: aio-mq
+          expirationSeconds: 86400
+
+  # Certificate chain for the application to validate the MQTT broker              
+  - name: aio-ca-trust-bundle
+    configMap:
+      name: aio-ca-trust-bundle-test-only
 
   containers:
-    - name: mqtt-client-dotnet
-      image: ghcr.io/azure-samples/explore-iot-operations/mqtt-client-dotnet:latest
-      imagePullPolicy: IfNotPresent
-      volumeMounts:
-        - name: mqtt-client-token
-          mountPath: /var/run/secrets/tokens
-        - name: aio-mq-ca-cert-chain
-          mountPath: /certs/aio-mq-ca-cert/      
-      env:
-        - name: IOT_MQ_HOST_NAME
-          value: "aio-mq-dmqtt-frontend"
-        - name: IOT_MQ_PORT
-          value: "8883"
-        - name: IOT_MQ_TLS_ENABLED
-          value: "true"
+  - name: mqtt-client-dotnet
+    image: ghcr.io/azure-samples/explore-iot-operations/mqtt-client-dotnet:latest
+    volumeMounts:
+    - name: mqtt-client-token
+      mountPath: /var/run/secrets/tokens/
+    - name: aio-ca-trust-bundle
+      mountPath: /var/run/certs/aio-mq-ca-cert/
+    env:
+    - name: hostname
+      value: "aio-mq-dmqtt-frontend"
+    - name: tcpPort
+      value: "8883"
+    - name: useTls
+      value: "true"
+    - name: caFile
+      value: "/var/run/certs/aio-mq-ca-cert/ca.crt"
+    - name: satAuthFile
+      value: "/var/run/secrets/tokens/mqtt-client-token"
 ```
 
-The token is mounted into the container at the path specified in `containers[].volumeMount.mountPath`
-
 To run the sample, follow the instructions in its [README](https://github.com/Azure-Samples/explore-iot-operations/tree/main/samples/mqtt-client-dotnet).
 
 ## Related content
 
-- [MQTT broker overview](../manage-mqtt-broker/overview-iot-mq.md)
-- [Develop with MQTT broker](edge-apps-overview.md)
+- [Publish and subscribe MQTT messages using MQTT broker](../manage-mqtt-broker/overview-iot-mq.md)
+- [Develop highly available distributed applications](edge-apps-overview.md)