ゲートウェイ階層シナリオ用に API プロキシ モジュールを構成する
適用対象: 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 プロキシ モジュールを構成します。
NGINX_DEFAULT_PORT 環境変数の値を
443
に設定します。コンテナー作成オプションを更新して、ポート 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" } ] } } }
プロキシ ポートの公開
ポート 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" } ] } } }
次の手順を使用して、サポート バンドルまたはログ ファイルを、最上位レイヤーにある 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 ゲートウェイに接続します。