ゲートウェイ階層シナリオ用に API プロキシ モジュールを構成する

対象: IoT Edge 1.5

この記事では、ゲートウェイ階層の要件をサポートするようにモジュールをカスタマイズできるように、API プロキシ モジュールの構成オプションについて説明します。

API プロキシ モジュールは、複数のサービスが HTTPS プロトコルを使用し、ポート 443 にバインドする場合に、IoT Edge デバイスの通信を簡略化します。 このセットアップは、isA-95 ベースのネットワーク分離アーキテクチャでのIoT Edge デバイスの階層展開に特に関連します。これは、ダウンストリーム デバイス上のクライアントがクラウドに直接接続できないため、Network でダウンストリーム デバイスを分離で説明されているものと同様です。

たとえば、ダウンストリーム IoT Edge デバイスで Docker イメージをプルするには、Docker レジストリ モジュールをデプロイする必要があります。 デバイスで BLOB をアップロードするには、同じIoT Edge デバイスにAzure Blob Storage モジュールをデプロイする必要があります。 どちらのサービスも通信に HTTPS を使用します。 API プロキシ モジュールを使用すると、IoT Edge デバイスでのこれらのデプロイが可能になります。 API プロキシ モジュールは、ポート 443 への各サービス バインドの代わりに、ホスト デバイス上のポート 443 にバインドし、ユーザーが構成可能な規則に基づいて、そのデバイスで実行されている正しいサービス モジュールに要求をルーティングします。 個々のサービスは、クライアントの認証や承認など、要求の処理を引き続き担当します。

API プロキシがない場合、各サービス モジュールはホスト デバイス上の個別のポートにバインドする必要があります。そのためには、親IoT Edge デバイスに接続する各子デバイスで、面倒でエラーが発生しやすい構成変更が必要です。

プロキシ モジュールをデプロイする

API プロキシ モジュールは Microsoft Container Registry (MCR) から入手でき、イメージ URI は mcr.microsoft.com/azureiotedge-api-proxy:latest。 Azure ポータル または Azure CLI を使用してモジュールをデプロイします。

プロキシ モジュールについて

API プロキシ モジュールでは、nginx リバース プロキシを使用して、ネットワーク レイヤー経由でデータをルーティングします。 モジュールにはプロキシが埋め込まれているため、モジュール イメージでプロキシ構成をサポートする必要があります。 たとえば、プロキシが特定のポートでリッスンする場合、モジュールはそのポートを開く必要があります。

プロキシは、モジュールに埋め込まれている既定の構成ファイルから始まります。 モジュール ツインを使用して、クラウドからモジュールに新しい構成を渡します。 環境変数を使用して、デプロイ時に構成設定をオンまたはオフにすることもできます。

この記事ではまず、既定の構成ファイルと、環境変数を使用してその設定を有効にする方法について説明します。 次に、構成ファイルをカスタマイズする方法について説明します。

既定の構成

API プロキシ モジュールには、一般的なシナリオをサポートし、カスタマイズできる既定の構成が付属しています。 モジュールの環境変数を使用して既定の構成を制御します。

現在、既定の環境変数は次のとおりです。

開いているポートを最小限に抑える

開いているポートを最小限に抑えるには、edgeHub モジュールのトラフィックを含むすべての HTTPS トラフィック (ポート 443) を中継するように API プロキシ モジュールを設定します。 既定では、API プロキシ モジュールは、ポート 443 上のすべての edgeHub トラフィックを再ルーティングします。

開いているポートを最小限に抑えるようにデプロイを設定するには、次の手順に従います。

1. edgeHub モジュールの設定を更新して、ポート 443 にバインドしないようにします。 それ以外の場合は、ポート バインドの競合が発生します。 既定では、edgeHub モジュールはポート 443、5671、および 8883 にバインドされます。 ポート 443 のバインドを削除し、他の 2 つをそのままにします。

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

2. ポート 443 でバインドするように API プロキシ モジュールを構成します。

   1. NGINX_DEFAULT_PORT環境変数の値を443に設定します。

   2. ポート 443 にバインドするようにコンテナー作成オプションを更新します。

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

開いているポートを最小限に抑える必要がない場合は、edgeHub モジュールでポート 443 を使用し、別のポートでリッスンするように API プロキシ モジュールを構成します。 たとえば、 NGINX_DEFAULT_PORT 環境変数を構成して、ポート 8000 のポート バインドを 8000 して作成します。

コンテナー イメージのダウンロードを有効にする

API プロキシ モジュールの一般的なユース ケースは、下位レイヤーのIoT Edgeデバイスがコンテナー イメージをプルできるようにすることです。 このシナリオでは、 Docker レジストリ モジュール を使用してクラウドからコンテナー イメージを取得し、最上位レイヤーにキャッシュします。 API プロキシは、下位レイヤーから上位レイヤーのレジストリ モジュールにコンテナー イメージをダウンロードするために、すべての HTTPS 要求を中継します。

このシナリオでは、ダウンストリームのIoT Edgeデバイスは、イメージのコンテナレジストリではなく、$upstreamの後に続くAPIプロキシモジュールのポート番号を指定します。 たとえば、「 $upstream:8000/azureiotedge-api-proxy:1.1 」のように入力します。

このユース ケースは、チュートリアル ゲートウェイを使用してIoT Edge デバイスの階層を作成するで示します。

