Configurar um dispositivo IoT Edge para se comunicar por meio de um servidor proxy

Aplica-se ao IoT Edge 1.1

Importante

A data de término do suporte do IoT Edge 1.1 foi em 13 de dezembro de 2022. Verifique o ciclo de vida do produto microsoft para obter informações sobre como este produto, serviço, tecnologia ou API tem suporte. Para obter mais informações sobre como atualizar para a versão mais recente do IoT Edge, consulte Atualizar o IoT Edge.

Os dispositivos IoT Edge enviam solicitações HTTPS para se comunicarem com o Hub IoT. Se o dispositivo estiver conectado a uma rede que usa um servidor proxy, você precisará configurar o runtime do IoT Edge para se comunicar por meio do servidor. Os servidores proxy também poderão afetar módulos individuais do IoT Edge se fizerem solicitações HTTP ou HTTPS que não são roteados por meio do hub do IoT Edge.

Este artigo examina as quatro seguintes etapas para configurar e gerenciar um dispositivo IoT Edge por trás de um servidor proxy:

Instalar o runtime do IoT Edge em seu dispositivo

Os scripts de instalação do IoT Edge efetuam pull de pacotes e arquivos da Internet. Portanto, o dispositivo precisa se comunicar pelo servidor proxy para fazer essas solicitações. Nos dispositivos Windows, o script de instalação também oferece uma opção de instalação offline.

Esta etapa é um processo único para configurar o dispositivo IoT Edge ao configurá-lo pela primeira vez. As mesmas conexões também são necessárias quando você atualiza o runtime do IoT Edge.
Configurar o IoT Edge e o runtime do contêiner em seu dispositivo

O IoT Edge é responsável pelas comunicações com o Hub IoT. O runtime de contêiner é responsável pelo gerenciamento de contêineres e, portanto, comunica-se com os registros de contêiner. Esses dois componentes precisam fazer solicitações da Web por meio do servidor proxy.

Esta etapa é um processo único para configurar o dispositivo IoT Edge ao configurá-lo pela primeira vez.
Configurar as propriedades do agente do IoT Edge no arquivo de configuração em seu dispositivo

A princípio, o daemon do IoT Edge inicia o módulo edgeAgent. Em seguida, o módulo edgeAgent recupera o manifesto de implantação do Hub IoT e inicia todos os outros módulos. Para que o agente do IoT Edge faça a conexão inicial com o Hub IoT, configure as variáveis de ambiente do módulo edgeAgent manualmente no próprio dispositivo. Depois da conexão inicial, você pode configurar o módulo edgeAgent remotamente.

Esta etapa é um processo único para configurar o dispositivo IoT Edge ao configurá-lo pela primeira vez.
Para todas as implantações futuras do módulo, defina variáveis de ambiente para qualquer módulo que se comunique por meio do proxy

Depois que o dispositivo IoT Edge for configurado e conectado ao Hub IoT por meio do servidor proxy, você precisará manter a conexão em todas as implantações futuras do módulo.

Esta etapa é um processo contínuo feito remotamente. Portanto, todos as novas atualizações de módulo ou implantação manterão a capacidade do dispositivo de se comunicar por meio do servidor proxy.

Saber a sua URL do proxy

Antes de seguir qualquer etapa deste artigo, você precisa saber a URL do proxy.

As URLs de proxy assumem o seguinte formato: protocolo://proxy_host:proxy_port.

O protocolo é HTTP ou HTTPS. O daemon do Docker pode usar qualquer protocolo, dependendo das configurações do registro de contêiner, mas o daemon do IoT Edge e os contêineres de runtime sempre devem usar HTTPS 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: proxy_host de usuário:senha@.
O proxy_port é a porta de rede na qual o proxy responde ao tráfego de rede.

Instalar o IoT Edge por meio de um proxy

