Руководство: Автоматизация службы автоматической подготовки устройств Azure с помощью GitHub Actions

Используйте средства автоматизации, такие как GitHub Actions, для управления жизненным циклом устройств Интернета вещей. В этом руководстве демонстрируется рабочий процесс GitHub Actions, который подключает устройство к Центру Интернета вещей с помощью службы подготовки устройств Azure (DPS).

В этом руководстве вы узнаете, как:

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

Предпосылки

• подписка Azure

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

• Интерфейс командной строки Azure

  • Используйте среду Bash в Azure Cloud Shell.

  • Или, если вы предпочитаете локально запускать справочные команды CLI, установите Azure CLI. Если вы работаете в Windows или macOS, попробуйте запустить Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, войдите в Azure CLI с помощью команды az login .

    • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

• Учетная запись GitHub с собственным репозиторием или репозиторием, к которому у вас есть доступ администратора. Дополнительные сведения см. в статье "Начало работы с GitHub".

1. Создание секретов репозитория

Рабочий процесс, заданный в следующем разделе, требует доступа к подписке Azure для создания ресурсов и управления ими. Вы не хотите поместить эти сведения в незащищенный файл, где его можно обнаружить, поэтому вместо этого мы используем секреты репозитория для хранения этих сведений, но по-прежнему сделать его доступным в качестве переменной среды в рабочем процессе. Дополнительные сведения см. в разделе "Использование секретов" в GitHub Actions.

Только владельцы репозитория и администраторы могут управлять секретами репозитория.

Создайте сервисного принципала

Вместо того, чтобы предоставлять личные учетные данные доступа, мы создадим учетную запись службы, а затем добавим эти учетные данные в качестве секретов репозитория. Используйте Azure CLI для создания нового служебного принципала. Дополнительные сведения см. в статье Создание субъекта-службы Azure с помощью Azure CLI.

1. Используйте команду az ad sp create-for-rbac, чтобы создать учётную запись службы с правами участника к определенной группе ресурсов. Замените <SUBSCRIPTION_ID> и <RESOURCE_GROUP_NAME> своими значениями.

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

   az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
   

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

   • Идентификатор клиента.
   • clientSecret. Это значение является созданным паролем для основной службы, к которому вы больше не сможете получить доступ.
   • Идентификатор клиента.

3. Используйте команду az role assignment create, чтобы назначить две дополнительные роли доступа служебному принципалу: вкладчика данных службы подготовки устройств и вкладчика данных IoT Hub. Замените <SP_CLIENT_ID> на значение clientId, которое вы скопировали из выходных данных предыдущей команды.

   az role assignment create --assignee "<SP_CLIENT_ID>" --role "Device Provisioning Service Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
   

   az role assignment create --assignee "<SP_CLIENT_ID>" --role "IoT Hub Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
   

Сохранение учетных данных учетной записи службы в виде секретов

1. В GitHub.com перейдите к параметрам репозитория.

2. Выберите секреты в меню навигации, а затем выберите "Действия".

3. Нажмите Создать секрет репозитория.

4. Создайте секрет для учетной записи службы.

   • Имя: APP_ID
   • Секрет: Вставьте идентификатор клиента, скопированный из выходных данных команды создания субъекта-службы.

5. Выберите "Добавить секрет", а затем выберите новый секрет репозитория , чтобы добавить второй секрет.

6. Создайте секрет для пароля учетной записи службы.

   • Имя: SECRET
   • Секрет: Вставьте clientSecret, скопированный из выходных данных команды создания служебной учётной записи.

7. Выберите "Добавить секрет", а затем выберите новый секрет репозитория , чтобы добавить окончательный секрет.

8. Создайте секрет для клиента Azure.

   • Имя: TENANT
   • Секрет. Вставьте идентификатор клиента , скопированный из выходных данных команды создания субъекта-службы.

9. Выберите Добавить секрет.

2. Создание рабочего процесса

Рабочий процесс GitHub Actions определяет задачи, выполняемые после активации рабочего процесса. Рабочий процесс содержит одно или несколько заданий , которые могут выполняться параллельно или последовательно. Дополнительные сведения см. в разделе "Общие сведения о действиях GitHub".

В этом руководстве мы создадим один рабочий процесс, содержащий задания для каждой из следующих задач:

• Создайте экземпляр Центра Интернета вещей и экземпляр DPS.
• Свяжите экземпляры "IoT Hub" и DPS между собой.
• Создайте индивидуальную регистрацию в экземпляре DPS и зарегистрируйте устройство в Центре Интернета Вещей с использованием аутентификации по симметричному ключу через регистрацию DPS.
• Имитируйте устройство в течение пяти минут и отслеживайте события Центра Интернета вещей.

Рабочие процессы — это файлы YAML, расположенные в .github/workflows/ каталоге репозитория.

1. В репозитории GitHub перейдите на вкладку Actions .

2. В области "Действия" выберите новый рабочий процесс.

3. На странице "Выбор рабочего процесса" можно выбрать готовые шаблоны для использования. Мы создадим собственный рабочий процесс для этого руководства, поэтому выберите " Настроить рабочий процесс самостоятельно".

4. GitHub создает новый файл рабочего процесса для вас. Обратите внимание, что он находится в каталоге .github/workflows/ . Присвойте новому файлу понятное имя, например dps-tutorial.yml.

