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

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

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.

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. Você pode implantar o módulo usando o portal do Azure ou a CLI do Azure.

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:

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:

1. 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"
           }
         ]
       }
     }
   }
   

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_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"
                }
             ]
          }
       }
    }
    

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"
                }
             ]
          }
       }
    }
    

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:

1. 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.

2. 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:

1. Grave seu arquivo de configuração. Você pode usar 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 do Azure IoT Edge.