Merge pull request #302648 from PatAltimore/patricka-freshness

prmerger-automator[bot] · web-flow · commit 66a8f1b0ea11 · 2025-07-11T23:02:40.000Z
Freshness review
diff --git a/articles/iot-edge/tutorial-nested-iot-edge.md b/articles/iot-edge/tutorial-nested-iot-edge.md
@@ -4,7 +4,7 @@ description: This tutorial shows you how to create a hierarchical structure of I
 author: PatAltimore
 
 ms.author: patricka
-ms.date: 06/10/2024
+ms.date: 07/11/2025
 ms.topic: tutorial
 ms.service: azure-iot-edge
 ms.custom: devx-track-azurecli
@@ -18,11 +18,11 @@ ai-usage: ai-assisted
 
 [!INCLUDE [iot-edge-version-all-supported](includes/iot-edge-version-all-supported.md)]
 
-You can deploy Azure IoT Edge nodes across networks organized in hierarchical layers. Each layer in a hierarchy is a gateway device that handles messages and requests from devices in the layer beneath it. This configuration is also known as *nested edge*.
+Deploy Azure IoT Edge nodes across networks organized in hierarchical layers. Each layer in a hierarchy is a gateway device that handles messages and requests from devices in the layer beneath it. This configuration is also known as *nested edge*.
 
