Configurar um dispositivo IoT Edge para comunicar através de um servidor proxy

Artigo
04/11/2024

Aplica-se a: IoT Edge 1.5 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.

Os dispositivos IoT Edge enviam solicitações HTTPS para se comunicar com o Hub IoT. Se você conectou seu dispositivo a uma rede que usa um servidor proxy, precisará configurar o tempo de execução do IoT Edge para se comunicar através do servidor. Os servidores proxy também podem afetar módulos individuais do IoT Edge se fizerem solicitações HTTP ou HTTPS que você não roteou pelo hub do IoT Edge.

Este artigo descreve as quatro etapas a seguir para configurar e gerenciar um dispositivo IoT Edge atrás de um servidor proxy:

Instalar o tempo de execução do IoT Edge no seu dispositivo

Os scripts de instalação do IoT Edge extraem pacotes e arquivos da Internet, portanto, seu dispositivo precisa se comunicar por meio do servidor proxy para fazer essas solicitações. Para dispositivos Windows, o script de instalação também fornece uma opção de instalação offline.

Esta etapa é um processo único para configurar o dispositivo IoT Edge quando você o configura pela primeira vez. Você também precisa dessas mesmas conexões quando atualiza o tempo de execução do IoT Edge.
Configurar o IoT Edge e o tempo de execução do contêiner em seu dispositivo

O IoT Edge é responsável pelas comunicações com o Hub IoT. O tempo de execução do contêiner é responsável pelo gerenciamento do contêiner, portanto, se comunica com os registros de contêiner. Ambos os componentes precisam fazer solicitações da Web através do servidor proxy.

Esta etapa é um processo único para configurar o dispositivo IoT Edge quando você o configura pela primeira vez.
Configurar as propriedades do agente do IoT Edge no arquivo de configuração em seu dispositivo

O daemon IoT Edge inicia o módulo edgeAgent inicialmente. Em seguida, o módulo edgeAgent recupera o manifesto de implantação do Hub IoT e inicia todos os outros módulos. Configure as variáveis de ambiente do módulo edgeAgent manualmente no próprio dispositivo, para que o agente do IoT Edge possa fazer a conexão inicial com o Hub IoT. Após a conexão inicial, você pode configurar o módulo edgeAgent remotamente.

Esta etapa é um processo único para configurar o dispositivo IoT Edge quando você o configura pela primeira vez.
Para todas as implantações futuras de módulos, defina variáveis de ambiente para qualquer módulo que se comunique através do proxy

Depois de configurar e conectar um dispositivo IoT Edge ao Hub IoT por meio do servidor proxy, você precisa manter a conexão em todas as implantações de módulo futuras.

Esta etapa é um processo contínuo feito remotamente para que cada novo módulo ou atualização de implantação mantenha a capacidade do dispositivo de se comunicar através do servidor proxy.

Conheça o URL do seu proxy

Antes de começar qualquer uma das etapas neste artigo, você precisa saber sua URL de proxy.

As URLs de proxy têm o seguinte formato: protocol://proxy_host:proxy_port.

O protocolo é HTTP ou HTTPS. O daemon do Docker pode usar qualquer protocolo, dependendo das configurações do Registro do contêiner, mas o daemon do IoT Edge e os contêineres de tempo de execução devem sempre usar HTTP para se conectar ao proxy.
O proxy_host é um endereço para o servidor proxy. Se o servidor proxy exigir autenticação, você poderá fornecer suas credenciais como parte do host proxy com o seguinte formato: user:password@proxy_host.
A proxy_port é a porta de rede na qual o proxy responde ao tráfego de rede.

Instalar o IoT Edge através de um proxy

Quer o seu dispositivo IoT Edge seja executado em Windows ou Linux, tem de aceder aos pacotes de instalação através do servidor proxy. Dependendo do seu sistema operacional, siga as etapas para instalar o tempo de execução do IoT Edge por meio de um servidor proxy.

Dispositivos Linux