5. Добавьте параметр имени , чтобы дать рабочему процессу имя.

   name: DPS Tutorial
   

6. Добавьте параметр on.workflow_dispatch . Параметр on определяет, когда выполняется рабочий процесс. Параметр workflow_dispatch указывает, что нужно вручную активировать рабочий процесс. С помощью этого параметра мы могли бы определить inputs , что будет передано рабочему процессу во время каждого запуска, но мы не используем inputs для этого руководства.

   on: workflow_dispatch
   

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

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

   env:
     HUB_NAME: <Globally unique IoT hub name>
     DPS_NAME: <Desired Device Provisioning Service name>
     DEVICE_NAME: <Desired device name>
     RESOURCE_GROUP: <Solution resource group where resources will be created>
   

8. Определите переменные среды для секретов, созданных в предыдущем разделе.

     SP_USER: ${{ secrets.APP_ID }}
     SP_SECRET: ${{ secrets.SECRET }}
     SP_TENANT: ${{ secrets.TENANT }}
   

9. Добавьте параметр заданий в файл рабочего процесса.

   jobs:
   

10. Определите первое задание для нашего рабочего процесса, которое мы называем provision заданием. Это задание подготавливает экземпляры Центра IoT и DPS (система управления устройствами):

      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
    

    Дополнительные сведения о командах, выполняемых в этом задании, см. в следующих статье:

    • az iot hub create
    • az iot dps create

11. Определите задание для configure экземпляров DPS и узла IoT. Обратите внимание, что это задание использует параметр потребностей , что означает, что configure задание не выполняется, пока указанное задание не завершит собственное выполнение успешно.

      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"   
    

    Дополнительные сведения о командах, выполняемых в этом задании, см. в следующих статье:

    • az iot dps linked-hub create

12. Определите задание register, которое создает индивидуальное зарегистрирование, а затем используйте это зарегистрирование для регистрации устройства в сети IoT Hub.

      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login   
    

    Замечание

    Эта задача и другие используют параметр --auth-type login в некоторых командах, чтобы указать, что операция должна использовать учетную запись службы из текущего сеанса Microsoft Entra. Альтернатива --auth-type key не требует настройки учетной записи службы, но менее безопасна.

    Дополнительные сведения о командах, выполняемых в этом задании, см. в следующих статье:

    • az iot dps enrollment create (создать запись регистрации)
    • az iot устройство регистрация создать

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

      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
    

    Дополнительные сведения о командах, выполняемых в этом задании, см. в следующих статье:

    • az симуляция iot-устройства

14. Создайте задачу для конечной точки monitor Центра Интернета вещей для событий и следите за сообщениями, поступающими с имитированного устройства. Обратите внимание, что имитированные и отслеживаемые задания определяют задание регистрации в параметре needs . Эта конфигурация означает, что после успешного завершения задания регистрации оба задания выполняются параллельно.

      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y   
    

    Дополнительные сведения о командах, выполняемых в этом задании, см. в следующих статье:

    • az iot hub монитор событий

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

    name: DPS Tutorial
    
    on: workflow_dispatch
    
    env:
      HUB_NAME: <Globally unique IoT hub name>
      DPS_NAME: <Desired Device Provisioning Service name>
      DEVICE_NAME: <Desired device name>
      RESOURCE_GROUP: <Solution resource group where resources will be created>
      SP_USER: ${{ secrets.APP_ID }}
      SP_SECRET: ${{ secrets.SECRET }}
      SP_TENANT: ${{ secrets.TENANT }}
    
    jobs:
      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"
      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login
      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y
    

16. Сохраните, зафиксируйте и отправьте этот новый файл в репозиторий GitHub.

3. Запуск рабочего процесса

1. Перейдите на вкладку Actions репозитория GitHub.

2. В области "Действия " выберите "Руководство по DPS", имя которого мы определили в файле рабочего процесса, а затем в раскрывающемся списке "Запуск рабочего процесса ".

   

3. Измените ветвь, если вы создали рабочий процесс в ветви, отличной от основной, а затем нажмите кнопку "Выполнить рабочий процесс".

4. Выполняется новый запуск рабочего процесса. Выберите название для просмотра сведений о выполнении.

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

6. После успешного завершения всех заданий по каждому из них должны отображаться зеленые флажки.

   

Очистите ресурсы

Если вы не собираетесь продолжать использовать эти ресурсы, созданные в этом руководстве, удалите их с помощью следующих действий.

Используйте Azure CLI:

1. Перечислите ресурсы в вашей группе ресурсов.

   az resource list --resource-group <RESOURCE_GROUP_NAME>
   

2. Чтобы удалить отдельные ресурсы, используйте идентификатор ресурса.

   az resource delete --resource-group <RESOURCE_GROUP_NAME> --ids <RESOURCE_ID>
   

3. Если вы хотите удалить всю группу ресурсов и все ресурсы в ней, выполните следующую команду:

   az group delete --resource-group <RESOURCE_GROUP_NAME>
   

Используйте портал Azure:

1. На портале Azure перейдите в группу ресурсов, в которой вы создали новые ресурсы.
2. Можно удалить всю группу ресурсов или выбрать отдельные ресурсы, которые требуется удалить, а затем нажмите кнопку "Удалить".

Дальнейшие шаги

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

Руководство. Использование пользовательских политик выделения с помощью службы подготовки устройств (DPS)