Inicio rápido: Implementación de un registro conectado en un dispositivo con IoT Edge

Artículo
10/31/2023

En este inicio rápido, se usa la CLI de Azure para implementar un registro conectado como un módulo en un dispositivo con Azure IoT Edge. El dispositivo con IoT Edge puede a la instancia de Azure Container Registry primaria en la nube.

Para obtener información general sobre el uso de un registro conectado con IoT Edge, consulte Uso de un registro conectado con Azure IoT Edge. Este escenario corresponde a un dispositivo en la capa superior de una jerarquía de IoT Edge.

Requisitos previos

Use el entorno de Bash en Azure Cloud Shell. Para más información, consulte Inicio rápido para 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. Para más información, vea Ejecución de la CLI de Azure en un contenedor de Docker.
- Si usa una instalación local, inicie sesión en la CLI de Azure mediante el comando az login. Siga los pasos que se muestran en el terminal para completar el proceso de autenticación. Para ver otras opciones de inicio de sesión, consulte Inicio de sesión con la CLI de Azure.
- En caso de que se le solicite, instale las extensiones de la CLI de Azure la primera vez que la use. Para más información sobre las extensiones, consulte Uso de extensiones con la CLI de Azure.
- 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.

Azure IoT Hub y dispositivo con IoT Edge. Para ver los pasos de implementación, consulte Inicio rápido: Implementación del primer módulo con IoT Edge en un dispositivo Linux virtual.

Importante

Para obtener acceso posteriormente a los módulos implementados en el dispositivo con IoT Edge, asegúrese de abrir los puertos 8000, 5671 y 8883 en el dispositivo. Para conocer los pasos de configuración, consulte Apertura de puertos en una máquina virtual con Azure Portal.
Recurso del registro conectado en Azure. Para conocer los pasos de implementación, consulte las guías de inicio rápido mediante la CLI de Azure o Azure Portal.
- En este escenario se puede usar un registro conectado en los modos ReadWrite o ReadOnly.
- En los comandos de este artículo, el nombre del registro conectado se almacena en la variable de entorno CONNECTED_REGISTRY_RW.

Importación de imágenes en el registro en la nube

Importe las siguientes imágenes de contenedor en el registro en la nube mediante el comando az acr import. Omita este paso si ya ha importado estas imágenes.

Imagen de registro conectado

Para admitir escenarios de IoT Edge, la imagen de contenedor para el entorno de ejecución del registro conectado debe estar disponible en la instancia privada de Azure Container Registry. Use el comando az acr import para importar la imagen del registro conectado en el registro privado.

# Use the REGISTRY_NAME variable in the following Azure CLI commands to identify the registry
REGISTRY_NAME=<container-registry-name>

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/acr/connected-registry:0.8.0

IoT Edge e imágenes del proxy de API

Para admitir el registro conectado en IoT Edge anidado, debe implementar módulos para IoT Edge y el proxy de API. Importe estas imágenes en el registro privado.

El módulo del proxy de API de IoT Edge permite que un dispositivo IoT Edge exponga varios servicios mediante el protocolo HTTPS en el mismo puerto, como 443.

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-agent:1.2.4

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-hub:1.2.4

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-api-proxy:1.1.2

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/azureiotedge-diagnostics:1.2.4

Imagen de Hola mundo

Para probar el registro conectado, importe la imagen hello-world. Este repositorio se sincronizará con el registro conectado y lo extraerán los clientes del registro conectado.

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/hello-world:1.1.2

Recuperación de la configuración del Registro conectado

Antes de implementar el registro conectado en el dispositivo con IoT Edge, es preciso recuperar la configuración del recurso del registro conectado en Azure.

Use el comando az acr connected-registry get-settings para obtener la información de configuración necesaria para instalar un registro conectado. En el ejemplo siguiente se especifica HTTPS como protocolo primario. Este protocolo es necesario cuando el registro primario es un registro en la nube.

az acr connected-registry get-settings \
  --registry $REGISTRY_NAME \
  --name $CONNECTED_REGISTRY_RW \
  --parent-protocol https

