Сведения о развертывании модулей и настройке маршрутов в IoT Edge

Статья
06/05/2024

Область применения: IoT Edge 1.5 IoT Edge 1.4

Внимание

Поддерживаются выпуски IoT Edge 1.5 LTS и IoT Edge 1.4 LTS. IoT Edge 1.4 LTS заканчивается жизнью 12 ноября 2024 года. Если вы используете более ранний выпуск, см. статью Обновление IoT Edge.

На каждом устройстве IoT Edge работают по меньшей мере два модуля – $edgeAgent и $edgeHub, входящие в среду выполнения IoT Edge. Устройство IoT Edge может запускать несколько модулей для любого количества процессов. Используйте манифест развертывания, чтобы сообщить устройству, какие модули нужно установить и как их нужно настроить для совместной работы.

Манифест развертывания — это документ JSON, который описывает:

Двойник модуля агента IoT Edge, который включает три компонента:
- образ контейнера для каждого модуля, запущенного на устройстве;
- учетные данные для доступа к закрытым реестрам контейнеров, содержащим образы модулей;
- инструкции по созданию модулей и управлению каждым модулем;
двойник модуля центра IoT Edge, которая описывает поток сообщений между модулями и в конечном итоге к Центру Интернета вещей;
Требуемые свойства всех дополнительных двойников модулей (необязательно).

Все устройства IoT Edge должны быть настроены с помощью манифеста развертывания. Недавно установленная среда выполнения IoT Edge будет сообщать код ошибки, пока не будет настроена с помощью допустимого манифеста.

В руководствах по Azure IoT Edge манифест развертывания создается с помощью мастера на портале Azure IoT Edge. Также с помощью REST или пакета SDK службы Центра Интернета вещей можно применить манифест развертывания программно. Дополнительные сведения см. в статье Основные сведения о развертываниях IoT Edge для отдельных устройств или в требуемом масштабе.

Создание манифеста развертывания

В общих чертах манифест развертывания представляет собой список двойников модулей, для которых настроены требуемые свойства. Манифест развертывания сообщает устройству IoT Edge (или группе устройств), какие модули нужно установить и как их нужно настроить. Манифесты развертывания содержат требуемые свойства для каждого двойника модуля. Устройства IoT Edge передают сообщаемые свойства от каждого модуля.

В каждый манифест должны быть включены два обязательных модуля: $edgeAgent и $edgeHub. Эти модули являются частью среды выполнения IoT Edge, которая управляет устройством IoT Edge и запущенными на нем модулями. См. дополнительные сведения о среде выполнения Azure IoT Edge и ее архитектуре.

Кроме двух модулей среды выполнения, вы можете добавить до 50 собственных модулей, чтобы выполнять их на устройстве IoT Edge.

Манифест развертывания, который содержит только среду выполнения IoT Edge (модули edgeAgent и edgeHub), тоже считается допустимым.

Манифесты развертывания имеют такую структуру:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules, and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Настройка модулей

Определите, как среда выполнения IoT Edge устанавливает модули в развертывании. Агент IoT Edge — это компонент среды выполнения, который управляет установкой, обновлением и отчетами о состоянии для устройства IoT Edge. Таким образом, двойник модуля $edgeAgent содержит сведения по управлению и настройке для всех модулей. Сюда также входят параметры настройки самого агента IoT Edge.

Свойства $edgeAgent имеют такую структуру:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // give the IoT Edge agent access to container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Версия 1,1 схемы агента IoT Edge была выпущена вместе с IoT Edge версии 1.0.10 и включает порядок запуска модуля. Версия схемы 1,1 рекомендуется для любого развертывания IoT Edge с версией 1.0.10 или более поздней.

Настройка и управление модулем

Список требуемых свойств агента IoT Edge — это место, где вы определяете, какие модули развертываются на IoT Edge устройстве и как нужно настраивать и управлять ими.

Полный список свойств, которые могут или должны быть включены, см. в статье Свойства агента IoT Edge и центра IoT Edge.

Например:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

У каждого модуля есть свойство Настройки, которое содержит Образмодуля, адрес образа контейнера в реестре контейнеров и параметры createOptions для настройки образа при запуске. Дополнительные сведения см. в разделе Настройка параметров создания контейнера для модулей IOT Edge.

Модуль edgeHub и пользовательские модули также имеют три свойства, указывающие агенту IoT Edge, как управлять ими:

Состояние: должен ли модуль запускаться или останавливаться при первом развертывании. Обязательный.
RestartPolicy: когда агент IOT Edge должен перезапустить модуль в случае его остановки. Если модуль остановлен без ошибок, он не будет запускаться автоматически. Дополнительные сведения см. в документации Docker— автоматическое запуск контейнеров. Обязательный.
StartupOrder: представлен в IoT Edge версии 1.0.10. Какой заказ агент IoT Edge должен запускать модули при первом развертывании. Порядок объявлен с целыми числами, где модуль с заданным начальным значением 0 запускается первыми, а затем — с более высоким числом. Модуль edgeAgent не имеет значения "запуск", так как всегда запускается первым. Необязательно.

Агент IoT Edge инициирует модули в порядке значения запуска, но не ожидает завершения каждого модуля, прежде чем перейти к следующему.

Порядок загрузки необходим, когда некоторые модули зависят от других. Например, может потребоваться запустить модуль edgeHub, чтобы он был готов к маршрутизации сообщений при запуске других модулей. Кроме того, перед запуском модулей, отправляющих данные в него, может потребоваться запустить модуль хранилища. Тем не менее следует всегда проектировать модули, чтобы устранить сбои других модулей. Контейнеры могут останавливаться и перезапускаться в любое время и любое количество раз.
Примечание.

Изменение свойств модуля приведет к перезапуску этого модуля. Например, перезагрузка произойдет, если изменить свойства для:
- Образ модуля
- Параметры создания Docker
- Переменные среды
- Политика перезапуска
- Политика извлечения изображений
- версия
- порядок запуска
Если свойство модуля не изменено, модуль не перезагрузится.

Объявление маршрутов

Центр IoT Edge управляет взаимодействием между модулями, Центр Интернета вещей и любыми подчиненными устройствами. Для этой цели двойник модуля $edgeHub содержит требуемое свойство с именем routes, в котором описываются правила передачи сообщений в конкретном развертывании. Один экземпляр развертывания может иметь несколько маршрутов.

Маршруты объявляются в требуемых свойствах $edgeHub. Синтаксис объявления следующий:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

Схема Центра IoT Edge версии 1 была выпущена вместе с IoT Edge версии 1.0.10 и обеспечивает приоритет маршрута и время жизни. Версия схемы 1,1 рекомендуется для любого развертывания IoT Edge с версией 1.0.10 или более поздней.

Каждому маршруту нужен источник, откуда поступают сообщения, и приемник, куда попадают сообщения. При необходимости можно также добавить условие, чтобы фильтровать сообщения.

Можно назначить приоритеты маршрутам, которые должны сначала обрабатывать свои сообщения. Эта функция полезна в сценариях, когда восходящее соединение является слабым или ограниченным и у вас есть важные данные, которым следует отдавать приоритет перед стандартными телеметрическими сообщениями.

Исходный код

Исходная точка определяет то место, откуда поступают сообщения. IoT Edge может направлять сообщения из модулей или подчиненных устройств.

С помощью пакетов SDK Для Интернета вещей модули могут объявлять определенные очереди выходных данных для своих сообщений с помощью класса ModuleClient. Очереди вывода необязательны, однако они полезны для управления несколькими маршрутами. Подчиненные устройства могут использовать класс DeviceClient пакетов SDK Интернета вещей для отправки сообщений на устройства шлюза IoT Edge таким же образом, как они будут отправлять сообщения в Центр Интернета вещей. См. общие сведения о пакетах SDK для Центра Интернета вещей Azure и их использовании.

Свойство source может принимать любое из следующих значений:

Оригинал	Description
`/*`	Все уведомления об изменениях между устройствами и двойниками с любого модуля или нижнего устройства
`/twinChangeNotifications`	Любое изменение двойника (сообщаемые свойства) из любого модуля или нижнего устройства
`/messages/*`	Любое сообщение из устройства в облако, отправленное модулем через некоторые или нет выходных данных или нижестоящим устройством
`/messages/modules/*`	Все сообщения с устройства в облако, отправленные модулем с некоторыми выходными данными или без них.
`/messages/modules/<moduleId>/*`	Все сообщения, отправляемые с устройства в облако конкретным модулем с выходными данными или без них.
`/messages/modules/<moduleId>/outputs/*`	Все сообщения, отправляемые с устройства в облако конкретным модулем с выходными данными или без них.
`/messages/modules/<moduleId>/outputs/<output>`	Все сообщения, отправляемые с устройства в облако конкретным модулем с выходными данными или без них.

Condition

