Руководство: Автоматизация службы автоматической подготовки устройств 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 для создания ресурсов и управления ими. Вы не хотите поместить эти сведения в незащищенный файл, где его можно обнаружить, поэтому вместо этого мы будем использовать секреты репозитория для хранения этих сведений, но по-прежнему сделать его доступным в качестве переменной среды в рабочем процессе. Дополнительные сведения см. в разделе "Зашифрованные секреты".

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

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

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

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 , что будет передано рабочему процессу при каждом запуске, но мы не будем использовать их для этого руководства.

   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, которая создаст отдельную регистрацию, а затем используйте ее для регистрации устройства в Центре Интернета вещей.

      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 monitor-events

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 с помощью других инструментов автоматизации.