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

Artigo
06/12/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.

Este artigo descreve as opções de configuração para o módulo de proxy de API, para que você possa personalizar o módulo para dar suporte aos requisitos de hierarquia de gateway.

O módulo de proxy de API simplifica a comunicação para dispositivos IoT Edge quando vários serviços são implantados que suportam o protocolo HTTPS e se ligam à porta 443. Isso é especialmente relevante em implantações hierárquicas de dispositivos IoT Edge em arquiteturas isoladas de rede baseadas em ISA-95, como as descritas em Dispositivos downstream isolados de rede, porque os clientes nos dispositivos downstream não podem se conectar diretamente à nuvem.

Por exemplo, para permitir que dispositivos IoT Edge downstream extraiam imagens do Docker, é necessário implantar um módulo de registro do Docker. Para permitir o carregamento de blobs, é necessário implantar um módulo de Armazenamento de Blobs do Azure no mesmo dispositivo IoT Edge. Ambos os serviços usam HTTPS para comunicação. O proxy de API permite essas implantações em um dispositivo IoT Edge. Em vez de cada serviço, o módulo de proxy de API se liga à porta 443 no dispositivo host e roteia a solicitação para o módulo de serviço correto em execução nesse dispositivo por regras configuráveis pelo usuário. Os serviços individuais ainda são responsáveis por lidar com as solicitações, incluindo autenticar e autorizar os clientes.

Sem o proxy de API, cada módulo de serviço teria que se vincular a uma porta separada no dispositivo host, exigindo uma alteração de configuração tediosa e propensa a erros em cada dispositivo filho que se conecta ao dispositivo IoT Edge pai.

Nota

Um dispositivo downstream emite dados diretamente para a Internet ou para dispositivos de gateway (habilitado para IoT Edge ou não). Um dispositivo filho pode ser um dispositivo downstream ou um dispositivo gateway em uma topologia aninhada.

Implantar o módulo proxy

O módulo de proxy da API está disponível no Microsoft Container Registry (MCR) e o URI da imagem é mcr.microsoft.com/azureiotedge-api-proxy:latest. Você pode implantar o módulo usando o portal do Azure ou a CLI do Azure.

Compreender o módulo proxy

O módulo de proxy API aproveita um proxy reverso nginx para rotear dados através de camadas de rede. Um proxy é incorporado no módulo, o que significa que a imagem do módulo precisa suportar a configuração de proxy. Por exemplo, se o proxy estiver escutando em uma determinada porta, o módulo precisará ter essa porta aberta.

O proxy começa com um arquivo de configuração padrão incorporado no módulo. Você pode passar uma nova configuração para o módulo a partir da nuvem usando seu módulo gêmeo. Além disso, você pode usar variáveis de ambiente para ativar ou desativar as definições de configuração no momento da implantação.

Este artigo se concentra primeiro no arquivo de configuração padrão e como usar variáveis de ambiente para habilitar suas configurações. Em seguida, discutimos a personalização do arquivo de configuração no final.

Configuração predefinida

O módulo de proxy da API vem com uma configuração padrão que suporta cenários comuns e permite personalização. Você pode controlar a configuração padrão através de variáveis de ambiente do módulo.

Atualmente, as variáveis de ambiente padrão incluem:

Variável de ambiente	Description
`PROXY_CONFIG_ENV_VAR_LIST`	Liste todas as variáveis que você pretende atualizar em uma lista separada por vírgula. Esta etapa evita a modificação acidental das definições de configuração erradas.
`NGINX_DEFAULT_TLS`	Especifica a lista de protocolos TLS a serem habilitados. Veja a ssl_protocols do NGINX. O padrão é 'TLSv1.2'.
`NGINX_DEFAULT_PORT`	Altera a porta que o proxy nginx escuta. Se você atualizar essa variável de ambiente, deverá expor a porta no dockerfile do módulo e declarar a ligação de porta no manifesto de implantação. Para obter mais informações, consulte Expor porta proxy. O padrão é 443. Quando implantada a partir do Azure Marketplace, a porta padrão é atualizada para 8000, para evitar conflitos com o módulo edgeHub. Para obter mais informações, consulte Minimizar portas abertas.
`DOCKER_REQUEST_ROUTE_ADDRESS`	Endereço para encaminhar solicitações do docker. Modifique essa variável no dispositivo de camada superior para apontar para o módulo do Registro. O padrão é o nome do host pai.
`BLOB_UPLOAD_ROUTE_ADDRESS`	Endereço para rotear solicitações de registro de blob. Modifique essa variável no dispositivo de camada superior para apontar para o módulo de armazenamento de blob. O padrão é o nome do host pai.

