Início Rápido: Implantar um registro conectado em um dispositivo IoT Edge (a ser preterido)

Artigo
10/16/2024

Neste guia de início rápido, você usará a CLI do Azure para implantar um Registro conectado como um módulo em um dispositivo Azure IoT Edge. O dispositivo IoT Edge pode acessar o registro de contêiner do Azure pai na nuvem.

Para obter uma visão geral do uso de um Registro conectado com o IoT Edge, confira Usar o Registro conectado com o Azure IoT Edge. Esse cenário corresponde a um dispositivo na camada superior de uma hierarquia do IoT Edge.

Pré-requisitos

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Dispositivo IoT Edge e Hub IoT do Azure. Para ver as etapas de implantação, confira Início Rápido: Implantar seu primeiro módulo do IoT Edge em um dispositivo Linux virtual.

Importante

Para acesso posterior aos módulos implantados no dispositivo IoT Edge, abra as portas 8000, 5671 e 8883 no dispositivo. Para conhecer as etapas de configuração, confira Como abrir as portas de uma máquina virtual com o portal do Azure.
Recurso de Registro conectado no Azure. Para as etapas de implantação, confira os guias de início rápido usando a CLI do Azure ou o portal do Azure.
- Um Registro conectado no modo ReadWrite ou ReadOnly pode ser usado nesse cenário.
- Nos comandos neste artigo, o nome do Registro conectado é armazenado na variável de ambiente CONNECTED_REGISTRY_RW.

Importar imagens para o registro na nuvem

Importe as seguintes imagens de contêiner para o registro na nuvem usando o comando az acr import. Ignore esta etapa se você já importou essas imagens.

Imagem do registro conectado

Para dar suporte a cenários de IoT Edge aninhados, a imagem de contêiner para o runtime do registro conectado deve estar disponível no registro de contêiner privado do Azure. Use o comando az acr import para importar a imagem de registro conectado para o 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

Imagens do proxy de API e IoT Edge

Para dar suporte ao registro conectado no IoT Edge aninhado, é necessário implantar módulos para o proxy de API e IoT Edge. Importe essas imagens para o registro privado.

O módulo de proxy de API do IoT Edge permite que um dispositivo de IoT Edge exponha vários serviços usando o 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 de olá, mundo

Para testar o registro conectado, importe a imagem hello-world. Esse repositório será sincronizado com o registro conectado e enviado para os clientes do registro conectado.

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

Recuperar a configuração do registro conectado

Para implantar cada Registro conectado no dispositivo IoT Edge, recupere as definições de configuração do recurso de Registro conectado no Azure.

Use o comando az acr connected-registry get-settings para obter as informações de configurações necessárias para instalar um Registro conectado. O exemplo a seguir especifica HTTPS como o protocolo pai. Esse protocolo é necessário quando o Registro pai é um Registro de nuvem.

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

Por padrão, as informações de configurações não incluem a senha do token de sincronização, que também é necessária para implantar o Registro conectado. Opcionalmente, gere uma das senhas passando o parâmetro --generate-password 1 ou generate-password 2. Salve a senha gerada em um local seguro. Ela não poderá ser recuperada novamente.

Aviso

A regeneração de uma senha faz a rotação das credenciais do token de sincronização. Se você tiver configurado um dispositivo usando a senha anterior, precisará atualizar a configuração.

A saída do comando inclui a cadeia de conexão do Registro e as configurações relacionadas. A seguinte saída de exemplo mostra a cadeia de conexão para o Registro conectado chamado myconnectedregistry com o registro pai 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 implantação para o IoT Edge

Um manifesto de implantação é um documento JSON que descreve quais módulo você deve implantar no dispositivo IoT Edge. Para obter mais informações, confira Noções básicas sobre como os módulos do IoT Edge podem ser usados, configurados e reutilizados.

Para implantar o Registro conectado e os módulos de proxy de API usando a CLI do Azure, salve o manifesto de implantação a seguir localmente como um arquivo manifest.json. Você usará o caminho do arquivo na próxima seção quando executar o comando para aplicar a configuração ao dispositivo.

Configurações do módulo do Registro conectado

Use as credenciais de token e a cadeia de conexão das seções anteriores para atualizar os valores JSON relevantes no nó env.

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

Variável	Descrição
`ACR_REGISTRY_LOGIN_SERVER`	Especifica um nome de host ou FQDN exclusivo. Se usado, o Registro conectado só aceita solicitações feitas a esse valor de servidor de logon. Se nenhum valor for fornecido, o Registro conectado poderá ser acessado com qualquer valor de servidor de logon.
`ACR_REGISTRY_CERTIFICATE_VOLUME`	Se o Registro conectado for acessível por HTTPS, apontará para o volume em que os certificados HTTPS estão armazenados. Se não estiver definido, o local padrão será `/var/acr/certs`.
`ACR_REGISTRY_DATA_VOLUME`	Substitui o local padrão `/var/acr/data` em que as imagens serão armazenadas pelo Registro conectado. Esse local precisa corresponder à associação de volume para o contêiner.

Importante

Se o Registro conectado escutar em uma porta diferente de 80 e 443, o valor ACR_REGISTRY_LOGIN_SERVER (se especificado) precisará incluir a porta. Exemplo: 192.168.0.100:8080.

Uma associação HostPort para o Registro conectado deverá ser definida se o módulo de proxy de API não for usado. Exemplo:

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

Configuraçõ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 configurações de proxy de API, confira o repositório GitHub do 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
                }
            }
        }
    }
}

Implantar o Registro conectado e os módulos de proxy de API no IoT Edge

Use o comando a seguir para implantar o Registro conectado e os módulos de proxy de API no dispositivo IoT Edge, usando o manifesto de implantação criado na seção anterior. Forneça a ID do dispositivo IoT Edge de camada superior e o nome do Hub IoT onde 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 os detalhes, confira Implantar os módulos do Azure IoT Edge com a CLI do Azure.

Para verificar o status do Registro conectado, use o comando az acr connected-registry show a seguir. O nome do Registro conectado é o valor de $CONNECTED_REGISTRY_RW.

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

Após a implantação bem-sucedida, o Registro conectado mostra um status de Online.

Próximas etapas

Neste guia de início rápido, você aprendeu a implantar um Registro conectado em um dispositivo IoT Edge. Prossiga para os próximos guias para saber como efetuar pull de imagens do Registro conectado recém-implantado ou implantar o Registro conectado em dispositivos IoT Edge aninhados.

Efetuar pull de imagens de um Registro conectado

Tutorial: Implantar o Registro conectado em dispositivos IoT Edge aninhados

Compartilhar via