Compartilhar via

Conectar dispositivos da Azure IoT Edge para criar uma hierarquia

  • Artigo

Aplica-se a: Marca de seleção do IoT Edge 1.5 IoT Edge 1.5 marca de seleção do IoT Edge 1.4 IoT Edge 1.4

Importante

O IoT Edge 1.5 LTS e o IoT Edge 1.4 LTS são versões com suporte. O IoT Edge 1.4 LTS chegará ao fim da vida útil em 12 de novembro de 2024. Se você estiver em uma versão anterior, confira Atualizar o IoT Edge.

Este artigo oferece instruções para estabelecer uma conexão confiável entre um gateway do IoT Edge e um dispositivo downstream do IoT Edge. Essa configuração também é conhecida como borda aninhada.

Em um cenário de gateway, um dispositivo do IoT Edge pode ser um gateway e um dispositivo downstream. Vários gateways IoT Edge podem ser dispostos em camadas para criar uma hierarquia de dispositivos. Os dispositivos downstream (filhos) podem autenticar e enviar ou receber mensagens por meio do seu dispositivo de gateway (pai).

Há duas configurações para dispositivos IoT Edge em uma hierarquia de gateway e este artigo aborda ambos. O primeiro é o dispositivo do IoT Edge de camada superior. Quando vários dispositivos do IoT Edge estão se conectando entre eles, considera-se que um dispositivo que não tem um dispositivo pai e se conecta diretamente ao Hub IoT esteja na camada superior. Esse dispositivo é responsável por lidar com solicitações de todos os dispositivos abaixo dele. A outra configuração se aplica a um dispositivo do IoT Edge em uma camada inferior da hierarquia. Esses dispositivos podem ser um gateway para outros dispositivos IoT downstream e IoT Edge, mas também precisam rotear qualquer comunicação por meio de seus próprios dispositivos pai.

Algumas arquiteturas de rede exigem que apenas o dispositivo do IoT Edge superior em uma hierarquia possa se conectar à nuvem. Nesta configuração, todos os dispositivos IoT Edge em camadas inferiores de uma hierarquia só podem se comunicar com seu dispositivo de gateway (pai) e qualquer dispositivo de downstream (filho).

Todas as etapas neste artigo se baseiam em Configurar um dispositivo do IoT Edge para atuar como um gateway transparente, que configura um dispositivo do IoT Edge para ser um gateway para dispositivos IoT downstream. As mesmas etapas básicas se aplicam a todos os cenários de gateway:

  • Autenticação: crie identidades do Hub IoT para todos os dispositivos na hierarquia de gateway.
  • Autorização: configure a relação pai/filho no Hub IoT para autorizar dispositivos de downstream a se conectarem ao dispositivo pai da mesma forma que se conectariam ao Hub IoT.
  • Descoberta de gateway: certifique-se de que o dispositivo dde downstream possa encontrar seu dispositivo pai na rede local.
  • Conexão segura: estabeleça uma conexão segura com certificados confiáveis que fazem parte da mesma cadeia.

Pré-requisitos

Dica

Este artigo oferece as etapas e opções detalhadas para ajudar a criar a hierarquia de gateway correta para seu cenário. Para ver um tutorial guiado, confira Criar uma hierarquia de dispositivos IoT Edge usando gateways.

Criar uma hierarquia de gateway

Para criar uma hierarquia de gateway IoT Edge, defina relações pai/filho para os dispositivos IoT Edge no cenário. Você pode definir um dispositivo pai ao criar uma identidade de dispositivo ou gerenciar o pai e os filhos de uma identidade de dispositivo existente.

A etapa de configuração de relações pai/filho autoriza os dispositivos de downstream a se conectarem ao dispositivo pai como se conectariam ao Hub IoT.

Somente dispositivos IoT Edge podem ser dispositivos pai, mas tanto dispositivos IoT Edge quanto IoT podem ser filhos. Um pai pode ter muitos filhos, mas um filho pode ter apenas um pai. Uma hierarquia de gateway é criada por meio do encadeamento de conjuntos pai/filho para que o filho de um dispositivo seja o pai de outro.

Por padrão, um pai pode ter até 100 filhos. Você pode alterar esse limite definindo a variável de ambiente MaxConnectedClients no módulo EdgeHub do dispositivo pai.

No portal do Azure, você pode gerenciar a relação pai/filho quando cria novas identidades de dispositivo ou edita os dispositivos existentes.

Ao criar um novo dispositivo do IoT Edge, você tem a opção de escolher dispositivos pai e filhos na lista de dispositivos do IoT Edge existentes nesse hub.

  1. No portal do Azure, navegue para o hub IoT.
  2. Selecione Dispositivos, no menu Gerenciamento de dispositivos.
  3. Selecione Adicionar dispositivo e marque a caixa de seleção Dispositivo do IoT Edge.
  4. Junto com a configuração da identidade do dispositivo e de autenticação, você pode Definir um dispositivo pai ou Escolher dispositivos filhos.
  5. Escolha o dispositivo ou os dispositivos que você quer que sejam pai ou filho.

Você também pode criar ou gerenciar relações pai/filho para dispositivos existentes.

  1. No portal do Azure, navegue para o hub IoT.
  2. Selecione No menu Dispositivos, no menu Gerenciamento de dispositivos.
  3. Selecione o dispositivos do IoT Edge que você deseja gerenciar da lista.
  4. Selecione o ícone de engrenagem Definir um dispositivo pai ou Gerenciar dispositivos filho.
  5. Adicionar ou remover um dispositivo pai ou filho.

Observação

Se você quiser estabelecer relações pai-filho programaticamente, poderá usar o SDK do serviço do Hub IoT de C#, Java ou Node.js.

Aqui está um exemplo de atribuição de dispositivos filhos usando o SDK do C#. A tarefa RegistryManager_AddAndRemoveDeviceWithScope() mostra como criar programaticamente uma hierarquia de três camadas. Um dispositivo IoT Edge está na camada um, como o pai. Outro dispositivo IoT Edge está na camada dois, servindo tanto como filho quanto como pai. Por fim, um dispositivo IoT está na camada três, como o dispositivo filho de camada mais baixa.

