Merge pull request #106021 from MicrosoftDocs/release-iotedge-109

Release iotedge 109

Author: huypub

.openpublishing.redirection.json

@@ -3258,6 +3258,11 @@
       "redirect_url": "/azure/iot-edge/how-to-register-device",
       "redirect_document_id": false
     },
+    {
+      "source_path": "articles/iot-edge/how-to-install-production-certificates.md",
+      "redirect_url": "/azure/iot-edge/how-to-manage-device-certificates",
+      "redirect_document_id": true
+    },
     {
       "source_path": "articles/cognitive-services/cognitive-services-recommendations-quick-start.md",
       "redirect_url": "/azure/cognitive-services/recommendations/overview",

articles/iot-edge/TOC.yml

@@ -125,8 +125,8 @@
       href: how-to-install-iot-edge-ubuntuvm.md
     - name: Kubernetes
       href: how-to-install-iot-edge-kubernetes.md
-    - name: Install production certificates
-      href: how-to-install-production-certificates.md
+    - name: Manage device certificates
+      href: how-to-manage-device-certificates.md
     - name: Create test certificates
       href: how-to-create-test-certificates.md
     - name: Update the runtime version
@@ -139,6 +139,8 @@
         href: how-to-auto-provision-simulated-device-linux.md
       - name: Windows
         href: how-to-auto-provision-simulated-device-windows.md
+    - name: X.509 certificate attestation
+      href: how-to-auto-provision-x509-certs.md
     - name: Symmetric key attestation
       href: how-to-auto-provision-symmetric-keys.md
   - name: Develop and debug custom modules
@@ -149,20 +151,26 @@
       href: how-to-vs-code-develop-module.md
   - name: Deploy modules
     items:
-    - name: Azure portal
-      href: how-to-deploy-modules-portal.md
-    - name: Azure CLI
-      href: how-to-deploy-modules-cli.md
-    - name: Visual Studio Code
-      href: how-to-deploy-modules-vscode.md
-  - name: Deploy and monitor at scale
+    - name: Deploy to individual devices
+      items:
+      - name: Azure portal
+        href: how-to-deploy-modules-portal.md
+      - name: Azure CLI
+        href: how-to-deploy-modules-cli.md
+      - name: Visual Studio Code
+        href: how-to-deploy-modules-vscode.md
+    - name: Deploy at scale
+      items:
+      - name: Azure portal
+        href: how-to-deploy-monitor.md
+      - name: Azure CLI
+        href: how-to-deploy-monitor-cli.md
+      - name: Visual Studio Code
+        href: how-to-deploy-monitor-vscode.md
+  - name: Monitor and diagnose deployments
     items:
-    - name: Azure portal
-      href: how-to-deploy-monitor.md
-    - name: Azure CLI
-      href: how-to-deploy-monitor-cli.md
-    - name: Visual Studio Code
-      href: how-to-deploy-monitor-vscode.md
+      - name: EdgeAgent direct methods
+        href: how-to-edgeagent-direct-method.md
   - name: Use IoT Edge devices as gateways
     items:
     - name: Configure a transparent gateway

articles/iot-edge/how-to-auto-provision-x509-certs.md

@@ -4,7 +4,7 @@ description: Create test certificates and learn how to install them on an Azure
 author: kgremban
 manager: philmea
 ms.author: kgremban
-ms.date: 12/07/2019
+ms.date: 02/26/2020
 ms.topic: conceptual
 ms.service: iot-edge
 services: iot-edge
@@ -22,6 +22,15 @@ You can create certificates on any machine, and then copy them over to your IoT
 It's easier to use your primary machine to create the certificates rather than generating them on your IoT Edge device itself.
 By using your primary machine, you can set up the scripts once and then repeat the process to create certificates for multiple devices.
 
+Follow these steps to create demo certificates for testing your IoT Edge scenario:
+
+1. [Set up scripts](#set-up-scripts) for certificate generation on your device.
+2. [Create the root CA certificate](#create-root-ca-certificate) that you use to sign all the other certificates for your scenario.
+3. Generate the certificates you need for the scenario you want to test:
+   * [Create IoT Edge device identity certificates](#create-iot-edge-device-identity-certificates) to test automatic provisioning with the IoT Hub Device Provisioning Service.
+   * [Create IoT Edge device CA certificates](#create-iot-edge-device-ca-certificates) to test production scenarios or gateway scenarios.
+   * [Create downstream device certificates](#create-downstream-device-certificates) to test authenticating downstream devices to IoT Hub in a gateway scenario.
+
 ## Prerequisites
 
 A development machine with Git installed.
@@ -169,7 +178,11 @@ Before proceeding with the steps in this section, follow the steps in the [Set u
 
 ## Create IoT Edge device CA certificates
 
-Every IoT Edge device going to production needs a device CA certificate that's referenced from the config.yaml file. The device CA certificate is responsible for creating certificates for modules running on the device. It's also how the IoT Edge device verifies its identity when connecting to downstream devices.
+Every IoT Edge device going to production needs a device CA certificate that's referenced from the config.yaml file.
+The device CA certificate is responsible for creating certificates for modules running on the device.
+It's also how the IoT Edge device verifies its identity when connecting to downstream devices.
+
+Device CA certificates go in the **Certificate** section of the config.yaml file on the IoT Edge device.
 
 Before proceeding with the steps in this section, follow the steps in the [Set up scripts](#set-up-scripts) and [Create root CA certificate](#create-root-ca-certificate) sections.
 
@@ -188,7 +201,9 @@ Before proceeding with the steps in this section, follow the steps in the [Set u
    * `<WRKDIR>\certs\iot-edge-device-MyEdgeDeviceCA-full-chain.cert.pem`
    * `<WRKDIR>\private\iot-edge-device-MyEdgeDeviceCA.key.pem`
 
-The gateway device name passed into those scripts should not be the same as the "hostname" parameter in config.yaml. The scripts help you avoid any issues by appending a ".ca" string to the gateway device name to prevent the name collision in case a user sets up IoT Edge using the same name in both places. However, it's good practice to avoid using the same name.
+The gateway device name passed into those scripts should not be the same as the "hostname" parameter in config.yaml, or the device's ID in IoT Hub.
+The scripts help you avoid any issues by appending a ".ca" string to the gateway device name to prevent the name collision in case a user sets up IoT Edge using the same name in both places.
+However, it's good practice to avoid using the same name.
 
 ### Linux
 
@@ -205,9 +220,49 @@ The gateway device name passed into those scripts should not be the same as the
    * `<WRKDIR>/certs/iot-edge-device-MyEdgeDeviceCA-full-chain.cert.pem`
    * `<WRKDIR>/private/iot-edge-device-MyEdgeDeviceCA.key.pem`
 
-The gateway device name passed into those scripts should not be the same as the "hostname" parameter in config.yaml. The scripts help you avoid any issues by appending a ".ca" string to the gateway device name to prevent the name collision in case a user sets up IoT Edge using the same name in both places. However, it's good practice to avoid using the same name.
+The gateway device name passed into those scripts should not be the same as the "hostname" parameter in config.yaml, or the device's ID in IoT Hub.
+The scripts help you avoid any issues by appending a ".ca" string to the gateway device name to prevent the name collision in case a user sets up IoT Edge using the same name in both places.
+However, it's good practice to avoid using the same name.
+
+## Create IoT Edge device identity certificates
+
+Device identity certificates are used to provision IoT Edge devices through the [Azure IoT Hub Device Provisioning Service (DPS)](../iot-dps/index.yml).
+
+Device identity certificates go in the **Provisioning** section of the config.yaml file on the IoT Edge device.
+
+Before proceeding with the steps in this section, follow the steps in the [Set up scripts](#set-up-scripts) and [Create root CA certificate](#create-root-ca-certificate) sections.
+
+### Windows
+
+Create the IoT Edge device identity certificate and private key with the following command:
+
+```powershell
+New-CACertsEdgeDeviceIdentity "<name>"
+```
+
+The name that you pass in to this command will be the device ID for the IoT Edge device in IoT Hub.
+
+The new device identity command creates several certificate and key files, including two that you'll use when creating an individual enrollment in DPS and installing the IoT Edge runtime:
+
+* `<WRKDIR>\certs\iot-edge-device-identity-<name>.cert.pem`
+* `<WRKDIR>\private\iot-edge-device-identity-<name>.key.pem`
+
+### Linux
+
+Create the IoT Edge device identity certificate and private key with the following command:
+
+```bash
+./certGen.sh create_edge_device_identity_certificate "<name>"
+```
+
+The name that you pass in to this command will be the device ID for the IoT Edge device in IoT Hub.
+
+The script creates several certificate and key files, including two that you'll use when creating an individual enrollment in DPS and installing the IoT Edge runtime:
+
+* `<WRKDIR>/certs/iot-edge-device-identity-<name>.cert.pem`
+* `<WRKDIR>/private/iot-edge-device-identity-<name>.key.pem`
 
-## Create X.509 certs for downstream devices
+## Create downstream device certificates
 
 If you're setting up a downstream IoT device for a gateway scenario, you can generate demo certificates for X.509 authentication.
 There are two ways to authenticate an IoT device using X.509 certificates: using self-signed certs or using certificate authority (CA) signed certs.

articles/iot-edge/how-to-create-test-certificates.md

@@ -43,7 +43,7 @@ The following steps walk you through the process of creating the certificates an
 
 ## Prerequisites
 
-An Azure IoT Edge device, configured with [production certificates](how-to-install-production-certificates.md).
+An Azure IoT Edge device, configured with [production certificates](how-to-manage-device-certificates.md).
 
 ## Deploy edgeHub to the gateway
 

articles/iot-edge/how-to-create-transparent-gateway.md

@@ -0,0 +1,74 @@
+---
+title: Built-in edgeAgent direct methods - Azure IoT Edge
+description: Monitor and manage an IoT Edge deployment using built-in direct methods in the IoT Edge agent runtime module
+author: kgremban
+manager: philmea
+ms.author: kgremban
+ms.date: 02/19/2020
+ms.topic: conceptual
+ms.reviewer: veyalla
+ms.service: iot-edge
+services: iot-edge
+---
+
+# Communicate with edgeAgent using built-in direct methods
+
+Monitor and manage IoT Edge deployments by using the direct methods included in the IoT Edge agent module. Direct methods are implemented on the device, and then can be invoked from the cloud. The IoT Edge agent includes direct methods that help you monitor and manage your IoT Edge devices remotely.
+
+For more information about direct methods, how to use them, and how to implement them in your own modules, see [Understand and invoke direct methods from IoT Hub](../iot-hub/iot-hub-devguide-direct-methods.md).
+
+## Ping
+
+The **ping** method is useful for checking whether IoT Edge is running on a device, or whether the device has an open connection to ioT Hub. Use this direct method to ping the IoT Edge agent and get its status. A successful ping returns an empty payload and **"status": 200**.
+
+For example:
+
+```azurecli
+az iot hub invoke-module-method --method-name 'ping' -n <hub name> -d <device name> -m '$edgeAgent'
+```
+
+In the Azure portal, invoke the method with the method name `ping` and an empty JSON payload `{}`.
+
+![Invoke direct method 'ping' in Azure portal](./media/how-to-edgeagent-direct-method/ping-direct-method.png)
+
+## Restart module
+
+The **RestartModule** method allows for remote management of modules running on an IoT Edge device. If a module is reporting a failed state or other unhealthy behavior, you can trigger the IoT Edge agent to restart it. A successful restart command returns an empty payload and **"status": 200**.
+
+The RestartModule method is available in IoT Edge version 1.0.9 and later. 
+
+You can use the RestartModule direct method on any module running on an IoT Edge device, including the edgeAgent module itself. However, if you use this direct method to shut down the edgeAgent, you won't receive a success result since the connection is disrupted while the module restarts.
+
+For example:
+
+```azurecli
+az iot hub invoke-module-method --method-name 'RestartModule' -n <hub name> -d <device name> -m '$edgeAgent' --method-payload \
+'
+    {
+        "schemaVersion": "1.0",
+        "id": "<module name>"
+    }
+'
+```
+
+In the Azure portal, invoke the method with the method name `RestartModule` and the following JSON payload:
+
+```json
+{
+    "schemaVersion": "1.0",
+    "id": "<module name>"
+}
+```
+
+![Invoke direct method 'RestartModule' in Azure portal](./media/how-to-edgeagent-direct-method/restartmodule-direct-method.png)
+
+## Experimental methods
+
+New direct method options are available as experimental features to test, including:
+
+* [UploadLogs](https://github.com/Azure/iotedge/blob/master/doc/built-in-logs-pull.md): Retrieve module logs and upload them to Azure Blob Storage.
+* [GetTaskStatus](https://github.com/Azure/iotedge/blob/master/doc/built-in-logs-pull.md#gettaskstatus): Check on the status of an upload logs request.
+
+## Next steps
+
+[Properties of the IoT Edge agent and IoT Edge hub module twins](module-edgeagent-edgehub.md)

articles/iot-edge/how-to-edgeagent-direct-method.md

@@ -8,7 +8,7 @@ ms.reviewer: veyalla
 ms.service: iot-edge
 services: iot-edge
 ms.topic: conceptual
-ms.date: 07/22/2019
+ms.date: 02/21/2020
 ms.author: kgremban
 ---
 # Install the Azure IoT Edge runtime on Debian-based Linux systems
@@ -174,20 +174,12 @@ sudo nano /etc/iotedge/config.yaml
 
 Find the provisioning configurations of the file and uncomment the **Manual provisioning configuration** section. Update the value of **device_connection_string** with the connection string from your IoT Edge device. Make sure any other provisioning sections are commented out. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
 
-   ```yaml
+   ```yml
    # Manual provisioning configuration
    provisioning:
      source: "manual"
      device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
-  
-   # DPS TPM provisioning configuration
-   # provisioning:
-   #   source: "dps"
-   #   global_endpoint: "https://global.azure-devices-provisioning.net"
-   #   scope_id: "{scope_id}"
-   #   attestation:
-   #     method: "tpm"
-   #     registration_id: "{registration_id}"
+     dyname_reprovisioning: false
    ```
 
 To paste clipboard contents into Nano `Shift+Right Click` or press `Shift+Insert`.
@@ -204,37 +196,67 @@ sudo systemctl restart iotedge
 
 ### Option 2: Automatic provisioning
 
-To automatically provision a device, [set up Device Provisioning Service and retrieve your device registration ID](how-to-auto-provision-simulated-device-linux.md). There are a number of attestation mechanisms supported by IoT Edge when using automatic provisioning but your hardware requirements also impact your choices. For example, Raspberry Pi devices do not come with a Trusted Platform Module (TPM) chip by default.
+IoT Edge devices can be automatically provisioned using the [Azure IoT Hub Device Provisioning Service (DPS)](../iot-dps/index.yml). Currently, IoT Edge supports two attestation mechanisms when using automatic provisioning, but your hardware requirements may impact your choices. For example, Raspberry Pi devices do not come with a Trusted Platform Module (TPM) chip by default. For more information, refer to the following articles:
+
+* [Create and provision an IoT Edge device with a virtual TPM on a Linux VM](how-to-auto-provision-simulated-device-linux.md)
+* [Create and provision an IoT Edge device using X.509 certificates](how-to-auto-provision-x509-certs.md)
+* [Create and provision an IoT Edge device using symmetric key attestation](how-to-auto-provision-symmetric-keys.md)
+
+Those articles walk you through setting up enrollments in DPS, and generating the proper certificates or keys for attestation. Regardless of which attestation mechanism you choose, the provisioning information is added to the IoT Edge configuration file on your IoT Edge device.
 
 Open the configuration file.
 
 ```bash
 sudo nano /etc/iotedge/config.yaml
 ```
 
-Find the provisioning configurations of the file and uncomment the section appropriate for your attestation mechanism. When using TPM attestation, for example, update the values of **scope_id** and **registration_id** with the values from your IoT Hub Device Provisioning service and your IoT Edge device with TPM, respectively. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
+Find the provisioning configurations of the file and uncomment the section appropriate for your attestation mechanism. Make sure any other provisioning sections are commented out. The **provisioning:** line should have no preceding whitespace, and nested items should be indented by two spaces. Update the value of **scope_id** with the value from your IoT Hub Device Provisioning Service instance, and provide the appropriate values for the attestation fields.
 
-   ```yaml
-   # Manual provisioning configuration
-   # provisioning:
-   #   source: "manual"
-   #   device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"
-  
-   # DPS TPM provisioning configuration
-   provisioning:
-     source: "dps"
-     global_endpoint: "https://global.azure-devices-provisioning.net"
-     scope_id: "{scope_id}"
-     attestation:
-       method: "tpm"
-       registration_id: "{registration_id}"
-   ```
+TPM attestation:
 
-To paste clipboard contents into Nano `Shift+Right Click` or press `Shift+Insert`.
+```yml
+# DPS TPM provisioning configuration
+provisioning:
+  source: "dps"
+  global_endpoint: "https://global.azure-devices-provisioning.net"
+  scope_id: "{scope_id}"
+  attestation:
+    method: "tpm"
+    registration_id: "{registration_id}"
+```
 
-Save and close the file.
+X.509 attestation:
+
+```yml
+# DPS X.509 provisioning configuration
+provisioning:
+  source: "dps"
+  global_endpoint: "https://global.azure-devices-provisioning.net"
+  scope_id: "{scope_id}"
+  attestation:
+    method: "x509"
+#   registration_id: "<OPTIONAL REGISTRATION ID. IF UNSPECIFIED CAN BE OBTAINED FROM CN OF identity_cert"
+    identity_cert: "<REQUIRED URI TO DEVICE IDENTITY CERTIFICATE>"
+    identity_pk: "<REQUIRED URI TO DEVICE IDENTITY PRIVATE KEY>"
+```
 
-   `CTRL + X`, `Y`, `Enter`
+Symmetric key attestation:
+
+```yml
+# DPS symmetric key provisioning configuration
+provisioning:
+  source: "dps"
+  global_endpoint: "https://global.azure-devices-provisioning.net"
+  scope_id: "{scope_id}"
+  attestation:
+    method: "symmetric_key"
+    registration_id: "{registration_id}"
+    symmetric_key: "{symmetric_key}"
+```
+
+To paste clipboard contents into Nano `Shift+Right Click` or press `Shift+Insert`.
+
+Save and close the file. `CTRL + X`, `Y`, `Enter`
 
 After entering the provisioning information in the configuration file, restart the daemon: