Настройка модуля прокси API для иерархии шлюзов

Статья
04/11/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.

В этой статье рассматриваются параметры конфигурации для модуля прокси API, позволяющие настроить модуль в соответствии с требованиями иерархии шлюзов.

Прокси-модуль API упрощает обмен данными для устройств IoT Edge при развертывании нескольких служб, которые поддерживают протокол HTTPS и привязаны к порту 443. Это особенно важно в иерархических развертываниях устройств IoT Edge в архитектурах, изолированных от сети ISA-95, таких как описанные в разделе "Сетевые изоляции подчиненных устройств ", так как клиенты на подчиненных устройствах не могут подключаться непосредственно к облаку.

Например, чтобы разрешить подчиненным устройствам IoT Edge извлекать образы Docker, требуется развертывание модуля реестра Docker. Чтобы разрешить отправку больших двоичных объектов, необходимо развернуть модуль Хранилища BLOB-объектов Azure на том же устройстве IoT Edge. Обе эти службы используют протокол HTTPS для обмена данными. Прокси API позволяет реализовать такие развертывания на устройстве IoT Edge. Прокси-модуль API привязывается к порту 443 вместо каждой службы на устройстве узла и направляет запрос в соответствующий модуль службы на этом устройстве согласно правилам, настраиваемым пользователем. Отдельные службы по-прежнему отвечают за обработку запросов, включая проверку подлинности и авторизацию клиентов.

Без прокси-сервера API каждый модуль службы должен привязываться к отдельному порту на главном устройстве, что предполагает трудоемкое изменение конфигурации для каждого дочернего устройства, которое подключается к родительскому устройству IoT Edge.

Примечание.

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

Развертывание модуля прокси

Модуль прокси API доступен в Microsoft Container Registry (MCR): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Вы можете также развернуть модуль прокси API непосредственно из Azure Marketplace: прокси-сервер API IoT Edge.

Общие сведения о модуле прокси

Модуль прокси API использует обратный прокси-сервер nginx для маршрутизации данных через уровни сети. Прокси-сервер внедрен в модуль, то есть образ модуля должен поддерживать конфигурацию прокси-сервера. Например, если прокси-сервер ожидает передачи данных через определенный порт, этот порт должен быть открыт в модуле.

Прокси-сервер запускается, используя файл конфигурации по умолчанию, внедренный в модуль. Вы можете передать новую конфигурацию в модуль из облака, используя его двойник модуля. Кроме того, можно использовать переменные среды для включения или отключения параметров конфигурации во время развертывания.

Эта статья сначала посвящена файлу конфигурации по умолчанию и использованию переменных среды для включения задаваемых в нем параметров. Затем мы рассмотрим настройку файла конфигурации.

Конфигурация по умолчанию

Модуль прокси API поставляется с конфигурацией по умолчанию, которая поддерживает распространенные сценарии и допускает настройку. Управлять конфигурацией по умолчанию можно с помощью переменных среды модуля.

В настоящее время поддерживаются следующие переменные среды по умолчанию.

Переменная среды	Description
`PROXY_CONFIG_ENV_VAR_LIST`	Выводит все переменные, которые вы собираетесь обновить, в виде списка с разделителями-запятыми. Этот шаг предотвращает случайное изменение параметров конфигурации по ошибке.
`NGINX_DEFAULT_TLS`	Указывает список протоколов TLS, которые необходимо включить. См. ssl_protocols NGINX. Значение по умолчанию — TLSv1.2.
`NGINX_DEFAULT_PORT`	Изменяет порт, через который прокси-сервер nginx ожидает передачи данных. При обновлении этой переменной среды необходимо предоставить порт в dockerfile модуля и объявить привязку портов в манифесте развертывания. Дополнительные сведения см. в разделе "Предоставление прокси-порта". По умолчанию задан порт 443. При развертывании из Azure Marketplace порт по умолчанию изменяется на 8000, чтобы избежать конфликтов с модулем edgeHub. Дополнительные сведения см. в разделе Уменьшение числа открытых портов.
`DOCKER_REQUEST_ROUTE_ADDRESS`	Адрес для маршрутизации запросов Docker. Измените эту переменную на устройстве верхнего уровня, чтобы она указывала на модуль реестра. По умолчанию используется родительское имя узла.
`BLOB_UPLOAD_ROUTE_ADDRESS`	Адрес для маршрутизации запросов к реестру BLOB-объектов. Измените эту переменную на устройстве верхнего уровня, чтобы она указывала на модуль хранилища BLOB-объектов. По умолчанию используется родительское имя узла.

