Configurare il modulo API proxy per lo scenario della gerarchia dei gateway

Si applica a: IoT Edge 1.5

Questo articolo descrive le opzioni di configurazione per il modulo proxy API, in modo da poter personalizzare il modulo per supportare i requisiti della gerarchia del gateway.

Il modulo proxy API semplifica la comunicazione per i dispositivi IoT Edge quando più servizi usano il protocollo HTTPS e si associano alla porta 443. Questa configurazione è particolarmente rilevante nelle distribuzioni gerarchiche di dispositivi IoT Edge in architetture isolate di rete basate su ISA-95, come quelle descritte in Isolamento dei dispositivi downstream nella rete, perché i client nei dispositivi downstream non possono connettersi direttamente al cloud.

Ad esempio, consentire ai dispositivi downstream IoT Edge di recuperare le immagini Docker richiede la distribuzione di un modulo del registro Docker. Consentire ai dispositivi di caricare i BLOB richiede la distribuzione di un modulo Azure Blob Storage nello stesso dispositivo IoT Edge. Entrambi i servizi usano HTTPS per la comunicazione. Il modulo proxy API abilita queste distribuzioni in un dispositivo IoT Edge. Anziché ogni associazione di servizi alla porta 443, il modulo proxy API viene associato alla porta 443 nel dispositivo host e instrada le richieste al modulo di servizio corretto in esecuzione su tale dispositivo in base alle regole configurabili dall'utente. I singoli servizi sono comunque responsabili della gestione delle richieste, inclusa l'autenticazione e l'autorizzazione dei client.

Senza il proxy API, ogni modulo di servizio deve essere associato a una porta separata nel dispositivo host, che richiede una modifica di configurazione noiosa e soggetta a errori in ogni dispositivo figlio che si connette al dispositivo padre IoT Edge.

Distribuire il modulo proxy

Il modulo proxy API è disponibile nel Microsoft Container Registry (MCR) e l'URI dell'immagine è mcr.microsoft.com/azureiotedge-api-proxy:latest. Distribuire il modulo usando il portale Azure o Azure CLI.

Informazioni sul modulo proxy

Il modulo proxy API usa un proxy inverso nginx per instradare i dati attraverso i livelli di rete. Il modulo ha un proxy incorporato, quindi l'immagine del modulo deve supportare la configurazione del proxy. Ad esempio, se il proxy è in ascolto su una determinata porta, il modulo deve avere tale porta aperta.

Il proxy inizia con un file di configurazione predefinito incorporato nel modulo. Passare una nuova configurazione al modulo dal cloud usando il modulo gemello. È anche possibile usare le variabili di ambiente per attivare o disattivare le impostazioni di configurazione in fase di distribuzione.

Questo articolo illustra innanzitutto il file di configurazione predefinito e come usare le variabili di ambiente per abilitarne le impostazioni. Viene quindi illustrato come personalizzare il file di configurazione.

Configurazione predefinita

Il modulo proxy API include una configurazione predefinita che supporta scenari comuni e consente di personalizzarla. Controllare la configurazione predefinita tramite le variabili di ambiente del modulo.

Attualmente, le variabili di ambiente predefinite includono:

Ridurre il numero di porte aperte

Per ridurre al minimo le porte aperte, impostare il modulo proxy API per inoltrare tutto il traffico HTTPS (porta 443), incluso il traffico per il modulo edgeHub. Per impostazione predefinita, il modulo proxy API reindirizza tutto il traffico edgeHub sulla porta 443.

Seguire questa procedura per configurare la distribuzione per ridurre al minimo le porte aperte:

1. Aggiornare le impostazioni del modulo edgeHub in modo che non venga associato alla porta 443. In caso contrario, si verificano conflitti di binding delle porte. Per impostazione predefinita, il modulo edgeHub viene associato alle porte 443, 5671 e 8883. Eliminare l'associazione della porta 443 e lasciare le altre due così come sono.

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

2. Configurare il modulo proxy API per l'associazione alla porta 443.

   1. Impostare il valore della variabile di ambiente NGINX_DEFAULT_PORT su 443.

   2. Aggiornare le opzioni di creazione del contenitore da associare alla porta 443.

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

Se non è necessario ridurre al minimo le porte aperte, consentire al modulo edgeHub di usare la porta 443 e configurare il modulo proxy API per l'ascolto su un'altra porta. Ad esempio, configurare la variabile di ambiente NGINX_DEFAULT_PORT in 8000 e creare un'associazione di porte per la porta 8000.

Abilitare il download dell'immagine del contenitore

Un caso d'uso comune per il modulo proxy API consiste nel consentire ai dispositivi IoT Edge nei livelli inferiori di scaricare immagini del contenitore. Questo scenario usa il modulo registro Docker per ottenere immagini del contenitore dal cloud e memorizzarle nella cache al livello superiore. Il proxy API inoltra tutte le richieste HTTPS per scaricare un'immagine del contenitore dai livelli inferiori al modulo del Registro di sistema nel livello superiore.

In questo scenario, i dispositivi downstream IoT Edge puntano al nome di dominio $upstream seguito dal numero di porta del modulo proxy API anziché dal registro contenitori di un'immagine. Ad esempio: $upstream:8000/azureiotedge-api-proxy:1.1.

Questo caso d'uso viene illustrato nell'esercitazione Creare una gerarchia di dispositivi IoT Edge usando gateway.

Configurare i moduli seguenti nel livello superiore:

