Tutorial: Criar uma hierarquia de dispositivos IoT Edge usando IoT Edge para Linux no Windows

Aplica-se a: IoT Edge 1.5

Implemente nós do Azure IoT Edge em redes organizadas em camadas hierárquicas. Cada camada em uma hierarquia é um dispositivo de gateway que processa as mensagens e as solicitações de dispositivos na camada abaixo dele. Essa configuração também é conhecida como borda aninhada.

Estruturar uma hierarquia de dispositivos para que apenas a camada superior tenha conectividade com a nuvem e as camadas inferiores possam se comunicar apenas com camadas norte e sul adjacentes. Essa camada de rede é a base da maioria das redes industriais, que seguem o padrão ISA-95.

Este tutorial mostra como criar uma hierarquia de dispositivos IoT Edge usando IoT Edge para Linux no Windows, implantar IoT Edge contêineres de runtime em seus dispositivos e configurar seus dispositivos localmente. Neste tutorial, você realizará as seguintes tarefas:

Neste tutorial, as seguintes camadas de rede são definidas:

• Top layer: IoT Edge dispositivos nessa camada podem se conectar diretamente à nuvem.

• Camadas inferiores: Dispositivos IoT Edge nas camadas inferiores à camada superior não podem se conectar diretamente à nuvem. Eles precisam passar por um ou mais dispositivos intermediários IoT Edge para enviar e receber dados.

Este tutorial usa uma hierarquia de dois dispositivos para simplificar. O dispositivo de nível superior representa um dispositivo no nível superior da hierarquia que pode se conectar diretamente à nuvem. Esse dispositivo é chamado de dispositivo pai. O dispositivo de nível inferior representa um dispositivo no nível inferior da hierarquia que não pode se conectar diretamente à nuvem. Adicione mais dispositivos para representar seu ambiente de produção conforme necessário. Dispositivos em camadas inferiores são chamados de dispositivos subordinados.

Pré-requisitos

Para criar uma hierarquia de dispositivos IoT Edge, você precisa:

• Um shell bash em Azure Cloud Shell usando Azure CLI v2.3.1 com a extensão Azure IoT v0.10.6 ou superior instalada. Este tutorial usa Azure Cloud Shell. Para verificar as versões atuais dos módulos e extensões Azure CLI, execute az version.
• Dois dispositivos Windows executando Azure IoT Edge para Linux no Windows. Implante ambos os dispositivos usando um comutador virtual externo.

• Uma conta Azure com uma assinatura válida. Se você não tiver uma assinatura Azure, crie uma conta free antes de começar.
• Uma camada gratuita ou padrão IoT Hub em Azure.
• Verifique se as seguintes portas estão abertas de entrada para todos os dispositivos, exceto o dispositivo de camada mais baixa: 443, 5671 e 8883:
  • 443: usado entre hubs de borda pai e filho para chamadas à API REST e pull das imagens de contêiner do Docker.
  • 5671, 8883: Usado para AMQP e MQTT.

Criar sua hierarquia de dispositivos IoT Edge

Dispositivos IoT Edge compõem as camadas da hierarquia. Este tutorial cria uma hierarquia de dois dispositivos IoT Edge: o dispositivo de camada top e o dispositivo de camada lower. Você pode criar mais dispositivos downstream conforme necessário.

Para criar e configurar sua hierarquia de dispositivos IoT Edge, use o comando az iot edge devices create Azure CLI. Essa ferramenta simplifica a configuração da hierarquia automatizando e condensando várias etapas:

• Cria dispositivos em seu IoT Hub
• Define as relações pai-filho para autorizar a comunicação entre os dispositivos
• Aplica o manifesto de implantação a cada dispositivo
• Gera uma cadeia de certificados para cada dispositivo de modo a estabelecer uma comunicação segura entre eles
• Gera arquivos de configuração para cada dispositivo

Criar uma configuração de dispositivo

