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

發行項
05/02/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 容器建立選項來管理這些設定，包括：

記憶體：以位元組為單位的記憶體限制。例如，268435456個字節 = 256 MB。
MemorySwap：記憶體限制總計（記憶體 + 交換）。例如，536870912個字節 = 512 MB。
NanoCpus：CPU 配額單位為 10-9^{（第 10} 億個）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 inspect 命令來查看 JSON 列印輸出中的新設定。

sudo docker inspect <YOUR-MODULE-NAME>

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

下一步

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

共用方式為