Интеграция IoT Central с Azure Pipelines для непрерывной интеграции и непрерывной доставки

Статья
10/27/2023

Непрерывная интеграция и непрерывная доставка (CI/CD) относится к процессу разработки и доставки программного обеспечения в короткие, частые циклы с помощью конвейеров автоматизации. В этой статье показано, как автоматизировать сборку, тестирование и развертывание конфигурации приложения IoT Central. Эта автоматизация позволяет группам разработчиков чаще предоставлять надежные выпуски.

Непрерывная интеграция начинается с фиксации кода в ветви в репозитории исходного кода. Каждая фиксация объединяется с фиксациями от других разработчиков, чтобы гарантировать отсутствие конфликтов. Изменения дополнительно проверяются путем создания сборки и выполнения автоматических тестов для этой сборки. Этот процесс в конечном итоге приводит к артефакту или пакету развертывания для развертывания в целевой среде. В этом случае целевой объект — это приложение Azure IoT Central.

Так же, как IoT Central является частью вашего более крупного решения IoT, IoT Central является частью конвейера CI/CD. Конвейер CI/CD должен развертывать все решение Интернета вещей и все конфигурации в каждой среде от разработки до рабочей среды:

Схема, на которую показаны этапы типичного конвейера CI/CD.

IoT Central — это платформа приложений как услуга , которая имеет различные требования к развертыванию от платформы в качестве компонентов службы . Для IoT Central вы развертываете конфигурации и шаблоны устройств. Эти конфигурации и шаблоны устройств управляются и интегрируются в конвейер выпуска с помощью API.

Хотя вы можете автоматизировать создание приложений IoT Central, перед разработкой конвейера CI/CD необходимо создать приложение в каждой среде.

С помощью REST API Azure IoT Central можно интегрировать конфигурации приложений IoT Central в конвейер выпуска.

В этом руководстве описывается создание нового конвейера, который обновляет приложение IoT Central на основе файлов конфигурации, управляемых в GitHub. В этом руководстве содержатся конкретные инструкции по интеграции с Azure Pipelines, но их можно адаптировать для включения IoT Central в любой конвейер выпуска, построенный с помощью таких средств, как Tekton, Jenkins, GitLab или GitHub Actions.

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

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

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

Необходимые компоненты

Чтобы выполнить действия, описанные в этом руководстве, необходимы следующие предварительные требования:

Два приложения IoT Central — один для среды разработки и один для рабочей среды. Дополнительные сведения см. в статье Создание приложения IoT Central.
Два хранилища Ключей Azure — один для среды разработки и один для рабочей среды. Рекомендуется использовать выделенное хранилище ключей для каждой среды. Дополнительные сведения см. в статье "Создание Azure Key Vault с помощью портал Azure".
Учетная запись GitHub GitHub.
Организация Azure DevOps. Дополнительные сведения см. в статье "Создание организации Azure DevOps".
PowerShell 7 для Windows, Mac или Linux. Получите PowerShell.
Модуль Azure Az PowerShell, установленный в среде PowerShell 7. Дополнительные сведения см. в статье "Установка модуля Azure Az PowerShell".
Visual Studio Code или другое средство для редактирования файлов PowerShell и JSON.Получите Visual Studio Code.
Клиент Git. Скачайте последнюю версию из Git — загрузки (git-scm.com).

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.
Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
- Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.
- Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.
- Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Скачивание примера кода

Чтобы приступить к работе, вилку репозитория CI/CD GitHub IoT Central и клонируйте вилку на локальный компьютер:

Чтобы создать вилку репозитория GitHub, откройте репозиторий CI/CD GitHub IoT Central и выберите Fork.
Клонируйте вилку репозитория на локальный компьютер, открыв окно консоли или bash и выполнив следующую команду.
```
git clone https://github.com/{your GitHub username}/iot-central-CICD-sample
```

Создание субъекта-службы

Хотя Azure Pipelines может интегрироваться непосредственно с хранилищем ключей, конвейеру требуется субъект-служба для некоторых динамических взаимодействий с хранилищем ключей, таких как получение секретов для назначений экспорта данных.

Чтобы создать субъект-службу, область в подписку:

Выполните следующую команду, чтобы создать новый субъект-службу:
```
az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor
```
Запишите пароль, appId и клиент , так как вам потребуются эти значения позже.
Добавьте пароль субъекта-службы в качестве секрета, вызываемого SP-Password в хранилище ключей рабочей среды:
```
az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}
```
Предоставьте субъекту-службе разрешение на чтение секретов из хранилища ключей:
```
az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}
```