Você cria um grupo de dispositivos de borda aninhados que contém um dispositivo pai com um dispositivo filho. Neste tutorial, usamos amostras de manifestos de implantação básicos. Para outros exemplos de cenário, examine os modelos de exemplo de configuração.

1. Antes de usar o comando az iot edge devices create, você precisa definir o manifesto de implantação para os dispositivos dos níveis superior e inferior. Baixe o arquivo de exemplo deploymentTopLayer.json no computador local.

   O manifesto de implantação do dispositivo de camada superior define o módulo de proxy de API do IoT Edge e declara a rota do dispositivo de camada inferior para o IoT Hub.

2. Baixe o arquivo de exemplo deploymentLowerLayer.json no computador local.

   O manifesto de implantação do dispositivo de nível inferior inclui o módulo de sensor de temperatura simulado e declara a rota para o dispositivo de nível superior. Você pode ver na seção systemModules que os módulos de runtime estão definidos para efetuar pull a partir do $upstream:443, em vez do mcr.microsoft.com. O dispositivo da camada inferior envia solicitações de imagem do Docker ao módulo API Proxy do IoT Edge na porta 443, pois não pode extrair diretamente as imagens da nuvem. O outro módulo implantado no dispositivo de camada inferior, o módulo do Sensor de temperatura simulado, também faz sua solicitação de imagem para $upstream:443.

   Para obter mais informações sobre como criar um manifesto de implantação de camada inferior, consulte Conectar dispositivos Azure IoT Edge para criar uma hierarquia.

3. No Azure Cloud Shell, use o comando Azure CLI az iot edge devices create para criar dispositivos no IoT Hub e pacotes de configuração para cada dispositivo na sua hierarquia. Substitua os espaços reservados pelos valores adequados:

   Espaço reservado	Descrição
   <nome do hub>	O nome do seu IoT Hub.
   <config-bundle-output-path>	O caminho da pasta na qual você deseja salvar os pacotes de configuração.
   <nome-do-dispositivo-mãe>	O nome da ID do dispositivo pai de nível superior.
   <manifesto de implantação principal>	O arquivo de manifesto da implantação do dispositivo pai.
   <parent-fqdn-or-ip>	Nome de domínio totalmente qualificado (FQDN) ou endereço IP do dispositivo pai.
   <nome-dispositivo-filho>	O nome da ID do dispositivo filho de nível inferior.
   <child-deployment-manifest>	O arquivo de manifesto de implantação do dispositivo filho.
   <child-fqdn-or-ip>	Nome de domínio totalmente qualificado (FQDN) ou endereço IP do dispositivo filho.

   az iot edge devices create \
      --hub-name <hub-name> \
      --output-path <config-bundle-output-path> \
      --default-edge-agent "mcr.microsoft.com/azureiotedge-agent:1.5" \
      --device id=<parent-device-name> \
         deployment=<parent-deployment-manifest> \
         hostname=<parent-fqdn-or-ip> \
      --device id=child-1 \
         parent=parent-1 \
         deployment=<child-deployment-manifest> \
         hostname=<child-fqdn-or-ip>
   

   Por exemplo, o comando a seguir cria uma hierarquia de dois dispositivos IoT Edge em IoT Hub. Um dispositivo de nível superior chamado parent-1 e um dispositivo de nível inferior chamado child-1.* O comando salva os pacotes de configuração para cada dispositivo no diretório de saída. O comando também gera certificados de teste autoassinados e os inclui no pacote de configuração. Os pacotes de configuração são instalados em cada dispositivo usando um script de instalação.

   az iot edge devices create \
      --hub-name my-iot-hub \
      --output-path ./output \
      --default-edge-agent "mcr.microsoft.com/azureiotedge-agent:1.5" \
      --device id=parent-1 \
         deployment=./deploymentTopLayer.json \
         hostname=10.0.0.4 \
      --device id=child-1 \
         parent=parent-1 \
         deployment=./deploymentLowerLayer.json \
         hostname=10.1.0.4
   

