Share via

Ligar dispositivos do Azure IoT Edge para criar uma hierarquia

  • Artigo

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

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS são versões suportadas. O IoT Edge 1.4 LTS termina a vida útil em 12 de novembro de 2024. Se tiver uma versão anterior, consulte Atualizar IoT Edge.

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

Em um cenário de gateway, um dispositivo IoT Edge pode ser um gateway e um dispositivo downstream. Vários gateways IoT Edge podem ser colocados em camadas para criar uma hierarquia de dispositivos. Os dispositivos downstream (filho) podem autenticar e enviar ou receber mensagens através do dispositivo gateway (pai).

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

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

Todas as etapas neste artigo se baseiam em Configurar um dispositivo IoT Edge para atuar como um gateway transparente, que configura um dispositivo 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 do gateway.
  • Autorização: configure a relação pai/filho no Hub IoT para autorizar dispositivos downstream a se conectarem ao dispositivo pai como se se conectassem ao Hub IoT.
  • Descoberta de gateway: certifique-se de que o dispositivo 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

  • Um hub IoT gratuito ou padrão.
  • Pelo menos dois dispositivos IoT Edge, um para ser o dispositivo de camada superior e um ou mais dispositivos de camada inferior. Se você não tiver dispositivos IoT Edge disponíveis, poderá Executar o Azure IoT Edge em máquinas virtuais do Ubuntu.
  • Se você usar a CLI do Azure para criar e gerenciar dispositivos, instale a extensão do Azure IoT.

Gorjeta

Este artigo fornece etapas e opções detalhadas para ajudá-lo a criar a hierarquia de gateway certa para seu cenário. Para obter um tutorial guiado, consulte Criar uma hierarquia de dispositivos IoT Edge usando gateways.

Criar uma hierarquia de gateway

Você cria uma hierarquia de gateway de Borda IoT definindo relações pai/filho para os dispositivos IoT Edge no cenário. Você pode definir um dispositivo pai ao criar uma nova identidade de dispositivo ou pode 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 downstream a se conectarem ao dispositivo pai como se se conectassem ao Hub IoT.

Apenas os dispositivos IoT Edge podem ser dispositivos pai, mas tanto os dispositivos IoT Edge quanto os dispositivos IoT podem ser crianças. Um progenitor pode ter muitos filhos, mas um filho só pode ter um progenitor. Uma hierarquia de gateway é criada encadeando conjuntos pai/filho juntos para que o filho de um dispositivo seja o pai de outro.

Por predefinição, um encarregado de educação 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 ao criar novas identidades de dispositivo ou editando dispositivos existentes.

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

  1. No Portal do Azure, navegue para o seu hub IoT.
  2. Selecione Dispositivos no menu Gerenciamento de dispositivos.
  3. Selecione Adicionar dispositivo e marque a caixa de seleção Dispositivo IoT Edge.
  4. Além de definir o ID do dispositivo e as configurações de autenticação, você pode Definir um dispositivo pai ou Escolher dispositivos filho.
  5. Escolha o dispositivo ou dispositivos que pretende como 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 seu hub IoT.
  2. Selecione Dispositivos no menu Gerenciamento de dispositivos.
  3. Selecione o dispositivo IoT Edge que você deseja gerenciar na lista.
  4. Selecione o ícone de engrenagem Definir um dispositivopai ou Gerenciar dispositivos filho.
  5. Adicione ou remova quaisquer dispositivos pai ou filho.

Nota

Se desejar estabelecer relações pai-filho programaticamente, você pode usar o C#, Java ou Node.js SDK do Serviço de Hub IoT.

Aqui está um exemplo de atribuição de dispositivos filho 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 como filho e pai. Finalmente, um dispositivo IoT está na camada três, como o dispositivo filho de camada mais baixa.

Gerar certificados

Uma cadeia consistente de certificados deve ser instalada entre 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 downstream IoT, precisa de uma cópia do mesmo certificado de autoridade de certificação raiz. Cada dispositivo IoT Edge na hierarquia usa esse certificado de autoridade de certificação raiz como a raiz para seu certificado de autoridade de certificação de dispositivo.

Com essa configuração, cada dispositivo IoT Edge downstream pode verificar a identidade de seu pai, verificando se o edgeHub ao qual eles se conectam tem um certificado de servidor assinado pelo certificado de CA raiz compartilhado.

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