-You can structure a hierarchy of devices so that only the top layer has connectivity to the cloud, and the lower layers can only communicate with adjacent upstream and downstream layers. This network layering is the foundation of most industrial networks that follow the [ISA-95 standard](https://en.wikipedia.org/wiki/ANSI/ISA-95).
+Structure a hierarchy of devices so that only the top layer has connectivity to the cloud, and the lower layers can communicate only with adjacent upstream and downstream layers. This network layering is the foundation of most industrial networks that follow the [ISA-95 standard](https://en.wikipedia.org/wiki/ANSI/ISA-95).
 
-This tutorial walks you through creating a hierarchy of IoT Edge devices, deploying IoT Edge runtime containers to your devices, and configuring your devices locally. You do the following tasks:
+This tutorial shows you how to create a hierarchy of IoT Edge devices, deploy IoT Edge runtime containers to your devices, and configure your devices locally. In this tutorial, you do the following tasks:
 
 > [!div class="checklist"]
 >
@@ -45,7 +45,7 @@ In this tutorial, the following network layers are defined:
 
 * **Lower layers**: IoT Edge devices at layers below the top layer can't connect directly to the cloud. They need to go through one or more intermediary IoT Edge devices to send and receive data.
 
-This tutorial uses a two device hierarchy for simplicity. The **top layer device** represents a device at the top layer of the hierarchy that can connect directly to the cloud. This device is referred to as the **parent device**. The **lower layer device** represents a device at the lower layer of the hierarchy that can't connect directly to the cloud. You can add more devices to represent your production environment, as needed. Devices at lower layers are referred to as **child devices**.
+This tutorial uses a two device hierarchy for simplicity. The **top layer device** represents a device at the top layer of the hierarchy that can connect directly to the cloud. This device is called the **parent device**. The **lower layer device** represents a device at the lower layer of the hierarchy that can't connect directly to the cloud. Add more devices to represent your production environment, as needed. Devices at lower layers are called **child devices**.
 
 ![Structure of the tutorial hierarchy, containing two devices: the top layer device and the lower layer device](./media/tutorial-nested-iot-edge/tutorial-hierarchy-diagram.png)
 
@@ -88,17 +88,17 @@ To create and configure your hierarchy of IoT Edge devices, you use the [az iot
 
 You create a group of nested edge devices with containing a parent device with one child device. In this tutorial, we use basic sample deployment manifests. For other scenario examples, review the [configuration example templates](https://github.com/Azure-Samples/iotedge_config_cli/tree/main/templates).
 
-1. Before you use the [az iot edge devices create](/cli/azure/iot/edge/devices#az-iot-edge-devices-create) command, you need to define the deployment manifest for the top layer and lower layer devices. Download the [deploymentTopLayer.json](https://github.com/Azure-Samples/iotedge_config_cli/blob/main/templates/tutorial/deploymentTopLayer.json) sample file to your local machine.
+1. Before you use the [az iot edge devices create](/cli/azure/iot/edge/devices#az-iot-edge-devices-create) command, define the deployment manifest for the top layer and lower layer devices. Download the [deploymentTopLayer.json](https://github.com/Azure-Samples/iotedge_config_cli/blob/main/templates/tutorial/deploymentTopLayer.json) sample file to your local machine.
 
    The top layer device deployment manifest defines the [IoT Edge API Proxy module](how-to-configure-api-proxy-module.md) and declares the [route](module-composition.md#declare-routes) from the lower layer device to IoT Hub.
 
 1. Download the [deploymentLowerLayer.json](https://github.com/Azure-Samples/iotedge_config_cli/blob/main/templates/tutorial/deploymentLowerLayer.json) sample file to your local machine.
 
-   The lower layer device deployment manifest includes the simulated temperature sensor module and declares the [route](module-composition.md#declare-routes) to the top layer device. You can see within **systemModules** section that the runtime modules are set to pull from **$upstream:443**, instead of **mcr.microsoft.com**. The *lower layer device* sends Docker image requests the *IoT Edge API Proxy* module on port 443, as it can't directly pull the images from the cloud. The other module deployed to the *lower layer device*, the *Simulated Temperature Sensor* module, also makes its image request to `$upstream:443`.
+   The lower layer device deployment manifest includes the simulated temperature sensor module and declares the [route](module-composition.md#declare-routes) to the top layer device. In the **systemModules** section, the runtime modules are set to pull from **$upstream:443** instead of **mcr.microsoft.com**. The *lower layer device* sends Docker image requests to the *IoT Edge API Proxy* module on port 443, because it can't directly pull the images from the cloud. The other module deployed to the *lower layer device*, the *Simulated Temperature Sensor* module, also makes its image request to `$upstream:443`.
 
-   For more information on how to create a lower layer deployment manifest, see [Connect Azure IoT Edge devices to create a hierarchy](how-to-connect-downstream-iot-edge-device.md#deploy-modules-to-lower-layer-devices).
+   For more information about creating a lower layer deployment manifest, see [Connect Azure IoT Edge devices to create a hierarchy](how-to-connect-downstream-iot-edge-device.md#deploy-modules-to-lower-layer-devices).
 
-1. In the [Azure Cloud Shell](https://shell.azure.com/), use the [az iot edge devices create](/cli/azure/iot/edge/devices#az-iot-edge-devices-create) Azure CLI command to create devices in IoT Hub and configuration bundles for each device in your hierarchy. Replace the following placeholders with the appropriate values:
+1. In the [Azure Cloud Shell](https://shell.azure.com/), use the [az iot edge devices create](/cli/azure/iot/edge/devices#az-iot-edge-devices-create) Azure CLI command to create devices in IoT Hub and configuration bundles for each device in your hierarchy. Replace the placeholder text in angle brackets with your own values:
 
    | Placeholder | Description |
    |-------------|-------------|
@@ -141,7 +141,7 @@ You create a group of nested edge devices with containing a parent device with o
          hostname=10.1.0.4
    ```
 
-After running the command, you can find the device configuration bundles in the output directory. For example:
+After you run the command, find the device configuration bundles in the output directory. For example:
 
 ```Output
 PS C:\nested-edge\output> dir
@@ -154,15 +154,15 @@ Mode                 LastWriteTime         Length Name
 -a---           4/10/2023  4:12 PM           6851 parent-1.tgz
 ```
 
-You can use your own certificates and keys passed as arguments to the command or create a more complex device hierarchy. For more information about creating nested devices using the *az* command, see [az iot edge devices create](/cli/azure/iot/edge/devices#az-iot-edge-devices-create). If you're unfamiliar with how certificates are used in a gateway scenario, see [the how-to guide's certificate section](how-to-connect-downstream-iot-edge-device.md#generate-certificates). 
+Use your own certificates and keys passed as arguments to the command, or create a more complex device hierarchy. For more information about creating nested devices using the *az* command, see [az iot edge devices create](/cli/azure/iot/edge/devices#az-iot-edge-devices-create). If you're unfamiliar with how certificates are used in a gateway scenario, see [the how-to guide's certificate section](how-to-connect-downstream-iot-edge-device.md#generate-certificates).
 
 In this tutorial, you use inline arguments to create the devices and configuration bundles. You can also use a configuration file in YAML or JSON format. For a sample configuration file, see the example [sample_devices_config.yaml](https://aka.ms/aziotcli-edge-devices-config).
 
 ## Configure the IoT Edge runtime
 
 In addition to the provisioning of your devices, the configuration steps establish trusted communication between the devices in your hierarchy using the certificates you created earlier. The steps also begin to establish the network structure of your hierarchy. The top layer device maintains internet connectivity, allowing it to pull images for its runtime from the cloud, while lower layer devices route through the top layer device to access these images.
 
-To configure the IoT Edge runtime, you need to apply the configuration bundles to your devices. The configurations differ between the *top layer device* and a *lower layer device*, so be mindful of the device configuration file you're applying to each device.
+To configure the IoT Edge runtime, apply the configuration bundles to your devices. The configurations are different for the *top layer device* and a *lower layer device*, so make sure you use the right configuration file for each device.
 
 1. Copy each configuration bundle archive file to its corresponding device. You can use a USB drive, a service like [Azure Key Vault](/azure/key-vault/general/overview), or with a function like [Secure file copy](https://www.ssh.com/ssh/scp/). Choose one of these methods that best matches your scenario. 
 
@@ -184,15 +184,15 @@ To configure the IoT Edge runtime, you need to apply the configuration bundles t
    chmod +x install.sh
    ```
 
-1. On each device, apply the configuration bundle to the device using root permission:
+1. On each device, run the install script with root permission to apply the configuration bundle:
 
    ```bash
    sudo ./install.sh
    ```
 
    ![Installing the configuration bundles update the config.toml files on your device and restart all IoT Edge services automatically](./media/tutorial-nested-iot-edge/configuration-install-output.png)
 
-   If you want a closer look at what modifications are being made to your device's configuration file, see [Connect Azure IoT Edge devices together to create a hierarchy](how-to-connect-downstream-iot-edge-device.md).
+   To see more details about changes to your device's configuration file, see [Connect Azure IoT Edge devices together to create a hierarchy](how-to-connect-downstream-iot-edge-device.md).
 
 To verify your devices are configured correctly, run the configuration and connectivity checks on your devices.
 
@@ -265,36 +265,36 @@ Connectivity checks
 2 check(s) were skipped due to errors from other checks. Re-run with --verbose for more details.
 ```
 
-On your **top layer device**, expect to see an output with several passing evaluations. You may see some warnings about logs policies and, depending on your network, DNS policies.
+On your **top layer device**, you see output with several passing checks. You might see some warnings about log policies and, depending on your network, DNS policies.
 
 ## Device module deployment
 
-The module deployment for your devices were applied when the devices were created in IoT Hub. The *az iot edge devices create* command applied the deployment JSON files for the top and lower layer devices.
-After those deployments completed, the **lower layer device** uses the **IoT Edge API Proxy** module to pull its necessary images.
+Module deployment for your devices is applied when you create the devices in IoT Hub. The *az iot edge devices create* command applies the deployment JSON files for the top and lower layer devices.
+After deployment finishes, the **lower layer device** uses the **IoT Edge API Proxy** module to pull its images.
 
-In addition the runtime modules **IoT Edge Agent** and **IoT Edge Hub**, the **top layer device** receives the **Docker registry** module and **IoT Edge API Proxy** module.
+In addition to the runtime modules **IoT Edge Agent** and **IoT Edge Hub**, the **top layer device** also gets the **Docker registry** module and **IoT Edge API Proxy** module.
 
-The **Docker registry** module points to an existing Azure Container Registry. In this case, `REGISTRY_PROXY_REMOTEURL` points to the Microsoft Container Registry. By default, **Docker registry** listens on port 5000.
+The **Docker registry** module points to an existing Azure Container Registry. In this case, `REGISTRY_PROXY_REMOTEURL` points to the Microsoft Container Registry. By default, the **Docker registry** module listens on port 5000.
 
-The *IoT Edge API Proxy* module routes HTTP requests to other modules, allowing lower layer devices to pull container images or push blobs to storage. In this tutorial, it communicates on port 443 and is configured to send Docker container image pull requests route to your **Docker registry** module on port 5000. Also, any blob storage upload requests route to module AzureBlobStorageonIoTEdge on port 11002. For more information about the **IoT Edge API Proxy** module and how to configure it, see the module's [how-to guide](how-to-configure-api-proxy-module.md).
+The *IoT Edge API Proxy* module routes HTTP requests to other modules, so lower layer devices can pull container images or push blobs to storage. In this tutorial, it communicates on port 443 and is configured to send Docker container image pull requests to your **Docker registry** module on port 5000. Blob storage upload requests go to the AzureBlobStorageonIoTEdge module on port 11002. For more information about the **IoT Edge API Proxy** module and how to configure it, see the module's [how-to guide](how-to-configure-api-proxy-module.md).
 
-If you'd like a look at how to create a deployment like this through the Azure portal or Azure Cloud Shell, see [top layer device section of the how-to guide](how-to-connect-downstream-iot-edge-device.md#deploy-modules-to-top-layer-devices).
+To learn how to create a deployment like this in the Azure portal or Azure Cloud Shell, see the [top layer device section of the how-to guide](how-to-connect-downstream-iot-edge-device.md#deploy-modules-to-top-layer-devices).
 
-You can view the status of your modules using the command:
+View the status of your modules with this command:
 
 ```azurecli
 az iot hub module-twin show --device-id <edge-device-id> --module-id '$edgeAgent' --hub-name <iot-hub-name> --query "properties.reported.[systemModules, modules]"
 ```
 
-This command outputs all the edgeAgent reported properties. Here are some helpful ones for monitoring the status of the device: *runtime status*, *runtime start time*, *runtime last exit time*, *runtime restart count*.
+This command shows all the edgeAgent reported properties. Helpful properties for monitoring device status include: *runtime status*, *runtime start time*, *runtime last exit time*, and *runtime restart count*.
 
-You can also see the status of your modules on the [Azure portal](https://portal.azure.com/). Navigate to the **Devices** section of your IoT Hub to see your devices and modules.
+You can also see the status of your modules in the [Azure portal](https://portal.azure.com/). Go to the **Devices** section of your IoT Hub to see your devices and modules.
 
 ## View generated data
 
-The **Simulated Temperature Sensor** module that you pushed generates sample environment data. It sends messages that include ambient temperature and humidity, machine temperature and pressure, and a timestamp.
+The **Simulated Temperature Sensor** module generates sample environment data. It sends messages that include ambient temperature and humidity, machine temperature and pressure, and a timestamp.
 
-You can also view these messages through the [Azure Cloud Shell](https://shell.azure.com/):
+You can also view these messages using [Azure Cloud Shell](https://shell.azure.com/):
 
 ```azurecli
 az iot hub monitor-events -n <iot-hub-name> -d <lower-layer-device-name>
@@ -320,21 +320,21 @@ az iot hub monitor-events -n my-iot-hub -d child-1
 
 ## Troubleshooting
 
-Run the `iotedge check` command to verify the configuration and to troubleshoot errors.
+Run the `iotedge check` command to verify the configuration and troubleshoot errors.
 
-You can run `iotedge check` in a nested hierarchy, even if the downstream machines don't have direct internet access.
+Run `iotedge check` in a nested hierarchy, even if downstream machines don't have direct internet access.
 
-When you run `iotedge check` from the lower layer, the program tries to pull the image from the parent through port 443.
+When you run `iotedge check` from the lower layer, the program pulls the image from the parent through port 443.
 
-The `azureiotedge-diagnostics` value is pulled from the container registry that's linked with the registry module. This tutorial has it set by default to https://mcr.microsoft.com:
+The `azureiotedge-diagnostics` value comes from the container registry that's linked with the registry module. This tutorial sets it by default to https://mcr.microsoft.com:
 
 | Name | Value |
 | - | - |
 | `REGISTRY_PROXY_REMOTEURL` | `https://mcr.microsoft.com` |
 
-If you're using a private container registry, make sure that all the images (IoTEdgeAPIProxy, edgeAgent, edgeHub, Simulated Temperature Sensor, and diagnostics) are present in the container registry.
+If you're using a private container registry, make sure all images (IoTEdgeAPIProxy, edgeAgent, edgeHub, Simulated Temperature Sensor, and diagnostics) are present in the container registry.
 
-If a downstream device has a different processor architecture from the parent device, you need the appropriate architecture image. You can use a [connected registry](/azure/container-registry/intro-connected-registry) or you can specify the correct image for the *edgeAgent* and *edgeHub* modules in the downstream device *config.toml* file. For example, if the parent device is running on an ARM32v7  architecture and the downstream device is running on an AMD64 architecture, you need to specify the matching version and architecture image tag in the downstream device *config.toml* file.
+If a downstream device uses a different processor architecture than the parent device, use the appropriate architecture image. Use a [connected registry](/azure/container-registry/intro-connected-registry) or specify the correct image for the *edgeAgent* and *edgeHub* modules in the downstream device *config.toml* file. For example, if the parent device runs on ARM32v7 and the downstream device runs on AMD64, specify the matching version and architecture image tag in the downstream device *config.toml* file.
 
 ```toml
 [agent.config]
