Tutorial: Automatizar o Serviço de Provisionamento de Dispositivo do Azure com ações do GitHub

Artigo
10/18/2023

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

Neste tutorial, irá aprender a:

Salve as credenciais de autenticação como segredos do repositório.
Crie um fluxo de trabalho para provisionar recursos do Hub IoT e 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 subscrição do Azure

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
A CLI do Azure
- Use o ambiente Bash no Azure Cloud Shell.
- Ou, se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se você estiver executando no Windows ou macOS, considere executar a CLI do Azure em um contêiner do Docker.
  - Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login.
  - Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.
Uma conta do GitHub com um repositório que você possui ou um repositório onde você tem acesso de administrador. Para obter mais informações, consulte 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. Você não quer colocar essas informações em um arquivo desprotegido onde elas possam ser descobertas, portanto, em vez disso, usaremos segredos de 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, consulte Segredos criptografados.

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

Criar um principal de serviço

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

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> com as suas próprias informações.

Este comando requer funções de proprietário ou administrador de acesso de usuário na assinatura.
```
az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
```
Copie os seguintes itens da saída do comando de criação da entidade de serviço para usar na próxima seção:
- O clientId.
- O clientSecret. Esta é uma senha gerada para a entidade de serviço que você não poderá acessar novamente.
- O tenantId.

Use o comando az role assignment create para atribuir mais duas funções de acesso à entidade de serviço: Device Provisioning Service Data Contributor e IoT Hub Data Contributor. Substitua <SP_CLIENT_ID> pelo valor clientId copiado 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

No GitHub.com, navegue até as Configurações do repositório.
Selecione Segredos no menu de navegação e, em seguida, selecione Ações.
Selecione Novo segredo do repositório.
Crie um segredo para o ID da entidade de serviço.
- Designação: APP_ID
- Secret: Cole o clientId que você copiou da saída do comando de criação da entidade de serviço.
Selecione Adicionar segredo e, em seguida, selecione Novo segredo do repositório para adicionar um segundo segredo.
Crie um segredo para a senha da entidade de serviço.
- Designação: SECRET
- Secret: Cole o clientSecret que você copiou da saída do comando de criação da entidade de serviço.
Selecione Adicionar segredo e, em seguida, selecione Novo segredo do repositório para adicionar o segredo final.
Crie um segredo para seu locatário do Azure.
- Designação: TENANT
- Secret: Cole o tenantId que você copiou da saída do comando de criação da entidade de serviço.
Selecione Add secret (Adicionar segredo).

2 - Criar um fluxo de trabalho

Um fluxo de trabalho de Ações do GitHub define as tarefas que serão executadas assim que forem acionadas 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 ações do GitHub.

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

Provisione uma instância do Hub IoT e uma instância do DPS.
Vincule as instâncias do Hub IoT e do DPS entre si.
Crie um registro individual na instância do DPS e registre um dispositivo no hub IoT usando a autenticação de chave simétrica por meio do registro do DPS.
Simule o dispositivo por cinco minutos e monitore os eventos do hub IoT.

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

No repositório do GitHub, navegue até a guia Ações .
No painel Ações, selecione Novo fluxo de trabalho.
Na página Escolha um fluxo de trabalho, você pode escolher modelos pré-criados para usar. Vamos criar o próprio fluxo de trabalho para este tutorial, portanto, selecione Configurar um fluxo de trabalho você mesmo.
O GitHub cria um novo arquivo de fluxo de trabalho para você. Observe que ele está no .github/workflows/ diretório. Dê ao novo arquivo um nome significativo, como dps-tutorial.yml.
Adicione o parâmetro name para dar um nome ao seu fluxo de trabalho.
```
name: DPS Tutorial
```
Adicione o parâmetro on.workflow_dispatch . O on parâmetro define quando um fluxo de trabalho será executado. O workflow_dispatch parâmetro indica que queremos acionar manualmente o fluxo de trabalho. Com esse parâmetro, poderíamos definir inputs que seria passado para o fluxo de trabalho em cada execução, mas não os usaremos para este tutorial.
```
on: workflow_dispatch
```
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. Você também pode definir variáveis de ambiente para trabalhos individuais ou para etapas individuais dentro de trabalhos.

Substitua os valores de espaço reservado por seus próprios valores. Certifique-se de especificar 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>
```

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

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

Defina o primeiro trabalho para o nosso fluxo de trabalho, que chamaremos de provision trabalho. 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 obter mais informações sobre os comandos executados neste trabalho, consulte:

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 não será executado até que o trabalho listado configure 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 obter mais informações sobre os comandos executados neste trabalho, consulte:
- az iot dps linked-hub criar
Defina um trabalho chamado register que criará um registro individual e, em seguida, use esse registro para registrar um dispositivo no 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   
```
Nota

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 atual do Microsoft Entra. A alternativa --auth-type key não requer a configuração da entidade de serviço, mas é menos segura.

Para obter mais informações sobre os comandos executados neste trabalho, consulte:
- az iot dps inscrição criar
- az iot registro de dispositivo criar

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 obter mais informações sobre os comandos executados neste trabalho, consulte:

Simular dispositivo AZ IoT

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 de simulação e monitoramento definem o trabalho de registro em seu needs parâmetro. Essa configuração significa que, uma vez que o trabalho de registro seja 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 obter mais informações sobre os comandos executados neste trabalho, consulte:
- AZ IoT Hub-Eventos-Monitor

O arquivo de fluxo de trabalho completo deve se parecer com 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

Salve, confirme e envie esse novo arquivo para o repositório do GitHub.

3 - Executar o fluxo de trabalho

Navegue até a guia Ações do repositório GitHub.
No painel Ações, selecione Tutorial do DPS, que é o nome que definimos no arquivo de fluxo de trabalho, e selecione a caixa suspensa Executar fluxo de trabalho.
Altere a ramificação se você criou seu fluxo de trabalho em uma ramificação diferente da principal e, em seguida, selecione Executar fluxo de trabalho.
Uma nova execução de fluxo de trabalho aparece em andamento. Selecione o nome para visualizar os detalhes da execução.
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 o Hub IoT. Durante esse tempo, selecione o trabalho de simulação para assistir às mensagens que estão sendo enviadas do dispositivo e o trabalho de monitor para observar essas mensagens sendo recebidas pelo Hub IoT.
Quando todos os trabalhos tiverem sido concluídos com sucesso, você verá marcas de seleção verdes por cada um.

Clean up resources (Limpar recursos)

Se você não vai continuar a usar esses recursos criados neste tutorial, exclua-os com as etapas a seguir.

Use a CLI do Azure:

Liste os recursos no seu grupo de recursos.

az resource list --resource-group <RESOURCE_GROUP_NAME>

Para excluir recursos individuais, use a ID do recurso.

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

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

Utilizar o portal do Azure:

No portal do Azure, navegue até o grupo de recursos onde você criou os novos recursos.
Pode eliminar todo o grupo de recursos ou selecionar os recursos individuais que pretende remover e, em seguida, selecionar Eliminar.

Próximos passos

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

Configurar o DPS com o Bicep

Share via