共用方式為


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

適用於:IoT Edge 1.5 複選標記 IoT Edge 1.5 IoT Edge 1.4 複選標記 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。 例如:

Docker 檢查 edgeHub 命令結果的螢幕快照。

常見案例

容器建立選項可啟用許多案例,但以下是建置 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 範例: