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

Aplica-se a: IoT Edge 1.5

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

O módulo proxy de API simplifica a comunicação para dispositivos IoT Edge quando vários serviços usam o protocolo HTTPS e associam à porta 443. Essa configuração é especialmente relevante em implantações hierárquicas de dispositivos IoT Edge em arquiteturas de rede isoladas baseadas no ISA-95, como as descritas em Network isolate downstream devices, porque os clientes em dispositivos downstream não podem se conectar diretamente à nuvem.

Por exemplo, permitir que dispositivos IoT Edge de downstream baixem imagens do Docker requer a implantação de um módulo de registro do Docker. Permitir que os dispositivos carreguem blobs requer a implantação de um módulo de Azure Blob Storage no mesmo dispositivo IoT Edge. Ambos os serviços usam HTTPS para comunicação. O módulo proxy de API habilita essas implantações em um dispositivo IoT Edge. Em vez de cada associação de serviço à porta 443, o módulo proxy de API se associa à porta 443 no dispositivo host e roteia solicitações para o módulo de serviço correto em execução nesse dispositivo com base em regras configuráveis pelo usuário. Os serviços individuais ainda são responsáveis por lidar com solicitações, incluindo autenticação e autorização de clientes.

Sem o proxy de API, cada módulo de serviço deve vincular-se a uma porta separada no dispositivo host, o que requer uma alteração de configuração tediosa e suscetível a erros em todos os dispositivos filhos conectados ao dispositivo IoT Edge principal.

Implantar o módulo proxy

O módulo proxy de API está disponível no MCR (Registro de Contêiner da Microsoft) e o URI da imagem é mcr.microsoft.com/azureiotedge-api-proxy:latest. Implante o módulo usando o portal Azure ou Azure CLI.

Entender o módulo proxy

O módulo proxy de API usa um proxy reverso nginx para rotear dados por meio de camadas de rede. O módulo tem um proxy inserido, portanto, a imagem do módulo precisa dar suporte à configuração de proxy. Por exemplo, se o proxy estiver escutando em uma determinada porta, o módulo precisa ter essa porta aberta.

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

Este artigo aborda primeiro o arquivo de configuração padrão e como usar variáveis de ambiente para habilitar suas configurações. Em seguida, ele explica como personalizar o arquivo de configuração.

Configuração padrão

O módulo proxy de API vem com uma configuração padrão que dá suporte a cenários comuns e permite personalizá-lo. Controle a configuração padrão por meio das variáveis de ambiente do módulo.

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

Minimizar portas abertas

Para minimizar portas abertas, defina o módulo proxy de API para retransmitir todo o tráfego HTTPS (porta 443), incluindo o tráfego para o módulo edgeHub. Por padrão, o módulo proxy de API redireciona todo o tráfego do EdgeHub na porta 443.

Siga estas etapas para configurar sua implantação para minimizar portas abertas:

1. Atualize as configurações do módulo edgeHub para que ele não se associe à porta 443. Caso contrário, ocorrerão conflitos de vinculação de porta. Por padrão, o módulo edgeHub é associado às portas 443, 5671 e 8883. Exclua a associação da porta 443 e mantenha as outras duas como estão.

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

2. Configure o módulo proxy de API para associação na porta 443.

   1. Defina o valor da variável de ambiente NGINX_DEFAULT_PORT como 443.

   2. Atualize as opções de criação do contêiner para associar à porta 443.

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

Se você não precisar minimizar portas abertas, permita que o módulo edgeHub use a porta 443 e configure o módulo proxy de API para escutar em outra porta. Por exemplo, configure a variável 8000 e crie uma associação de porta para a porta 8000.

Habilitar download de imagem de contêiner

Um caso de uso comum para o módulo proxy de API é permitir que dispositivos IoT Edge nas camadas inferiores baixem imagens de contêiner. Esse cenário usa o módulo do Registro do Docker para obter imagens de contêiner da nuvem e armazená-las em cache na camada superior. O proxy de API retransmite todas as solicitações HTTPS para baixar uma imagem de contêiner das camadas inferiores para o módulo do Registro na camada superior.

Nesse cenário, os dispositivos IoT Edge downstream devem apontar para o nome de domínio $upstream seguido pelo número da porta do módulo proxy de API, em vez do registro de contêiner da 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 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 opções de criação:

    {
       "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 opções de criação:

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

Expor porta do proxy

A porta 8000 é exposta por padrão da imagem do Docker. Se você usar uma porta proxy nginx diferente, adicione a seção ExposedPorts para declarar 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

Outro caso de uso para o módulo proxy de API é permitir que dispositivos IoT Edge em camadas inferiores carreguem blobs. Esse caso de uso permite solucionar problemas de dispositivos de camadas inferiores, como subir logs de módulos ou pacotes de suporte.

Esse cenário usa o módulo Azure Blob Storage no módulo IoT Edge na camada superior para lidar com a criação e o upload de blobs. Em um cenário aninhado, há suporte para até cinco camadas. O módulo Azure Blob Storage no módulo IoT Edge é necessário no dispositivo de camada superior, mas é opcional para dispositivos de camada inferior. Para obter uma implantação de várias camadas de exemplo, consulte a amostra Azure IoT Edge para IoT industrial.

Configure os seguintes módulos na camada superior:

• Um Azure Blob Storage no módulo 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 opções de criação:

    {
       "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 opções de criação:

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

Siga estas etapas para carregar o pacote de suporte ou o arquivo de log no módulo de armazenamento de blobs na camada superior:

1. Crie um contêiner de blob usando Azure Storage Explorer ou as APIs REST. Para obter mais informações, consulte a documentação Azure Storage Explorer.

2. Para solicitar upload de logs ou pacotes de suporte, siga as etapas 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 passar uma nova configuração para o módulo por meio da nuvem usando o módulo gêmeo.

Ao escrever sua própria configuração, você ainda pode usar variáveis de ambiente para ajustar as configurações de cada implantação. Use a seguinte sintaxe:

• Use ${MY_ENVIRONMENT_VARIABLE} para obter 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, ele primeiro substitui todas as variáveis de ambiente listadas em PROXY_CONFIG_ENV_VAR_LIST com seus valores usando substituição. Em seguida, ele substitui tudo entre um par de #if_tag e #endif_tag. Em seguida, o módulo fornece a configuração analisada ao proxy reverso Nginx.

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

1. Grave seu arquivo de configuração. Use este modelo padrão como referência: nginx_default_config.conf.

2. Copie o texto do arquivo de configuração e converta-o em base64.

3. 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 de Azure IoT Edge.