Создание маркеров API IoT Central

В этом руководстве конвейер использует маркеры API для взаимодействия с приложениями IoT Central. Кроме того, можно использовать субъект-службу.

Примечание.

Срок действия маркеров API IoT Central истекает через год.

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

В приложении IoT Central выберите разрешения и маркеры API.
Выберите Создать.
Присвойте маркеру имя, укажите организацию верхнего уровня в приложении и задайте роль app Администратор istrator.
Запишите маркер API из приложения IoT Central разработки. Вы используете его позже при запуске скрипта IoTC-Config.ps1 .
Сохраните созданный маркер из рабочего приложения IoT Central в качестве секрета, вызываемого API-Token в хранилище ключей рабочей среды:
```
az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'
```

Создание файла конфигурации

Эти действия создают файл конфигурации JSON для среды разработки на основе существующего приложения IoT Central. Вы также скачайте все существующие шаблоны устройств из приложения.

Выполните следующий скрипт PowerShell 7 в локальной копии репозитория CI/CD IoT Central:
```
cd .\iot-central-CICD-sample\PowerShell\
.\IoTC-Config.ps1
```
Следуйте инструкциям для входа в учетную запись Azure.
После входа скрипт отображает меню параметров конфигурации IoTC. Скрипт может создать файл конфигурации из существующего приложения IoT Central и применить конфигурацию к другому приложению IoT Central.
Выберите вариант 1 , чтобы создать файл конфигурации.
Введите необходимые параметры и нажмите клавишу ВВОД:
- Маркер API, созданный для приложения IoT Central для разработки.
- Поддомен приложения IoT Central для разработки.
- Введите .. \Config\Dev в качестве папки для хранения файла конфигурации и шаблонов устройств.
- Имя хранилища ключей разработки.
Скрипт создает папку с именем IoTC Configuration в папке Config\Dev в локальной копии репозитория. Эта папка содержит файл конфигурации и папку с именем "Модели устройств" для всех шаблонов устройств в приложении.

Измените файл конфигурации.

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

Создайте копию папки разработки, созданной ранее, и вызовите ее Production.
Откройте IoTC-Config.json в рабочей папке с помощью текстового редактора.

Файл содержит несколько разделов. Однако если в приложении не используется определенный параметр, этот раздел опущен из файла:

{
  "APITokens": {
    "value": [
      {
        "id": "dev-admin",
        "roles": [
          {
            "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
          }
        ],
        "expiry": "2023-05-31T10:47:08.53Z"
      }
    ]
  },
  "data exports": {
    "value": [
      {
        "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",
        "displayName": "All telemetry to blob storage",
        "enabled": false,
        "source": "telemetry",
        "destinations": [
          {
            "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"
          }
        ],
        "status": "notStarted"
      }
    ]
  },
  "device groups": {
    "value": [
      {
        "id": "66f41d29-832d-4a12-9e9d-18932bee3141",
        "displayName": "MXCHIP Getting Started Guide - All devices"
      },
      {
        "id": "494dc749-0963-4ec1-89ff-e1de2228e750",
        "displayName": "RS40 Occupancy Sensor - All devices"
      },
      {
        "id": "dd87877d-9465-410b-947e-64167a7a1c39",
        "displayName": "Cascade 500 - All devices"
      },
      {
        "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",
        "displayName": "Simulated devices"
      }
    ]
  },
  "organizations": {
    "value": []
  },
  "roles": {
    "value": [
      {
        "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
        "displayName": "Builder"
      },
      {
        "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
        "displayName": "Administrator"
      },
      {
        "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
        "displayName": "Operator"
      }
    ]
  },
  "destinations": {
    "value": [
      {
        "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
        "displayName": "Blob destination",
        "type": "blobstorage@v1",
        "authorization": {
          "type": "connectionString",
          "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",
          "containerName": "dataexport"
        },
        "status": "waiting"
      }
    ]
  },
  "file uploads": {
    "connectionString": "FileUpload",
    "container": "fileupload",
    "sasTtl": "PT1H"
  },
  "jobs": {
    "value": []
  }
}

Если приложение использует отправку файлов, скрипт создает секрет в хранилище ключей разработки со значением, показанным в свойстве connectionString . Создайте секрет с тем же именем в хранилище ключей рабочей среды, которое содержит строка подключения для рабочей учетной записи хранения. Например:
```
az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'
```
Если приложение использует экспорт данных, добавьте секреты для назначений в хранилище ключей рабочей среды. Файл конфигурации не содержит фактических секретов для назначения, секреты хранятся в хранилище ключей.