最上位レイヤーで次のモジュールを構成します。

• Docker レジストリ モジュール
  • registry のようなわかりやすい名前を使用してモジュールを構成し、要求を受信するためにモジュールのポートを公開します。
  • コンテナー レジストリにマップするようにモジュールを構成します。
• API プロキシ モジュール

  • 以下の環境変数を構成します。

    名前	値
    DOCKER_REQUEST_ROUTE_ADDRESS	レジストリ モジュールの名前と開いているポート。 たとえば、「 registry:5000 」のように入力します。
    NGINX_DEFAULT_PORT	nginx プロキシがダウンストリーム デバイスからの要求をリッスンするポート。 たとえば、「 8000 」のように入力します。

  • 次の createOptions を構成します。

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

このシナリオでは、次のモジュールを下位レイヤーに構成します。

• API プロキシ モジュール API プロキシ モジュールは、最下位レイヤー デバイスを除くすべての下位レイヤー デバイスで必要です。

  • 以下の環境変数を構成します。

    名前	値
    NGINX_DEFAULT_PORT	nginx プロキシがダウンストリーム デバイスからの要求をリッスンするポート。 たとえば、「 8000 」のように入力します。

  • 次の createOptions を構成します。

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

プロキシ ポートの公開

ポート 8000 は、Docker イメージから既定で公開されます。 別の nginx プロキシ ポートを使用する場合は、 ExposedPorts セクションを追加して、配置マニフェストでポートを宣言します。 たとえば、nginx プロキシ ポートを 8001 に変更する場合は、配置マニフェストに次のコードを追加します。

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

BLOB アップロードを有効にする

API プロキシ モジュールのもう 1 つのユース ケースは、下位レイヤーのIoT Edgeデバイスで BLOB をアップロードできるようにすることです。 このユース ケースでは、モジュール ログやサポート バンドルのアップロードなど、下位レイヤーデバイスのトラブルシューティングを行うことができます。

このシナリオでは、最上位レイヤーの IoT Edge モジュールの Azure Blob Storage を使用して、BLOB の作成とアップロードを処理します。 入れ子になったシナリオでは、最大 5 つのレイヤーがサポートされます。 IoT Edge モジュールの Azure Blob Storage は最上位レイヤー デバイスで必要ですが、下位レイヤー デバイスでは省略可能です。 多層デプロイのサンプルについては、Industrial IoT の Azure IoT Edge サンプルを参照してください。

最上位レイヤーで次のモジュールを構成します。

• Azure Blob Storage IoT Edge モジュール。
• API プロキシ モジュール

  • 以下の環境変数を構成します。

    名前	値
    BLOB_UPLOAD_ROUTE_ADDRESS	Blob Storage モジュールの名前と開いているポート。 たとえば、「 azureblobstorageoniotedge:11002 」のように入力します。
    NGINX_DEFAULT_PORT	nginx プロキシがダウンストリーム デバイスからの要求をリッスンするポート。 たとえば、「 8000 」のように入力します。

  • 次の createOptions を構成します。

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

このシナリオでは、次のモジュールを下位レイヤーに構成します。

• API プロキシ モジュール

  • 以下の環境変数を構成します。

    名前	値
    NGINX_DEFAULT_PORT	nginx プロキシがダウンストリーム デバイスからの要求をリッスンするポート。 たとえば、「 8000 」のように入力します。

  • 次の createOptions を構成します。

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

次の手順に従って、サポート バンドルまたはログ ファイルを最上位レイヤーの BLOB ストレージ モジュールにアップロードします。

1. Azure Storage Explorerまたは REST API を使用して BLOB コンテナーを作成します。 詳細については、Azure Storage Explorer ドキュメントを参照してください。

2. retrieve logs from IoT Edge deployments の手順に従ってログまたはサポート バンドルのアップロードを要求しますが、BLOB ストレージ モジュール アドレスではなく、ドメイン名 $upstream とオープン プロキシ ポートを使用します。 次に例を示します。

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

プロキシ構成を編集する

既定の構成ファイルは API プロキシ モジュールに埋め込まれていますが、モジュール ツインを使用して、クラウド経由でモジュールに新しい構成を渡すことができます。

独自の構成を記述する場合でも、環境変数を使用して各デプロイの設定を調整できます。 次の構文を使用します。

• 環境変数の値を取得するには、 ${MY_ENVIRONMENT_VARIABLE} を使用します。

• 環境変数の値に基づいて設定を有効または無効にするには、条件付きステートメントを使用します。

  #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}
  

API プロキシ モジュールは、プロキシ構成を解析するときに、最初に、 PROXY_CONFIG_ENV_VAR_LIST に一覧表示されているすべての環境変数を置換を使用して値に置き換えます。 次に、 #if_tag と #endif_tag のペアの間のすべてを置き換えます。 その後、モジュールが、解析された構成を nginx リバース プロキシに提供します。

プロキシ構成を動的に更新するには、次の手順に従います。

1. 構成ファイルを作成します。 この既定のテンプレートを参照として使用します:nginx_default_config.conf。

2. 構成ファイルのテキストをコピーし、base64 に変換します。

3. エンコードされた構成ファイルをモジュール ツインの proxy_config の必要なプロパティの値として貼り付けます。

   

次のステップ

API プロキシ モジュールを使用して、ダウンストリーム IoT Edge デバイスを Azure IoT Edge ゲートウェイに接続します。