Se você estiver instalando o tempo de execução do IoT Edge em um dispositivo Linux, configure o gerenciador de pacotes para passar pelo servidor proxy para acessar o pacote de instalação. Por exemplo, configure o apt-get para usar um http-proxy. Depois de configurar seu gerenciador de pacotes, siga as instruções em Instalar o tempo de execução do Azure IoT Edge como de costume.

Dispositivos Windows usando IoT Edge para Linux no Windows

Se você estiver instalando o tempo de execução do IoT Edge usando o IoT Edge para Linux no Windows, o IoT Edge será instalado por padrão em sua máquina virtual Linux. Não é necessário instalar ou atualizar quaisquer outros passos.

Dispositivos Windows usando contêineres do Windows

Se você estiver instalando o tempo de execução do IoT Edge em um dispositivo Windows, precisará passar pelo servidor proxy duas vezes. A primeira conexão baixa o arquivo de script do instalador e a segunda conexão é durante a instalação para baixar os componentes necessários. Você pode configurar informações de proxy nas configurações do Windows ou incluir suas informações de proxy diretamente nos comandos do PowerShell.

As etapas a seguir demonstram um exemplo de uma instalação do Windows usando o -proxy argumento:

O comando Invoke-WebRequest precisa de informações de proxy para acessar o script do instalador. Em seguida, o comando Deploy-IoTEdge precisa das informações de proxy para baixar os arquivos de instalação.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
O comando Initialize-IoTEdge não precisa passar pelo servidor proxy, portanto, a segunda etapa requer apenas informações de proxy para Invoke-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

Se você tiver credenciais complicadas para o servidor proxy que não pode incluir na URL, use o -ProxyCredential parâmetro em -InvokeWebRequestParameters. Por exemplo,

$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }

Para obter mais informações sobre parâmetros de proxy, consulte Invoke-WebRequest.

Configurar o IoT Edge e o Moby

O IoT Edge depende de dois daemons em execução no dispositivo IoT Edge. O daemon Moby faz solicitações da Web para extrair imagens de contêiner de registros de contêiner. O daemon IoT Edge faz solicitações da Web para se comunicar com o Hub IoT.

Você deve configurar os daemons Moby e IoT Edge para usar o servidor proxy para funcionalidade contínua do dispositivo. Esta etapa ocorre no dispositivo IoT Edge durante a configuração inicial do dispositivo.

Daemon Moby

Como o Moby é construído no Docker, consulte a documentação do Docker para configurar o daemon Moby com variáveis de ambiente. A maioria dos registros de contêiner (incluindo o DockerHub e o Azure Container Registries) oferece suporte a solicitações HTTPS, portanto, o parâmetro que você deve definir é HTTPS_PROXY. Se você estiver extraindo imagens de um registro que não suporta TLS (Transport Layer Security), defina o parâmetro HTTP_PROXY .

Escolha o artigo que se aplica ao seu sistema operacional do dispositivo IoT Edge:

Configurar o daemon do Docker no Linux O daemon Moby em dispositivos Linux mantém o nome Docker.
Configurar o daemon do Docker no Windows O daemon Moby em dispositivos Windows é chamado iotedge-moby. Os nomes são diferentes porque é possível executar o Docker Desktop e o Moby em paralelo em um dispositivo Windows.

Daemon do IoT Edge

O daemon IoT Edge é semelhante ao daemon Moby. Use as etapas a seguir para definir uma variável de ambiente para o serviço, com base no seu sistema operacional.

O daemon do IoT Edge sempre usa HTTPS para enviar solicitações ao Hub IoT.

Linux

Abra um editor no terminal para configurar o daemon do IoT Edge.

sudo systemctl edit aziot-edged

Insira o seguinte texto, substituindo a URL> do <proxy pelo endereço e porta do servidor proxy. Em seguida, salve e saia.

[Service]
Environment="https_proxy=<proxy URL>"

A partir da versão 1.2, o IoT Edge usa o serviço de identidade IoT para lidar com o provisionamento de dispositivos com o Hub IoT ou o Serviço de Provisionamento de Dispositivos do Hub IoT. Abra um editor no terminal para configurar o daemon do serviço de identidade IoT.

sudo systemctl edit aziot-identityd

