建立部署 - AWS IoT Greengrass

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

建立部署

您可以建立以物件或物群組為目標的部署。

建立部署時，您可以規劃要部署的軟體元件，以及如何將部署工作推出至目標裝置。您可以在提供給的 JSON 檔案中定義部署AWS CLI。

部署目標會決定您要在其上執行元件的裝置。若要部署至一個核心裝置，請指定物件。若要部署到多個核心裝置，請指定包含這些裝置的物件群組。如需有關如何設定物件群組的詳細資訊，請參閱AWS IoT開發人員指南中的靜態物件群組與動態物件群組。

請遵循本節中的步驟來建立目標的部署。如需如何在具有部署之目標上更新軟體元件的詳細資訊，請參閱修訂部署。

警告

該CreateDeployment操作可以從核心設備卸載組件。如果元件存在於先前的部署中，而不是新部署中，則核心裝置會解除安裝該元件。若要避免解除安裝元件，請先使用此ListDeployments作業來檢查部署的目標是否已有現有部署。然後，在建立新部署時，使用該GetDeployment作業從該現有部署開始。

若要建立部署 (AWS CLI)

  1. 建立名為的檔案deployment.json，然後將下列 JSON 物件複製到檔案中。以要針對部署的目標之AWS IoT物件或物群組的 ARN 取代 Tar Tarn。物件與物件群組 ARN 具有下列格式：

    • 物件：arn:aws:iot:region:account-id:thing/thingName

    • 物件群組：arn:aws:iot:region:account-id:thinggroup/thingGroupName

    {
  "targetArn": "targetArn"
}

  2. 檢查部署目標是否具有您要修訂的現有部署。請執行下列操作：

    1. 執行下列命令以列出部署目標的部署。以目標AWS IoT物件或物群組的 ARN 取代目標 targe tArn n。

      aws greengrassv2 list-deployments --target-arn targetArn

      回應包含一份包含目標最新部署的清單。如果回應為空白，表示目標沒有現有的部署，您可以跳到步驟 3。否則，請deploymentId從響應中復制以在下一個步驟中使用。

      注意

      您也可以修訂目標的最新修訂版以外的部署。指定--history-filter ALL引數以列出目標的所有部署。然後，複製您要修訂的部署 ID。

    2. 執行下列命令以取得部署的詳細資料。這些詳細資料包括中繼資料、元件和工作組態。使用上一個步驟的 ID 取代部署 ID。

      aws greengrassv2 get-deployment --deployment-id deploymentId

      回應包含部署的詳細資料。

    3. 將以下任何鍵-值對從上一個命令的響應複製到deployment.json。您可以變更新部署的這些值。

      • deploymentName— 部署的名稱。

      • components— 部署的元件。若要解除安裝元件，請將其從此物件中移除。

      • deploymentPolicies— 部署的原則。

      • iotJobConfiguration— 部署的工作組態。

      • tags— 部署的標籤。

  3. (選擇性) 定義部署的名稱。將部署名稱取代為部署的名稱。

    {
  "targetArn": "targetArn",
  "deploymentName": "deploymentName"
}

  4. 新增每個元件以部署目標裝置。若要這麼做，請將索引鍵值配對新增至components物件，其中索引鍵是元件名稱，而值是包含該元件詳細資訊的物件。為您新增的每個元件指定下列詳細資訊：

    • version— 要部署的元件版本。

    • configurationUpdate— 要部署的組態更新。更新是修補程式作業，會修改元件在每個目標裝置上的現有組態，或修改元件的預設組態 (如果目標裝置上不存在)。您可以指定下列組態更新：

      • 重設更新 (reset) — (選用) JSON 指標清單，用於定義要在目標裝置上重設為預設值的組態值。AWS IoT Greengrass Core 軟體會先套用重設更新，然後再套用合併更新。如需詳細資訊，請參閱 重設更新。

      • 合併更新 (merge) — (選用) 定義要合併到目標裝置的組態值的 JSON 文件。您必須將 JSON 文檔序列化為字符串。如需詳細資訊，請參閱 合併更新。

    • runWith— (選擇性) AWS IoT Greengrass Core 軟體用來在核心裝置上執行此元件處理程序的系統處理程序選項。如果您省略runWith物件中的參數，AWS IoT Greengrass核心軟體會使用您在 Greengrass 核心元件上設定的預設值。

      您可以指定下列任何選項：

      • posixUser— 用於在 Linux 核心裝置上執行此元件的 POSIX 系統使用者和 (選擇性) 群組。使用者和群組 (若有指定) 必須存在於每個 Linux 核心裝置上。以下列格式指定使用者和群組，並以冒號 (:) 分隔：user:group。群組為選用項目。如果您未指定群組，AWS IoT GreengrassCore 軟體會使用使用者的主要群組。如需詳細資訊，請參閱 設定執行元件的使用者。

      • windowsUser— 用來在 Windows 核心裝置上執行此元件的 Windows 使用者。使用者必須存在於每個 Windows 核心裝置上，且其名稱和密碼必須儲存在 LocalSystem 帳戶的認證管理員執行個體中。如需詳細資訊，請參閱 設定執行元件的使用者。

        此功能適用於 v2.5.0 及更高版 Greeng rass 核組件。

      • systemResourceLimits— 系統資源限制套用至此元件的處理序。您可以將系統資源限制套用至一般和非容器化 Lambda 元件。如需詳細資訊，請參閱 設定元件的系統資源限制。

        您可以指定下列任何選項：

        • cpus— 此元件的處理序可以在核心裝置上使用的 CPU 時間上限。核心裝置的 CPU 總時間等於裝置的 CPU 核心數。例如，在具有 4 個 CPU 核心的核心裝置上，您可以將此值設定為2將此元件的處理序限制為每個 CPU 核心的 50% 使用率。在具有 1 個 CPU 核心的裝置上，您可以將此值設定0.25為將此元件的處理序限制為 CPU 使用率 25%。如果您將此值設定為大於 CPU 核心數目的數字，AWS IoT Greengrass核心軟體就不會限制元件的 CPU 使用率。

        • memory— 此元件的處理序可在核心裝置上使用的最大 RAM 量 (以 KB 為單位)。

        此功能適用於 v2.4.0 和更高版 Greeng rass 核組件。 AWS IoT Greengrass目前在 Windows 核心裝置上不支援此功能。

     

    範例基本組態更新

    下列範例components物件指定要部署需要名為的組態參數的元件pythonVersion。com.example.PythonRuntime

    {
  "targetArn": "targetArn",
  "deploymentName": "deploymentName",
  "components": {
    "com.example.PythonRuntime": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "merge": "{\"pythonVersion\":\"3.7\"}"
      }
    }
  }
}
    範例 包含重設和合併更新的範例組態更新

    請考慮具有下列預設組態的工業儀表板元件範例。com.example.IndustrialDashboard

    {
  "name": null,
  "mode": "REQUEST",
  "network": {
    "useHttps": true,
    "port": {
      "http": 80,
      "https": 443
    },
  },
  "tags": []
}

    下列組態更新會指定下列指示：

    1. 將 HTTPS 設定重設為預設值 (true)。

    2. 將工業標籤清單重設為空白清單。

    3. 合併工業標籤清單，以識別兩個鍋爐的溫度和壓力資料流。

    {
  "reset": [
    "/network/useHttps",
    "/tags"
  ],
  "merge": {
    "tags": [
      "/boiler/1/temperature",
      "/boiler/1/pressure",
      "/boiler/2/temperature",
      "/boiler/2/pressure"
    ]
  }
}

    下列範例components物件指定要部署此工業儀表板元件和組態更新。

    {
  "targetArn": "targetArn",
  "deploymentName": "deploymentName",
  "components": {
    "com.example.IndustrialDashboard": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "reset": [
          "/network/useHttps",
          "/tags"
        ],
        "merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
      }
    }
  }
}

  5. (選擇性) 定義部署的部署原則。您可以設定核心裝置何時可以安全地套用部署，或是核心裝置無法套用部署時該如何處理。若要這樣做，請將deploymentPolicies物件新增至deployment.json，然後執行下列任一項作業：

    1. (選擇性) 指定元件更新原則 (componentUpdatePolicy)。此原則定義部署是否允許元件延遲更新，直到準備好更新為止。例如，元件可能需要清理資源或完成重要動作，才能重新啟動以套用更新。此原則也會定義元件必須回應更新通知的時間量。

      此原則是具有下列參數的物件：

      • action— (選用) 是否要通知元件，並等待它們在準備更新時報告。您可以從以下選項中選擇：

        • NOTIFY_COMPONENTS – 部署會在停止前向每個元件發出通知並更新該元件。元件可以使用 SubscribeToComponentUpdates IPC 作業來接收這些通知。

        • SKIP_NOTIFY_COMPONENTS – 部署不會向元件發出通知，也不會等到可安全更新元件時才更新。

        預設為 NOTIFY_COMPONENTS。

      • timeoutInSeconds每個元件必須透過 DeferComponentUpdate IPC 作業回應更新通知的時間 (以秒為單位)。如果元件沒有在這段時間內回應，則部署會在核心裝置上繼續進行。

        預設值為 60 秒。

    2. (選擇性) 指定組態驗證原則 (configurationValidationPolicy)。此原則定義每個元件必須驗證部署中組態更新的時間長度。元件可以使用 SubscribeToValidateConfigurationUpdates IPC 作業來訂閱其自身組態更新的通知。然後，組件可以使用 SendConfigurationValidityReport IPC 操作來告訴 AWS IoT Greengrass Core 軟件配置更新是否有效。如果組態更新無效，則部署會失敗。

      此原則是具有下列參數的物件：

      • timeoutInSeconds(選擇性) 每個元件驗證組態更新所需的時間 (秒)。如果元件沒有在這段時間內回應，則部署會在核心裝置上繼續進行。

        預設值為 30 秒。

    3. (選擇性) 指定失敗處理原則 (failureHandlingPolicy)。此原則是一個字串，用來定義部署失敗時是否要復原裝置。您可以從以下選項中選擇：

      • ROLLBACK— 如果核心裝置上的部署失敗，則 AWS IoT Greengrass Core 軟體會將該核心裝置回復為先前的組態。

      • DO_NOTHING— 如果核心裝置上的部署失敗，則 AWS IoT Greengrass Core 軟體會保留新的組態。如果新的組態無效，這可能會導致損毀的元件。

      預設為 ROLLBACK。

    您在中的部署看起來deployment.json可能類似下列範例：

    {
  "targetArn": "targetArn",
  "deploymentName": "deploymentName",
  "components": {
    "com.example.IndustrialDashboard": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "reset": [
          "/network/useHttps",
          "/tags"
        ],
        "merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
      }
    }
  },
  "deploymentPolicies": {
    "componentUpdatePolicy": {
      "action": "NOTIFY_COMPONENTS",
      "timeoutInSeconds": 30
    },
    "configurationValidationPolicy": {
      "timeoutInSeconds": 60
    },
    "failureHandlingPolicy": "ROLLBACK"
  }
}

  6. (選擇性) 定義部署停止、推出或逾時的方式。 AWS IoT Greengrass使用AWS IoT Core工作將部署傳送至核心裝置，因此這些選項與AWS IoT Core工作的組態選項相同。如需詳細資訊，請參閱AWS IoT開發人員指南中的 Job 推出和中止設定。

    若要定義工作選項，請將iotJobConfiguration物件新增至deployment.json。然後，定義要設定的選項。

    您在中的部署看起來deployment.json可能類似下列範例：

    {
  "targetArn": "targetArn",
  "deploymentName": "deploymentName",
  "components": {
    "com.example.IndustrialDashboard": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "reset": [
          "/network/useHttps",
          "/tags"
        ],
        "merge": "{\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}"
      }
    }
  },
  "deploymentPolicies": {
    "componentUpdatePolicy": {
      "action": "NOTIFY_COMPONENTS",
      "timeoutInSeconds": 30
    },
    "configurationValidationPolicy": {
      "timeoutInSeconds": 60
    },
    "failureHandlingPolicy": "ROLLBACK"
  },
  "iotJobConfiguration": {
    "abortConfig": {
      "criteriaList": [
        {
          "action": "CANCEL",
          "failureType": "ALL",
          "minNumberOfExecutedThings": 100,
          "thresholdPercentage": 5
        }
      ]
    },
    "jobExecutionsRolloutConfig": {
      "exponentialRate": {
        "baseRatePerMinute": 5,
        "incrementFactor": 2,
        "rateIncreaseCriteria": {
          "numberOfNotifiedThings": 10,
          "numberOfSucceededThings": 5
        }
      },
      "maximumPerMinute": 50
    },
    "timeoutConfig":  {
      "inProgressTimeoutInMinutes": 5
    }
  }
}

  7. (選擇性) 為部署新增標籤 (tags)。如需詳細資訊，請參閱 標記您的 AWS IoT Greengrass Version 2 資源。

  8. 執行下列命令以從中建立部署deployment.json。

    aws greengrassv2 create-deployment --cli-input-json file://deployment.json

    回應包括識別deploymentId此部署的。您可以使用部署 ID 來檢查部署的狀態。如需更多詳細資訊，請參閱 檢查部署狀態。