Gerar certificados

Uma cadeia consistente de certificados precisa ser instalada em dispositivos na mesma hierarquia de gateway para estabelecer uma comunicação segura entre eles. Cada dispositivo na hierarquia, seja um dispositivo IoT Edge ou um dispositivo de downstream do IoT, precisa de uma cópia do mesmo certificado CA raiz. Cada dispositivo IoT Edge na hierarquia utiliza então esse certificado de CA raiz como raiz para o seu certificado de CA Edge.

Com essa configuração, cada dispositivo downstream do IoT Edge pode confirmar a identidade do pai verificando se os edgeHub aos quais eles se conectam têm um certificado de servidor assinado pelo certificado de autoridade de certificação raiz compartilhada.

Ilustração da cadeia de certificados emitida pela AC raiz no gateway e no dispositivo downstream

Para obter mais informações sobre os requisitos de certificado do IoT Edge, confira Entenda como o Azure IoT Edge usa certificados.

  1. Crie ou solicite os seguintes certificados:

    • Um certificado de autoridade de certificação raiz, que é o certificado compartilhado mais elevado para todos os dispositivos em uma determinada hierarquia de gateway. Esse certificado está instalado em todos os dispositivos.
    • Certificados intermediários que você queira incluir na cadeia de certificados raiz.
    • Um certificado Edge CA e sua chave privada, gerada pelos certificados raiz e intermediário. Você precisa de um certificado Edge CA exclusivo para cada dispositivo IoT Edge na hierarquia do gateway.

    Você pode usar uma autoridade de certificado autoassinado ou comprar uma de uma autoridade de certificação comercial confiável, como Baltimore, Verisign, Digicert ou GlobalSign.

  2. Se você não tiver seus próprios certificados para usar no teste, crie um conjunto de certificados raiz e intermediários e, em seguida, crie certificados Edge CA para cada dispositivo. Neste artigo, usaremos certificados de teste gerados usando certificados de autoridade de certificação de teste para exemplos e tutoriais. Por exemplo, os comandos a seguir criam um certificado de autoridade de certificação raiz, um certificado de dispositivo pai e um certificado de dispositivo filho.

    # !!! For test only - do not use in production !!!

# Create the the root CA test certificate
./certGen.sh create_root_and_intermediate

# Create the parent (gateway) device test certificate 
# signed by the shared root CA certificate
./certGen.sh create_edge_device_ca_certificate "gateway"

# Create the downstream device test certificate
# signed by the shared root CA certificate
./certGen.sh create_edge_device_ca_certificate "downstream"

    Aviso

    Não use certificados criados pelos scripts de teste para produção. Eles contêm senhas embutidas em código que expiram por padrão após 30 dias. Os certificados de AC de teste são fornecidos para fins de demonstração para ajudá-lo a entender os Certificados de AC. Use suas práticas recomendadas de segurança para criação de certificação e gerenciamento de tempo de vida em produção.

    Para obter mais informações sobre como criar certificados de teste, confira Criar certificados de demonstração para testar recursos do dispositivo do IoT Edge.

  3. Você precisará transferir os certificados e as chaves para cada dispositivo. Você pode usar uma unidade USB, um serviço como o Azure Key Vault ou uma função como uma Cópia de arquivo segura. Escolha entre esses métodos aquele que melhor corresponde ao seu cenário. Copie os arquivos no diretório preferencial para certificados e chaves. Use /var/aziot/certs para certificados e /var/aziot/secrets para chaves.

Para obter mais informações sobre como instalar certificados em um dispositivo, confira Gerenciar certificados em um dispositivo do IoT Edge.

Configurar dispositivo pai

Para configurar seu dispositivo pai, abra um shell de comando local ou remoto.

Para permitir ligações seguras, cada dispositivo pai IoT Edge num cenário de gateway precisa de ser configurado com um certificado de CA Edge exclusivo e uma cópia do certificado de CA raiz partilhado por todos os dispositivos na hierarquia do gateway.

  1. Verifique se os certificados atendem aos requisitos de formato.

  2. Transfira o certificado de AC raiz, o certificado de AC do dispositivo pai e a chave privada pai para o dispositivo pai.

  3. Copie os certificados e as chaves para os diretórios corretos. Os diretórios preferenciais para certificados de dispositivo são /var/aziot/certs para os certificados e /var/aziot/secrets para chaves.

    ### Copy device certificate ###

# If the device certificate and keys directories don't exist, create, set ownership, and set permissions
sudo mkdir -p /var/aziot/certs
sudo chown aziotcs:aziotcs /var/aziot/certs
sudo chmod 755 /var/aziot/certs

sudo mkdir -p /var/aziot/secrets
sudo chown aziotks:aziotks /var/aziot/secrets
sudo chmod 700 /var/aziot/secrets

# Copy full-chain device certificate and private key into the correct directory
sudo cp iot-edge-device-ca-gateway-full-chain.cert.pem /var/aziot/certs
sudo cp iot-edge-device-ca-gateway.key.pem /var/aziot/secrets

### Root certificate ###

# Copy root certificate into the /certs directory
sudo cp azure-iot-test-only.root.ca.cert.pem /var/aziot/certs

# Copy root certificate into the CA certificate directory and add .crt extension.
# The root certificate must be in the CA certificate directory to install it in the certificate store.
# Use the appropriate copy command for your device OS or if using EFLOW.

# For Ubuntu and Debian, use /usr/local/share/ca-certificates/
sudo cp azure-iot-test-only.root.ca.cert.pem /usr/local/share/azure-iot-test-only.root.ca.cert.pem.crt
# For EFLOW, use /etc/pki/ca-trust/source/anchors/
sudo cp azure-iot-test-only.root.ca.cert.pem /etc/pki/ca-trust/source/anchors/azure-iot-test-only.root.ca.pem.crt

  4. Altere a propriedade e as permissões dos certificados e das chaves.

    # Give aziotcs ownership to certificates