Para obter mais informações sobre os requisitos de certificado do IoT Edge, consulte Entender 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 alto para todos os dispositivos em uma determinada hierarquia de gateway. Este certificado é instalado em todos os dispositivos.
    • Todos os certificados intermediários que você deseja incluir na cadeia de certificados raiz.
    • Um certificado de CA de dispositivo e sua chave privada, gerada pelos certificados raiz e intermediário. Você precisa de um certificado de CA de dispositivo exclusivo para cada dispositivo IoT Edge na hierarquia de gateway.

    Você pode usar uma autoridade de certificação autoassinada 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 de CA de dispositivo IoT Edge para cada dispositivo. Neste artigo, usaremos certificados de teste gerados usando certificados de CA de teste para amostras 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 codificadas e expiram por padrão após 30 dias. Os certificados de autoridade de certificação de teste são fornecidos para fins de demonstração para ajudá-lo a entender os certificados de autoridade de certificação. Use suas próprias práticas recomendadas de segurança para a criação de certificação e gerenciamento de tempo de vida na produção.

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

  3. Você precisará transferir os certificados e chaves para cada dispositivo. Você pode usar uma unidade USB, um serviço como o Azure Key Vault ou com uma função como Cópia segura de arquivos. Escolha um destes métodos que melhor corresponda ao seu cenário. Copie os arquivos para o 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, consulte Gerenciar certificados em um dispositivo IoT Edge.

Configurar dispositivo pai

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

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

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

  2. Transfira o certificado de autoridade de certificação raiz, o certificado de autoridade de certificação do dispositivo pai e a chave privada pai para o dispositivo pai.

  3. Copie os certificados e 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 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 autoridade de certificação raiz no dispositivo IoT Edge pai atualizando o armazenamento de certificados no dispositivo usando o 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 como usar update-ca-trust no EFLOW, consulte CBL-Mariner SSL CA certificates management.

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

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

Atualizar arquivo de configuração pai

