設定閘道階層案例的 API Proxy 模組

發行項
06/14/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 Proxy 模組的設定選項，以便您可以自訂模組以支援閘道階層需求。

當部署多個服務時，API Proxy 模組可簡化 IoT Edge 裝置的通訊，這些服務全都支援 HTTPS 通訊協定，並繫結至連接埠 443。這特別適用於 ISA-95 型網路隔離架構中 IoT Edge 裝置的階層式部署，例如網路隔離下游裝置中所述的裝置，因為下游裝置上的用戶端無法直接連線到雲端。

例如，若要允許 IoT Edge 下游裝置提取 Docker 映像，需要部署 Docker 登錄模組。若要允許上傳 Blob，需要在相同的 IoT Edge 裝置上部署 Azure Blob 儲存體模組。這兩個服務都會使用 HTTPS 進行通訊。 API Proxy 可在 IoT Edge 裝置上啟用這類部署。 API Proxy 模組不是個別服務，而是繫結至主機裝置上的連接埠 443，並將要求路由傳送至每位使用者可設定規則在該裝置上執行的正確服務模組。個別服務仍負責處理要求，包括驗證和授權用戶端。

如果沒有 API Proxy，每個服務模組都必須繫結至主機裝置上的個別連接埠，這需要在連線至 IoT Edge 父代裝置的每個子系裝置上，進行繁瑣且容易出錯的設定變更。

注意

下游裝置會將資料直接發出至網際網路或網路閘道裝置 (已啟用或未啟用 IoT Edge)。子裝置可以是巢狀拓撲中的下游裝置或網路閘道裝置。

部署 Proxy 模組

API Proxy 模組可從 Microsoft Container Registry (MCR) 取得，而映像 URI 為 mcr.microsoft.com/azureiotedge-api-proxy:latest。您可以使用 Azure 入口網站或 Azure CLI 來部署模組。

了解 Proxy 模組

API Proxy 模組會利用 nginx 反向 Proxy，透過網路層來路由傳送資料。 Proxy 內嵌在模組中，這表示模組映像需要支援 Proxy 組態。例如，如果 Proxy 正在接聽特定連接埠，則模組必須開放該連接埠。

Proxy 會從內嵌在模組中的預設設定檔開始。您可以使用其模組對應項，將新的設定從雲端傳遞至模組。此外，您可以使用環境變數在部署期間開啟或關閉組態設定。

本文首先著重於預設設定檔，以及如何使用環境變數來啟用其設定。然後，我們會在結尾討論自訂設定檔。

預設的組態

API Proxy 模組隨附支援常見案例的預設組態，並允許自訂。您可以透過模組的環境變數來控制預設組態。

目前，預設環境變數包括：

環境變數	描述
`PROXY_CONFIG_ENV_VAR_LIST`	列出您想要在逗號分隔清單中更新的所有變數。此步驟可防止意外修改錯誤的組態設定。
`NGINX_DEFAULT_TLS`	指定要啟用的 TLS 通訊協定清單。請參閱 NGINX 的 ssl_protocols。預設值為「TLSv1.2」。
`NGINX_DEFAULT_PORT`	變更 nginx Proxy 接聽的連接埠。如果您更新此環境變數，則必須在模組 dockerfile 中公開連接埠，並在部署資訊清單中宣告為連接埠繫結。如需詳細資訊，請參閱公開 Proxy 連接埠。預設值為 443。從 Azure Marketplace 部署時，預設連接埠會更新為 8000，以避免與 edgeHub 模組發生衝突。如需詳細資訊，請參閱將開放的連接埠數量最小化。
`DOCKER_REQUEST_ROUTE_ADDRESS`	路由傳送 Docker 要求的位址。修改最上層裝置上的此變數，以指向登錄模組。預設值為父代主機名稱。
`BLOB_UPLOAD_ROUTE_ADDRESS`	路由傳送 Blob 登錄要求的位址。修改最上層裝置上的此變數，以指向 Blob 儲存體模組。預設值為父代主機名稱。

將開放的連接埠數量最小化

為了將開放的連接埠數量最小化，API Proxy 模組應該轉送所有 HTTPS 流量 (連接埠 443)，包括以 edgeHub 模組為目標的流量。 API Proxy 模組預設會設定為在連接埠 443 上重新路由傳送所有 edgeHub 流量。

使用下列步驟來設定部署，以將開放的連接埠數量最小化：

將 edgeHub 模組設定更新為不要繫結在連接埠 443 上，否則會有連接埠繫結衝突。根據預設，edgeHub 模組會在連接埠 443、5671 和 8883 上繫結。刪除連接埠 443 繫結，並保留其他兩個繫結：
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
設定 API Proxy 模組以繫結在連接埠 443 上。
1. 將 NGINX_DEFAULT_PORT 環境變數的值設定為 443。
2. 將容器建立選項更新為繫結在連接埠 443 上。
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

如果您不需要將開放的連接埠數量最小化，您可以讓 edgeHub 模組使用連接埠 443，並將 API Proxy 模組設定為接聽另一個連接埠。例如，API Proxy 模組可以將 NGINX_DEFAULT_PORT 環境變數的值設定為 8000，並建立連接埠 8000 的連接埠繫結，來接聽連接埠 8000。

啟用容器映像下載

