Início Rápido: Implementar um registo ligado num dispositivo IoT Edge

Artigo
10/31/2023

Neste início rápido, vai utilizar a CLI do Azure para implementar um registo ligado como um módulo num dispositivo IoT Edge do Azure. O dispositivo IoT Edge pode aceder ao registo de contentor do Azure principal na cloud.

Para obter uma descrição geral da utilização de um registo ligado com IoT Edge, veja Utilizar o registo ligado com o Azure IoT Edge. Este cenário corresponde a um dispositivo na camada superior de uma hierarquia IoT Edge.

Pré-requisitos

Utilize o ambiente bash no Azure Cloud Shell. Para obter mais informações, veja Início Rápido do Bash no Azure Cloud Shell.
Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, veja Como executar a CLI do Azure num contentor do Docker.
- Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de início de sessão, veja Iniciar sessão com a CLI do Azure.
- Quando lhe for pedido, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.
- 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.

Hub IoT do Azure e IoT Edge dispositivo. Para obter os passos de implementação, veja Início Rápido: Implementar o primeiro módulo IoT Edge num dispositivo Linux virtual.

Importante

Para aceder mais tarde aos módulos implementados no dispositivo IoT Edge, certifique-se de que abre as portas 8000, 5671 e 8883 no dispositivo. Para obter os passos de configuração, veja Como abrir portas para uma máquina virtual com o portal do Azure.
Recurso de registo ligado no Azure. Para obter os passos de implementação, veja inícios rápidos com a CLI do Azure ou portal do Azure.
- Neste cenário, pode ser utilizado um registo ligado em ambos ou ReadWriteReadOnly no modo.
- Nos comandos neste artigo, o nome do registo ligado é armazenado na variável de ambiente CONNECTED_REGISTRY_RW.

Importar imagens para o seu registo na cloud

Importe as seguintes imagens de contentor para o seu registo na cloud com o comando az acr import . Ignore este passo se já tiver importado estas imagens.

Imagem do registo ligado

Para suportar cenários de IoT Edge aninhados, a imagem de contentor do runtime de registo ligado tem de estar disponível no seu registo de contentor privado do Azure. Utilize o comando az acr import para importar a imagem do registo ligado para o seu registo 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 imagens de proxy de API

Para suportar o registo ligado em IoT Edge aninhadas, tem de implementar módulos para o IoT Edge e o proxy de API. Importe estas imagens para o seu registo privado.

O módulo de proxy da API IoT Edge permite que um dispositivo IoT Edge exponha vários serviços através do protocolo HTTPS na mesma porta, 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

Imagem hello-world

Para testar o registo ligado, importe a hello-world imagem. Este repositório será sincronizado com o registo ligado e solicitado pelos clientes de registo ligados.

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

Obter a configuração do registo ligado

Antes de implementar o registo ligado no dispositivo IoT Edge, tem de obter as definições de configuração do recurso de registo ligado no Azure.

Utilize o comando az acr connected-registry get-settings para obter as informações de definições necessárias para instalar um registo ligado. O exemplo seguinte especifica HTTPS como o protocolo principal. Este protocolo é necessário quando o registo principal é um registo na cloud.

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

Por predefinição, as informações de definições não incluem a palavra-passe do token de sincronização , que também é necessária para implementar o registo ligado. Opcionalmente, gere uma das palavras-passe ao transmitir o --generate-password 1 parâmetro ou generate-password 2 . Guarde a palavra-passe gerada numa localização segura. Não é possível recuperá-la novamente.

Aviso

Regenerar uma palavra-passe roda as credenciais do token de sincronização. Se tiver configurado um dispositivo com a palavra-passe anterior, terá de atualizar a configuração.

A saída do comando inclui a cadeia de ligação do registo e as definições relacionadas. O resultado de exemplo seguinte mostra a cadeia de ligação do registo ligado com o nome myconnectedregistry com o registo principal contosoregistry:

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

Configurar um manifesto de implementação para IoT Edge

Um manifesto de implementação é um documento JSON que descreve os módulos a implementar no dispositivo IoT Edge. Para obter mais informações, veja Compreender como IoT Edge módulos podem ser utilizados, configurados e reutilizados.

Para implementar os módulos de registo ligado e proxy de API com a CLI do Azure, guarde o seguinte manifesto de implementação localmente como um manifest.json ficheiro. Irá utilizar o caminho do ficheiro na secção seguinte quando executar o comando para aplicar a configuração ao seu dispositivo.

Definições do módulo de registo ligado

Utilize as credenciais do token e a cadeia de ligação das secções anteriores para atualizar os valores JSON relevantes no env nó.

As seguintes variáveis de ambiente são opcionais no env nó:

Variável	Descrição
`ACR_REGISTRY_LOGIN_SERVER`	Especifica um nome de anfitrião ou FQDN exclusivo. Se for utilizado, o registo ligado só aceita pedidos feitos a este valor de servidor de início de sessão. Se não for fornecido nenhum valor, o registo ligado pode ser acedido com qualquer valor de servidor de início de sessão.
`ACR_REGISTRY_CERTIFICATE_VOLUME`	Se o seu registo ligado estiver acessível através de HTTPS, aponta para o volume onde os certificados HTTPS estão armazenados. Se não estiver definida, a localização predefinida é `/var/acr/certs`.
`ACR_REGISTRY_DATA_VOLUME`	Substitui a localização `/var/acr/data` predefinida onde as imagens serão armazenadas pelo registo ligado. Esta localização tem de corresponder ao enlace de volume do contentor.

Importante

Se o registo ligado escutar numa porta diferente de 80 e 443, o ACR_REGISTRY_LOGIN_SERVER valor (se especificado) tem de incluir a porta. Exemplo: 192.168.0.100:8080.

Um HostPort enlace para o registo ligado deve ser definido se o módulo de proxy de API não for utilizado. Exemplo:

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

Definições do módulo de proxy de API

O proxy de API escutará na porta 8000 configurada como NGINX_DEFAULT_PORT. Para obter mais informações sobre as definições de proxy de API, veja o repositório IoT Edge GitHub.

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

Implementar o registo ligado e os módulos de proxy de API no IoT Edge

Utilize o seguinte comando para implementar os módulos de registo ligado e proxy de API no dispositivo IoT Edge, com o manifesto de implementação criado na secção anterior. Indique o ID do dispositivo de camada superior IoT Edge e o nome do Hub IoT indicado.

# 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 obter detalhes, veja Deploy Azure IoT Edge modules with Azure CLI (Implementar módulos do Azure IoT Edge com a CLI do Azure).

Para verificar o estado do registo ligado, utilize o seguinte comando az acr connected-registry show . O nome do registo ligado é o valor de $CONNECTED_REGISTRY_RW.

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

Após a implementação com êxito, o registo ligado mostra o estado .Online

Passos seguintes

Neste início rápido, aprendeu a implementar um registo ligado num dispositivo IoT Edge. Avance para os guias seguintes para saber como extrair imagens do registo ligado recentemente implementado ou implementar o registo ligado em dispositivos aninhados IoT Edge.

Extrair imagens de um registo ligado

Tutorial: Implementar o registo ligado em dispositivos IoT Edge aninhados

Share via