Уменьшение числа открытых портов

Чтобы свести к минимуму количество открытых портов, модуль прокси API должен ретранслировать весь трафик HTTPS (порт 443), включая трафик, предназначенный для модуля edgeHub. Модуль прокси API по умолчанию настроен для перенаправления всего трафика edgeHub через порт 443.

Чтобы настроить развертывание для ограничения открытых портов, выполните следующие действия.

Обновите параметры модуля edgeHub, удалив привязку к порту 443. В противном случае произойдет конфликт привязки портов. По умолчанию модуль edgeHub привязывается к портам 443, 5671 и 8883. Удалите привязку порта 443 и оставьте две другие.
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
Настройте для модуля прокси API привязку к порту 443.
1. Задайте для переменной среды NGINX_DEFAULT_PORT значение 443.
2. Обновите параметры создания контейнера, указав привязку к порту 443.
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

Если не нужно сокращать количество открытых портов, можно разрешить модулю edgeHub использовать порт 443 и настроить модуль прокси API для ожидания передачи данных через другой порт. Например, модуль прокси API может ожидать передачи данных через порт 8000. Для этого можно задать для переменной среды NGINX_DEFAULT_PORT значение 8000 и создать привязку для порта 8000.

Разрешение скачивания образов контейнеров

Распространенным вариантом использования модуля прокси API является разрешение устройствам IoT Edge на более низких уровнях извлекать образы контейнеров. В этом сценарии используется модуль реестра Docker. Он служит для получения образов контейнеров из облака и сохранения их в кэш на верхнем уровне. Прокси-сервер API передает все HTTPS-запросы для скачивания образов контейнеров с нижних уровней, которые должен обработать модуль реестра на верхнем уровне.

В этом сценарии требуется, чтобы нисходящие устройства IoT Edge указывали доменное имя $upstream и номер порта модуля прокси API вместо реестра контейнеров, в котором размещен образ. Например: $upstream:8000/azureiotedge-api-proxy:1.1.

Этот вариант использования демонстрируется в статье Учебник. Создание иерархии устройств IoT Edge.

Настройте приведенные ниже модули на верхнем уровне.

Модуль реестра Docker
- Настройте для модуля запоминающееся имя, например registry, и предоставьте порт в модуле для получения запросов.
- Настройте модуль для сопоставления с реестром контейнеров.

Модуль прокси-сервера API

Настройте следующие переменные среды.

Имя.	Значение
`DOCKER_REQUEST_ROUTE_ADDRESS`	Имя модуля реестра и открытый порт. Например, `registry:5000`.
`NGINX_DEFAULT_PORT`	Порт, через который прокси-сервер nginx ожидает передачи запросов от нисходящих устройств. Например, `8000`.

Настройте следующие параметры createOptions:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Настройте приведенный ниже модуль на любом нижнем уровне для данного сценария.

Модуль прокси-сервера API. Модуль прокси-сервера API необходим для всех устройств нижнего слоя, кроме устройства нижнего слоя.

Настройте следующие переменные среды.

Имя.	Значение
`NGINX_DEFAULT_PORT`	Порт, через который прокси-сервер nginx ожидает передачи запросов от нисходящих устройств. Например, `8000`.

Настройте следующие параметры createOptions:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Предоставление прокси-порта

Порт 8000 предоставляется по умолчанию из образа Docker. Если используется другой порт прокси-сервера nginx, добавьте раздел ExposedPorts , объявляющий порт в манифесте развертывания. Например, если изменить порт прокси-сервера nginx на 8001, добавьте следующее в манифест развертывания:

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

Включение передачи BLOB-объектов