API Proxy 模組的常見使用案例，是讓較低層中的 IoT Edge 裝置提取容器映像。此案例會使用 Docker 登錄模組從雲端擷取容器映像，並在最上層快取。 API Proxy 會轉送所有 HTTPS 要求，以從較低層下載容器映像，供最上層的登錄模組提供服務。

此案例要求下游 IoT Edge 裝置指向網域名稱 $upstream，後面接著 API Proxy 模組連接埠號碼，而不是映像的容器登錄。例如： $upstream:8000/azureiotedge-api-proxy:1.1 。

本使用案例會在使用閘道建立 IoT Edge 裝置階層教學課程中示範。

在最上層設定下列模組：

Docker 登錄模組
- 使用 registry 之類的易記名稱設定模組，並在模組中公開連接埠以接收要求。
- 設定模組以對應至您的容器登錄。

API Proxy 模組

設定下列環境變數：

名稱	值
`DOCKER_REQUEST_ROUTE_ADDRESS`	登錄模組名稱與開放的連接埠。例如： `registry:5000` 。
`NGINX_DEFAULT_PORT`	nginx Proxy 接聽來自下游裝置要求的連接埠。例如： `8000` 。

設定下列 createOptions：

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

在此案例的任何較低層上設定下列模組：

API Proxy 模組。除了底層裝置以外，所有較低層裝置上都需要 API Proxy 模組。
- 設定下列環境變數：
  
  名稱值
  
  NGINX_DEFAULT_PORT nginx Proxy 接聽來自下游裝置要求的連接埠。例如： 8000 。
- 設定下列 createOptions：
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

名稱	值
`NGINX_DEFAULT_PORT`	nginx Proxy 接聽來自下游裝置要求的連接埠。例如： `8000` 。

公開 Proxy 連接埠

連接埠 8000 預設會從 Docker 映像公開。如果使用不同的 nginx Proxy 連接埠，請在部署指令清單中新增宣告連接埠的 ExposedPorts 區段。例如，如果您將 nginx Proxy 連接埠變更為 8001，請將下列內容新增至部署指令清單：

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

啟用 Blob 上傳

API Proxy 模組的常見使用案例，是讓較低層中的 IoT Edge 裝置上傳 Blob。此使用案例可在較低層裝置上啟用疑難排解功能，例如上傳模組記錄或上傳支援套件組合。

此案例會使用最上層 IoT Edge 模組上的 Azure Blob 儲存體來處理 Blob 建立和上傳。在巢狀案例中，最多支援五個圖層。 IoT Edge 模組上的 Azure Blob 儲存體 是最上層裝置上的必要專案，對於較低層裝置則為選用專案。如需多層部署範例，請參閱適用於工業 IoT 的 Azure IoT Edge 範例。

在最上層設定下列模組：

IoT Edge 模組上的 Azure Blob 儲存體。

API Proxy 模組

設定下列環境變數：

名稱	值
`BLOB_UPLOAD_ROUTE_ADDRESS`	Blob 儲存體模組名稱與開放的連接埠。例如： `azureblobstorageoniotedge:11002` 。
`NGINX_DEFAULT_PORT`	nginx Proxy 接聽來自下游裝置要求的連接埠。例如： `8000` 。

設定下列 createOptions：

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

在此案例的任何較低層上設定下列模組：

API Proxy 模組
- 設定下列環境變數：
  
  名稱值
  
  NGINX_DEFAULT_PORT nginx Proxy 接聽來自下游裝置要求的連接埠。例如： 8000 。
- 設定下列 createOptions：
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

名稱	值
`NGINX_DEFAULT_PORT`	nginx Proxy 接聽來自下游裝置要求的連接埠。例如： `8000` 。

使用下列步驟，將支援套件組合或記錄檔上傳至位於最上層的 Blob 儲存體模組：

使用 Azure 儲存體總管或 REST API 建立 Blob 容器。如需詳細資訊，請參閱在 IoT Edge 上使用 Azure Blob 儲存體儲存邊緣資料。
根據從 IoT Edge 部署擷取記錄中的步驟，要求記錄或支援套件組合上傳，但使用網域名稱 $upstream 和開放的 Proxy 連接埠來取代 Blob 儲存體模組位址。例如：
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

編輯 Proxy 組態

預設設定檔會內嵌在 API Proxy 模組中，但您可以使用模組對應項，透過雲端將新的設定傳遞至模組。

當您撰寫自己的設定時，您仍然可以使用環境來調整每個部署的設定。使用下列語法：

使用 ${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 模組剖析 Proxy 設定時，它會先使用替代，以其提供的值來取代 PROXY_CONFIG_ENV_VAR_LIST 中所列的所有環境變數。然後，會取代 #if_tag　和 #endif_tag 配對之間的全部內容。模組接著會將已剖析的設定提供給 nginx 反向 Proxy。

若要動態更新 Proxy 設定，請使用下列步驟：

撰寫您的設定檔。您可以使用此預設範本作為參考：nginx_default_config.conf
複製設定檔的文字，並將其轉換為 base64。
將編碼的設定檔貼上為模組對應項中 proxy_config 所需屬性的值。

下一步

使用 API Proxy 模組將下游 IoT Edge 裝置連線到 Azure IoT Edge 閘道。

共用方式為