Merge pull request #106217 from kgremban/mar02-109release

IoT Edge 1.0.9 release

Author: megvanhuygen

.openpublishing.redirection.json

@@ -3265,6 +3265,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-symmetric-keys.md

@@ -170,14 +170,14 @@ The section in the configuration file for symmetric key provisioning looks like
 provisioning:
    source: "dps"
    global_endpoint: "https://global.azure-devices-provisioning.net"
-   scope_id: "{scope_id}"
+   scope_id: "<SCOPE_ID>"
    attestation:
       method: "symmetric_key"
-      registration_id: "{registration_id}"
-      symmetric_key: "{symmetric_key}"
+      registration_id: "<REGISTRATION_ID>"
+      symmetric_key: "<SYMMETRIC_KEY>"
 ```
 
-Replace the placeholder values for `{scope_id}`, `{registration_id}`, and `{symmetric_key}` with the data you collected earlier. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
+Replace the placeholder values for `<SCOPE_ID>`, `<REGISTRATION_ID>`, and `<SYMMETRIC_KEY>` with the data you collected earlier. Make sure the **provisioning:** line has no preceding whitespace and that nested items are indented by two spaces.
 
 ### Windows device
 

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.
@@ -49,7 +58,7 @@ There are several ways to install OpenSSL, including the following options:
 
    1. Navigate to a directory where you want to install vcpkg. Follow the instructions to download and install [vcpkg](https://github.com/Microsoft/vcpkg).
 
-   2. Once vcpkg is installed, run the following command from a powershell prompt to install the OpenSSL package for Windows x64. The installation typically takes about 5 minutes to complete.
+   2. Once vcpkg is installed, run the following command from a PowerShell prompt to install the OpenSSL package for Windows x64. The installation typically takes about 5 minutes to complete.
 
       ```powershell
       .\vcpkg install openssl:x64-windows
@@ -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: 03/02/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)