Você já deve ter o IoT Edge instalado no seu dispositivo. Caso contrário, siga as etapas para provisionar manualmente um único dispositivo Linux IoT Edge.

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

    Se o arquivo de configuração não existir no seu 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 do IoT Edge usando um editor. Por exemplo, use o nano editor para abrir o /etc/aziot/config.toml arquivo.

    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 ser o nome de domínio totalmente qualificado (FQDN) 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 de gateway de Borda IoT (pai) precisa especificar um parâmetro de nome de host que seus dispositivos filho usarão para localizá-lo na rede local. Cada dispositivo IoT Edge downstream precisa especificar um parâmetro parent_hostname para identificar seu pai. Em um cenário hierárquico em que um único dispositivo IoT Edge é um dispositivo pai e um dispositivo filho, ele precisa de ambos os parâmetros.

    Os parâmetros hostname 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 menor que 64 caracteres, que é o limite de caracteres para um nome comum de certificado de servidor.

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

    Defina o nome do host antes que o contêiner edgeHub seja criado. Se o edgeHub estiver em execução, alterar o 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, consulte a seção Verificar configuração pai.

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

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

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

  5. Localize ou adicione a seção Certificado de autoridade de certificação de borda no arquivo de configuração. Atualize os parâmetros de certificado cert e chave pk privada com os caminhos de URI de arquivo para o certificado de cadeia completa e os arquivos de chave no dispositivo IoT Edge pai. O IoT Edge exige que o certificado e a chave privada estejam no formato PEM (email com privacidade aprimorada) 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 seu dispositivo IoT Edge usa a versão correta do agente do IoT Edge quando ele é iniciado. Encontre a seção Agente de Borda Padrão e defina o valor da imagem do IoT Edge para a versão 1.5. Por exemplo:

    [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 config.toml configuração. Por exemplo, se estiver a utilizar o nano editor, selecione Ctrl+O - Write out, Enter e Ctrl+X - Exit.

  9. Se você já usou outros certificados para o IoT Edge antes, exclua os arquivos nos dois diretórios a seguir para garantir que seus novos certificados sejam aplicados:

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

  10. Aplique as alterações.

    sudo iotedge config apply

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

    sudo iotedge check --verbose

    Nota

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

    × prontidão para produção: o diretório de armazenamento do Edge Hub é mantido no sistema de arquivos host - Erro

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

    Esse erro é esperado em um dispositivo recém-provisionado porque o módulo IoT Edge Hub 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 IoT Edge Hub.

Verificar a configuração pai

O nome do host deve ser um nome de domínio qualificado (FQDN) ou o endereço IP do dispositivo IoT Edge porque o IoT Edge usa esse valor no certificado do servidor quando dispositivos downstream se conectam. Os valores devem corresponder ou você receberá erro de incompatibilidade de endereço IP.

Para verificar o nome do host, 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 hostnameconfig.toml. Se não corresponder, o contêiner 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. Quando 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 dispositivo downstream

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

Para habilitar conexões seguras, cada dispositivo downstream do IoT Edge em um cenário de gateway precisa ser configurado com um certificado de CA de dispositivo exclusivo e uma cópia do certificado de CA raiz compartilhado por todos os dispositivos na hierarquia de gateway.

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

  2. Transfira o certificado de autoridade de certificação raiz, o certificado de autoridade de certificação do dispositivo filho e a chave privada filho para o dispositivo downstream.

  3. Copie os certificados e 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 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 autoridade de certificação raiz no dispositivo IoT Edge downstream atualizando o armazenamento de certificados no dispositivo usando o 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 como usar update-ca-trust no EFLOW, consulte CBL-Mariner SSL CA certificates management.

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

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

Atualizar arquivo de configuração downstream

Você já deve ter o IoT Edge instalado no seu dispositivo. Caso contrário, siga as etapas para provisionar manualmente um único dispositivo Linux IoT Edge.

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

    Se o arquivo de configuração não existir no seu 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 do IoT Edge usando um editor. Por exemplo, use o nano editor para abrir o /etc/aziot/config.toml arquivo.

    sudo nano /etc/aziot/config.toml

  3. Encontre o parâmetro parent_hostname ou adicione-o ao início do arquivo de configuração Todo dispositivo IoT Edge downstream precisa especificar um parâmetro parent_hostname para identificar seu pai. Atualize o parent_hostname parâmetro para ser o FQDN ou o endereço IP do dispositivo pai, correspondendo ao que foi fornecido como o nome do host no arquivo de configuração do dispositivo pai. Por exemplo:

    parent_hostname = "10.0.0.4"

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

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

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

  5. Localize ou adicione a seção Certificado de CA de Borda no arquivo de configuração. Atualize os parâmetros de certificado cert e chave pk privada com os caminhos de URI de arquivo para o certificado de cadeia completa e os arquivos de chave no dispositivo downstream do IoT Edge. O IoT Edge exige que o certificado e a chave privada estejam no formato PEM (email com privacidade aprimorada) 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 seu dispositivo IoT Edge usa a versão correta do agente do IoT Edge quando ele é iniciado. Encontre a seção Agente de Borda Padrão e defina o valor da imagem do IoT Edge para a versão 1.5. Por exemplo:

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

  7. O início do arquivo de configuração 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 config.toml configuração. Por exemplo, se estiver a utilizar o nano editor, selecione Ctrl+O - Write out, Enter e Ctrl+X - Exit.

  9. Se você já usou outros certificados para o IoT Edge antes, exclua os arquivos nos dois diretórios a seguir para garantir que seus novos certificados sejam aplicados:

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

  10. Aplique as alterações.

    sudo iotedge config apply

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

    sudo iotedge check --verbose

    Gorjeta

    A ferramenta de verificação do IoT Edge usa um contêiner para executar parte da verificação de diagnóstico. Se você quiser usar essa ferramenta em dispositivos IoT Edge downstream, certifique-se de que eles possam acessar mcr.microsoft.com/azureiotedge-diagnostics:latestou ter a imagem de contêiner em seu registro de contêiner privado.

    Nota

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

    × prontidão para produção: o diretório de armazenamento do Edge Hub é mantido no sistema de arquivos host - Erro

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

    Esse erro é esperado em um dispositivo recém-provisionado porque o módulo IoT Edge Hub 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 IoT Edge Hub.

Dispositivos downstream isolados em rede

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

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

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

  • O módulo de proxy de API é necessário em qualquer gateway do IoT Edge que tenha outro dispositivo IoT Edge abaixo dele. Isso significa que ele deve estar em todas as camadas de uma hierarquia de gateway, exceto na camada inferior. Este módulo usa um proxy reverso nginx para rotear dados HTTP através de camadas de rede em uma única porta. É altamente configurável através do seu módulo twin e variáveis de ambiente, pelo que pode ser ajustado para se adequar aos requisitos do seu cenário de gateway.

  • O módulo de registro do Docker pode ser implantado no gateway IoT Edge na camada superior de uma hierarquia de gateway. Este módulo é responsável por recuperar e armazenar em cache imagens de contêiner em nome de todos os dispositivos IoT Edge em camadas inferiores. A alternativa para implantar este módulo na camada superior é usar um registro local ou carregar manualmente 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. Este módulo é responsável por carregar blobs em nome de todos os dispositivos IoT Edge em camadas inferiores. A capacidade de carregar blobs também permite uma funcionalidade útil de solução de problemas para dispositivos IoT Edge em camadas inferiores, como upload de log de módulo e upload de pacote de suporte.

Configuração de rede

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

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

  • Autorize comunicações de saída desse endereço IP para seu nome de host do Hub IoT do Azure pelas portas 443 (HTTPS) e 5671 (AMQP).

  • Autorize comunicações de saída desse endereço IP para seu nome de host do Registro de Contêiner do Azure pela porta 443 (HTTPS).

    O módulo de proxy da API só pode lidar com conexões com um registro de contêiner de cada vez. Recomendamos que todas as imagens de contêiner, incluindo as imagens públicas fornecidas pelo Microsoft Container Registry (mcr.microsoft.com), sejam armazenadas em seu registro de contêiner privado.

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

  • Forneça um endereço IP estático.
  • Autorize comunicações de saída desse endereço IP para o endereço IP do gateway pai pelas portas 443 (HTTPS) e 5671 (AMQP).

Implantar módulos em dispositivos de camada superior

O dispositivo IoT Edge na camada superior de uma hierarquia de gateway tem um conjunto de módulos necessários que devem ser implantados nele, além de quaisquer 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 a maioria dos cenários de gateway comuns. Este artigo fornece um exemplo para configurar os módulos em uma configuração básica. Consulte Configurar o módulo de proxy de API para seu cenário de hierarquia de gateway para obter informações mais detalhadas e exemplos.

  1. No Portal do Azure, navegue para o seu hub IoT.

  2. Selecione Dispositivos no menu Gerenciamento de dispositivos.

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

  4. Selecione Definir módulos.

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

  6. Procure e selecione o módulo IoT Edge API Proxy .

  7. Selecione o nome do módulo de proxy de API na lista de módulos implantados e atualize as seguintes configurações de módulo:

    1. Na guia Variáveis de ambiente, atualize o valor de NGINX_DEFAULT_PORT para 443.

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

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

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

  8. Selecione Configurações de tempo de execução e localize as opções de criação do módulo edgeHub. Exclua a ligação de porta para a porta 443, deixando as ligações para as portas 5671 e 8883.

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

  9. Selecione Salvar para salvar as alterações nas configurações de tempo de execução.

  10. Selecione Adicionar novamente e, em seguida, escolha Módulo IoT Edge.

  11. Forneça os seguintes valores para adicionar o módulo de registro do Docker à sua implantação:

    1. Nome do módulo IoT Edge: registry

    2. Na guia Configurações do módulo, URI da imagem:registry:latest

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

      • Nome: REGISTRY_PROXY_REMOTEURLValor: A URL do registro de contêiner para o qual você deseja mapear este módulo do Registro. Por exemplo, https://myregistry.azurecr.

        O módulo de registro só pode mapear para um registro de contêiner, portanto, recomendamos ter todas as imagens de contêiner em um único registro de contêiner privado.

      • Nome: REGISTRY_PROXY_USERNAMEValor: Nome de usuário para autenticar no registro do contêiner.

      • Nome: REGISTRY_PROXY_PASSWORDValor: Senha para autenticar no registro do contêiner.

    4. Na guia Opções de criação de contêiner, cole:

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

  12. Selecione Adicionar para adicionar o módulo à implantação.

  13. Selecione Next: Routes para ir para a próxima etapa.

  14. Para permitir que mensagens de dispositivo para nuvem de dispositivos downstream cheguem ao Hub IoT, inclua uma rota que passe todas as mensagens para o Hub IoT. Por exemplo:

    1. Designação: Route
    2. Valor: FROM /messages/* INTO $upstream

  15. Selecione Rever + criar para ir para a etapa final.

  16. Selecione Criar para implantar no seu dispositivo.

Implantar módulos em dispositivos de camada inferior

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

Extrair imagens de contêiner de rota

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

Se seus dispositivos de camada inferior não puderem se conectar à nuvem, mas você quiser que eles extraiam imagens de módulo como de costume, o dispositivo de camada superior da hierarquia de gateway deverá ser configurado para lidar com essas solicitações. O dispositivo de camada superior precisa executar um módulo de registro do Docker que é mapeado para o registro do contêiner. Em seguida, configure o módulo de proxy da API para rotear solicitações de contêiner para ele. Esses detalhes são discutidos nas seções anteriores deste artigo. Nessa configuração, os dispositivos de camada inferior não devem apontar para registros de contêiner em 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 inferior devem chamar $upstream:443/azureiotedge-api-proxy:1.1.

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

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

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

Inicializar o agente do IoT Edge

O agente do IoT Edge é o primeiro componente de tempo de execução a ser iniciado em qualquer dispositivo IoT Edge. Você precisa certificar-se de que todos os dispositivos IoT Edge downstream possam acessar a imagem do módulo edgeAgent quando forem iniciados e, em seguida, possam acessar implantações e iniciar o restante das imagens do módulo.

Quando você entra no arquivo de configuração em um dispositivo IoT Edge para fornecer suas informações de autenticação, certificados e nome de host pai, atualize também a imagem do 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 do host pai e pela porta de escuta do proxy da API. No manifesto de implantação, você pode usar $upstream como um atalho, mas isso requer o módulo edgeHub para lidar com o roteamento e esse módulo não foi iniciado neste momento. 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 as imagens de contêiner manualmente no dispositivo, atualize o arquivo de configuração de acordo.

Configurar o tempo de execução e implantar o módulo proxy

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

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

  1. No Portal do Azure, navegue para o seu hub IoT.

  2. Selecione Dispositivos no menu Gerenciamento de dispositivos.

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

  4. Selecione Definir módulos.

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

  6. Procure e selecione o módulo IoT Edge API Proxy .

  7. Selecione o nome do módulo de proxy de API na lista de módulos implantados e atualize as seguintes configurações de módulo:

    1. Na guia Configurações do módulo, atualize o valor do URI da imagem. Substituir mcr.microsoft.com por $upstream:443.

    2. Na guia Variáveis de ambiente, atualize o valor de NGINX_DEFAULT_PORT para 443.

    3. Na guia Opções de criação de contêiner, atualize as ligações de porta para a porta de referência 443.

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

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

  8. Selecione Configurações de tempo de execução.

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

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

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

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

  11. Selecione Salvar para salvar as alterações nas configurações de tempo de execução.

  12. Selecione Next: Routes para ir para a próxima etapa.

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

    1. Designação: Route
    2. Valor: FROM /messages/* INTO $upstream

  14. Selecione Rever + criar para ir para a etapa final.

  15. Selecione Criar para implantar no seu dispositivo.

Verificar a conectividade da criança para o pai

  1. Verifique a conexão TLS/SSL do filho para o pai executando o seguinte openssl comando no dispositivo downstream. Substitua <parent hostname> pelo FQDN ou 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 depth=0 CN = valor deve corresponder ao parâmetro hostname especificado no arquivo de configuração do config.toml pai.

    Se o comando expirar, pode haver portas bloqueadas entre os dispositivos filho e pai. Reveja a configuração de rede e as definiçõ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 openssl s_client ... comando 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 IoT Edge downstream se o certificado de dispositivo de cadeia completa não for usado e configurado no dispositivo downstream.

Integre o Microsoft Defender para IoT com o gateway IoT Edge

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

Saiba mais sobre o microagente do Defender for IoT.

Para integrar o Microsoft Defender for IoT com o IoT Edge usando proxy de dispositivo downstream:

  1. Inicie sessão no portal do Azure.

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

  3. Selecione o seu dispositivo.

    Captura de ecrã a mostrar onde o dispositivo está localizado para seleção.

  4. Selecione o DefenderIotMicroAgent módulo twin que você criou a partir destas instruções.

    Captura de tela mostrando a localização do DefenderIotMicroAgent.

  5. Selecione o botão para copiar a cadeia 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. Por exemplo, HostName=nested11.azure-devices.net;DeviceId=downstream1;ModuleId=module1;SharedAccessKey=xxx;GatewayHostName=10.16.7.4.

  7. Abra um terminal no dispositivo a jusante.

  8. Use o seguinte comando para colocar a cadeia de conexão codificada em utf-8 no diretório do agente do Defender for Cloud no arquivo no seguinte connection_string.txt 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 deve agora estar localizado no seguinte local /etc/defender_iot_micro_agent/connection_string.txtdo caminho.

  9. Reinicie o serviço usando este comando:

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

  10. Navegue de volta para o dispositivo.

    Captura de ecrã a mostrar como navegar de volta para o seu dispositivo.

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

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

  12. Selecione o dispositivo pai na lista exibida.

  13. Verifique se a porta 8883 (MQTT) entre o dispositivo downstream e o dispositivo IoT Edge está aberta.

Próximos passos

De que forma um dispositivo IoT Edge pode ser utilizado como gateway

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