Minimizar portas abertas

Para minimizar o número de portas abertas, o módulo proxy da API deve retransmitir todo o tráfego HTTPS (porta 443), incluindo o tráfego direcionado ao módulo edgeHub. O módulo de proxy da API é configurado por padrão para redirecionar todo o tráfego do edgeHub na porta 443.

Use as seguintes etapas para configurar sua implantação para minimizar portas abertas:

Atualize as configurações do módulo edgeHub para não vincular na porta 443, caso contrário, haverá conflitos de vinculação de porta. Por padrão, o módulo edgeHub se liga às portas 443, 5671 e 8883. Exclua a ligação da porta 443 e deixe as outras duas no lugar:
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
Configure o módulo de proxy da API para vincular na porta 443.
1. Defina o valor da variável de ambiente NGINX_DEFAULT_PORT como 443.
2. Atualize o contêiner, crie opções para vincular na porta 443.
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

Se você não precisar minimizar as portas abertas, poderá permitir que o módulo edgeHub use a porta 443 e configure o módulo proxy da API para escutar em outra porta. Por exemplo, o módulo de proxy da API pode escutar na porta 8000 definindo o valor da variável 8000 de ambiente NGINX_DEFAULT_PORT e criando uma ligação de porta para a porta 8000.

Ativar o download de imagens de contêiner

Um caso de uso comum para o módulo de proxy de API é habilitar dispositivos IoT Edge em camadas inferiores para extrair imagens de contêiner. Este cenário usa o módulo de registro do Docker para recuperar imagens de contêiner da nuvem e armazená-las em cache na camada superior. O proxy da API retransmite todas as solicitações HTTPS para baixar uma imagem de contêiner das camadas inferiores a serem atendidas pelo módulo do Registro na camada superior.

Esse cenário requer que os dispositivos downstream do IoT Edge apontem para o nome $upstream de domínio seguido pelo número da porta do módulo de proxy de API em vez do registro de contêiner de uma imagem. Por exemplo: $upstream:8000/azureiotedge-api-proxy:1.1.

Esse caso de uso é demonstrado no tutorial Criar uma hierarquia de dispositivos IoT Edge usando gateways.

Configure os seguintes módulos na camada superior:

Um módulo de registro do Docker
- Configure o módulo com um nome memorável como registro e exponha uma porta no módulo para receber solicitações.
- Configure o módulo para mapear para o registro do contêiner.

Um módulo de proxy de API

Configure as seguintes variáveis de ambiente:

Nome	Valor
`DOCKER_REQUEST_ROUTE_ADDRESS`	O nome do módulo de registo e a porta aberta. Por exemplo, `registry:5000`.
`NGINX_DEFAULT_PORT`	A porta que o proxy nginx escuta para solicitações de dispositivos downstream. Por exemplo, `8000`.

Configure as seguintes createOptions:

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

Configure o seguinte módulo em qualquer camada inferior para este cenário:

Módulo de proxy de API. O módulo proxy da API é necessário em todos os dispositivos de camada inferior, exceto no dispositivo de camada inferior.
- Configure as seguintes variáveis de ambiente:
  
  Nome Valor
  
  NGINX_DEFAULT_PORT A porta que o proxy nginx escuta para solicitações de dispositivos downstream. Por exemplo, 8000.
- Configure as seguintes createOptions:
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

Nome	Valor
`NGINX_DEFAULT_PORT`	A porta que o proxy nginx escuta para solicitações de dispositivos downstream. Por exemplo, `8000`.

Expor porta proxy

A porta 8000 é exposta por padrão a partir da imagem do docker. Se uma porta de proxy nginx diferente for usada, adicione a seção ExposedPorts declarando a porta no manifesto de implantação. Por exemplo, se você alterar a porta de proxy nginx para 8001, adicione o seguinte ao manifesto de implantação:

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