Independentemente do dispositivo IoT Edge ser executado no Windows ou no Linux, você precisa acessar os pacotes de instalação por meio do servidor proxy. Dependendo do sistema operacional, siga as etapas para instalar o runtime do IoT Edge por meio de um servidor proxy.

Dispositivos do Linux

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

Dispositivos Windows que usam o IoT Edge para Linux no Windows

Se você estiver instalando o runtime do IoT Edge usando o IoT Edge para Linux no Windows, o IoT Edge será instalado por padrão na sua máquina virtual Linux. Nenhuma instalação adicional ou etapas de atualização são necessárias.

Dispositivos Windows que usam contêineres do Windows

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

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

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 fazer download dos 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 somente requer informações de proxy para o 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 ser incluído na URL, use o -ProxyCredential parâmetro dentro -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. Para obter mais informações sobre os parâmetros de instalação do Windows, consulte os scripts do PowerShell para IoT Edge no Windows.

Configurar IoT Edge e Moby

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

Tanto o Moby quanto os daemons do IoT Edge precisam ser configurados para usar o servidor proxy para a funcionalidade contínua do dispositivo. Essa etapa ocorre no dispositivo IoT Edge durante a configuração inicial do dispositivo.

Daemon do Moby

Como o Moby é integrado ao Docker, veja a documentação do Docker para configurar o daemon do Moby com variáveis de ambiente. A maioria dos registros de contêiner (incluindo o DockerHub e os Registros de Contêiner do Azure) dá 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 dá suporte à TLS (segurança de camada de transporte), defina o parâmetro HTTP_PROXY .

Escolha o artigo que se aplica ao 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 paralelamente em um dispositivo Windows.

Daemon do IoT Edge

O daemon do IoT Edge é configurado de maneira semelhante ao daemon moby. Use as etapas a seguir para definir uma variável de ambiente para o serviço, com base em 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 iotedge

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

[Service]
Environment=https_proxy=<proxy URL>

Atualize o gerenciador de serviços para pegar a nova configuração do IoT Edge.

sudo systemctl daemon-reload

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

sudo systemctl restart iotedge

Verifique se a variável de ambiente foi criada e se a nova configuração foi carregada.

systemctl show --property=Environment iotedge

Windows que usa o IoT Edge para Linux no Windows

Faça logon no IoT Edge para Linux na máquina virtual do Windows:

Connect-EflowVm

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

Windows que usa 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 <a URL> do proxy pelo endereço do servidor proxy e pela porta.

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 dispositivo IoT Edge

O agente IoT Edge é o primeiro módulo a ser iniciado em qualquer dispositivo IoT Edge. Ele é iniciado pela primeira vez com base nas informações no arquivo de configuração do IoT Edge. O agente do IoT Edge então se conecta ao Hub IoT para recuperar manifestos de implantação, que declaram quais outros módulos devem ser implantados no dispositivo.

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

Abra o arquivo config.yaml em seu dispositivo IoT Edge. Em sistemas Linux, esse arquivo está localizado em /etc/iotedge/config.yaml. Em sistemas Windows, esse arquivo está localizado em C:\ProgramData\iotedge\config.yaml. O arquivo de configuração é protegido, portanto, você precisa de privilégios administrativos para acessá-lo. Em sistemas Linux, use o comando sudo antes de abrir o arquivo no seu editor de texto preferido. No Windows, abra um editor de texto como o Bloco de Notas como administrador e abra o arquivo.
No arquivo config.yaml, localize a seção de especificação do módulo de Agente de Borda. A definição do agente do IoT Edge inclui um parâmetro env em que você pode adicionar variáveis de ambiente.
Remova os colchetes que são espaços reservados para o parâmetro env e adicione a nova variável em uma nova linha. Lembre-se de que a indentação no YAML é de dois espaços.
```
https_proxy: "<proxy URL>"
```
O runtime do IoT Edge usa o AMQP por padrão para falar com o IoT Hub. Alguns servidores proxy bloqueiam as portas AMQP. Se for esse o caso, você também precisará configurar o edgeAgent para usar o AMQP em WebSocket. Adicione uma segunda variável de ambiente.
```
UpstreamProtocol: "AmqpWs"
```
Salve as alterações em config.yaml e feche o editor. Reinicie o IoT Edge para que as alterações entrem em vigor.
- Linux e IoT Edge para Linux no Windows:
```
sudo systemctl restart iotedge
```
- Windows usando contêineres do Windows:
```
Restart-Service iotedge
```

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

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

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

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

