Share via

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

  • Articolo

Si applica a:Segno di spunta IoT Edge 1.5 IoT Edge 1.5 Segno di spunta IoT Edge 1.4 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS è di fine vita il 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

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 del 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 isolate dalla rete basate su ISA-95, come quelle descritte in Isolare i dispositivi downstream di rete 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 di sistema Docker. Per consentire il caricamento dei BLOB, è necessario distribuire un modulo Archiviazione BLOB di Azure nello stesso dispositivo IoT Edge. Entrambi questi 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.

Nota

Un dispositivo downstream genera dati direttamente in Internet o nei dispositivi gateway (abilitati o meno per IoT Edge). Un dispositivo figlio può essere un dispositivo downstream o un dispositivo gateway in una topologia annidata.

Distribuire il modulo proxy

Il modulo proxy DELL'API è disponibile nel Registro Contenitori Microsoft : mcr.microsoft.com/azureiotedge-api-proxy:1.1.

È anche possibile distribuire il modulo proxy API direttamente da Azure Marketplace: Proxy API IoT Edge.

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. Verrà quindi illustrato come personalizzare il file di configurazione alla fine.

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:

Variabile di ambiente Descrizione
PROXY_CONFIG_ENV_VAR_LIST Elencare tutte le variabili che si intende aggiornare in un elenco delimitato da virgole. Questo passaggio impedisce di modificare accidentalmente le impostazioni di configurazione errate.
NGINX_DEFAULT_TLS Specifica l'elenco dei protocolli TLS da abilitare. Vedere ssl_protocols di NGINX.

Il valore predefinito è 'TLSv1.2'.
NGINX_DEFAULT_PORT Modifica la porta su cui il proxy nginx è in ascolto. Se si aggiorna questa variabile di ambiente, è necessario esporre la porta nel dockerfile del modulo e dichiarare l'associazione di porte nel manifesto della distribuzione. Per altre informazioni, vedere Esporre la porta proxy.

Il valore predefinito è 443.

Quando viene distribuita da Azure Marketplace, la porta predefinita viene aggiornata a 8000 per evitare conflitti con il modulo edgeHub. Per altre informazioni, vedere Ridurre al minimo le porte aperte.
DOCKER_REQUEST_ROUTE_ADDRESS Indirizzo per instradare le richieste Docker. Modificare questa variabile nel dispositivo di livello superiore in modo che punti al modulo del Registro di sistema.

Il valore predefinito è il nome host padre.
BLOB_UPLOAD_ROUTE_ADDRESS Indirizzo per instradare le richieste del Registro di sistema BLOB. Modificare questa variabile nel dispositivo di livello superiore in modo che punti al modulo di archiviazione BLOB.

Il valore predefinito è il nome host padre.

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 reindirizzare 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 per 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 sulla 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 sulla 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 impostando il valore della variabile di ambiente NGINX_DEFAULT_PORT su 8000 e creando 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 nell'abilitare i dispositivi IoT Edge in livelli inferiori per eseguire il pull delle immagini del contenitore. Questo scenario usa il modulo 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 da gestire dal modulo del Registro di sistema nel livello superiore.

Questo scenario richiede che i dispositivi IoT Edge downstream puntino al nome $upstream di dominio 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 usando i gateway.

Configurare i moduli seguenti al livello superiore:

  • Un modulo del Registro di sistema Docker
    • Configurare il modulo con un nome memorabile, ad esempio registro ed esporre una porta nel modulo per ricevere le richieste.
    • Configurare il modulo per eseguire il mapping al registro contenitori.
  • Un modulo proxy API

    • Configurare le variabili di ambiente seguenti:

      Nome Valore
      DOCKER_REQUEST_ROUTE_ADDRESS Nome del modulo del Registro di sistema 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 di livello inferiore.

    • Configurare 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 che dichiara 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 blob

Un altro caso d'uso per il modulo proxy API consiste nell'abilitare i dispositivi IoT Edge in livelli inferiori per 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 Archiviazione BLOB di Azure 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 Archiviazione BLOB di Azure nel modulo IoT Edge è necessario nel dispositivo di livello superiore e facoltativo per i dispositivi di livello inferiore. Per una distribuzione multi-layer di esempio, vedere l'esempio azure IoT Edge per IoT industriale.

Configurare i moduli seguenti al livello superiore:

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

    • Configurare 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

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

Usare la procedura seguente 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 Archiviazione di Azure Explorer o le API REST. Per altre informazioni, vedere Archiviare i dati nella rete perimetrale 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 $upstream di dominio 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 di tutto tutte le variabili di ambiente elencate in PROXY_CONFIG_ENV_VAR_LIST con i valori specificati usando la sostituzione. Quindi, tutti gli elementi tra una #if_tag coppia e #endif_tag vengono sostituiti. 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 proxy_config proprietà desiderata nel modulo gemello.

    Screenshot che mostra come incollare il file di configurazione codificato come valore della proprietà proxy_config.

Passaggi successivi

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