# Read and write for aziotcs, read-only for others
sudo chown -R aziotcs:aziotcs /var/aziot/certs
sudo find /var/aziot/certs -type f -name "*.*" -exec chmod 644 {} \;

# Give aziotks ownership to private keys
# Read and write for aziotks, no permission for others
sudo chown -R aziotks:aziotks /var/aziot/secrets
sudo find /var/aziot/secrets -type f -name "*.*" -exec chmod 600 {} \;

# Verify permissions of directories and files
sudo ls -Rla /var/aziot

    A saída da lista com propriedade e permissão corretas é semelhante à seguinte:

    azureUser@vm:/var/aziot$ sudo ls -Rla /var/aziot
/var/aziot:
total 16
drwxr-xr-x  4 root    root    4096 Dec 14 00:16 .
drwxr-xr-x 15 root    root    4096 Dec 14 00:15 ..
drwxr-xr-x  2 aziotcs aziotcs 4096 Jan 14 00:31 certs
drwx------  2 aziotks aziotks 4096 Jan 23 17:23 secrets

/var/aziot/certs:
total 20
drwxr-xr-x 2 aziotcs aziotcs 4096 Jan 14 00:31 .
drwxr-xr-x 4 root    root    4096 Dec 14 00:16 ..
-rw-r--r-- 1 aziotcs aziotcs 1984 Jan 14 00:24 azure-iot-test-only.root.ca.cert.pem
-rw-r--r-- 1 aziotcs aziotcs 5887 Jan 14 00:27 iot-edge-device-ca-gateway-full-chain.cert.pem

/var/aziot/secrets:
total 16
drwx------ 2 aziotks aziotks 4096 Jan 23 17:23 .
drwxr-xr-x 4 root    root    4096 Dec 14 00:16 ..
-rw------- 1 aziotks aziotks 3243 Jan 14 00:28 iot-edge-device-ca-gateway.key.pem

  5. Instale o certificado de AC raiz no dispositivo de IoT Edge pai atualizando o repositório de certificados no dispositivo através do comando específico da plataforma.

    # Update the certificate store

# For Ubuntu or Debian - use update-ca-certificates
sudo update-ca-certificates
# For EFLOW or RHEL - use update-ca-trust
sudo update-ca-trust

    Para obter mais informações sobre o uso de update-ca-trust no EFLOW, confira consulte Gerenciamento de certificados de CBL-Mariner, SSL e CA.

O comando relata que um certificado foi adicionado a /etc/ssl/certs.

Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.

Atualizar arquivo de configuração pai

Você precisa ter o IoT Edge instalado no dispositivo. Caso contrário, siga as etapas para Provisionar manualmente um único dispositivo de Azure IoT Edge Linux.

  1. Verifique se o arquivo de configuração /etc/aziot/config.toml existe no dispositivo pai.

    Se o arquivo de configuração ainda não existir no dispositivo, use o seguinte comando para criá-lo com base no arquivo de modelo:

    sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

    Você também pode usar o arquivo de modelo como referência para adicionar parâmetros de configuração nesta seção.

  2. Abra o arquivo de configuração IoT Edge usando um editor. Por exemplo, use o editor nano para abrir o arquivo /etc/aziot/config.toml.

    sudo nano /etc/aziot/config.toml

  3. Localize o parâmetro hostname ou adicione-o ao início do arquivo de configuração. Atualize o valor para que ele seja o FQDN (nome de domínio totalmente qualificado) ou o endereço IP do dispositivo pai do IoT Edge. Por exemplo:

    hostname = "10.0.0.4"

    Para habilitar a descoberta de gateway, cada dispositivo (pai) de gateway do IoT Edge precisará especificar um parâmetro hostname que os respectivos dispositivos filho usarão para encontrá-lo na rede local. Cada dispositivo do IoT Edge downstream precisa especificar um parâmetro parent_hostname para identificar o respectivo pai. Se um mesmo dispositivo do IoT Edge for um dispositivo pai e filho simultaneamente, ele precisará dos dois parâmetros.

    Os parâmetros nome do host e trust_bundle_cert devem estar no início do arquivo de configuração antes de qualquer seção. Adicionar o parâmetro antes das seções definidas garante que ele seja aplicado corretamente.

    Use um nome de host com menos de 64 caracteres, que é o limite para o nome comum do certificado de um servidor.

    Seja consistente com o padrão do hostname em uma hierarquia de gateway. Use FQDNs ou endereços IP, mas não ambos. O FQDN ou o endereço IP é necessário para conectar dispositivos downstream.

    Defina o nome do host antes que o contêiner edgeHub seja criado. Se edgeHub estiver em execução, a alteração do nome do host no arquivo de configuração não terá efeito até que o contêiner seja recriado. Para obter mais informações sobre como verificar se o nome do host é aplicado, confira a seção verificar a configuração pai.

  4. Localize o parâmetro Trust bundle cert ou adicione-o ao início do arquivo de configuração.

    Atualize o parâmetro trust_bundle_cert com o URI do arquivo do certificado de autoridade de certificação raiz no seu dispositivo. Por exemplo:

    trust_bundle_cert = "file:///var/aziot/certs/azure-iot-test-only.root.ca.cert.pem"

  5. Encontre ou adicione a seção Certificado de autoridade de certificação do Edge no arquivo de configuração. Atualize os parâmetros de certificado cert e chave privada pk com os caminhos de URI do arquivo para os arquivos de certificado de cadeia completa e chave no dispositivo pai do IoT Edge. O IoT Edge exige que o certificado e a chave privada estejam no formato PEM (email aprimorado para privacidade) baseado em texto. Por exemplo:

    [edge_ca]