• Un modulo del registro Docker
  • Configurare il modulo con un nome facile da ricordare, ad esempio registro ed esporre una porta nel modulo per ricevere le richieste.
  • Configurare il modulo per mappare il registro contenitori.
• Un modulo API proxy

  • Configura le seguenti variabili di ambiente:

    Nome	Valore
    DOCKER_REQUEST_ROUTE_ADDRESS	Nome del modulo del registro e porta aperta. Ad esempio: registry:5000.
    NGINX_DEFAULT_PORT	Porta su cui il proxy nginx è in ascolto per le richieste dai dispositivi downstream. Ad esempio: 8000.

  • Configurare le seguenti opzioni di creazione:

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

Configurare il modulo seguente in qualsiasi livello inferiore per questo scenario:

• Modulo proxy API. Il modulo proxy API è necessario in tutti i dispositivi di livello inferiore, ad eccezione del dispositivo al livello più basso.

  • Configura le seguenti variabili di ambiente:

    Nome	Valore
    NGINX_DEFAULT_PORT	Porta su cui il proxy nginx è in ascolto per le richieste dai dispositivi downstream. Ad esempio: 8000.

  • Configurare le seguenti opzioni di creazione:

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

Esporre la porta proxy

La porta 8000 è esposta per impostazione predefinita dall'immagine Docker. Se si usa una porta proxy nginx diversa, aggiungere la sezione ExposedPorts per dichiarare la porta nel manifesto della distribuzione. Ad esempio, se si modifica la porta proxy nginx in 8001, aggiungere quanto segue al manifesto della distribuzione:

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

Abilitare il caricamento di blob

Un altro caso d'uso per il modulo proxy API consiste nel consentire ai dispositivi di IoT Edge in livelli inferiori di caricare BLOB. Questo caso d'uso consente di risolvere i problemi relativi ai dispositivi di livello inferiore, ad esempio il caricamento dei log dei moduli o il bundle di supporto.

Questo scenario usa il modulo Azure Blob Storage nel modulo IoT Edge al livello superiore per gestire la creazione e il caricamento dei BLOB. In uno scenario annidato sono supportati fino a cinque livelli. Il modulo Azure Blob Storage in IoT Edge è necessario nel dispositivo di livello superiore, ma è facoltativo per i dispositivi di livello inferiore. Per una distribuzione multilivello di esempio, vedere l'esempio Azure IoT Edge per Industrial IoT.

Configurare i moduli seguenti nel livello superiore:

• Un Azure Blob Storage nel modulo IoT Edge.
• Un modulo API proxy

  • Configura le seguenti variabili di ambiente:

    Nome	Valore
    BLOB_UPLOAD_ROUTE_ADDRESS	Nome del modulo di archiviazione BLOB e porta aperta. Ad esempio: azureblobstorageoniotedge:11002.
    NGINX_DEFAULT_PORT	Porta su cui il proxy nginx è in ascolto per le richieste dai dispositivi downstream. Ad esempio: 8000.

  • Configurare le seguenti opzioni di creazione:

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

Configurare il modulo seguente in qualsiasi livello inferiore per questo scenario:

• Un modulo API proxy

  • Configura le seguenti variabili di ambiente:

    Nome	Valore
    NGINX_DEFAULT_PORT	Porta su cui il proxy nginx è in ascolto per le richieste dai dispositivi downstream. Ad esempio: 8000.

  • Configurare le seguenti opzioni di creazione:

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

Seguire questa procedura per caricare il bundle di supporto o il file di log nel modulo di archiviazione BLOB al livello superiore:

1. Creare un contenitore BLOB usando Azure Storage Explorer o le API REST. Per altre informazioni, vedere la documentazione Azure Storage Explorer.

2. Richiedere il caricamento di un bundle di log o di supporto seguendo la procedura descritta in Retrieve logs from IoT Edge deployments, ma usare il nome di dominio $upstream e la porta proxy aperta anziché l'indirizzo del modulo di archiviazione BLOB. Ad esempio:

   {
      "schemaVersion": "1.0",
      "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
      "since": "2d",
      "until": "1d",
      "edgeRuntimeOnly": false
   }
   

Modificare la configurazione del proxy

Un file di configurazione predefinito è incorporato nel modulo proxy API, ma è possibile passare una nuova configurazione al modulo tramite il cloud usando il modulo gemello.

Quando si scrive una configurazione personalizzata, è comunque possibile usare le variabili di ambiente per regolare le impostazioni per ogni distribuzione. Usare la sintassi seguente:

• Usare ${MY_ENVIRONMENT_VARIABLE} per ottenere il valore di una variabile di ambiente.

• Usare istruzioni condizionali per attivare o disattivare le impostazioni in base al valore di una variabile di 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 il modulo proxy API analizza una configurazione proxy, prima sostituisce tutte le variabili di ambiente elencate in PROXY_CONFIG_ENV_VAR_LIST con i relativi valori usando la sostituzione. Sostituisce quindi tutti gli elementi tra una #if_tag coppia e #endif_tag . Il modulo fornisce quindi la configurazione analizzata al proxy inverso nginx.

Per aggiornare la configurazione proxy in modo dinamico, seguire questa procedura:

1. Scrivere il file di configurazione. Usare questo modello predefinito come riferimento: nginx_default_config.conf.

2. Copiare il testo del file di configurazione e convertirlo in base64.

3. Incollare il file di configurazione codificato come valore della proprietà proxy_config desiderata nel modulo gemello.

   

Passaggi successivi

Usare il modulo proxy API per connettere un dispositivo downstream IoT Edge a un gateway Azure IoT Edge.