Merge pull request #78824 from kgremban/jun3-proxyissue

tfosmark · web-flow · commit 7de67642af0d · 2019-06-05T14:41:59.000-07:00
Improve clarity in proxy article
diff --git a/articles/iot-edge/how-to-configure-proxy-support.md b/articles/iot-edge/how-to-configure-proxy-support.md
@@ -4,7 +4,7 @@ description: How to configure the Azure IoT Edge runtime and any internet-facing
 author: kgremban
 manager: 
 ms.author: kgremban
-ms.date: 03/20/2019
+ms.date: 06/05/2019
 ms.topic: conceptual
 ms.service: iot-edge
 services: iot-edge
@@ -15,16 +15,35 @@ ms.custom: seodec18
 
 IoT Edge devices send HTTPS requests to communicate with IoT Hub. If your device is connected to a network that uses a proxy server, you need to configure the IoT Edge runtime to communicate through the server. Proxy servers can also affect individual IoT Edge modules if they make HTTP or HTTPS requests that aren't routed through the IoT Edge hub. 
 
-Configuring an IoT Edge device to work with a proxy server follows these basic steps: 
+This article walks through the following four steps to configure and then manage an IoT Edge device behind a proxy server: 
 
-1. Install the IoT Edge runtime on your device. 
-2. Configure the Docker daemon and the IoT Edge daemon on your device to use the proxy server.
-3. Configure the edgeAgent properties in the config.yaml file on your device.
-4. Set environment variables for the IoT Edge runtime and other IoT Edge modules in the deployment manifest.
+1. **Install the IoT Edge runtime on your device.**
+
+   The IoT Edge installation scripts pull packages and files from the internet, so your device needs to communicate through the proxy server to make those requests. For detailed steps, see the [Install the runtime through a proxy](#install-the-runtime-through-a-proxy) section of this article. For Windows devices, the installation script also provides an [Offline installation](how-to-install-iot-edge-windows.md#offline-installation) option. 
+
+   This step is a one-time process performed on the IoT Edge device when you first set it up. The same connections are also required when you update the IoT Edge runtime. 
+
+2. **Configure the Docker daemon and the IoT Edge daemon on your device.**
+
+   IoT Edge uses two daemons on the device, both of which need to make web requests through the proxy server. The IoT Edge daemon is responsible for communications with IoT Hub. The Moby daemon is responsible for container management, so communicates with container registries. For detailed steps, see the [Configure the daemons](#configure-the-daemons) section of this article. 
+
+   This step is a one-time process performed on the IoT Edge device when you first set it up.
+
+3. **Configure the IoT Edge agent properties in the config.yaml file on your device.**
+
+   The IoT Edge daemon starts the edgeAgent module initially, but then the edgeAgent module is responsible for retrieving the deployment manifest from IoT Hub and starting all the other modules. For the IoT Edge agent to make the initial connection to IoT Hub, configure the edgeAgent module environment variables manually on the device itself. After the initial connection, you can configure the edgeAgent module remotely. For detailed steps, see the [Configure the IoT Edge agent](#configure-the-iot-edge-agent) section of this article.
+
+   This step is a one-time process performed on the IoT Edge device when you first set it up.
+
+4. **For all future module deployments, set environment variables for any module communicating through the proxy.**
+
+   Once your IoT Edge device is set up and connected to IoT Hub through the proxy server, you need to maintain the connection in all future module deployments. For detailed steps, see the [Configure deployment manifests](#configure-deployment-manifests) section of this article. 
+
+   This step is an ongoing process performed remotely so that every new module or deployment update maintains the device's ability to communicate through the proxy server. 
 
 ## Know your proxy URL
 
-To configure both the Docker daemon and IoT Edge on your device, you need to know your proxy URL.
+Before you begin any of the steps in this article, you need to know your proxy URL.
 
 Proxy URLs take the following format: **protocol**://**proxy_host**:**proxy_port**.
 
@@ -34,11 +53,19 @@ Proxy URLs take the following format: **protocol**://**proxy_host**:**proxy_port
 
 * The **proxy_port** is the network port at which the proxy responds to network traffic.
 
-## Install the runtime
+## Install the runtime through a proxy
+
+Whether your IoT Edge device runs on Windows or Linux, you need to access the installation packages through the proxy server. Depending on your operating system, follow the steps to install the IoT Edge runtime through a proxy server. 
+
+### Linux
 
 If you're installing the IoT Edge runtime on a Linux device, configure the package manager to go through your proxy server to access the installation package. For example, [Set up apt-get to use a http-proxy](https://help.ubuntu.com/community/AptGet/Howto/#Setting_up_apt-get_to_use_a_http-proxy). Once your package manager is configured, follow the instructions in [Install Azure IoT Edge runtime on Linux (ARM32v7/armhf)](how-to-install-iot-edge-linux-arm.md) or [Install the Azure IoT Edge runtime on Linux (x64)](how-to-install-iot-edge-linux.md) as usual.
 
-If you're installing the IoT Edge runtime on a Windows device, you need to go through the proxy server twice. The first connection is to download the installer script file, and the second connection is during the installation to download the necessary components. You can configure proxy information in Windows settings, or include your proxy information directly in the PowerShell commands. The following steps demonstrate an example of a windows installation using the `-proxy` argument:
+### Windows
+
+If you're installing the IoT Edge runtime on a Windows device, you need to go through the proxy server twice. The first connection downloads the installer script file, and the second connection is during the installation to download the necessary components. You can configure proxy information in Windows settings, or include your proxy information directly in the PowerShell commands. 
+
+The following steps demonstrate an example of a windows installation using the `-proxy` argument:
 
 1. The Invoke-WebRequest command needs proxy information to access the installer script. Then the Deploy-IoTEdge command needs the proxy information to download the installation files. 
 
@@ -59,13 +86,13 @@ $proxyCredential = (Get-Credential).GetNetworkCredential()
 Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }
 ```
 
-For more information about proxy parameters, see [Invoke-WebRequest](https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest). For more information about Windows installation options, see [Install Azure IoT Edge runtime on Windows](how-to-install-iot-edge-windows.md).
-
-Once the IoT Edge runtime is installed, use the following section to configure it with your proxy information. 
+For more information about proxy parameters, see [Invoke-WebRequest](https://docs.microsoft.com/powershell/module/microsoft.powershell.utility/invoke-webrequest). For more information about Windows installation options, including offline installation, see [Install Azure IoT Edge runtime on Windows](how-to-install-iot-edge-windows.md).
 
 ## Configure the daemons
 
-The Moby and IoT Edge daemons running on your IoT Edge device need to be configured to use the proxy server. The Moby daemon makes web requests to pull container images from container registries. The IoT Edge daemon makes web requests to communicate with IoT Hub.
+IoT Edge relies on two daemons running on the IoT Edge device. The Moby daemon makes web requests to pull container images from container registries. The IoT Edge daemon makes web requests to communicate with IoT Hub.
+
+Both the Moby and the IoT Edge daemons need to be configured to use the proxy server for ongoing device functionality. This step takes place on the IoT Edge device during initial device setup. 
 
 ### Moby daemon
 
@@ -80,7 +107,9 @@ Choose the article that applies to your IoT Edge device operating system:
 
 ### IoT Edge daemon
 
-The IoT Edge daemon is configured in a similar manner to the Moby daemon. All the requests that IoT Edge sends to IoT Hub use HTTPS. Use the following steps to set an environment variable for the service, based on your operating system. 
+The IoT Edge daemon is configured in a similar manner to the Moby daemon. Use the following steps to set an environment variable for the service, based on your operating system. 
+
+The IoT Edge daemon always uses HTTPS to send requests to IoT Hub.
 
 #### Linux
 
@@ -133,47 +162,49 @@ Restart-Service iotedge
 
 The IoT Edge agent is the first module to start on any IoT Edge device. It's started for the first time based on the information in the IoT Edge config.yaml file. The IoT Edge agent then connects to IoT Hub to retrieve deployment manifests, which declare what other modules should be deployed on the device.
 
-Open the config.yaml file on your IoT Edge device. On Linux systems, this file is located at **/etc/iotedge/config.yaml**. On Windows systems, this file is located at **C:\ProgramData\iotedge\config.yaml**. The configuration file is protected, so you need administrative privileges to access it. On Linux systems, that means using the `sudo` command before opening the file in your preferred text editor. On Windows, that means opening a text editor like Notepad to run as administrator and then opening the file. 
+This step takes place once on the IoT Edge device during initial device setup. 
 
-In the config.yaml file, find the **Edge Agent module spec** section. The IoT Edge agent definition includes an **env** parameter where you can add environment variables. 
+1. Open the config.yaml file on your IoT Edge device. On Linux systems, this file is located at **/etc/iotedge/config.yaml**. On Windows systems, this file is located at **C:\ProgramData\iotedge\config.yaml**. The configuration file is protected, so you need administrative privileges to access it. On Linux systems, use the `sudo` command before opening the file in your preferred text editor. On Windows, open a text editor like Notepad as administrator and then open the file. 
 
-<!--
-![edgeAgent definition](./media/how-to-configure-proxy-support/edgeagent-unedited.png)
--->
+2. In the config.yaml file, find the **Edge Agent module spec** section. The IoT Edge agent definition includes an **env** parameter where you can add environment variables. 
 
-Remove the curly brackets that are placeholders for the env parameter, and add the new variable on a new line. Remember that indents in YAML are two spaces. 
+3. Remove the curly brackets that are placeholders for the env parameter, and add the new variable on a new line. Remember that indents in YAML are two spaces. 
 
-```yaml
-https_proxy: "<proxy URL>"
-```
+   ```yaml
+   https_proxy: "<proxy URL>"
+   ```
 
-The IoT Edge runtime uses AMQP by default to talk to IoT Hub. Some proxy servers block AMQP ports. If that's the case, then you also need to configure edgeAgent to use AMQP over WebSocket. Add a second environment variable.
+4. The IoT Edge runtime uses AMQP by default to talk to IoT Hub. Some proxy servers block AMQP ports. If that's the case, then you also need to configure edgeAgent to use AMQP over WebSocket. Add a second environment variable.
 
-```yaml
-UpstreamProtocol: "AmqpWs"
-```
+   ```yaml
+   UpstreamProtocol: "AmqpWs"
+   ```
 
-![edgeAgent definition with environment variables](./media/how-to-configure-proxy-support/edgeagent-edited.png)
+   ![edgeAgent definition with environment variables](./media/how-to-configure-proxy-support/edgeagent-edited.png)
 
-Save the changes to config.yaml and close the editor. Restart IoT Edge for the changes to take effect. 
+5. Save the changes to config.yaml and close the editor. Restart IoT Edge for the changes to take effect. 
 
-* Linux: 
+   * Linux: 
 
-   ```bash
-   sudo systemctl restart iotedge
-   ```
+      ```bash
+      sudo systemctl restart iotedge
+      ```
 
-* Windows:
+   * Windows:
 
-   ```powershell
-   Restart-Service iotedge
-   ```
+      ```powershell
+      Restart-Service iotedge
+      ```
 
 ## Configure deployment manifests  
 
-Once your IoT Edge device is configured to work with your proxy server, you need to continue to declare the environment variables in future deployment manifests. Always configure the two runtime modules, edgeAgent and edgeHub, to communicate through the proxy server so they can maintain a connection with IoT Hub. Other IoT Edge modules that connect to the internet should be configured for the proxy server. However, modules that route their messages through edgeHub or that only communicate with other modules on the device don't need the proxy server details. 
+Once your IoT Edge device is configured to work with your proxy server, you need to continue to declare the environment variables in future deployment manifests. You can edit deployment manifests either using the Azure portal wizard or by editing a deployment manifest JSON file. 
+
+Always configure the two runtime modules, edgeAgent and edgeHub, to communicate through the proxy server so they can maintain a connection with IoT Hub. If you remove the proxy information from the edgeAgent module, the only way to reestablish connection is by editing the config.yaml file on the device, as described in the previous section. 
+
+Other IoT Edge modules that connect to the internet should be configured to communicate through the proxy server, too. However, modules that route their messages through edgeHub or that only communicate with other modules on the device don't need the proxy server details. 
 
-You can create deployment manifests using the Azure portal or manually by editing a JSON file. 
+This step is ongoing throughout the life of the IoT Edge device. 
 
 ### Azure portal
 
