如何設定 IoT Edge 模組的容器建立選項

發行項
12/04/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。

部署資訊清單中的 createOptions 參數可讓您在執行階段設定模組容器。此參數會擴充您對模組的控制，並允許可允許或限制模組對主機裝置資源的存取權或設定網路這類工作。

IoT Edge 模組會實作為 IoT Edge 裝置上的 Docker 相容容器。 Docker 提供許多用於建立容器的選項，而且這些選項也適用於 IoT Edge 模組。如需詳細資訊，請參閱 Docker 容器建立選項。

格式化建立選項

IoT Edge 部署資訊清單接受格式化為 JSON 的建立選項。例如，採用每個 edgeHub 模組自動包括的建立選項：

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

此 edgeHub 範例會使用 HostConfig.PortBindings 參數，以將容器上的已公開連接埠對應至主機裝置上的連接埠。

如果您使用適用於 Visual Studio 或 Visual Studio Code 的 Azure IoT Edge 延伸模組，則可以在 deployment.template.json 檔案中以 JSON 格式撰寫建立選項。然後，當您使用此延伸模組來建置 IoT Edge 解決方案或產生部署資訊清單時，將會以 IoT Edge 執行階段所預期的格式對 JSON 進行字串化。例如：

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

重要

Azure IoT Edge Visual Studio Code 延伸模組目前處於維護模式。 iotedgedev 工具是開發 IoT Edge 模組的建議工具。

撰寫建立選項的其中一個秘訣是使用 docker inspect 命令。在開發程序期間，使用 docker run <container name> 以在本機執行模組。當您讓模組以您想要的方式運作之後，請執行 docker inspect <container name>。此命令會輸出 JSON 格式的模組詳細資料。尋找您所設定的參數，並複製 JSON。例如：

常見案例

容器建立選項可啟用許多案例，但以下是建置 IoT Edge 解決方案時最常發生的一些案例：

提供模組存取本機儲存體的權限
將主機連接埠對應至模組連接埠
限制模組記憶體和 CPU 使用量
GPU 最佳化 IoT Edge 模組

將主機連接埠對應至模組連接埠

如果您的模組需要與 IoT Edge 解決方案以外的服務進行通訊，而且未使用訊息路由來執行此動作，則您需要將主機連接埠對應至模組連接埠。

提示

相同裝置上的模組對模組通訊不需要此連接埠對應。如果模組 A 需要查詢模組 B 上所裝載的 API，則可以執行此動作，而不需要任何連接埠對應。模組 B 需要在其 dockerfile 中公開連接埠，例如：EXPOSE 8080。然後，模組 A 可以使用模組 B 的名稱來查詢 API，例如：http://ModuleB:8080/api。

首先，請確定公開模組內的連接埠以接聽連線。您可以使用 dockerfile 中的 EXPOSE 指令來執行此動作。例如： EXPOSE 8080 。如果未指定，則公開指令預設為 TCP 通訊協定，或者您可以指定 UDP。

然後，使用 Docker 容器建立選項之 HostConfig 群組中的 PortBindings 設定，以將模組中公開的連接埠對應至主機裝置上的連接埠。例如，如果您已在模組內公開連接埠 8080，而且想要將該連接埠對應至主機裝置的連接埠 80，則 template.json 檔案中的建立選項看起來會像下列範例：

"createOptions": {
  "HostConfig": {
    "PortBindings": {
      "8080/tcp": [
        {
          "HostPort": "80"
        }
      ]
    }
  }
}

針對部署資訊清單進行字串化之後，相同的設定看起來會像下列範例：

"createOptions": "{\"HostConfig\":{\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"80\"}]}}}"

限制模組的記憶體和 CPU 使用量

您可以宣告模組可使用多少主機資源。此控制項有助於確保一個模組不會耗用太多記憶體或 CPU 使用量，並防止在裝置上執行其他程序。您可以使用 HostConfig 群組中的 Docker 容器建立選項來管理這些設定，包括：

Memory：記憶體限制 (位元組)。例如，268435456 個位元組 = 256 MB。
MemorySwap：記憶體總限制 (記憶體 + 交換)。例如，536870912 個位元組 = 512 MB。
NanoCpus：以 10^-9 (十億分之一) 個 CPU 為單位的 CPU 配額。例如，250000000 nanocpus = 0.25 CPU。

在 template.json 格式中，這些值看起來會像下列範例：

"createOptions": {
  "HostConfig": {
    "Memory": 268435456,
    "MemorySwap": 536870912,
    "NanoCpus": 250000000
  }
}

針對最終部署資訊清單進行字串化之後，這些值看起來會像下列範例：

"createOptions":"{\"HostConfig\":{\"Memory\":268435456,\"MemorySwap\":536870912,\"CpuPeriod\":25000}}"

GPU 最佳化 IoT Edge 模組

如果您要在 GPU 最佳化虛擬機器上執行 IoT Edge 模組，則也可以啟用 IoT Edge 模組來連線至 GPU。若要使用現有模組來執行此動作，請將一些規格新增至您的 createOptions：

{"HostConfig": {"DeviceRequests": [{"Count": -1,"Capabilities": [["gpu"]]}]}}

若要確認已成功新增這些設定，請使用 Docker 檢查命令來查看 JSON 列印輸出中的新設定。

sudo docker inspect <YOUR-MODULE-NAME>

若要深入了解您的裝置和虛擬機器如何連線至 GPU，請參閱設定、連線和驗證 GPU 的 IoT Edge 模組。

下一步

如需作用中建立選項的更多範例，請參閱下列 IoT Edge 範例：

共用方式為