Insira o seguinte texto, substituindo a URL> do <proxy pelo endereço e porta do servidor proxy. Em seguida, salve e saia.

[Service]
Environment="https_proxy=<proxy URL>"

Atualize o gerenciador de serviços para pegar as novas configurações.

sudo systemctl daemon-reload

Reinicie os serviços do sistema IoT Edge para que as alterações em ambos os daemons entrem em vigor.

sudo iotedge system restart

Verifique se as variáveis de ambiente e a nova configuração estão presentes.

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

Windows usando IoT Edge para Linux no Windows

Entre no seu IoT Edge para Linux na máquina virtual Windows:

Connect-EflowVm

Siga as mesmas etapas da seção Linux deste artigo para configurar o daemon do IoT Edge.

Windows usando contêineres do Windows

Abra uma janela do PowerShell como administrador e execute o seguinte comando para editar o registro com a nova variável de ambiente. Substitua <url> proxy pelo endereço e porta do servidor proxy.

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

Reinicie o IoT Edge para que as alterações entrem em vigor.

Restart-Service iotedge

Configurar o agente IoT Edge

O agente IoT Edge é o primeiro módulo a ser iniciado em qualquer dispositivo IoT Edge. Este módulo é iniciado pela primeira vez com base nas informações do arquivo de configuração do IoT Edge. Em seguida, o agente do IoT Edge se conecta ao Hub IoT para recuperar manifestos de implantação. O manifesto declara quais outros módulos o dispositivo deve implantar.

Esta etapa ocorre uma vez no dispositivo IoT Edge durante a configuração inicial do dispositivo.

Abra o arquivo de configuração no dispositivo IoT Edge: /etc/aziot/config.toml. Você precisa de privilégios administrativos para acessar o arquivo de configuração. Em sistemas Linux, use o sudo comando antes de abrir o arquivo em seu editor de texto preferido.
No arquivo de configuração, localize a [agent] seção , que contém todas as informações de configuração para o módulo edgeAgent usar na inicialização. Verifique se a [agent] seção está sem comentários. Se a [agent] seção estiver faltando, adicione-a config.tomlao arquivo . A definição do agente IoT Edge inclui uma [agent.env] subseção onde você pode adicionar variáveis de ambiente.

Adicione o parâmetro https_proxy à seção de variáveis de ambiente e defina sua URL de proxy como seu valor.

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

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

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