Ativar upload de blob

Outro caso de uso para o módulo de proxy de API é habilitar dispositivos IoT Edge em camadas inferiores para carregar blobs. Este caso de uso permite a funcionalidade de solução de problemas em dispositivos de camada inferior, como carregar logs de módulo ou carregar o pacote de suporte.

Este cenário usa o módulo Armazenamento de Blob do Azure no IoT Edge na camada superior para lidar com a criação e o carregamento de blobs. Em um cenário aninhado, há suporte para até cinco camadas. O módulo Armazenamento de Blob do Azure no IoT Edge é necessário no dispositivo de camada superior e opcional para dispositivos de camada inferior. Para obter um exemplo de implantação multicamada, consulte o exemplo do Azure IoT Edge para IoT Industrial.

Configure os seguintes módulos na camada superior:

Um módulo de Armazenamento de Blob do Azure no IoT Edge.

Um módulo de proxy de API

Configure as seguintes variáveis de ambiente:

Nome	Valor
`BLOB_UPLOAD_ROUTE_ADDRESS`	O nome do módulo de armazenamento de blob e a porta aberta. Por exemplo, `azureblobstorageoniotedge:11002`.
`NGINX_DEFAULT_PORT`	A porta que o proxy nginx escuta para solicitações de dispositivos downstream. Por exemplo, `8000`.

Configure as seguintes createOptions:

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

Configure o seguinte módulo em qualquer camada inferior para este cenário:

Um módulo de proxy de API
- Configure as seguintes variáveis de ambiente:
  
  Nome Valor
  
  NGINX_DEFAULT_PORT A porta que o proxy nginx escuta para solicitações de dispositivos downstream. Por exemplo, 8000.
- Configure as seguintes createOptions:
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

Nome	Valor
`NGINX_DEFAULT_PORT`	A porta que o proxy nginx escuta para solicitações de dispositivos downstream. Por exemplo, `8000`.

Use as seguintes etapas para carregar o pacote de suporte ou o arquivo de log para o módulo de armazenamento de blob localizado na camada superior:

Crie um contêiner de blob, usando o Gerenciador de Armazenamento do Azure ou as APIs REST. Para obter mais informações, consulte Armazenar dados na borda com o Armazenamento de Blob do Azure no IoT Edge.
Solicite um upload de log ou pacote de suporte de acordo com as etapas em Recuperar logs de implantações do IoT Edge, mas use o nome $upstream de domínio e a porta proxy aberta no lugar do endereço do módulo de armazenamento de blob. Por exemplo:
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

Editar a configuração do proxy

Um arquivo de configuração padrão é incorporado no módulo de proxy da API, mas você pode passar uma nova configuração para o módulo através da nuvem usando o módulo gêmeo.

Quando você escreve sua própria configuração, ainda pode usar o ambiente para ajustar as configurações por implantação. Utilize a seguinte sintaxe:

Use ${MY_ENVIRONMENT_VARIABLE} para recuperar o valor de uma variável de ambiente.

Use instruções condicionais para ativar ou desativar as configurações com base no valor de uma variável de ambiente:

#if_tag ${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 1
#endif_tag ${MY_ENVIRONMENT_VARIABLE}

#if_tag !${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 0
#endif_tag !${MY_ENVIRONMENT_VARIABLE}

Quando o módulo de proxy da API analisa uma configuração de proxy, ele primeiro substitui todas as variáveis de ambiente listadas PROXY_CONFIG_ENV_VAR_LIST no com seus valores fornecidos usando substituição. Em seguida, tudo entre um #if_tag e #endif_tag par é substituído. Em seguida, o módulo fornece a configuração analisada para o proxy reverso nginx.

Para atualizar a configuração de proxy dinamicamente, use as seguintes etapas:

Escreva seu arquivo de configuração. Você pode usar este modelo padrão como referência: nginx_default_config.conf
Copie o texto do arquivo de configuração e converta-o em base64.
Cole o arquivo de configuração codificado como o valor da proxy_config propriedade desejada no módulo gêmeo.

Próximos passos

Use o módulo de proxy de API para conectar um dispositivo IoT Edge downstream a um gateway do Azure IoT Edge.

Partilhar via