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

Si applica a: IoT Edge 1.5 IoT Edge 1.4

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

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

Ad esempio, per consentire ai dispositivi IoT Edge downstream di eseguire il pull delle immagini Docker, è necessario distribuire un modulo del registro Docker. Per consentire il caricamento dei BLOB, è necessario distribuire un modulo di Archiviazione BLOB di Azure nello stesso dispositivo IoT Edge. Entrambi i servizi usano HTTPS per la comunicazione. Il proxy API abilita tali distribuzioni in un dispositivo IoT Edge. Invece di ogni servizio, il modulo proxy API viene associato alla porta 443 nel dispositivo host e instrada la richiesta al modulo di servizio corretto in esecuzione nel 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 del servizio deve essere associato a una porta separata nel dispositivo host, richiedendo una modifica di configurazione noiosa e soggetta a errori in ogni dispositivo figlio che si connette al dispositivo IoT Edge padre.

Distribuire il modulo proxy

Il modulo proxy dell'API è disponibile in Microsoft Container Registry (MCR) e l'URI dell'immagine è mcr.microsoft.com/azureiotedge-api-proxy:latest. È possibile distribuire il modulo usando il portale di Azure o l'interfaccia della riga di comando di Azure.

Informazioni sul modulo proxy

Il modulo proxy API usa un proxy inverso nginx per instradare i dati attraverso i livelli di rete. Un proxy è incorporato nel modulo, il che significa che 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. È possibile passare una nuova configurazione al modulo dal cloud usando il modulo gemello. Inoltre, è possibile usare le variabili di ambiente per attivare o disattivare le impostazioni di configurazione in fase di distribuzione.

Questo articolo è incentrato innanzitutto sul file di configurazione predefinito e su come usare le variabili di ambiente per abilitarne le impostazioni. Alla fine verrà quindi illustrato come personalizzare il file di configurazione.

Configurazione predefinita

Il modulo proxy API include una configurazione predefinita che supporta scenari comuni e consente la personalizzazione. È possibile controllare la configurazione predefinita tramite le variabili di ambiente del modulo.

Attualmente, le variabili di ambiente predefinite includono:

Ridurre al minimo le porte aperte

Per ridurre al minimo il numero di porte aperte, il modulo proxy API deve inoltrare tutto il traffico HTTPS (porta 443), incluso il traffico destinato al modulo edgeHub. Il modulo proxy API è configurato per impostazione predefinita per reinstradare tutto il traffico edgeHub sulla porta 443.

Per configurare la distribuzione per ridurre al minimo le porte aperte, seguire questa procedura:

1. Aggiornare le impostazioni del modulo edgeHub in modo da non eseguire l'associazione sulla porta 443. In caso contrario, ci saranno conflitti di associazione delle porte. Per impostazione predefinita, il modulo edgeHub si associa alle porte 443, 5671 e 8883. Eliminare l'associazione della porta 443 e lasciare invariate le altre due:

   {
     "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 in modo da eseguire l'associazione alla porta 443.

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

Se non è necessario ridurre al minimo le porte aperte, è possibile consentire al modulo edgeHub di usare la porta 443 e configurare il modulo proxy API per l'ascolto su un'altra porta. Ad esempio, il modulo proxy API può essere in ascolto sulla porta 8000 se si imposta il valore della variabile di ambiente NGINX_DEFAULT_PORT su 8000 e si crea 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 permettere ai dispositivi IoT Edge in livelli inferiori di eseguire il pull delle immagini del contenitore. Questo scenario usa il modulo del registro Docker per recuperare le 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 in modo che vengano gestite dal modulo del registro nel livello superiore.

Questo scenario richiede che i dispositivi IoT Edge downstream puntino 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 è illustrato nell'esercitazione Creare una gerarchia di dispositivi IoT Edge con i 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 in modo da eseguire il mapping al registro contenitori.
• Un modulo proxy API

  • Dichiarare le variabili di ambiente seguenti:

    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 opzioni createOptions seguenti:

    {
       "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.

  • Dichiarare le variabili di ambiente seguenti:

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

  • Configurare le opzioni createOptions seguenti:

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

Esporre la porta proxy

La porta 8000 viene esposta per impostazione predefinita dall'immagine Docker. Se viene usata una porta proxy nginx diversa, aggiungere la sezione ExposedPorts dichiarando 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 IoT Edge in livelli inferiori di caricare i BLOB. Questo caso d'uso abilita la funzionalità di risoluzione dei problemi nei dispositivi di livello inferiore, ad esempio il caricamento dei log dei moduli o il caricamento del bundle di supporto.

Questo scenario usa il modulo Archiviazione BLOB di Azure in 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 Archiviazione BLOB di Azure in IoT Edge è necessario nel dispositivo di livello superiore e facoltativo per i dispositivi di livello inferiore. Per una distribuzione a più livelli di esempio, vedere l'esempio Azure IoT Edge per IoT industriale.

Configurare i moduli seguenti nel livello superiore:

• Un modulo Archiviazione BLOB di Azure in IoT Edge.
• Un modulo proxy API

  • Dichiarare le variabili di ambiente seguenti:

    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 opzioni createOptions seguenti:

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

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

• Un modulo proxy API

  • Dichiarare le variabili di ambiente seguenti:

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

  • Configurare le opzioni createOptions seguenti:

    {
       "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 situato al livello superiore:

1. Creare un contenitore BLOB usando Azure Storage Explorer o le API REST. Per altre informazioni, vedere Archiviare i dati nei dispositivi perimetrali con Archiviazione BLOB di Azure in IoT Edge.

2. Richiedere il caricamento di un bundle di log o di supporto in base alla procedura descritta in Recuperare i log dalle distribuzioni di IoT Edge, ma usare il nome di dominio $upstream e la porta proxy aperta al posto dell'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 l'ambiente per modificare le impostazioni per ogni distribuzione. Usare la sintassi seguente:

• Usare ${MY_ENVIRONMENT_VARIABLE} per recuperare 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, sostituisce prima tutte le variabili di ambiente elencate in PROXY_CONFIG_ENV_VAR_LIST con i valori specificati usando la sostituzione. Vengono quindi sostituiti tutti gli elementi tra una coppia di #if_tag 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. È possibile 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 IoT Edge downstream a un gateway Azure IoT Edge.