Tutorial: Automatización de Azure Device Provisioning Service con Acciones de GitHub

Artículo
03/09/2023

Use herramientas de automatización como Acciones de GitHub para administrar el ciclo de vida de sus dispositivos IoT. En este tutorial se describe un flujo de trabajo de Acciones de GitHub que conecta un dispositivo a un centro de IoT mediante Azure Device Provisioning Service (DPS).

En este tutorial, aprenderá a:

Guardar credenciales de autenticación como secretos de repositorio
Crear un flujo de trabajo para aprovisionar recursos de IoT Hub y Device Provisioning Service
Ejecutar el flujo de trabajo y supervisar un dispositivo simulado mientras se conecta a IoT Hub

Requisitos previos

Una suscripción de Azure

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.
La CLI de Azure
- Use el entorno de Bash en Azure Cloud Shell.
- Si prefiere ejecutar comandos de referencia de la CLI localmente, instale la CLI de Azure. Si utiliza Windows o macOS, considere la posibilidad de ejecutar la CLI de Azure en un contenedor Docker.
  - Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login.
  - Ejecute az version para buscar cuál es la versión y las bibliotecas dependientes que están instaladas. Para realizar la actualización a la versión más reciente, ejecute az upgrade.
Una cuenta de GitHub con un repositorio de su propiedad o un repositorio al que tenga acceso como administrador. Para obtener más información, vea Introducción a GitHub.

1. Creación de secretos de repositorio

El flujo de trabajo que definiremos en la siguiente sección requiere acceso a su suscripción de Azure para crear y administrar recursos. No conviene colocar esa información en un archivo sin protección donde pueda encontrarse, por lo que, en su lugar, usaremos secretos del repositorio para almacenarla en ellos, si bien seguirá estando accesible como una variable de entorno en el flujo de trabajo. Para más información, consulte Secretos cifrados.

Solo los propietarios y los administradores del repositorio pueden administrar secretos de repositorio.

Creación de una entidad de servicio

En lugar de proporcionar sus credenciales de acceso personales, crearemos una entidad de servicio y luego agregaremos esas credenciales como secretos de repositorio. Use la CLI de Azure para crear la entidad de servicio. Para más información, consulte Creación de una entidad de servicio de Azure.

Use el comando az ad sp create-for-rbac para crear una entidad de servicio con acceso de colaborador a un grupo de recursos específico. Reemplace <SUBSCRIPTION_ID> y <RESOURCE_GROUP_NAME> por su propia información.

Este comando requiere roles de administrador de acceso de usuario o de propietario en la suscripción.
```
az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
```
Copie los elementos siguientes de la salida del comando de creación de la entidad de servicio para usarlo en la sección siguiente:
- El valor clientId.
- El valor clientSecret. Se trata de una contraseña generada para la entidad de servicio a la que no podrá acceder de nuevo.
- El valor tenantId.
Use el comando az role assignment create para asignar dos roles de acceso más a la entidad de servicio: Colaborador de datos del servicio de aprovisionamiento de dispositivos y Colaborador de datos de IoT Hub. Reemplace <SP_CLIENT_ID> por el valor clientId que copió de la salida del 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>"
```

Guardar las credenciales de entidad de servicio como secretos

En GitHub.com, vaya a la configuración de su repositorio.
Seleccione Secretos en el menú de navegación y, a continuación, seleccione Acciones.
Seleccione New repository secret (Nuevo secreto del repositorio).
Cree un secreto para el identificador de la entidad de servicio.
- Nombre: APP_ID
- Secreto: pegue el valor de clientId que copió de la salida del comando de creación de la entidad de servicio.
Seleccione Add secret (Agregar secreto) y, a continuación, seleccione New repository secret (Nuevo secreto de repositorio) para agregar un segundo secreto.
Cree un secreto para la entidad de servicio de la entidad de servicio.
- Nombre: SECRET
- Secreto: pegue el valor de clientSecret que copió de la salida del comando de creación de la entidad de servicio.
Seleccione Add secret (Agregar secreto) y, a continuación, seleccione New repository secret (Nuevo secreto de repositorio) para agregar el último secreto.
Cree un secreto para el inquilino de Azure.
- Nombre: TENANT
- Secreto: pegue el valor de tenantId que copió de la salida del comando de creación de la entidad de servicio.
Seleccione Add secret (Agregar secreto).

2. Creación de un flujo de trabajo

Un flujo de trabajo de Acciones de GitHub define las tareas que se ejecutarán una vez que un evento lo desencadene. Un flujo de trabajo contiene uno o varios trabajos que se pueden ejecutar en orden secuencial o en paralelo. Para obtener más información, vea Descripción de Acciones de GitHub.

En este tutorial, crearemos un flujo de trabajo que contiene trabajos para cada una de las tareas siguientes:

Aprovisionar una instancia de IoT Hub y una instancia de DPS
Vincular las instancias de IoT Hub y DPS entre sí
Cree una inscripción individual en la instancia de DPS y registre un dispositivo en el centro de IoT con la autenticación de clave simétrica través de la inscripción de DPS.
Simular el dispositivo durante cinco minutos y supervisar los eventos de IoT Hub

Los flujos de trabajo son archivos YAML que se encuentran en el directorio .github/workflows/ de un repositorio.

En su repositorio de GitHub, vaya a la pestaña Acciones.
En el panel Acciones, seleccione Nuevo flujo de trabajo.
En la página Choose a workflow (Elegir un flujo de trabajo), puede elegir plantillas precompiladas para usarlas. Vamos a crear nuestro propio flujo de trabajo para este tutorial, así que seleccione Set up a workflow yourself (Configurar un flujo de trabajo personalmente).
GitHub creará un archivo de flujo de trabajo automáticamente. Observe que está en el directorio .github/workflows/. Asigne un nombre descriptivo al nuevo archivo, como dps-tutorial.yml.
Agregue el parámetro name para asignar un nombre al flujo de trabajo.
```
name: DPS Tutorial
```
Agregue el parámetro on.workflow_dispatch. El parámetro on define cuándo se ejecutará un flujo de trabajo. El parámetro workflow_dispatch indica que queremos desencadenar el flujo de trabajo manualmente. Con este parámetro, podríamos definir el elemento inputs que se pasaría al flujo de trabajo en cada ejecución, pero no los usaremos en este tutorial.
```
on: workflow_dispatch
```
Defina las variables de entorno de los recursos que vamos a crear en el flujo de trabajo. Estas variables estarán disponibles en todos los trabajos del flujo de trabajo. También puede definir variables de entorno para trabajos individuales o para pasos individuales dentro de trabajos.

Reemplace los valores de los marcadores de posición por sus propios valores. Asegúrese de especificar el mismo grupo de recursos al que tiene acceso la entidad de servicio.
```
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 variables de entorno para los secretos que creamos en la sección anterior.

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