O runtime do IoT Edge usa o AMQP por padrão para falar com o IoT Hub. Alguns servidores proxy bloqueiam as portas AMQP. Se for esse o caso, você também precisará configurar o edgeAgent para usar o AMQP em WebSocket. Remova a marca de comentário do parâmetro UpstreamProtocol.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Salve as alterações e feche o editor. Aplique as suas últimas alterações.
```
sudo iotedge config apply
```
Verifique se as configurações de proxy são propagadas usando docker inspect edgeAgent na seção Env. Caso contrário, o contêiner deve ser recriado.
```
sudo docker rm -f edgeAgent
```
O runtime do IoT Edge deve ser recriado edgeAgent dentro de um minuto. Depois que o edgeAgent contêiner estiver em execução novamente, docker inspect edgeAgent verifique se as configurações de proxy correspondem ao arquivo de configuração.

Configurar manifestos de implantação

Depois que o dispositivo IoT Edge estiver configurado para funcionar com o servidor proxy, você precisará continuar a declarar a variável de ambiente HTTPS_PROXY em manifestos de implantação futuros. Você pode editar os 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 runtime: edgeAgent e edgeHub para se comunicar por meio do servidor proxy para que eles 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 será editar 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 outros recursos do Azure além do Hub IoT, como o armazenamento de blobs, devem ter a variável HTTPS_PROXY especificada no arquivo de manifesto de implantação.

O procedimento a seguir se aplica durante a vida útil do dispositivo IoT Edge.

Portal do Azure

Quando você usa o assistente Definir módulos para criar implantações para dispositivos do IoT Edge, cada módulo tem uma seção Variáveis de Ambiente em que 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 Runtime Settings na primeira etapa do assistente.

Definir configurações avançadas do Edge Runtime

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

Definir a variável de ambiente https_proxy

Todos os outros módulos adicionados a um manifesto de implantação seguem o mesmo padrão.

Arquivos de manifesto de implantação de 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.

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 ser semelhante ao seguinte exemplo edgeHub:

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
        "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 à definição do módulo do agente do IoT Edge também.

"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 o tráfego criptografado em TLS. Durante a inspeção do tráfego TLS, o certificado retornado pelo proxy não é o do servidor de destino, mas aquele assinado pelo próprio certificado raiz do proxy. Por padrão, o certificado desse proxy não é confiável pelos módulos do IoT Edge (incluindo edgeAgent e edgeHub) e o handshake do TLS falha.

Para resolver isso, o certificado raiz do proxy precisa ser confiável tanto pelo sistema operacional quanto pelos módulos do IoT Edge.

Configure o certificado do proxy no repositório de certificados raiz confiáveis do sistema operacional host. Para obter mais informações sobre como instalar um certificado raiz, consulte Instalar a CA raiz no repositório de certificados do sistema operacional.
Configure o 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 conjunto de certificados de confiança, consulte Gerenciar AC raiz confiável (conjunto de certificados de confiança).

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

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

Se o proxy tiver um firewall que exija que você coloque todos os FQDNs na lista de permissões para conectividade com a internet, examine a lista de Permitir conexões de dispositivos IoT Edge para determinar quais FQDNs adicionar.

Próximas etapas

Saiba mais sobre as funções do runtime do IoT Edge.

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

Last updated on 2022-07-26

Compartilhar via