Merge pull request #208437 from bishal41/Module-Image-Garbage-Collection

Image garbage collection

Author: BCS2022

articles/iot-edge/iot-edge-modules.md

@@ -19,8 +19,8 @@ Azure IoT Edge lets you deploy and manage business logic on the edge in the form
 
 * A **module image** is a package containing the software that defines a module.
 * A **module instance** is the specific unit of computation running the module image on an IoT Edge device. The module instance is started by the IoT Edge runtime.
-* A **module identity** is a piece of information (including security credentials) stored in IoT Hub, that is associated to each module instance.
-* A **module twin** is a JSON document stored in IoT Hub, that contains state information for a module instance, including metadata, configurations, and conditions.
+* A **module identity** is a piece of information (including security credentials) stored in IoT Hub that is associated to each module instance.
+* A **module twin** is a JSON document stored in IoT Hub that contains state information for a module instance, including metadata, configurations, and conditions.
 
 ## Module images and instances
 
@@ -63,7 +63,6 @@ await client.OpenAsync();
 // Get the module twin
 Twin twin = await client.GetTwinAsync();
 ```
-
 ## Offline capabilities
 
 Azure IoT Edge modules can operate offline indefinitely after syncing with IoT Hub at least once. IoT Edge devices can also extend this offline capability to other IoT devices. For more information, see [Understand extended offline capabilities for IoT Edge devices, modules, and child devices](offline-capabilities.md).

articles/iot-edge/production-checklist.md

@@ -88,6 +88,7 @@ Once your IoT Edge device connects, be sure to continue configuring the Upstream
   * Reduce memory space used by the IoT Edge hub
   * Use correct module images in deployment manifests
   * Be mindful of twin size limits when using custom modules
+  * Configure how updates to modules are applied
 
 ### Be consistent with upstream protocol
 
@@ -148,13 +149,38 @@ If you deploy a large number of modules, you might exhaust this twin size limit.
 - Store any configuration in the custom module twin, which has its own limit.
 - Store some configuration that points to a non-space-limited location (that is, to a blob store).
 
-## Container management
+::: moniker range=">=iotedge-1.4"
+### Configure how updates to modules are applied
+When a deployment is updated, Edge Agent receives the new configuration as a twin update. If the new configuration has new or updated module images, by default, Edge Agent sequentially processes each module:
+1. The updated image is downloaded
+1. The running module is stopped
+1. A new module instance is started
+1. The next module update is processed
+
+In some cases, for example when dependencies exist between modules, it may be desirable to first download all updated module images before restarting any running modules. This module update behavior can be configured by setting an IoT Edge Agent environment variable `ModuleUpdateMode` to string value `WaitForAllPulls`. For more information, see [IoT Edge Environment Variables](https://github.com/Azure/iotedge/blob/main/doc/EnvironmentVariables.md).
+
+```JSON
+"modulesContent": {
+    "$edgeAgent": {
+        "properties.desired": {
+            ...
+            "systemModules": {
+                "edgeAgent": {
+                    "env": {
+                        "ModuleUpdateMode": {
+                            "value": "WaitForAllPulls"
+                        }
+                    ...
+```
+::: moniker-end
+### Container management
 
 * **Important**
   * Use tags to manage versions
   * Manage volumes
 * **Helpful**
   * Store runtime containers in your private registry
+  * Configure image garbage collection
 
 ### Use tags to manage versions
 
@@ -194,6 +220,31 @@ Next, be sure to update the image references in the deployment.template.json fil
 
     `"image": "<registry name and server>/azureiotedge-hub:1.1",`
 
+::: moniker range=">=iotedge-1.4"
+### Configure image garbage collection
+Image garbage collection is a feature in IoT Edge v1.4 and later to automatically clean up Docker images that are no longer used by IoT Edge modules. It only deletes Docker images that were pulled by the IoT Edge runtime as part of a deployment. Deleting unused Docker images helps conserve disk space.
+
+The feature is implemented in IoT Edge's host component, the `aziot-edged` service and enabled by default. Cleanup is done every day at midnight (device local time) and removes unused Docker images that were last used seven days ago. The parameters to control cleanup behavior are set in the `config.toml` and explained later in this section. If parameters aren't specified in the configuration file, the default values are applied.
+
+For example, the following is the `config.toml` image garbage collection section using default values:
+ 
+```toml
+[image_garbage_collection]
+enabled = true
+cleanup_recurrence = "1d"
+image_age_cleanup_threshold = "7d" 
+cleanup_time = "00:00"
+```
+The following table describes image garbage collection parameters. All parameters are **optional** and can be set individually to change the default settings.
+
+| Parameter | Description | Required | Default value |
+|-----------|-------------|----------|---------------|
+| `enabled` | Enables the image garbage collection. You may choose to disable the feature by changing this setting to `false`. | Optional | true |
+| `cleanup_recurrence` | Controls the recurrence frequency of the cleanup task. Must be specified as a multiple of days and can't be less than one day. <br><br> For example: 1d, 2d, 6d, etc. | Optional | 1d |
+| `image_age_cleanup_threshold` | Defines the minimum age threshold of unused images before considering for cleanup and must be specified in days. You can specify as *0d* to clean up the images as soon as they're removed from the deployment. <br><br>  Images are considered unused *after* they've been removed from the deployment. | Optional | 7d |
+| `cleanup_time` | Time of day, *in device local time*, when the cleanup task runs. Must be in 24-hour HH:MM format. | Optional | 00:00 |
+
+::: moniker-end
 ## Networking
 
 * **Helpful**