De forma predeterminada, la información de la configuración no incluye la contraseña del token de sincronización, que también es necesaria para implementar el registro conectado. Opcionalmente, genere una de las contraseñas pasando los parámetros --generate-password 1 o generate-password 2. Guarde la contraseña generada en una ubicación segura. Recuerde que no podrá recuperarla de nuevo.

Advertencia

Al volver a generar una contraseña, se rotan las credenciales del token de sincronización. Si configuró un dispositivo con la contraseña anterior, es preciso que actualice la configuración.

La salida del comando incluye la cadena de conexión del registro y la configuración relacionada. En la salida de ejemplo siguiente, se muestra la cadena de conexión del registro conectado llamado myconnectedregistry con el registro primario contosoregistry:

{
  "ACR_REGISTRY_CONNECTION_STRING": "ConnectedRegistryName=myconnectedregistry;SyncTokenName=myconnectedregistry-sync-token;SyncTokenPassword=xxxxxxxxxxxxxxxx;ParentGatewayEndpoint=contosoregistry.eastus.data.azurecr.io;ParentEndpointProtocol=https"
}

Configuración de un manifiesto de implementación para IoT Edge

Un manifiesto de implementación es un documento JSON que describe los módulos que se implementan en el dispositivo con IoT Edge. Para más información, consulte Descripción de cómo se pueden utilizar, configurar y reutilizar los módulos de IoT Edge.

Para implementar el registro conectado y los módulos de proxy de API mediante el CLI de Azure, guarde el siguiente manifiesto de implementación localmente en forma de archivo manifest.json. Usará la ruta de acceso al archivo en la sección siguiente, al ejecutar el comando para aplicar la configuración al dispositivo.

Configuración del módulo de registro conectado

Use las credenciales del token y la cadena de conexión de las secciones anteriores para actualizar los valores JSON pertinentes en el nodo env.

Las siguientes variables de entorno son opcionales en el nodo env:

Variable	Descripción
`ACR_REGISTRY_LOGIN_SERVER`	Especifica un nombre de host único o un FQDN. Si se utiliza, el registro conectado solo acepta las solicitudes realizadas a este valor de servidor de inicio de sesión. Si no se proporciona ningún valor, se puede acceder al registro conectado con cualquier valor de servidor de inicio de sesión.
`ACR_REGISTRY_CERTIFICATE_VOLUME`	Si el registro conectado va a ser accesible mediante HTTPS, apunta al volumen en el que se almacenan los certificados HTTPS. Si no se establece, la ubicación predeterminada es `/var/acr/certs`.
`ACR_REGISTRY_DATA_VOLUME`	Sobrescribe la ubicación predeterminada `/var/acr/data` en la que el registro conectado almacenará las imágenes. Esta ubicación debe coincidir con el enlace de volumen del contenedor.

Importante

Si el registro conectado escucha en un puerto diferente del 80 y el 443, el valor de ACR_REGISTRY_LOGIN_SERVER (si se especifica) debe incluir el puerto. Ejemplo: 192.168.0.100:8080.

Se debe establecer un enlace HostPort para el registro conectado si no se usa el módulo de proxy de API. Ejemplo:

 "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"],\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"8080\"}]}}}"

Configuración del módulo de proxy de API

El proxy de API escuchará en el puerto 8000 configurado como NGINX_DEFAULT_PORT. Para más información sobre la configuración del proxy de API, consulte el repositorio de GitHub de IoT Edge.