Условие является необязательным при объявлении маршрута. Если нужно передать все сообщения из источника в приемник, просто не заполняйте предложение WHERE. Можно также воспользоваться языком запросов Центра Интернета вещей для фильтрации определенных сообщений или типов сообщений, удовлетворяющих заданному условию. Маршруты IoT Edge не поддерживает фильтрацию сообщений на основе тегов или свойств двойников.

Сообщения, которые проходят между модулями в IoT Edge, форматируются так же, как сообщения, которые проходят между вашими устройствами и Центром Интернета вещей. Все сообщения представлены в формате JSON с параметрами systemProperties, appProperties и body.

Запросы для всех трех параметров создаются с помощью следующего синтаксиса:

свойства системы — $<propertyName> или {$<propertyName>};
свойства приложения — <propertyName>;
свойства текста —$body.<propertyName>.

Примеры создания запросов к свойствам сообщений см. в разделе Выражения запросов по маршрутам сообщений, отправляемых с устройства в облако.

Пример, характерный для IoT Edge, заключается в том, когда требуется фильтровать сообщения, поступающие на устройство шлюза с нижестоящего устройства. Сообщения, отправляемые из модулей, включают системное свойство connectionModuleId. Поэтому, если вы хотите маршрутизировать сообщения с подчиненных устройств непосредственно в Центр Интернета вещей, используйте следующий маршрут, чтобы исключить сообщения модуля:

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Приемник

Конечная точка определяет пункт назначения отправленных сообщений. Только модули и Центр Интернета вещей могут получать сообщения. Сообщения невозможно перенаправить на другие устройства. Для свойства приемника не поддерживаются подстановочные знаки.

Свойство sink может принимать любое из следующих значений:

Приемник	Description
`$upstream`	Отправляет сообщение в Центр Интернета вещей.
`BrokeredEndpoint("/modules/<moduleId>/inputs/<input>")`	Отправка сообщений на определенный вход конкретного модуля

IoT Edge предоставляет гарантии как минимум однократной доставки. Если маршрут не может доставить сообщение в назначенный приемник, центр IoT Edge сохраняет такое сообщение локально. Например, если центр IoT Edge не может подключиться к Центру Интернета вещей или не подключен целевой модуль.

Центр IoT Edge хранит сообщения до окончания срока хранения, указанного в свойстве storeAndForwardConfiguration.timeToLiveSecs требуемых свойств концентратора Edge.

Приоритет и срок жизни маршрута

Маршруты могут быть объявлены либо просто строкой, определяющей маршрут, либо как объект, который принимает строку маршрута, целое число приоритета и целое число срока жизни.

Вариант 1:

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Вариант 2, введенный в IoT Edge версии 1.0.10 с схемой центра IoT Edge версии 1,1:

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Значения приоритета могут быть от 0 до 9 включительно, где 0 — наивысший приоритет. Сообщения ставятся в очередь в зависимости от их конечных точек. Все сообщения приоритета 0, предназначенные для конкретной конечной точки, обрабатываются до обработки всех сообщений с приоритетом 1, предназначенных для одной конечной точки, и вниз по строке. Если несколько маршрутов для одной конечной точки имеют одинаковый приоритет, их сообщения обрабатываются в первой очереди. Если приоритет не указан, маршруту назначается самый низкий приоритет.

Свойство timeToLiveSecs наследует свое значение от storeAndForwardConfiguration из Центра IoT Edge, если оно не задано явно. Значением может быть любое положительное целое число.

Для получения подробной информации об управлении приоритетными очередями см. справочную страницу про приоритет маршрута и срок жизни.

Определение или обновление требуемых свойств

Манифест развертывания определяет требуемые средства для каждого модуля, развернутого в устройстве IoT Edge. Требуемые свойства в манифесте развертывания переопределяют любые требуемые свойства, находящиеся на данный момент в двойнике модуля.

Если в манифесте развертывания не указаны требуемые свойства двойника модуля, Центр Интернета вещей не изменит двойник модуля каким-либо образом. Вместо этого требуемые свойства можно задать программным способом.

Для изменения двойников модуля используются те же механизмы, что и для двойников устройства. Дополнительные сведения см. в статье Общие сведения о двойниках модулей и их использование в Центре Интернета вещей.

Пример манифеста развертывания

Ниже демонстрируется пример допустимого документа с манифестом развертывания.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Следующие шаги

Полный список свойств, которые могут или должны быть у $edgeAgent и $edgeHub, см. в статье Свойства агента IoT Edge и центра IoT Edge.
Теперь, когда вы знаете, как используются модули IoT Edge, ознакомьтесь со статьей Сведения о требованиях и средствах разработки модулей IoT Edge.

Поделиться через