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

[アーティクル]
04/11/2024

適用対象: IoT Edge 1.4

重要

IoT Edge 1.4 がサポートされているリリースです。以前のリリースの場合は、「IoT Edge を更新する」を参照してください。

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

API プロキシモジュールにより、すべてが HTTPS プロトコルをサポートしてポート 443 にバインドする複数のサービスが展開された IoT Edge デバイスでの通信が簡略化されます。ダウンストリームデバイスのクライアントはクラウドに直接接続できないため、これは、「ネットワークでダウンストリームデバイスを分離する」で説明されているもののような ISA-95 ベースのネットワーク分離アーキテクチャにおける IoT Edge デバイスの階層型展開に関連します。

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

API プロキシを使用しないと、サービスモジュールごとにホストデバイス上の異なるポートにバインドする必要があり、親 IoT Edge デバイスに接続する個々の子デバイスで、エラーが発生しやすい煩雑な構成の変更を行う必要があります。

Note

ダウンストリームデバイスは、インターネットまたはゲートウェイデバイスに (IoT Edge 対応かどうかに関係なく) 直接データを出力します。子デバイスには、入れ子になったトポロジ内のダウンストリームデバイスまたはゲートウェイデバイスを使用できます。

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

API プロキシモジュールは、Microsoft Container Registry (MCR) mcr.microsoft.com/azureiotedge-api-proxy:1.1 から入手できます。

API プロキシモジュールは、Azure Marketplace: IoT Edge API プロキシから直接デプロイすることもできます。

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

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

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

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

既定の構成

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

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

環境変数	説明
`PROXY_CONFIG_ENV_VAR_LIST`	更新するすべての変数をコンマ区切りのリストで一覧表示します。この手順によって、正しくない構成設定が誤って変更されるのを防ぐことができます。
`NGINX_DEFAULT_TLS`	有効にする TLS プロトコルの一覧を指定します。 NGINX の ssl_protocols を参照してください。既定値は 'TLSv1.2' です。
`NGINX_DEFAULT_PORT`	nginx プロキシがリッスンするポートを変更します。この環境変数を更新する場合、モジュール dockerfile でポートを公開し、デプロイマニフェストでポートのバインドを宣言する必要があります。詳細については、プロキシポートの公開に関する記事を参照してください。既定値は 443 です。 Azure Marketplace からデプロイした場合は、edgeHub モジュールとの競合を防ぐために、既定のポートが 8000 に更新されます。詳細については、「開いているポートを最小限に抑える」を参照してください。
`DOCKER_REQUEST_ROUTE_ADDRESS`	Docker 要求をルーティングするアドレス。最上位レイヤーのデバイスで、レジストリモジュールを指すようにこの変数を変更します。既定値は親ホスト名です。
`BLOB_UPLOAD_ROUTE_ADDRESS`	BLOB レジストリ要求をルーティングするアドレス。最上位レイヤーのデバイスで、BLOB ストレージモジュールを指すようにこの変数を変更します。既定値は親ホスト名です。

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

開いているポートの数を最小限に抑えるために、API プロキシモジュールは、edgeHub モジュールをターゲットとするトラフィックを含むすべての HTTPS トラフィック (ポート 443) をリレーする必要があります。 API プロキシモジュールは、既定でポート 443 のすべての edgeHub トラフィックを再ルーティングするように構成されています。

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

EdgeHub モジュールの設定をポート 443 でバインドしないように更新します。そうしないと、ポートのバインドの競合が発生します。既定では、edgeHub モジュールはポート 443、5671、および 8883 でバインドします。ポート 443 のバインドを削除し、他の 2 つをそのままにします。
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
ポート 443 でバインドするように API プロキシモジュールを構成します。
1. NGINX_DEFAULT_PORT 環境変数の値を 443 に設定します。
2. コンテナー作成オプションを更新して、ポート 443 にバインドします。
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

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

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

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

このシナリオでは、ダウンストリーム IoT Edge デバイスが、イメージのコンテナーレジストリではなく、後に API プロキシモジュールのポート番号が続くドメイン名 $upstream を指す必要があります。 (例: $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"
            }
         ]
      }
   }
}
```

名前	値
`NGINX_DEFAULT_PORT`	nginx プロキシがダウンストリームデバイスからの要求をリッスンするポート。たとえば、`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 モジュールは、最上位レイヤーデバイスで必須であり、下位レイヤーデバイスでは任意です。多層デプロイのサンプルについては、Azure IoT Edge for Industrial IoT サンプルを参照してください。

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

IoT Edge 上の Azure Blob Storage モジュール。

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

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

次の手順を使用して、サポートバンドルまたはログファイルを、最上位レイヤーにある Blob Storage モジュールにアップロードします。

Azure Storage Explorer または REST API のいずれかを使用して、BLOB コンテナーを作成します。詳細については、「IoT Edge 上の Azure Blob Storage を使用してエッジにデータを格納する」を参照してください。
「IoT Edge の展開からログを取得する」の手順に従ってログを要求するか、バンドルのアップロードをサポートします。ただし、Blob Storage モジュールのアドレスの代わりに、ドメイン名 $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 リバースプロキシに提供します。

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

構成ファイルを作成します。この既定のテンプレートを参照 (nginx_default_config) として使用することができます。
構成ファイルのテキストをコピーし、base64 に変換します。
エンコードされた構成ファイルをモジュールツインの proxy_config の必要なプロパティの値として貼り付けます。

次のステップ

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

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

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

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