Compartilhar via

Tutorial: Automatizar o Serviço de Provisionamento de Dispositivos do Azure com o GitHub Actions

  • Artigo

Use ferramentas de automação como o GitHub Actions para gerenciar o ciclo de vida do dispositivo IoT. Este tutorial demonstra um fluxo de trabalho do GitHub Actions que conecta um dispositivo a um hub IoT usando o DPS (Serviço de Provisionamento de Dispositivos) do Azure.

Neste tutorial, você aprenderá como:

  • Salve as credenciais de autenticação como segredos do repositório.
  • Crie um fluxo de trabalho para provisionar o Hub IoT e os recursos do Serviço de Provisionamento de Dispositivos.
  • Execute o fluxo de trabalho e monitore um dispositivo simulado à medida que ele se conecta ao Hub IoT.

Pré-requisitos

  • Uma assinatura do Azure

    Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

  • A CLI do Azure

  • Uma conta do GitHub com um repositório que você possui ou um repositório em que você tem acesso de administrador. Para obter mais informações, confira Introdução ao GitHub.

1 - Criar segredos do repositório

O fluxo de trabalho que você definirá na próxima seção requer acesso à sua assinatura do Azure para criar e gerenciar recursos. Não é recomendável colocar essas informações em um arquivo desprotegido onde elas podem ser descobertas e, portanto, usaremos segredos do repositório para armazenar essas informações, mas ainda torná-las acessíveis como uma variável de ambiente no fluxo de trabalho. Para obter mais informações, confira Segredos criptografados.

Somente proprietários e administradores do repositório podem gerenciar segredos do repositório.

Criar uma entidade de serviço

Em vez de fornecer suas credenciais de acesso pessoal, criaremos uma entidade de serviço e, em seguida, adicionaremos essas credenciais como segredos do repositório. Use a CLI do Azure para criar uma nova entidade de serviço. Para mais informações, consulte Criar uma entidade de serviço do Azure.

  1. Use o comando az ad sp create-for-rbac para criar uma entidade de serviço com acesso de colaborador a um grupo de recursos específico. Substitua <SUBSCRIPTION_ID> e <RESOURCE_GROUP_NAME> pelas suas informações.

    Este comando requer funções de administrador de acesso do proprietário ou do usuário na assinatura.

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

  2. Copie os seguintes itens da saída do comando de criação da entidade de serviço para usar na próxima seção:

    • The clientId.
    • The clientSecret. Essa é uma senha gerada para a entidade de serviço que você não poderá acessar novamente.
    • The tenantId.

  3. Use o comando az role assignment create para atribuir mais duas funções de acesso à entidade de serviço: Colaborador de Dados do Serviço de Provisionamento de Dispositivos e Colaborador de Dados do Hub IoT. Substitua <SP_CLIENT_ID> pelo valor clientId que você copiou da saída do comando anterior.

    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>"

Salvar credenciais da entidade de serviço como segredos

  1. No GitHub.com, navegue até Configurações do repositório.

  2. Selecione Segredos no menu de navegação e, em seguida, selecione Ações.

  3. Selecione Novo segredo de repositório.

  4. Crie um segredo para a ID da entidade de serviço.

    • Nome: APP_ID
    • Segredo: cole o clientId que você copiou da saída do comando de criação da entidade de serviço.

  5. Selecione Adicionar segredo e, em seguida, selecione Novo segredo do repositório para adicionar um segundo segredo.

  6. Crie um segredo para a senha da entidade de serviço.

    • Nome: SECRET
    • Segredo: cole o clientSecret que você copiou da saída do comando de criação da entidade de serviço.

  7. Selecione Adicionar segredo e, em seguida, selecione Novo segredo do repositório para adicionar o segredo final.

  8. Crie um segredo para o seu locatário do Azure.

    • Nome: TENANT
    • Segredo: cole o tenantId que você copiou da saída do comando de criação da entidade de serviço.

  9. Selecione Adicionar segredo.

2 - Criar um fluxo de trabalho

Um fluxo de trabalho do GitHub Actions define as tarefas que serão executadas depois de disparadas por um evento. Um fluxo de trabalho contém um ou mais trabalhos que podem ser executados em paralelo ou sequencialmente. Para obter mais informações, consulte Noções básicas sobre o GitHub Actions.

Para este tutorial, criaremos um fluxo de trabalho que contém trabalhos para cada uma das seguintes tarefas:

  • Provisionar uma instância do Hub IoT e uma instância do DPS.
  • Vincular as instâncias do Hub IoT e do DPS umas às outras.
  • Crie um registro individual na instância do DPS e registre um dispositivo no Hub IoT usando autenticação de chave simétrica por meio do registro do DPS.
  • Simular o dispositivo por cinco minutos e monitorar os eventos do Hub IoT.