Agregue el parámetro jobs al archivo de flujo de trabajo.
```
jobs:
```

Defina el primer trabajo del flujo de trabajo; a este trabajo lo llamaremos provision. Este trabajo aprovisiona las instancias de IoT Hub y 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 obtener más información sobre los comandos que se ejecutan en este trabajo, consulte:

Defina un trabajo configure para configurar las instancias de IoT Hub y DPS. Observe que este trabajo usa el parámetro needs, lo que significa que el trabajo configure no se ejecutará hasta que el trabajo que figura termine de ejecutarse correctamente.
```
  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 obtener más información sobre los comandos que se ejecutan en este trabajo, consulte:
- az iot dps linked-hub create
Defina un trabajo llamado register, que creará una inscripción individual y luego la usará para registrar un dispositivo en 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   
```
Nota:

Este trabajo y otros usan el parámetro --auth-type login en algunos comandos para indicar que la operación debe usar la entidad de servicio de la sesión actual de Microsoft Entra. La alternativa, --auth-type key, no requiere la configuración de la entidad de servicio, pero es menos segura.

Para obtener más información sobre los comandos que se ejecutan en este trabajo, consulte:
- az iot dps enrollment create
- az iot device registration create

Defina un trabajo simulate para simular un dispositivo IoT que se conectará al centro de IoT y enviará mensajes de telemetría de ejemplo.

  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 obtener más información sobre los comandos que se ejecutan en este trabajo, consulte:

az iot device simulate

Defina un trabajo monitor para supervisar el punto de conexión de IoT Hub en busca de eventos y vigilar los mensajes procedentes del dispositivo simulado. Observe que los trabajos simulate y monitor definen el trabajo register en sus correspondientes parámetros needs. Esta configuración significa que, una vez que el trabajo register se complete correctamente, ambos trabajos se ejecutarán en 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 obtener más información sobre los comandos que se ejecutan en este trabajo, consulte:
- az iot hub monitor-events

El archivo de flujo de trabajo completo debe tener un aspecto similar al de este ejemplo, con su información reemplazando los valores de marcador de posición en las variables de entorno:

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

Guarde y confirme este nuevo archivo y envíelo a su repositorio de GitHub.

3. Ejecución del flujo de trabajo

Vaya a la pestaña Acciones en su repositorio de GitHub.
En el panel Acciones, seleccione DPS Tutorial (que es el nombre que definimos en el archivo de flujo de trabajo) y, a continuación, seleccione el cuadro desplegable Ejecutar flujo de trabajo.
Cambie la rama si creó el flujo de trabajo en una rama distinta a la rama principal y, a continuación, seleccione Ejecutar flujo de trabajo.
Aparece una nueva ejecución de flujo de trabajo en curso. Seleccione el nombre para ver detalles de la ejecución.
En el resumen del flujo de trabajo, puede ver cómo comienza y acaba cada trabajo. Seleccione un nombre de trabajo cualquiera para ver sus detalles correspondientes. El trabajo de dispositivo simulado se ejecuta durante cinco minutos y envía telemetría a IoT Hub. Durante este tiempo, seleccione el trabajo simulate para inspeccionar los mensajes enviados desde el dispositivo y el trabajo monitor para ver los mensajes recibidos por IoT Hub.
Cuando todos los trabajos se hayan completado correctamente, deberían aparecer marcas de verificación verdes en cada uno de ellos.

Limpieza de recursos

Si no va a seguir usando los recursos creados en este tutorial, elimínelos con los siguientes pasos:

Uso de la CLI de Azure:

Acceda a los recursos del grupo de recursos.

az resource list --resource-group <RESOURCE_GROUP_NAME>

Para eliminar recursos individuales, use el identificador de recurso.

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

Si desea eliminar todo el grupo de recursos y todos los recursos que contiene, ejecute el siguiente comando:
```
az group delete --resource-group <RESOURCE_GROUP_NAME>
```

Utilice Azure Portal:

En Azure Portal, vaya al grupo de recursos donde creó los recursos en cuestión.
Puede eliminar todo el grupo de recursos o seleccionar los recursos concretos que quiera quitar. A continuación, seleccione Eliminar.

Pasos siguientes

Sepa cómo aprovisionar instancias de DPS con otras herramientas de automatización.

Configuración de DPS con Bicep

Compartir a través de