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

[アーティクル]
06/12/2024

適用対象: IoT Edge 1.5 IoT Edge 1.4

重要

サポートされているリリースは、IoT Edge 1.5 LTS と IoT Edge 1.4 LTS です。 IoT Edge 1.4 LTS は、2024 年 11 月 12 日にサポートが終了します。以前のリリースの場合は、「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) から入手でき、イメージ URI は mcr.microsoft.com/azureiotedge-api-proxy:latest です。 Azure portal または Azure CLI を使用してモジュールをデプロイできます。

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

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 プロキシモジュールを構成する

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

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

既定の構成

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

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

プロキシポートの公開

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

プロキシ構成を編集する

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

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

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

既定の構成

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

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

プロキシ ポートの公開

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

プロキシ構成を編集する

次のステップ

フィードバック

その他のリソース

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

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

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

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

プロキシポートの公開