O tempo de execução do IoT Edge usa AMQP por padrão para falar com o Hub IoT. Alguns servidores proxy bloqueiam portas AMQP. Se esse for o caso, você também precisará configurar o edgeAgent para usar AMQP sobre WebSocket. Descomente o UpstreamProtocol parâmetro.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```

Adicione o parâmetro https_proxy à seção de variáveis de ambiente e defina sua URL de proxy como seu valor.

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

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

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

O tempo de execução do IoT Edge usa AMQP por padrão para falar com o Hub IoT. Alguns servidores proxy bloqueiam portas AMQP. Se esse for o caso, você também precisará configurar o edgeAgent para usar AMQP sobre WebSocket. Descomente o UpstreamProtocol parâmetro.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Salve as alterações e feche o editor. Aplique as alterações mais recentes.
```
sudo iotedge config apply
```
Verifique se as configurações de proxy são propagadas usando docker inspect edgeAgent a Env seção . Caso contrário, você deve recriar o contêiner.
```
sudo docker rm -f edgeAgent
```
O tempo de execução do IoT Edge deve ser recriado edgeAgent em um minuto. Quando o edgeAgent contêiner estiver sendo executado novamente, use o docker inspect edgeAgent comando para verificar se as configurações de proxy correspondem ao arquivo de configuração.

Configurar manifestos de implantação

Depois de configurar seu dispositivo IoT Edge para trabalhar com seu servidor proxy, declare a variável de ambiente HTTPS_PROXY em manifestos de implantação futuros. Você pode editar manifestos de implantação usando o assistente do portal do Azure ou editando um arquivo JSON de manifesto de implantação.

Sempre configure os dois módulos de tempo de execução, edgeAgent e edgeHub, para se comunicarem através do servidor proxy para que possam manter uma conexão com o Hub IoT. Se você remover as informações de proxy do módulo edgeAgent, a única maneira de restabelecer a conexão é editando o arquivo de configuração no dispositivo, conforme descrito na seção anterior.

Além dos módulos edgeAgent e edgeHub, outros módulos podem precisar da configuração de proxy. Os módulos que precisam acessar recursos do Azure além do Hub IoT, como armazenamento de blob, devem ter a variável HTTPS_PROXY especificada no arquivo de manifesto de implantação.

O procedimento a seguir é aplicável durante toda a vida útil do dispositivo IoT Edge.

Portal do Azure

Quando você usa o assistente Definir módulos para criar implantações para dispositivos IoT Edge, cada módulo tem uma seção Variáveis de Ambiente onde você pode configurar conexões de servidor proxy.

Para configurar o agente do IoT Edge e os módulos do hub do IoT Edge, selecione Configurações de tempo de execução na primeira etapa do assistente.

Captura de tela de como definir configurações avançadas do Edge Runtime.

Adicione a variável de ambiente https_proxy às definições de configurações de tempo de execução do agente do IoT Edge e do módulo do hub IoT Edge. Se você incluiu a variável de ambiente UpstreamProtocol no arquivo de configuração em seu dispositivo IoT Edge, adicione-a também à definição do módulo do agente do IoT Edge.

Todos os outros módulos que você adiciona a um manifesto de implantação seguem o mesmo padrão. Selecione Aplicar para guardar as alterações.

Arquivos de manifesto de implantação JSON

Se você criar implantações para dispositivos IoT Edge usando os modelos no Visual Studio Code ou criando manualmente arquivos JSON, poderá adicionar as variáveis de ambiente diretamente a cada definição de módulo. Se você não os adicionou no portal do Azure, adicione-os aqui ao seu arquivo de manifesto JSON. Substitua <proxy URL> pelo seu próprio valor.

Use o seguinte formato JSON:

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

Com as variáveis de ambiente incluídas, sua definição de módulo deve se parecer com o seguinte exemplo de edgeHub:

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

Se você incluiu a variável de ambiente UpstreamProtocol no arquivo confige.yaml em seu dispositivo IoT Edge, adicione-a também à definição do módulo do agente do IoT Edge.

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

Trabalhando com proxies de inspeção de tráfego

Alguns proxies como o Zscaler podem inspecionar tráfego encriptado por TLS. Durante a inspeção de tráfego TLS, o certificado retornado pelo proxy não é o certificado do servidor de destino, mas é o certificado assinado pelo próprio certificado raiz do proxy. Por padrão, os módulos do IoT Edge (incluindo edgeAgent e edgeHub) não confiam no certificado desse proxy e o handshake TLS falha.

Para resolver o handshake com falha, configure o sistema operacional e os módulos do IoT Edge para confiar no certificado raiz do proxy com as etapas a seguir.

Configure o certificado de proxy no armazenamento de certificados raiz confiável do seu sistema operacional host. Para obter mais informações sobre como instalar um certificado raiz, consulte Instalar a autoridade de certificação raiz no armazenamento de certificados do sistema operacional.
Configure seu dispositivo IoT Edge para se comunicar por meio de um servidor proxy fazendo referência ao certificado no pacote de confiança. Para obter mais informações sobre como configurar o pacote de confiança, consulte Gerenciar CA raiz confiável (pacote de confiança).

Para configurar o suporte a proxy de inspeção de tráfego para contêineres não gerenciados pelo IoT Edge, entre em contato com seu provedor de proxy.

Nomes de domínio totalmente qualificados (FQDNs) de destinos com os quais o IoT Edge se comunica

Se o firewall do seu proxy exigir que você adicione todos os FQDNs à sua lista de permissões para conectividade com a Internet, revise a lista em Permitir conexões de dispositivos IoT Edge para determinar quais FQDNs adicionar.

Próximos passos

Saiba mais sobre as funções do tempo de execução do IoT Edge.

Solucionar erros de instalação e configuração com problemas e resoluções comuns para o Azure IoT Edge