{
    "modulesContent": {
        "$edgeAgent": {
            "properties.desired": {
                "modules": {
                    "connected-registry": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/acr/connected-registry:0.8.0",
                            "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/azureuser/connected-registry:/var/acr/data\"]}}"
                        },
                        "type": "docker",
                        "env": {
                            "ACR_REGISTRY_CONNECTION_STRING": {
                                "value": "ConnectedRegistryName=<REPLACE_WITH_CONNECTED_REGISTRY_NAME>;SyncTokenName=<REPLACE_WITH_SYNC_TOKEN_NAME>;SyncTokenPassword=REPLACE_WITH_SYNC_TOKEN_PASSWORD;ParentGatewayEndpoint=<REPLACE_WITH_CLOUD_REGISTRY_NAME>.<REPLACE_WITH_CLOUD_REGISTRY_REGION>.data.azurecr.io;ParentEndpointProtocol=https"
                            }
                        },
                        "status": "running",
                        "restartPolicy": "always",
                        "version": "1.0"
                    },
                    "IoTEdgeAPIProxy": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-api-proxy:1.1.2",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8000/tcp\":[{\"HostPort\":\"8000\"}]}}}"
                        },
                        "type": "docker",
                        "env": {
                            "NGINX_DEFAULT_PORT": {
                                "value": "8000"
                            },
                            "CONNECTED_ACR_ROUTE_ADDRESS": {
                                "value": "connected-registry:8080"
                            },
                            "BLOB_UPLOAD_ROUTE_ADDRESS": {
                                "value": "AzureBlobStorageonIoTEdge:11002"
                            }
                        },
                        "status": "running",
                        "restartPolicy": "always",
                        "version": "1.0"
                    }
                },
                "runtime": {
                    "settings": {
                        "minDockerVersion": "v1.25",
                        "registryCredentials": {
                            "cloudregistry": {
                                "address": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io",
                                "password": "<REPLACE_WITH_SYNC_TOKEN_PASSWORD>",
                                "username": "<REPLACE_WITH_SYNC_TOKEN_NAME>"
                            }
                        }
                    },
                    "type": "docker"
                },
                "schemaVersion": "1.1",
                "systemModules": {
                    "edgeAgent": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-agent:1.2.4",
                            "createOptions": ""
                        },
                        "type": "docker",
                        "env": {
                            "SendRuntimeQualityTelemetry": {
                                "value": "false"
                            }
                        }
                    },
                    "edgeHub": {
                        "settings": {
                            "image": "<REPLACE_WITH_CLOUD_REGISTRY_NAME>.azurecr.io/azureiotedge-hub:1.2.4",
                            "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
                        },
                        "type": "docker",
                        "status": "running",
                        "restartPolicy": "always"
                    }
                }
            }
        },
        "$edgeHub": {
            "properties.desired": {
                "routes": {
                    "route": "FROM /messages/* INTO $upstream"
                },
                "schemaVersion": "1.1",
                "storeAndForwardConfiguration": {
                    "timeToLiveSecs": 7200
                }
            }
        }
    }
}

Implementación del registro conectado y los módulos de proxy de API en IoT Edge

Use el siguiente comando para implementar el registro conectado y los módulos de proxy de API en el dispositivo con IoT Edge, mediante el manifiesto de implementación creado en la sección anterior. Especifique el identificador del dispositivo de la capa superior de IoT Edge y el nombre de la instancia de IoT Hub donde se indica.

# Set the IOT_EDGE_TOP_LAYER_DEVICE_ID and IOT_HUB_NAME environment variables for use in the following Azure CLI command
IOT_EDGE_TOP_LAYER_DEVICE_ID=<device-id>
IOT_HUB_NAME=<hub-name>

az iot edge set-modules \
  --device-id $IOT_EDGE_TOP_LAYER_DEVICE_ID \
  --hub-name $IOT_HUB_NAME \
  --content manifest.json

Para más detalles, consulte Implementación de módulos de Azure IoT Edge con la CLI de Azure.

Para comprobar el estado del registro conectado, use el siguiente comando az acr connected-registry show. El nombre del registro conectado es el valor de $CONNECTED_REGISTRY_RW.

az acr connected-registry show \
  --registry $REGISTRY_NAME \
  --name $CONNECTED_REGISTRY_RW \
  --output table

Después de una implementación correcta, el registro conectado muestra el estado Online.

Pasos siguientes

En este inicio rápido, ha aprendido a implementar un registro conectado en un dispositivo con IoT Edge. En las siguientes guías aprenderá a extraer imágenes del registro conectado recién implementado o a implementar el registro conectado en dispositivos con IoT Edge anidados.

Extracción de imágenes de un registro conectado

Tutorial: Implementación de un registro conectado en dispositivos con IoT Edge anidados