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

Artigo
04/11/2024

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Importante

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

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

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

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

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

Observação

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

Implantar o módulo proxy

O módulo proxy de API está disponível no MCR (Microsoft Container Registry): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Você também pode implantar o módulo proxy de API diretamente do Azure Marketplace: Proxy API do IoT Edge.

Entender o módulo proxy

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

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

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

Configuração padrão

O módulo proxy de API vem com configuração padrão que oferece suporte a cenários comuns e permite personalização. Você pode controlar a configuração padrão usando variáveis de ambiente do módulo.

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

Variável de ambiente	Descrição
`PROXY_CONFIG_ENV_VAR_LIST`	Agrupe todas as variáveis que você pretende atualizar em uma lista separada por vírgulas. Esta etapa impede a modificação acidental das definições de configuração incorretas.
`NGINX_DEFAULT_TLS`	Especifica a lista de protocolo TLS a serem habilitados. Confira 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 módulo dockerfile e declarar a associação de portas no manifesto de implantação. Para obter mais informações, consulte Expor porta do proxy. O padrão é 443. Quando implantada no 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 rotear solicitações do docker. Modifique essa variável no dispositivo de camada superior para que aponte 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 blobs. Modifique essa variável no dispositivo de camada superior para que aponte para o módulo de armazenamento de blobs. O padrão é o nome do host pai.

Minimizar portas abertas

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

Use as etapas a seguir para configurar sua implantação para que minimize portas abertas:

Atualize as configurações do módulo edgeHub para que não haja associação na porta 443, caso contrário haverá conflitos de associação de porta. Por padrão, o módulo edgeHub faz associações nas portas 443, 5671 e 8883. Exclua a associação da porta 443 e deixe as outras duas em vigor:
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
Configure o módulo proxy de API para associação na porta 443.
1. Defina o valor da variável de ambiente NGINX_DEFAULT_PORTT como 443.
2. Atualize as opções de criação de contêiner para associação na porta 443.
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

Se você não precisar minimizar portas abertas, poderá deixar que o módulo edgeHub use a porta 443 e configurar o módulo proxy de API para escutar em outra porta. Por exemplo, o módulo proxy de API pode escutar na porta 8000 com a definição de valor da variável de ambiente NGINX_DEFAULT_PORT como 8000 e a criação de uma associação para a porta 8000.

Habilitar download de imagem de contêiner

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

Esse cenário requer que os dispositivos com IoT Edge downstream apontem para o nome de domínio $upstream 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 com IoT Edge usando gateways.

Configure os seguintes módulos na camada superior:

Configurar um módulo de registro Docker
- Configure o módulo com um nome de fácil memorização, como registro, e exponha uma porta no módulo para receber solicitações.
- Configure o módulo para mapear para o seu registro de contêiner.

Um módulo proxy de API

Adicione estas variáveis de ambiente:

Nome	Valor
`DOCKER_REQUEST_ROUTE_ADDRESS`	O nome do módulo do registro e a porta aberta. Por exemplo, `registry:5000`.
`NGINX_DEFAULT_PORT`	A porta na qual o proxy nginx escuta 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 de proxy de API é necessário em todos os dispositivos de camada inferior, exceto no dispositivo de camada mais inferior.
- Adicione estas variáveis de ambiente:
  
  Nome Valor
  
  NGINX_DEFAULT_PORT A porta na qual o proxy nginx escuta 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 na qual o proxy nginx escuta solicitações de dispositivos downstream. Por exemplo, `8000`.

Expor porta do proxy

A porta 8000 é exposta por padrão da imagem do docker. Se uma porta do 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 do proxy nginx para 8001, adicione o seguinte ao manifesto de implantação:

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

Habilitar carregamento de blobs

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

Esse cenário usa o módulo Armazenamento de Blobs 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 Blobs do Azure no IoT Edge é necessário no dispositivo de camada superior e opcional para dispositivos de camada inferior. Para uma implantação de várias camadas de exemplo, consulte o exemplo Azure IoT Edge para IoT Industrial.

Configure os seguintes módulos na camada superior:

Armazenamento de Blobs do Azure no módulo do IoT Edge.

Um módulo proxy de API

Adicione estas variáveis de ambiente:

Nome	Valor
`BLOB_UPLOAD_ROUTE_ADDRESS`	O nome do módulo de armazenamento de blobs e a porta aberta. Por exemplo, `azureblobstorageoniotedge:11002`.
`NGINX_DEFAULT_PORT`	A porta na qual o proxy nginx escuta 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 proxy de API
- Adicione estas variáveis de ambiente:
  
  Nome Valor
  
  NGINX_DEFAULT_PORT A porta na qual o proxy nginx escuta 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 na qual o proxy nginx escuta solicitações de dispositivos downstream. Por exemplo, `8000`.

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

Crie um contêiner de blobs 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 Blobs do Azure no IoT Edge.
Solicite um carregamento de logs ou do pacote de suporte de acordo com as etapas descritas em Recuperar logs de implantações do IoT Edge, mas use o nome de domínio $upstream e a porta de proxy aberta no lugar do endereço do módulo de armazenamento de blobs. Por exemplo:
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

Editar a configuração de proxy

Um arquivo de configuração padrão é inserido no módulo proxy de API, mas você pode transmitir uma nova configuração ao módulo pela nuvem usando o módulo gêmeo.

Ao escrever sua própria configuração, você ainda pode usar o ambiente para ajustar configurações por implantação. Use 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 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 proxy de API analisa uma configuração de proxy, primeiro substitui todas as variáveis de ambiente listadas na PROXY_CONFIG_ENV_VAR_LIST por seus valores fornecidos usando a substituição. Em seguida, todo o conteúdo entre um par #if_tag e #endif_tag é substituído. A seguir, o módulo fornece a configuração analisada ao proxy reverso nginx.

Para atualizar a configuração de proxy dinamicamente, siga estas etapas:

Grave 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óximas etapas

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

Compartilhar via