Еще одним вариантом использования модуля прокси API является разрешение устройствам IoT Edge на более низких уровнях передавать BLOB-объекты. Этот вариант использования позволяет устранять неполадки на устройствах более низкого уровня, например посредством передачи журналов модулей или пакета поддержки.

В этом сценарии на верхнем уровне используется Хранилище BLOB-объектов Azure в модуле IOT Edge для управления созданием и передачей BLOB-объектов. В вложенном сценарии поддерживаются до пяти уровней. Хранилище BLOB-объектов Azure в модуле IoT Edge требуется на устройстве верхнего слоя и необязательно для устройств нижнего слоя. Пример развертывания с несколькими слоями см. в примере Azure IoT Edge для промышленного Интернета вещей .

Настройте приведенные ниже модули на верхнем уровне.

Хранилище BLOB-объектов Azure в модуле IoT Edge.

Модуль прокси-сервера API

Настройте следующие переменные среды.

Имя.	Значение
`BLOB_UPLOAD_ROUTE_ADDRESS`	Имя модуля хранилища BLOB-объектов и открытый порт. Например, `azureblobstorageoniotedge:11002`.
`NGINX_DEFAULT_PORT`	Порт, через который прокси-сервер nginx ожидает передачи запросов от нисходящих устройств. Например, `8000`.

Настройте следующие параметры createOptions:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Настройте приведенный ниже модуль на любом нижнем уровне для данного сценария.

Модуль прокси-сервера API

Настройте следующие переменные среды.

Имя.	Значение
`NGINX_DEFAULT_PORT`	Порт, через который прокси-сервер nginx ожидает передачи запросов от нисходящих устройств. Например, `8000`.

Настройте следующие параметры createOptions:

{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Выполните следующие действия, чтобы передать пакет поддержки или файл журнала в модуль хранилища BLOB-объектов, расположенный на верхнем уровне.

Создайте контейнер BLOB-объектов, используя Обозреватель службы хранилища Azure или интерфейсы REST API. Дополнительные сведения см. в разделе Хранение данных на пограничных устройствах с использованием хранилища BLOB-объектов Azure в IoT Edge.
Запросите передачу журнала или пакета поддержки в соответствии с инструкциями в статье Получение журналов из IoT Edge развертываний, но укажите доменное имя $upstream и открытый порт прокси-сервера вместо адреса модуля хранилища BLOB-объектов. Например:
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

Изменение конфигурации прокси-сервера

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

При создании собственной конфигурации можно по-прежнему использовать среду, чтобы настроить параметры для каждого развертывания. Используйте следующий синтаксис:

Используйте ${MY_ENVIRONMENT_VARIABLE}, чтобы получить значение переменной среды.

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

#if_tag ${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 1
#endif_tag ${MY_ENVIRONMENT_VARIABLE}

#if_tag !${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 0
#endif_tag !${MY_ENVIRONMENT_VARIABLE}

Когда модуль прокси API анализирует конфигурацию прокси-сервера, он сначала с помощью подстановки заменяет все переменные среды, перечисленные в PROXY_CONFIG_ENV_VAR_LIST, их значениями. Затем заменяется все между #if_tag и #endif_tag. После этого модуль предоставляет проанализированную конфигурацию для обратного прокси-сервера nginx.

Чтобы динамически обновить конфигурацию прокси-сервера, выполните следующие действия.

Создайте файл конфигурации. В качестве эталона можно использовать этот шаблон по умолчанию: nginx_default_config.conf
Скопируйте текст файла конфигурации и преобразуйте его в формат Base64.
Вставьте закодированный файл конфигурации в значение требуемого свойства proxy_config в модуле двойника.

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

Используйте модуль прокси API для подключения нисходящего устройства IoT Edge к шлюзу Azure IoT Edge.

Настройка модуля прокси API для иерархии шлюзов

Развертывание модуля прокси

Общие сведения о модуле прокси

Конфигурация по умолчанию

Уменьшение числа открытых портов

Разрешение скачивания образов контейнеров

Предоставление прокси-порта

Включение передачи BLOB-объектов

Изменение конфигурации прокси-сервера

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

Дополнительные ресурсы