Fluxos de trabalho são arquivos YAML localizados no diretório .github/workflows/ de um repositório.

  1. No repositório GitHub, navegue até a guia Ações.

  2. No painel Ações, selecione Novo fluxo de trabalho.

  3. Na página Escolher um fluxo de trabalho, você pode escolher modelos predefinidos a serem usados. Vamos criar um fluxo de trabalho próprio para este tutorial, então, selecione Configurar um fluxo de trabalho por conta própria.

  4. O GitHub cria um arquivo de fluxo de trabalho para você. Observe que ele está no diretório .github/workflows/. Dê ao novo arquivo um nome significativo, como dps-tutorial.yml.

  5. Adicione o parâmetro name para dar um nome ao fluxo de trabalho.

    name: DPS Tutorial

  6. Adicione o parâmetro on.workflow_dispatch. O parâmetro on define quando um fluxo de trabalho será executado. O parâmetro workflow_dispatch indica que queremos disparar manualmente o fluxo de trabalho. Com esse parâmetro, poderíamos definir inputs que seriam passadas para o fluxo de trabalho em cada execução, mas não as usaremos para este tutorial.

    on: workflow_dispatch

  7. Defina as variáveis de ambiente para os recursos que você está criando no fluxo de trabalho. Essas variáveis estarão disponíveis para todos os trabalhos no fluxo de trabalho. Também é possível definir variáveis de ambiente para trabalhos individuais ou para etapas individuais em trabalhos.

    Substitua os valores do espaço reservado pelos seus. Especifique o mesmo grupo de recursos ao qual a entidade de serviço tem acesso.

    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. Defina variáveis de ambiente para os segredos que você criou na seção anterior.

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

  9. Adicione o parâmetro jobs ao arquivo de fluxo de trabalho.

    jobs:

  10. Defina o primeiro trabalho para o fluxo de trabalho, que chamaremos de trabalho provision. Este trabalho provisiona as instâncias do Hub IoT e do 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"

    Para saber mais sobre os comandos executados neste trabalho, confira:

  11. Defina um trabalho para configure as instâncias do DPS e do Hub IoT. Observe que esse trabalho usa o parâmetro needs, o que significa que o trabalho configure não será executado até que o trabalho listado conclua sua própria execução com êxito.

      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"

    Para saber mais sobre os comandos executados neste trabalho, confira:

  12. Defina um trabalho chamado register que criará um registro individual e, em seguida, use esse registro para registrar um dispositivo para o Hub IoT.

      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

    Observação

    Este trabalho e outros usam o parâmetro --auth-type login em alguns comandos para indicar que a operação deve usar a entidade de serviço da sessão do Microsoft Entra atual. A alternativa --auth-type key não requer a configuração da entidade de serviço, mas é menos segura.

    Para saber mais sobre os comandos executados neste trabalho, confira:

  13. Defina um trabalho para simulate um dispositivo IoT que se conectará ao Hub IoT e enviará mensagens de telemetria de exemplo.

      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"

    Para saber mais sobre os comandos executados neste trabalho, confira:

  14. Defina um trabalho para monitor o ponto de extremidade do Hub IoT para eventos e observe as mensagens recebidas do dispositivo simulado. Observe que os trabalhos simular e monitorar definem o trabalho registrar em seu parâmetro needs. Essa configuração significa que, depois que o trabalho registrar for concluído com êxito, ambos os trabalhos serão executados em paralelo.

      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

    Para saber mais sobre os comandos executados neste trabalho, confira:

  15. O arquivo de fluxo de trabalho completo deve ser semelhante a este exemplo, com suas informações substituindo os valores de espaço reservado nas variáveis de ambiente:

    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. Salve, confirme e envie por push esse novo arquivo para o repositório GitHub.

3 - Executar o fluxo de trabalho

  1. Navegue até a guia Ações do seu repositório GitHub.

  2. No painel Ações, selecione Tutorial do DPS, que é o nome que definimos no arquivo de fluxo de trabalho, e, em seguida, selecione a caixa suspensa Executar fluxo de trabalho.

    Screenshot of the action tab where you can select a workflow and run it.

  3. Altere o branch se você tiver criado o fluxo de trabalho em um branch diferente do principal e selecione Executar fluxo de trabalho.

  4. Uma nova execução de fluxo de trabalho aparece em andamento. Selecione o nome para exibir detalhes da execução.

  5. No resumo do fluxo de trabalho, você pode observar como cada trabalho começa e é concluído. Selecione qualquer nome de trabalho para visualizar seus detalhes. O trabalho de dispositivo simulado é executado por cinco minutos e envia telemetria para Hub IoT. Durante esse tempo, selecione o trabalho simular para ver as mensagens que estão sendo enviadas do dispositivo e o trabalho monitorar para observar as mensagens recebidas pelo Hub IoT.

  6. Quando todos os trabalhos tiverem sido concluídos com êxito, você deverá ver marcas de seleção verdes por cada um deles.

    Screenshot of a successfully completed workflow.

Limpar os recursos

Se você não quiser continuar usando esses recursos criados nesse tutorial, exclua-os com as seguintes etapas.

Usar a CLI do Azure:

  1. Liste os recursos no seu grupo de recursos.

    az resource list --resource-group <RESOURCE_GROUP_NAME>

  2. Para excluir recursos individuais, use a ID do recurso.

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

  3. Se você quiser excluir todo o grupo de recursos e todos os recursos dentro dele, execute o seguinte comando:

    az group delete --resource-group <RESOURCE_GROUP_NAME>

Usar o portal do Azure:

  1. No portal do Azure, navegue até o grupo de recursos em que você criou os novos recursos.
  2. Você pode excluir todo o grupo de recursos ou selecionar os recursos individuais que quer remover e, em seguida, selecionar Excluir.

Próximas etapas

Saiba como provisionar instâncias do DPS com outras ferramentas de automação.

Configurar o DPS com o Bicep