cert = "file:///var/aziot/certs/iot-edge-device-ca-gateway-full-chain.cert.pem"
pk = "file:///var/aziot/secrets/iot-edge-device-ca-gateway.key.pem"

  6. Verifique se o dispositivo do IoT Edge usará a versão correta do agente do IoT Edge quando ele for iniciado. Encontre a seção Agente padrão do Edge e defina o valor da imagem do IoT Edge como a versão 1.5. Por exemplo:

    [agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

  7. O início do arquivo de configuração pai deve ser semelhante ao exemplo a seguir.

    hostname = "10.0.0.4"
trust_bundle_cert = "file:///var/aziot/certs/azure-iot-test-only.root.ca.cert.pem"

[edge_ca]
cert = "file:///var/aziot/certs/iot-edge-device-ca-gateway-full-chain.cert.pem"
pk = "file:///var/aziot/secrets/iot-edge-device-ca-gateway.key.pem"

  8. Salve e feche o arquivo de configuração config.toml. Por exemplo, se você estiver usando o editor nano, selecione Ctrl+O - Gravar, Enter e Ctrl+X - Sair.

  9. Se você tiver usado outros certificados para IoT Edge, exclua os arquivos nos dois diretórios a seguir para confirmar que os novos certificados serão aplicados:

    • /var/lib/aziot/certd/certs
    • /var/lib/aziot/keyd/keys

  10. Aplique suas alterações.

    sudo iotedge config apply

  11. Verifique se há erros na configuração.

    sudo iotedge check --verbose

    Observação

    Em um dispositivo recém-provisionado, você pode ver um erro relacionado ao Hub do IoT Edge:

    × preparação para produção: o diretório de armazenamento do Hub do Edge é persistente no sistema de arquivos do host – erro

    Não foi possível verificar o estado atual do contêiner edgeHub

    Esse erro é esperado em um dispositivo recém-provisionado, pois o módulo do Hub do IoT Edge não está em execução. Para resolver o erro, no Hub IoT, defina os módulos para o dispositivo e crie uma implantação. A criação de uma implantação para o dispositivo inicia os módulos no dispositivo, incluindo o módulo Hub do IoT Edge.

Verificar a configuração pai

O parâmetro hostname precisa ser um FQDN (nome de domínio totalmente qualificado) ou o endereço IP do dispositivo do IoT Edge, porque o IoT Edge usa esse valor no certificado do servidor quando dispositivos downstream se conectam. Os valores precisarão corresponder, caso contrário você receberá um erro de incompatibilidade de endereço IP.

Para verificar o parâmetro hostname, você precisa inspecionar as variáveis de ambiente do contêiner edgeHub.

  1. Liste os contêineres do IoT Edge em execução.

    iotedge list

    Verifique se os contêineres edgeAgent e edgeHub estão em execução. A saída do comando deve ser semelhante ao exemplo a seguir.

    NAME                        STATUS           DESCRIPTION      CONFIG
SimulatedTemperatureSensor  running          Up 5 seconds     mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0
edgeAgent                   running          Up 17 seconds    mcr.microsoft.com/azureiotedge-agent:1.5
edgeHub                     running          Up 6 seconds     mcr.microsoft.com/azureiotedge-hub:1.5

  2. Inspecione o contêiner EdgeHub.

    sudo docker inspect edgeHub

  3. Na saída, localize o parâmetro EdgeDeviceHostName na seção Env.

    "EdgeDeviceHostName=10.0.0.4"

  4. Verifique se o valor do parâmetro EdgeDeviceHostName corresponde à configuração de config.toml hostname. Se não corresponde, significa que o contêiner do edgeHub estava em execução quando você modificou e aplicou a configuração. Para atualizar o EdgeDeviceHostName, remova o contêiner edgeAgent.

    sudo docker rm -f edgeAgent

    Os contêineres edgeAgent e edgeHub são recriados e iniciados em poucos minutos. Depois que o contêiner edgeHub estiver em execução, inspecione o contêiner e verifique se o parâmetro EdgeDeviceHostName corresponde ao arquivo de configuração.

Configurar um dispositivo de downstream

Para configurar seu dispositivo de downstream, abra um shell de comando local ou remoto.

Para permitir ligações seguras, cada dispositivo a jusante IoT Edge num cenário de gateway precisa de ser configurado com um certificado de CA Edge exclusivo e uma cópia do certificado de CA raiz partilhado por todos os dispositivos na hierarquia do gateway.

  1. Verifique se os certificados atendem aos requisitos de formato.

  2. Transfira o certificado CA raiz, o certificado CA Edge filho e a chave privada filho para o dispositivo downstream.

  3. Copie os certificados e as chaves para os diretórios corretos. Os diretórios preferenciais para certificados de dispositivo são /var/aziot/certs para os certificados e /var/aziot/secrets para chaves.

    ### Copy device certificate ###

# If the device certificate and keys directories don't exist, create, set ownership, and set permissions
sudo mkdir -p /var/aziot/certs
sudo chown aziotcs:aziotcs /var/aziot/certs
sudo chmod 755 /var/aziot/certs

sudo mkdir -p /var/aziot/secrets
sudo chown aziotks:aziotks /var/aziot/secrets
sudo chmod 700 /var/aziot/secrets

# Copy device full-chain certificate and private key into the correct directory
sudo cp iot-device-downstream-full-chain.cert.pem /var/aziot/certs
sudo cp iot-device-downstream.key.pem /var/aziot/secrets

### Root certificate ###

# Copy root certificate into the /certs directory
sudo cp azure-iot-test-only.root.ca.cert.pem /var/aziot/certs

# Copy root certificate into the CA certificate directory and add .crt extension.
# The root certificate must be in the CA certificate directory to install it in the certificate store.
# Use the appropriate copy command for your device OS or if using EFLOW.

# For Ubuntu and Debian, use /usr/local/share/ca-certificates/
sudo cp azure-iot-test-only.root.ca.cert.pem /usr/local/share/azure-iot-test-only.root.ca.cert.pem.crt
# For EFLOW, use /etc/pki/ca-trust/source/anchors/
sudo cp azure-iot-test-only.root.ca.cert.pem /etc/pki/ca-trust/source/anchors/azure-iot-test-only.root.ca.pem.crt

  4. Altere a propriedade e as permissões dos certificados e das chaves.

    # Give aziotcs ownership to certificates
# Read and write for aziotcs, read-only for others
sudo chown -R aziotcs:aziotcs /var/aziot/certs
sudo find /var/aziot/certs -type f -name "*.*" -exec chmod 644 {} \;

# Give aziotks ownership to private keys
# Read and write for aziotks, no permission for others
sudo chown -R aziotks:aziotks /var/aziot/secrets
sudo find /var/aziot/secrets -type f -name "*.*" -exec chmod 600 {} \;

  5. Instale o certificado de AC raiz no dispositivo downstream de IoT Edge pai atualizando o repositório de certificados no dispositivo através do comando específico da plataforma.

    # Update the certificate store

# For Ubuntu or Debian - use update-ca-certificates
sudo update-ca-certificates
# For EFLOW or RHEL - use update-ca-trust
sudo update-ca-trust

    Para obter mais informações sobre o uso de update-ca-trust no EFLOW, confira consulte Gerenciamento de certificados de CBL-Mariner, SSL e CA.

O comando relata que um certificado foi adicionado a /etc/ssl/certs.

Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.

Atualizar o arquivo de configuração de downstream

Você precisa ter o IoT Edge instalado no dispositivo. Caso contrário, siga as etapas para Provisionar manualmente um único dispositivo de Azure IoT Edge Linux.

  1. Verifique se o arquivo de configuração /etc/aziot/config.toml existe no dispositivo de downstream.

    Se o arquivo de configuração ainda não existir no dispositivo, use o seguinte comando para criá-lo com base no arquivo de modelo:

    sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

    Você também pode usar o arquivo de modelo como referência para adicionar parâmetros de configuração nesta seção.

  2. Abra o arquivo de configuração IoT Edge usando um editor. Por exemplo, use o editor nano para abrir o arquivo /etc/aziot/config.toml.

    sudo nano /etc/aziot/config.toml

  3. Localize o parâmetro parent_hostname ou adicione-o ao início do arquivo de configuração. Todo dispositivo do IoT Edge downstream precisa especificar um parâmetro parent_hostname para identificar o próprio pai. Atualize o parâmetro parent_hostname para que seja o FQDN ou o endereço IP do dispositivo pai, seja qual for o fornecido como nome do host no arquivo de configuração do dispositivo pai. Por exemplo:

    parent_hostname = "10.0.0.4"

  4. Localize o parâmetro Trust bundle cert ou adicione-o ao início do arquivo de configuração.

    Atualize o parâmetro trust_bundle_cert com o URI do arquivo do certificado de autoridade de certificação raiz no seu dispositivo. Por exemplo:

    trust_bundle_cert = "file:///var/aziot/certs/azure-iot-test-only.root.ca.cert.pem"

  5. Encontre ou adicione a seção Certificado de autoridade de certificação do Edge no arquivo de configuração. Atualize os parâmetros de certificado cert e chave privada pk com os caminhos de URI do arquivo para os arquivos de certificado de cadeia completa e chave no dispositivo de downstream do IoT Edge. O IoT Edge exige que o certificado e a chave privada estejam no formato PEM (email aprimorado para privacidade) baseado em texto. Por exemplo:

    [edge_ca]
cert = "file:///var/aziot/certs/iot-device-downstream-full-chain.cert.pem"
pk = "file:///var/aziot/secrets/iot-device-downstream.key.pem"

  6. Verifique se o dispositivo do IoT Edge usará a versão correta do agente do IoT Edge quando ele for iniciado. Encontre a seção Agente padrão do Edge e defina o valor da imagem do IoT Edge como a versão 1.5. Por exemplo:

    [agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image: "mcr.microsoft.com/azureiotedge-agent:1.5"

  7. O início do arquivo de configuração de downstream deve ser semelhante ao exemplo a seguir.

    parent_hostname = "10.0.0.4"
trust_bundle_cert = "file:///var/aziot/certs/azure-iot-test-only.root.ca.cert.pem"

[edge_ca]
cert = "file:///var/aziot/certs/iot-device-downstream-full-chain.cert.pem"
pk = "file:///var/aziot/secrets/iot-device-downstream.key.pem"

  8. Salve e feche o arquivo de configuração config.toml. Por exemplo, se você estiver usando o editor nano, selecione Ctrl+O - Gravar, Enter e Ctrl+X - Sair.

  9. Se você tiver usado outros certificados para IoT Edge, exclua os arquivos nos dois diretórios a seguir para confirmar que os novos certificados serão aplicados:

    • /var/lib/aziot/certd/certs
    • /var/lib/aziot/keyd/keys

  10. Aplique suas alterações.

    sudo iotedge config apply

  11. Verifique se há erros na configuração.

    sudo iotedge check --verbose

    Dica

    A ferramenta de verificação do IoT Edge usa um contêiner para executar algumas verificações de diagnóstico. Se quiser usar essa ferramenta em dispositivos downstream do IoT Edge, verifique se eles podem acessar mcr.microsoft.com/azureiotedge-diagnostics:latest ou se a imagem de contêiner está no seu registro de contêiner privado.

    Observação

    Em um dispositivo recém-provisionado, você pode ver um erro relacionado ao Hub do IoT Edge:

    × preparação para produção: o diretório de armazenamento do Hub do Edge é persistente no sistema de arquivos do host – erro

    Não foi possível verificar o estado atual do contêiner edgeHub

    Esse erro é esperado em um dispositivo recém-provisionado, pois o módulo do Hub do IoT Edge não está em execução. Para resolver o erro, no Hub IoT, defina os módulos para o dispositivo e crie uma implantação. A criação de uma implantação para o dispositivo inicia os módulos no dispositivo, incluindo o módulo Hub do IoT Edge.

Dispositivos downstream isolados na rede

As etapas até o momento neste artigo configuram dispositivos do IoT Edge como gateway ou dispositivo downstream e criam uma conexão confiável entre eles. O dispositivo de gateway lida com as interações entre o dispositivo downstream e o Hub IoT, inclusive autenticação e roteamento de mensagens. Os módulos implantados em dispositivos do IoT Edge downstream ainda podem criar as próprias conexões com os serviços de nuvem.

Algumas arquiteturas de rede, como as que seguem o padrão ISA-95, buscam minimizar o número de conexões com a internet. Nesses cenários, você pode configurar dispositivos do IoT Edge downstream sem conectividade direta com a Internet. Além de rotear as comunicações do Hub IoT por meio do respectivo dispositivo de gateway, os dispositivos do IoT Edge downstream podem contar com o dispositivo de gateway para todas as conexões de nuvem.

Essa configuração de rede requer que apenas o dispositivo do IoT Edge na camada superior de uma hierarquia de gateway tenha conexões diretas com a nuvem. Os dispositivos do IoT Edge nas camadas inferiores só podem se comunicar com o respectivo dispositivo pai ou com dispositivos filhos. Módulos especiais nos dispositivos de gateway permitem esse cenário, incluindo:

  • O módulo proxy de API é necessário em um gateway do IoT Edge que tenha outro dispositivo do IoT Edge abaixo dele. Isso significa que ele precisa estar em todas as camadas de uma hierarquia de gateway, exceto na camada inferior. Esse módulo usa um proxy reverso nginx para rotear dados HTTP por camadas de rede em uma única porta. Ele é altamente configurável por meio dos respectivos módulo gêmeo e variáveis de ambiente, portanto, pode ser ajustado para se adequar aos seus requisitos de cenário de gateway.

  • O módulo do registro do Docker pode ser implantado no gateway do IoT Edge na camada superior de uma hierarquia de gateway. Esse módulo é responsável por recuperar e armazenar em cache as imagens de contêiner em nome de todos os dispositivos do IoT Edge em camadas inferiores. Uma maneira alternativa para implantar esse módulo na camada superior é usar um registro local ou carregar manualmente as imagens de contêiner em dispositivos e definir a política de pull de módulo como nunca.

  • O Armazenamento de Blobs do Azure no IoT Edge pode ser implantado no gateway do IoT Edge na camada superior de uma hierarquia de gateway. Esse módulo é responsável por carregar blobs em nome de todos os dispositivos do IoT Edge em camadas inferiores. A capacidade de fazer upload de blobs também permite uma funcionalidade útil de solução de problemas para dispositivos do IoT Edge em camadas inferiores, como upload de log de módulo e de pacote de suporte.

Configuração de rede

Para cada dispositivo de gateway na camada superior, os operadores de rede precisam:

  • Informe um endereço IP estático ou FQDN (nome de domínio totalmente qualificado).

  • Autorize a comunicação de saída desse endereço IP com o nome do host do Hub IoT do Azure nas portas 443 (HTTPS) e 5671 (AMQP).

  • Autorize a comunicação de saída desse endereço IP com o nome do host do Registro de Contêiner do Azure pela porta 443 (HTTPS).

    O módulo proxy de API só pode lidar com conexões para um registro de contêiner por vez. Recomendamos ter todas as imagens de contêiner, inclusive as imagens públicas fornecidas pelo Microsoft Container Registry (mcr.microsoft.com), armazenadas no seu registro de contêiner privado.

Para cada dispositivo de gateway na camada inferior, os operadores de rede precisam:

  • Informar um endereço IP estático.
  • Autorize a comunicação de saída desse endereço IP com o endereço IP do gateway pai nas portas 443 (HTTPS) e 5671 (AMQP).

Implantar módulos nos dispositivos de camada superior

O dispositivo do IoT Edge na camada superior de uma hierarquia de gateway tem um conjunto de módulos necessários que precisam ser implantados nele, além dos módulos de carga de trabalho que você possa executar no dispositivo.

O módulo de proxy de API foi projetado para ser personalizado para lidar com os cenários de gateway mais comuns. Este artigo apresenta um exemplo para configuração básica dos módulos. Veja Configurar o módulo de proxy de API para seu cenário de hierarquia de gateway para obter informações e exemplos mais detalhados.

  1. No portal do Azure, navegue para o hub IoT.

  2. Selecione Dispositivos, no menu Gerenciamento de dispositivos.

  3. Selecione o dispositivo IoT Edge de camada superior que você está configurando da lista.

  4. Selecione Definir módulos.

  5. Na seção Módulos do IoT Edge, escolha Adicionar e escolha Módulo do IoT Edge.

  6. Atualize as seguintes configurações de módulo:

    Configuração Valor
    Nome do módulo IoT IoTEdgeAPIProxy
    URI da imagem mcr.microsoft.com/azureiotedge-api-proxy:latest
    Política de reinicialização always
    Status desejado executando

    Se você quiser usar uma versão ou arquitetura diferente do módulo de proxy da API, localize as imagens disponíveis no Registro de Artefato da Microsoft.

    1. Na guia Variáveis de ambiente, adicione uma variável chamada NGINX_DEFAULT_PORT do tipo Texto com o valor 443.

    2. Na guia Opções de criação de contêiner, atualize as associações de porta para fazer referência à porta 443.

      {
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}

    Essas alterações configuram o módulo de proxy de API para escutar na porta 443. Para evitar conflitos de associação de porta, você precisa configurar o módulo edgeHub para não escutar na porta 443. Em vez disso, o módulo de proxy de API roteará tráfego edgeHub na porta 443.

  7. Escolha Adicionar para adicionar o módulo à implantação.

  8. Escolha Configurações de runtime e encontre as Opções de Criação do Container do módulo edgeHub. Exclua a associação da porta 443, deixando as associações das portas 5671 e 8883.

    {
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}

  9. Escolha Aplicar para salvar as alterações nas configurações de runtime.

  10. Informe os valores a seguir para adicionar o módulo do registro Docker à sua implantação.

    1. Na seção Módulos do IoT Edge, escolha Adicionar e escolha Módulo do IoT Edge.

      Configuração Valor
      Nome do módulo IoT registry
      URI da imagem registry:latest
      Política de reinicialização always
      Status desejado running

    2. Na guia Variáveis de ambiente, adicione as seguintes variáveis:

      Nome Tipo Valor
      REGISTRY_PROXY_REMOTEURL Texto A URL do registro de contêiner para o qual você quer mapear esse módulo de registro. Por exemplo, https://myregistry.azurecr. O módulo do registro só pode ser mapeado para um registro de contêiner, portanto, recomendamos ter todas as imagens de contêiner em um único registro de contêiner privado.
      REGISTRY_PROXY_USERNAME Texto O nome de usuário para autenticar o registro de contêiner.
      REGISTRY_PROXY_PASSWORD Texto A senha para autenticar o registro de contêiner.

    3. Na guia Opções de criação de contêiner, atualize as associações de porta à porta de referência 5000.

    {
  "HostConfig": {
    "PortBindings": {
      "5000/tcp": [
        {
          "HostPort": "5000"
        }
      ]
    }
  }
}

  11. Escolha Adicionar para adicionar o módulo à implantação.

  12. Escolha Avançar: rotas para passar para a próxima etapa.

  13. Para habilitar mensagens dos dispositivos downstream para nuvem para acessar o Hub IoT, inclua uma rota que passe todas as mensagens ao Hub IoT. Por exemplo:

    1. Nome: Route
    2. Valor: FROM /messages/* INTO $upstream

  14. Escolha Revisar + criar para ir para a etapa final.

  15. Escolha Criar para implantar no seu dispositivo.

Implantar módulos nos dispositivos de camada inferior

Dispositivos do IoT Edge em camadas inferiores de uma hierarquia de gateway têm um módulo necessário que precisa ser implantado neles, além dos módulos de carga de trabalho que você possa executar no dispositivo.

Direcionar pulls de imagem de contêiner

Antes de discutir o módulo de proxy necessário para dispositivos do IoT Edge em hierarquias de gateway, é importante entender como dispositivos do IoT Edge em camadas inferiores obtêm imagens de módulo.

Se os dispositivos de camada inferior não puderem se conectar à nuvem, mas você quiser que eles recebam imagens de módulo como de costume, o dispositivo de camada superior da hierarquia de gateway precisará ser configurado para lidar com essas solicitações. O dispositivo de camada superior precisa executar um módulo de registro do Docker mapeado para o registro de contêiner. Em seguida, configure o módulo de proxy de API para rotear solicitações de contêiner para ele. Isso é discutido em detalhes nas seções anteriores deste artigo. Nessa configuração, os dispositivos de camada inferior não devem apontar para registros de contêiner de nuvem, mas para o registro em execução na camada superior.

Por exemplo, em vez de chamar mcr.microsoft.com/azureiotedge-api-proxy:1.1, os dispositivos de camada inferiores devem chamar $upstream:443/azureiotedge-api-proxy:1.1.

O parâmetro $upstream aponta para o pai de um dispositivo de camada inferior, de modo que a solicitação será roteada por todas as camadas até atingir a superior, que tem um ambiente de proxy que roteia solicitações de contêiner para o módulo do registro. A porta :443 neste exemplo deve ser substituída por uma que o módulo de proxy de API no dispositivo pai esteja escutando.

O módulo proxy de API só pode rotear para um módulo do registro e cada módulo do registro só pode ser mapeado para um registro de contêiner. Portanto, todas as imagens que os dispositivos de camada inferior precisam efetuar pull precisam ser armazenadas em um único registro de contêiner.

Se não quiser que dispositivos de camada inferior façam solicitações pull de módulo por meio de uma hierarquia de gateway, você também pode gerenciar uma solução de registro local. Ou efetue o push das imagens do módulo para os dispositivos antes de criar implantações e, em seguida, defina imagePullPolicy como nunca.

Inicializar o agente do IoT Edge

O agente IoT Edge é o primeiro componente de runtime a ser iniciado em um dispositivo do IoT Edge. Você precisa verificar se os dispositivos downstream IoT Edge podem acessar a imagem do módulo edgeAgent quando eles são iniciados e, em seguida, as implantações e iniciar o restante das imagens do módulo.

Entrar no arquivo de configuração em um dispositivo do IoT Edge para fornecer informações de autenticação, certificados e nome do host pai, também atualiza a imagem de contêiner edgeAgent.

Se o dispositivo de gateway de nível superior estiver configurado para lidar com solicitações de imagem de contêiner, substitua mcr.microsoft.com pelo nome de host pai e pela porta de escuta de proxy de API. No manifesto de implantação, você pode usar $upstream como atalho, mas isso requer que o módulo edgeHub trate do roteamento e esse módulo não tenha começado nesse ponto. Por exemplo:

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image: "{Parent FQDN or IP}:443/azureiotedge-agent:1.5"

Se você estiver usando um registro de contêiner local ou fornecendo manualmente as imagens de contêiner ao dispositivo, atualize o arquivo de configuração levando isso em consideração.

Configurar runtime e implantar módulo proxy

O módulo proxy de API é necessário para rotear todas as comunicações entre a nuvem e os dispositivos downstream do IoT Edge. Um dispositivo do IoT Edge na camada inferior da hierarquia, sem dispositivos downstream do IoT Edge, não precisa desse módulo.

O módulo de proxy de API foi projetado para ser personalizado para lidar com os cenários de gateway mais comuns. Este artigo aborda brevemente as etapas para fazer a configuração básica dos módulos. Veja Configurar o módulo de proxy de API para seu cenário de hierarquia de gateway para obter informações e exemplos mais detalhados.

  1. No portal do Azure, navegue para o hub IoT.

  2. Selecione Dispositivos, no menu Gerenciamento de dispositivos.

  3. Selecione o dispositivo IoT Edge de camada inferior que você está configurando da lista.

  4. Selecione Definir módulos.

  5. Na seção Módulos do IoT Edge, escolha Adicionar e escolha Módulo do IoT Edge.

  6. Atualize as seguintes configurações de módulo:

    Configuração Valor
    Nome do módulo IoT IoTEdgeAPIProxy
    URI da imagem mcr.microsoft.com/azureiotedge-api-proxy:latest
    Política de reinicialização always
    Status desejado running

    Se você quiser usar uma versão ou arquitetura diferente do módulo de proxy da API, localize as imagens disponíveis no Registro de Artefato da Microsoft.

    1. Na guia Variáveis de ambiente, adicione uma variável chamada NGINX_DEFAULT_PORT do tipo Texto com o valor 443.

    2. Na guia Opções de criação de contêiner, atualize as associações de porta para fazer referência à porta 443.

      {
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}

    Essas alterações configuram o módulo de proxy de API para escutar na porta 443. Para evitar conflitos de associação de porta, você precisa configurar o módulo edgeHub para não escutar na porta 443. Em vez disso, o módulo de proxy de API roteará tráfego edgeHub na porta 443.

  7. Selecione Configurações de Runtime.

  8. Atualizar as configurações de módulo do edgeHub:

    1. No campo Imagem, substitua mcr.microsoft.com por $upstream:443.
    2. No campo Criar opções, exclua a associação da porta 443, deixando as associações para as portas 5671 e 8883.
    {
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}

  9. Atualize as configurações do módulo edgeAgent:

    1. No campo Imagem, substitua mcr.microsoft.com por $upstream:443.

  10. Escolha Aplicar para salvar as alterações nas configurações de runtime.

  11. Escolha Avançar: rotas para passar para a próxima etapa.

  12. Para habilitar mensagens dos dispositivos downstream para nuvem para acessar o Hub IoT, inclua uma rota que passe todas as mensagens ao $upstream. O parâmetro upstream aponta para o dispositivo pai no caso de dispositivos de camada inferior. Por exemplo:

    1. Nome: Route
    2. Valor: FROM /messages/* INTO $upstream

  13. Escolha Revisar + criar para ir para a etapa final.

  14. Escolha Criar para implantar no seu dispositivo.

Verificar a conectividade de filho para pai

  1. Verifique a conexão TLS/SSL do filho para o pai executando o comando openssl a seguir no dispositivo de downstream. Substitua <parent hostname> pelo endereço FQDN ou o endereço IP do pai.

    openssl s_client -connect <parent hostname>:8883 </dev/null 2>&1 >/dev/null

    O comando deve declarar a validação bem-sucedida da cadeia de certificados pai semelhante ao exemplo a seguir:

    azureUser@child-vm:~$ openssl s_client -connect <parent hostname>:8883 </dev/null 2>&1 >/dev/null
Can't use SSL_get_servername
depth=3 CN = Azure_IoT_Hub_CA_Cert_Test_Only
verify return:1
depth=2 CN = Azure_IoT_Hub_Intermediate_Cert_Test_Only
verify return:1
depth=1 CN = gateway.ca
verify return:1
depth=0 CN = <parent hostname>
verify return:1
DONE

    A mensagem "Não é possível usar SSL_get_servername" pode ser ignorada.

    O valor depth=0 CN = deve corresponder ao parâmetro hostname especificado no arquivo de configuração config.toml do pai.

    Se o comando atingir o tempo limite, poderá haver portas bloqueadas entre os dispositivos filho e pai. Examine a configuração de rede e as configurações dos dispositivos.

    Aviso

    Não usar um certificado de cadeia completa na seção do [edge_ca] gateway resulta em erros de validação de certificado do dispositivo downstream. Por exemplo, o comando openssl s_client ... acima produzirá:

    Can't use SSL_get_servername
depth=1 CN = gateway.ca
verify error:num=20:unable to get local issuer certificate
verify return:1
depth=0 CN = <parent hostname>
verify return:1
DONE

    O mesmo problema ocorre para dispositivos habilitados para TLS que se conectam ao dispositivo de IoT Edge downstream se o certificado de dispositivo de cadeia completa não for usado e configurado no dispositivo downstream.

Integrar o Microsoft Defender para IoT com gateway do IoT Edge

Os dispositivos de downstream podem ser usados para integrar o microagente do Microsoft Defender para IoT com o gateway IoT Edge usando proxy de dispositivo de downstream.

Instale o microagente do Defender para IoT.

Para integrar o Microsoft Defender para IoT ao IoT Edge usando o proxy de dispositivo de downstream:

  1. Entre no portal do Azure.

  2. Navegue até IoT Hub>Your Hub>Gerenciamento de dispositivos>Dispositivos

  3. Selecione seu dispositivo.

    Captura de tela que mostra onde seu dispositivo está localizado para seleção.

  4. Selecione o módulo gêmeo DefenderIotMicroAgent que você criou nestas instruções.

    Captura de tela que mostra a localização do DefenderIotMicroAgent.

  5. Selecione o botão para copiar a sua cadeia de caracteres de Conexão (chave primária).

  6. Cole a cadeia de conexão em um aplicativo de edição de texto e adicione o GatewayHostName à cadeia de caracteres. O GatewayHostName é o nome de domínio totalmente qualificado ou o endereço IP do dispositivo pai. Por exemplo, HostName=nested11.azure-devices.net;DeviceId=downstream1;ModuleId=module1;SharedAccessKey=xxx;GatewayHostName=10.16.7.4.

  7. Abrir um terminal no dispositivo de downstream.

  8. Use o comando a seguir para colocar a string de conexão codificada em utf-8 no diretório do agente Defender para Nuvem no arquivo connection_string.txt no seguinte caminho: /etc/defender_iot_micro_agent/connection_string.txt:

    sudo bash -c 'echo "<connection string>" > /etc/defender_iot_micro_agent/connection_string.txt'

    O connection_string.txt agora estará na localização do caminho /etc/defender_iot_micro_agent/connection_string.txt.

  9. Reinicie o serviço usando este comando:

    sudo systemctl restart defender-iot-micro-agent.service

  10. Navegue de volta ao dispositivo.

    Captura de tela que mostra como navegar de volta ao dispositivo.

  11. Habilite a conexão com o Hub IoT e selecione o ícone de engrenagem.

    Captura de tela que mostra o que selecionar para definir um dispositivo pai.

  12. Selecione o dispositivo pai na lista exibida.

  13. Certifique-se de que a porta 8883 (MQTT) entre o dispositivo de downstream e o dispositivo do IoT Edge esteja aberta.

Próximas etapas

Como um dispositivo IoT Edge pode ser usado como um gateway

Configurar o módulo proxy de API para seu cenário de hierarquia de gateway