Обновите секреты в файле конфигурации с именем секрета в хранилище ключей.

Тип назначения	Свойство для изменения
Очередь служебной шины	connectionString
Раздел служебной шины	connectionString
Azure Data Explorer	clientSecret
Хранилище BLOB-объектов Azure	connectionString
Event Hubs	connectionString
Веб-перехватчик без проверки подлинности	Н/П

Например:

"destinations": {
  "value": [
    {
      "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
      "displayName": "Blob destination",
      "type": "blobstorage@v1",
      "authorization": {
        "type": "connectionString",
        "connectionString": "Storage-CS",
        "containerName": "dataexport"
      },
      "status": "waiting"
    }
  ]
}

Чтобы отправить папку конфигурации в репозиторий GitHub, выполните следующие команды из папки IoTC-CICD-howto.
```
 git add Config
 git commit -m "Adding config directories and files"
 git push
```

Создание конвейера

Откройте организацию Azure DevOps в веб-браузере, перейдя в раздел . https://dev.azure.com/{your DevOps organization}
Выберите новый проект , чтобы создать новый проект.
Присвойте проекту имя и необязательное описание, а затем нажмите кнопку "Создать".
На странице "Добро пожаловать в проект" выберите "Конвейеры" и "Создать конвейер".
Выберите GitHub в качестве расположения кода.
Выберите "Авторизовать AzurePipelines", чтобы авторизовать Azure Pipelines для доступа к учетной записи GitHub.
На странице "Выбор репозитория" выберите вилку репозитория IoT Central CI/CD GitHub.
При появлении запроса на вход в GitHub и предоставления разрешения azure Pipelines для доступа к репозиторию выберите " Утвердить и установить".
На странице "Настройка конвейера" выберите "Начальный конвейер", чтобы приступить к работе. Отображается azure-pipelines.yml для редактирования.

Создание группы переменных

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

Выберите библиотеку в разделе "Конвейеры " меню слева.
Выберите и группу переменных.
Введите keyvault имя группы переменных.
Включите переключатель для связывания секретов из хранилища ключей Azure.
Выберите подписку Azure и авторизовать ее. Затем выберите имя хранилища ключей рабочей среды.
Нажмите кнопку "Добавить ", чтобы начать добавлять переменные в группу.
Добавьте следующие секреты:
- Ключ API IoT Central для рабочего приложения. Этот секрет API-Token вызывается при его создании.
- Пароль для созданного ранее субъекта-службы. Этот секрет SP-Password вызывается при его создании.
Нажмите ОК.
Нажмите кнопку "Сохранить", чтобы сохранить группу переменных.

Настройка конвейера

Теперь настройте конвейер для отправки изменений конфигурации в приложение IoT Central:

Выберите "Конвейеры" в разделе "Конвейеры" меню слева.
Замените содержимое YAML конвейера следующим yamL. В конфигурации предполагается, что хранилище ключей рабочей среды содержит следующее:
- Маркер API для рабочего приложения IoT Central в секрете API-Token.
- Пароль субъекта-службы в секрете вызывается SP-Password.
Замените значения для -AppName-KeyVault рабочих экземпляров и соответствующими значениями.

Вы запишите и -AppId-TenantId при создании субъекта-службы.
```
trigger:
- master
variables:
- group: keyvault
- name: buildConfiguration
  value: 'Release'
steps:
- task: PowerShell@2
  displayName: 'IoT Central'
  inputs:
    filePath: 'PowerShell/IoTC-Task.ps1'
    arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'
    pwsh: true
    failOnStderr:  true
```
Выберите Сохранить и выполнить.
ФАЙЛ YAML сохраняется в репозитории GitHub, поэтому необходимо предоставить сообщение фиксации, а затем снова нажать кнопку "Сохранить и запустить ".

Конвейер помещается в очередь. До запуска может потребоваться несколько минут.

При первом запуске конвейера вам будет предложено предоставить разрешения для конвейера для доступа к подписке и доступа к хранилищу ключей. Выберите "Разрешить " и снова "Разрешить " для каждого ресурса.

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

Повышение изменений от разработки к рабочей среде

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

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

Теперь, когда вы знаете, как интегрировать конфигурации IoT Central в конвейеры CI/CD, рекомендуется узнать, как управлять приложениями IoT Central и отслеживать их.