Após executar o comando, você pode encontrar os pacotes de configuração do dispositivo no diretório de saída. Por exemplo:

PS C:\nested-edge\output> dir

   Directory: C:\nested-edge\output

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a---           4/10/2023  4:12 PM           7192 child-1.tgz
-a---           4/10/2023  4:12 PM           6851 parent-1.tgz

Você pode usar seus próprios certificados e chaves transmitidos como argumentos para o comando ou criar uma hierarquia de dispositivos mais complexa. Para obter mais informações sobre como criar dispositivos aninhados usando o comando az , confira az iot edge devices create. Se não estiver familiarizado com o modo como os certificados são usados em um cenário de gateway, confira a seção “certificado” do guia de instruções.

Neste tutorial, você usa argumentos embutidos para criar os dispositivos e pacotes de configuração. Você também pode usar um arquivo de configuração nos formatos YAML ou JSON. Para obter uma amostra de arquivo de configuração, confira o exemplo sample_devices_config.yaml.

Configurar o ambiente de runtime do IoT Edge

Além do provisionamento dos dispositivos, as etapas de configuração estabelecem uma comunicação confiável entre os dispositivos da hierarquia usando os certificados criados anteriormente. As etapas também começam a estabelecer uma estrutura de rede da hierarquia. O dispositivo de nível superior manterá a conectividade com a internet, permitindo que efetue um pull de imagens da nuvem para o respectivo runtime, enquanto os dispositivos de nível inferior serão roteados através do dispositivo de nível superior para acessar essas imagens.

Para configurar o IoT Edge runtime, você precisa aplicar os pacotes de configuração aos seus dispositivos. As configurações diferem um pouco entre um dispositivo de nível superior e um dispositivo de nível inferior, então tenha sempre em mente qual arquivo de configuração de dispositivo você está aplicando a cada dispositivo.

Cada dispositivo precisa do seu pacote de configuração correspondente. Você pode usar a unidade USB ou uma cópia de arquivo seguro para mover os pacotes de certificados para cada dispositivo. Você precisa copiar o pacote de configuração para o sistema operacional Windows host de cada dispositivo EFLOW e copiá-lo para a VM EFLOW.

Configuração de dispositivo de camada superior

1. Conecte-se ao dispositivo host Windows de nível superior e copie o arquivo parent-1.tgz para o dispositivo.

2. Inicie uma sessão com privilégios elevados do PowerShell usando Executar como Administrador.

3. Copie parent-1.tgz para a VM EFLOW.

   Copy-EflowVmFile -fromFile parent-1.tgz -toFile ~/ -pushFile
   

4. Conecte-se à máquina virtual EFLO

   Connect-EflowVm
   

5. Extraia o arquivo do pacote de configuração. Por exemplo, use o comando tar para extrair o arquivo parent-1 compactado:

   tar -xzf ./parent-1.tgz
   

6. Defina a permissão de execução para o script de instalação.

   chmod +x install.sh
   

7. Execute o script install.sh.

   sudo sh ./install.sh
   

8. Aplique as permissões de certificado corretas e reinicie o runtime do IoT Edge.

   sudo chmod -R 755 /etc/aziot/certificates/
   sudo iotedge system restart
   

9. Verifique se todos os serviços IoT Edge estão sendo executados corretamente.

   sudo iotedge system status
   

10. Por fim, adicione as regras de firewall apropriadas para habilitar a conectividade entre o dispositivo de camada inferior e o dispositivo de camada superior.

    sudo iptables -A INPUT -p tcp --dport 5671 -j ACCEPT
    sudo iptables -A INPUT -p tcp --dport 8883 -j ACCEPT
    sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
    sudo iptables -A INPUT -p icmp --icmp-type 8 -s 0/0 -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT
    sudo iptables-save | sudo tee /etc/systemd/scripts/ip4save
    

11. Execute a configuração e as verificações de conectividade nos dispositivos.

    sudo iotedge check
    

No dispositivo de camada superior, você deverá ver uma saída com várias avaliações de passagem. Você pode ver alguns avisos sobre políticas de logs e, dependendo de sua rede, políticas DNS.

Se você quiser ver mais de perto quais modificações estão sendo feitas no arquivo de configuração do dispositivo, consulte a configuração IoT Edge na seção de dispositivos do guia de instruções.

Configuração do dispositivo de camada superior

1. Conecte-se ao dispositivo host Windows de nível inferior e copie o arquivo child-1.tgz para o dispositivo.

2. Inicie uma sessão com privilégios elevados do PowerShell usando Executar como Administrador.

3. Copie child-1.tgz para a VM EFLOW.

   Copy-EflowVmFile -fromFile child-1.tgz -toFile ~/ -pushFile
   

4. Conecte-se à máquina virtual EFLO

   Connect-EflowVm
   

5. Extraia o arquivo do pacote de configuração. Por exemplo, use o comando tar para extrair o arquivo child-1 compactado:

   tar -xzf ./child-1.tgz
   

6. Defina a permissão de execução para o script de instalação.

   chmod +x install.sh
   

7. Execute o script install.sh.

   sudo sh ./install.sh
   

8. Aplique as permissões de certificado corretas e reinicie o runtime do IoT Edge.

   sudo chmod -R 755 /etc/aziot/certificates/
   sudo iotedge system restart
   

9. Verifique se todos os serviços IoT Edge estão sendo executados corretamente.

   sudo iotedge system status
   

10. Execute a configuração e as verificações de conectividade nos dispositivos. Para o dispositivo de camada inferior, a imagem de diagnóstico precisa ser passada manualmente no comando:

    sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:443/azureiotedge-diagnostics:1.5
    

Se tiver executado as etapas acima corretamente, você poderá verificar se os seus dispositivos estão configurados corretamente. Quanto estiver satisfeito com as configurações corretas em cada dispositivo, você estará pronto para prosseguir.

Implantação do módulo do dispositivo

A implantação do módulo para seus dispositivos foi realizada quando os dispositivos foram criados no IoT Hub. O comando az iot edge devices create aplicou os arquivos JSON de implantação para os dispositivos de níveis superior e inferior. Após essas implantações serem concluídas, o dispositivo de nível inferior usará o módulo de Proxy da API da IoT Edge para efetuar pull das imagens necessárias.

Além disso, além dos módulos de tempo de execução IoT Edge Agent e IoT Edge Hub, o dispositivo de camada superior recebe o módulo Docker Registry e o módulo Proxy de API do IoT Edge.

O módulo Docker registry aponta para um Azure Container Registry existente. Nesse caso, REGISTRY_PROXY_REMOTEURL aponta para o Microsoft Container Registry. Por padrão, o registro do Docker escuta a porta 5000.

O módulo Proxy de API do IoT Edge roteia solicitações HTTP para outros módulos, permitindo que dispositivos de camada inferior façam download de imagens de contêiner ou enviem blobs para armazenamento. Neste tutorial, ele se comunica na porta 443 e está configurado para enviar a rota de solicitações de pull da imagem de contêiner do Docker para o módulo do registro do Docker na porta 5000. Além disso, qualquer solicitação de upload do armazenamento de blobs é roteada para o módulo AzureBlobStorageonIoTEdge na porta 11002. Para obter mais informações sobre o módulo Proxy de API do IoT Edge e como configurá-lo, consulte o guia de instruções do módulo.

Para saber como criar uma implantação como esta no Portal do Azure ou no Azure Cloud Shell, consulte a seção de dispositivo de camada superior do guia passo a passo.

Exiba o status dos módulos com o seguinte comando:

az iot hub module-twin show --device-id <edge-device-id> --module-id '$edgeAgent' --hub-name <iot-hub-name> --query "properties.reported.[systemModules, modules]"

Este comando mostra todas as propriedades relatadas por edgeAgent. As propriedades úteis para monitorar o status do dispositivo incluem: status do runtime, hora de início do tempo de execução, hora de última saída do runtime e contagem de reinicialização do runtime.

Você também verá o status dos módulos no Azure portal. Vá para a seção Devices do IoT Hub para exibir seus dispositivos e módulos.

Exibir os dados gerados

O módulo Sensor de Temperatura Simulado que você enviou por push gera dados de ambiente de exemplo. Ele envia mensagens que incluem temperatura ambiente e umidade, temperatura do computador e pressão e um carimbo de data/hora.

Você também pode exibir essas mensagens usando Azure Cloud Shell:

az iot hub monitor-events -n <iot-hub-name> -d <lower-layer-device-name>

Por exemplo:

az iot hub monitor-events -n my-iot-hub -d child-1

{
    "event": {
        "origin": "child-1",
        "module": "simulatedTemperatureSensor",
        "interface": "",
        "component": "",
        "payload": "{\"machine\":{\"temperature\":104.29281270901808,\"pressure\":10.48905461241978},\"ambient\":{\"temperature\":21.086561171611102,\"humidity\":24},\"timeCreated\":\"2023-04-17T21:50:30.1082487Z\"}"
    }
}

Solução de problemas

Execute o comando iotedge check para verificar a configuração e solucionar os erros.

Você pode executar iotedge check em uma hierarquia aninhada, mesmo que os dispositivos de downstream não tenham acesso direto à Internet.

Quando você executa iotedge check por meio da camada inferior, o programa tenta efetuar pull da imagem do pai pela porta 443.

sudo iotedge check --diagnostics-image-name $upstream:443/azureiotedge-diagnostics:1.5

O valor de azureiotedge-diagnostics é extraído do registro de contêiner que está vinculado ao módulo do Registro. Este tutorial o define por padrão como https://mcr.microsoft.com:

Se você usar um registro de contêiner privado, verifique se todas as imagens (IoTEdgeAPIProxy, edgeAgent, edgeHub, sensor de temperatura simulado e diagnóstico) estão no registro de contêiner.

Se um dispositivo downstream tiver uma arquitetura de processador diferente do dispositivo pai, use a imagem de arquitetura apropriada. Use um registro conectado ou especifique a imagem correta para os módulos edgeAgent e edgeHub no arquivo config.toml do dispositivo downstream. Por exemplo, se o dispositivo pai for executado em uma arquitetura ARM32v7 e o dispositivo downstream for executado em uma arquitetura AMD64, especifique a marca de imagem de versão e arquitetura correspondente no arquivo config.toml do dispositivo downstream.

[agent.config]
image = "$upstream:443/azureiotedge-agent:1.5.15-linux-amd64"

"systemModules": {
   "edgeAgent": {
      "settings": {
            "image": "$upstream:443/azureiotedge-agent:1.5.15-linux-amd64"
      },
   },
   "edgeHub": {
      "settings": {
            "image": "$upstream:443/azureiotedge-hub:1.5.15-linux-amd64",
      }
   }
}

Limpar os recursos

Você pode excluir as configurações locais e os recursos Azure que você criou neste artigo para evitar encargos.

Para excluir os recursos:

1. Entre no portal Azure e selecione Resource groups.

2. Selecione o nome do grupo de recursos que contém seus recursos de teste IoT Edge.

3. Reveja a lista de recursos contidos no grupo de recursos. Se você deseja excluir todos eles, selecione Excluir grupo de recursos. Se quiser excluir apenas alguns, clique em cada recurso para excluí-los individualmente.

Próximas etapas

Neste tutorial, você configurou dois dispositivos IoT Edge como gateways e definiu um como o dispositivo pai do outro. Em seguida, você demonstrou como efetuar pull de uma imagem de contêiner para o dispositivo filho por meio do módulo do Proxy de API do IoT Edge. Confira o Guia de instruções sobre o uso do módulo do proxy se você quiser saber mais.

Para saber mais sobre como usar gateways para criar camadas hierárquicas de dispositivos IoT Edge, consulte o artigo a seguir.