本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 创建部署 您可以创建以事物或事物组为目标的部署。 创建部署时，需要配置要部署的软件组件以及部署作业如何扩展到目标设备。您可以在提供给 AWS CLI 的 JSON 文件中定义部署。 部署目标可确定要在哪些设备上运行组件。要部署到一台核心设备，请指定一个事物。要部署到多台核心设备，请指定包含这些设备的事物组。有关如何配置事物组的更多信息，请参阅《AWS IoT 开发人员指南》**中的[静态事物组](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html)和[动态事物组](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html)。 按照本节中的步骤将部署创建到目标中。有关如何在具有部署的目标上更新软件组件的更多信息，请参阅 [修改部署](revise-deployments.md)。 **警告** [CreateDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_CreateDeployment.html) 操作可以从核心设备上卸载组件。如果某个组件存在于之前的部署中（而不是新部署中），则核心设备将卸载该组件。为避免卸载组件，请先使用 [ListDeployments](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_ListDeployments.html) 操作来检查部署目标是否已有现存的部署。然后，在创建新部署时，使用 [GetDeployment](https://docs.aws.amazon.com/greengrass/v2/APIReference/API_GetDeployment.html) 操作从现存的部署开始操作。 **要创建部署（AWS CLI），请执行以下操作** 1. 创建一个名为 `deployment.json` 的文件，然后将以下 JSON 对象复制到该文件中。将 *targetArn* 替换为部署目标的 AWS IoT 事物或事物组的 ARN。事物和事物组 ARN 的格式如下： + 事物：`arn:aws:iot:region:account-id:thing/thingName` + 事物组：`arn:aws:iot:region:account-id:thinggroup/thingGroupName` ``` { "targetArn": "targetArn" } ``` 1. 检查部署目标是否有要修改的现有部署。执行以下操作： 1. 运行以下命令，列出部署目标的部署。将 *targetArn* 替换为目标 AWS IoT 事物或事物组的 ARN。 ``` aws greengrassv2 list-deployments --target-arn targetArn ``` 响应中包含目标最新部署的列表。如果响应为空，则表示目标没有现有部署，您可以跳到 [Step 3](#create-deployment-define-name-step)。否则，请复制响应中的 `deploymentId`，以便在下一步中使用。 **注意** 您还可以修改除目标最新修订之外的部署。指定 `--history-filter ALL` 参数以列出目标的所有部署。然后，复制要修改的部署的 ID。 1. 运行以下命令，获取部署的详细信息。这些详细信息包括元数据、组件和作业配置。将 *deploymentId* 替换为上一步中的 ID。 ``` aws greengrassv2 get-deployment --deployment-id deploymentId ``` 响应包含部署的详细信息。 1. 从上一个命令的响应中，将以下任何键值对复制到 `deployment.json` 中。您可以为新部署更改这些值。 + `deploymentName` – 部署的名称。 + `components` – 部署的组件。要卸载组件，请将其从该对象中移除。 + `deploymentPolicies` – 部署的策略。 + `iotJobConfiguration` – 部署的作业配置。 + `tags` – 部署的标签。 1. （可选）定义部署的名称。将 *deploymentName* 替换为部署的名称。 ``` { "targetArn": "targetArn", "deploymentName": "deploymentName" } ``` 1. 添加每个组件以部署目标设备。为此，请向 `components` 对象添加键值对，其中键是组件名称，值是包含该组件详细信息的对象。为添加的每个组件指定以下详细信息： + `version` – 要部署的组件版本。 + `configurationUpdate` – 要部署的[配置更新](update-component-configurations.md)。更新是一项修补操作，用于修改组件在每台目标设备上的现有配置，或者修改组件的默认配置（如果目标设备上不存在该配置）。您可以指定以下配置更新： + 重置更新（`reset`）–（可选）JSON 指针列表，用于定义要在目标设备上重置为默认值的配置值。AWS IoT Greengrass 核心软件会在其应用合并更新前应用重置更新。有关更多信息，请参阅 [重置更新](update-component-configurations.md#reset-configuration-update)。 + 合并更新（`merge`）–（可选）JSON 文档，用于定义要合并到目标设备的配置值。必须将 JSON 文档序列化为字符串。有关更多信息，请参阅 [合并更新](update-component-configurations.md#merge-configuration-update)。 + `runWith` –（可选）AWS IoT Greengrass Core 软件在核心设备上运行此组件进程时使用的系统进程选项。如果您忽略 `runWith` 对象中的参数，AWS IoT Greengrass Core 软件会使用您在 [Greengrass nucleus 组件](greengrass-nucleus-component.md)上配置的默认值。 您可以指定以下任意选项： + `posixUser` – 用于在 Linux 核心设备上运行此组件的 POSIX 系统用户和（可选的）组。用户和组（如果已指定）必须存在于每台 Linux 核心设备上。使用以下格式指定由半角冒号（`:`）分隔的用户和组：`user:group`。组是可选的。如果您未指定组，则 AWS IoT Greengrass Core 软件会为用户使用主组。有关更多信息，请参阅 [配置运行组件的用户](configure-greengrass-core-v2.md#configure-component-user)。 + `windowsUser` – 用于在 Windows 核心设备上运行此组件的 Windows 用户。用户必须存在于每台 Windows 核心设备上，并且其名称和密码必须存储于 LocalSystem 账户的 Credentials Manager 实例中。有关更多信息，请参阅 [配置运行组件的用户](configure-greengrass-core-v2.md#configure-component-user)。 此功能适用于 [Greengrass Nucleus 组件](greengrass-nucleus-component.md) v2.5.0 及更高版本。 + `systemResourceLimits` – 应用于此组件进程的系统资源限制。您可以将系统资源限制应用于通用和非容器化 Lambda 组件。有关更多信息，请参阅 [配置组件的系统资源限制](configure-greengrass-core-v2.md#configure-component-system-resource-limits)。 您可以指定以下任意选项： + `cpus` – 此组件进程可在核心设备上使用的最大 CPU 时间。核心设备的总 CPU 时间等于 CPU 核心的设备数量。例如，在一台有 4 个 CPU 核心的核心设备上，您可以将此值设置为 `2`，以便将此组件进程限制为使用每个 CPU 核心的 50%。在一台有 1 个 CPU 核心的设备上，您可以将此值设置为 `0.25`，以便将此组件进程限制为使用 CPU 的 25%。如果您将此值设置为大于 CPU 核心数量的数字，AWS IoT Greengrass 核心软件不会限制组件的 CPU 使用。 + `memory` – 此组件进程可在核心设备上使用的最大 RAM 数量（以千字节表示）。 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的 v2.4.0 及更高版本中提供了此功能。AWS IoT Greengrass 目前不支持在 Windows 核心设备上使用此功能。   **Example 基本配置更新示例** 以下示例 `components` 对象指定部署组件 `com.example.PythonRuntime`，该组件需要名为 `pythonVersion` 的配置参数。 ``` { "targetArn": "targetArn", "deploymentName": "deploymentName", "components": { "com.example.PythonRuntime": { "componentVersion": "1.0.0", "configurationUpdate": { "merge": "{\"pythonVersion\":\"3.7\"}" } } } } ``` **Example 使用重置更新和合并更新的配置更新示例** 以一个具有以下默认配置的工业控制面板组件 `com.example.IndustrialDashboard` 为例。 ``` { "name": null, "mode": "REQUEST", "network": { "useHttps": true, "port": { "http": 80, "https": 443 }, }, "tags": [] } ``` 以下配置更新指定了以下说明： 1. 将 HTTPS 设置重置为默认值（`true`）。 1. 将工业标签列表重置为空列表。 1. 将用于标识两台锅炉温度和压力数据流的工业标签列表合并。 ``` { "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\"]}" } } } } ``` 1. （可选）为部署定义部署策略。您可以配置核心设备何时可以安全地应用部署，或者在核心设备无法应用部署时该怎么做。为此，请将 `deploymentPolicies` 对象添加到 `deployment.json` 中，然后执行以下任意操作： 1. （可选）指定组件更新策略（`componentUpdatePolicy`）。此策略定义了部署是否允许组件推迟更新，直到组件准备好更新。例如，组件可能需要清理资源或完成关键操作，然后才能重新启动以应用更新。此策略还定义了组件响应更新通知所需的时长。 此策略是具有以下参数的对象： + `action` –（可选）是否通知组件并等待组件在准备好更新时报告。从以下选项中进行选择： + `NOTIFY_COMPONENTS` – 部署会在其停止并更新该组件前通知每个组件。组件可以使用 [SubscribeToComponentUpdates](ipc-component-lifecycle.md#ipc-operation-subscribetocomponentupdates) IPC 操作来接收这些通知。 + `SKIP_NOTIFY_COMPONENTS` – 部署不会通知组件或等待它们可安全更新。 默认值为 `NOTIFY_COMPONENTS`。 + `timeoutInSeconds` 每个组件通过 [DeferComponentUpdate](ipc-component-lifecycle.md#ipc-operation-defercomponentupdate) IPC 操作响应更新通知所需的时长（以秒为单位）。如果组件在这段时间内没有响应，则部署将在核心设备上继续进行。 默认值为 60 秒。 1. （可选）指定配置验证策略（`configurationValidationPolicy`）。此策略定义了每个组件验证部署中的配置更新所需的时长。组件可以使用 [SubscribeToValidateConfigurationUpdates](ipc-component-configuration.md#ipc-operation-subscribetovalidateconfigurationupdates) IPC 操作为自己的配置更新订阅通知。然后，组件可以使用 [SendConfigurationValidityReport](ipc-component-configuration.md#ipc-operation-sendconfigurationvalidityreport) IPC 操作来告知 AWS IoT Greengrass Core 软件配置更新是否有效。如果配置更新无效，则部署失败。 此策略是具有以下参数的对象： + `timeoutInSeconds`（可选）每个组件验证配置更新所需的时长（以秒为单位）。如果组件在这段时间内没有响应，则部署将在核心设备上继续进行。 默认值为 30 秒。 1. （可选）指定故障处理策略（`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" } } ``` 1. （可选）定义部署如何停止、推出或超时。AWS IoT Greengrass 使用 AWS IoT Core 作业将部署发送到核心设备，因此这些选项与 AWS IoT Core 作业的配置选项相同。有关更多信息，请参阅《AWS IoT 开发人员指南》**中的[作业推出和中止配置](https://docs.aws.amazon.com/iot/latest/developerguide/job-rollout-abort.html)。 要定义作业选项，请将 `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 } } } ``` 1. （可选）为部署添加标签（`tags`）。有关更多信息，请参阅 [标记您的 AWS IoT Greengrass Version 2 资源](tag-resources.md)。 1. 要从 `deployment.json` 创建部署，请运行以下命令。 ``` aws greengrassv2 create-deployment --cli-input-json file://deployment.json ``` 响应中包含用于标识此部署的 `deploymentId`。您可以使用部署 ID 来检查部署的状态。有关更多信息，请参阅 [检查部署状态](check-deployment-status.md#check-cloud-deployment-status)。 # 更新组件配置 组件配置是定义每个组件参数的 JSON 对象。每个组件的配方都定义了其默认配置，当您将组件部署至核心设备时，可以修改这些配置。 创建部署时，可以指定要应用于每个组件的*配置更新*。配置更新是补丁操作，这意味着更新会修改核心设备上存在的组件配置。如果核心设备没有该组件，则配置更新会修改并应用该部署的默认配置。 配置更新定义了*重置*更新和*合并*更新。重置更新定义了要将哪些配置值重置为默认值或移除哪些配置值。合并更新定义要为组件设置的新配置值。部署配置更新时， AWS IoT Greengrass Core 软件会在合并更新之前运行重置更新。 组件可以验证您部署的配置更新。当部署更改配置时，该组件会订阅以接收通知，并可拒绝不支持的配置。有关更多信息，请参阅 [与组件配置交互](ipc-component-configuration.md)。 **Topics** + [重置更新](#reset-configuration-update) + [合并更新](#merge-configuration-update) + [示例](#configuration-update-example) ## 重置更新 重置更新定义了要重置为核心设备默认值的配置值。如果配置值没有默认值，则重置更新会将该值从组件的配置中移除。这可以帮助您修复因配置无效而中断的组件。 使用 JSON 指针列表来定义要重置哪些配置值。JSON 指针以正斜杠 `/` 开头。要识别嵌套组件配置中的值，请使用正斜杠 (`/`) 分隔配置中每一级的键。有关更多信息，请参阅 [JSON 指针规范](https://tools.ietf.org/html/rfc6901)。 **注意** 您只能将整个列表重置为其默认值。您不能使用重置更新来重置列表中的单个元素。 要将组件的整个配置重置为其默认值，请指定一个空字符串作为重置更新。 ``` "reset": [""] ``` ## 合并更新 合并更新定义了要插入核心组件配置的配置值。合并更新是一个 JSON 对象， AWS IoT Greengrass 核心软件会在重置您在重置更新中指定的路径中重置值后合并该对象。使用 AWS CLI 或时 AWS SDKs，必须将此 JSON 对象序列化为字符串。 您可以合并组件默认配置中不存在的键值对。您也可以合并类型与具有相同键的值不同的键值对。新值将替换旧值。这意味着您可以更改配置对象的结构。 您可以合并空值和空字符串、列表和对象。 **注意** 不能将合并更新用于在列表中插入元素或将元素附加到列表中。您可以替换整个列表，也可以定义一个对象，其中每个元素都有一个唯一键。 AWS IoT Greengrass 使用 JSON 作为配置值。JSON 指定了数字类型，但不区分整数和浮点数。因此， AWS IoT Greengrass中的配置值可能会转换为浮点数。为确保您的组件使用正确的数据类型，我们建议您将数字配置值定义为字符串。然后，让组件将其解析为整数或浮点数。这样可以确保您的配置值在配置和核心设备上具有相同的类型。 ### 在合并更新中使用配方变量 此功能适用于 [Greengrass Nucleus 组件](greengrass-nucleus-component.md)的 v2.6.0 及更高版本。 如果您将 Greengrass n [interpolateComponentConfiguration](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-interpolate-component-configuration)ucleus 的配置选项设置为，则可以在合并更新中使用配方变量`true`以外的配`component_dependency_name:configuration:json_pointer`方变量。例如，您可以在合并更新中使用`{iot:thingName}`配方变量，将核心设备 AWS IoT 的事物名称包含在组件配置值（例如[进程间通信 (IPC) 授权策略）](interprocess-communication.md#ipc-authorization-policies)中。 ## 示例 以下示例演示了具有以下默认配置的控制面板组件的配置更新。此示例组件显示有关工业设备的信息。 ``` { "name": null, "mode": "REQUEST", "network": { "useHttps": true, "port": { "http": 80, "https": 443 }, }, "tags": [] } ``` ### 工业控制面板组件配方 ------ #### [ JSON ] ``` { "RecipeFormatVersion": "2020-01-25", "ComponentName": "com.example.IndustrialDashboard", "ComponentVersion": "1.0.0", "ComponentDescription": "Displays information about industrial equipment.", "ComponentPublisher": "Amazon", "ComponentConfiguration": { "DefaultConfiguration": { "name": null, "mode": "REQUEST", "network": { "useHttps": true, "port": { "http": 80, "https": 443 }, }, "tags": [] } }, "Manifests": [ { "Platform": { "os": "linux" }, "Lifecycle": { "Run": "python3 -u {artifacts:path}/industrial_dashboard.py" } }, { "Platform": { "os": "windows" }, "Lifecycle": { "Run": "py -3 -u {artifacts:path}/industrial_dashboard.py" } } ] } ``` ------ #### [ YAML ] ``` --- RecipeFormatVersion: '2020-01-25' ComponentName: com.example.IndustrialDashboard ComponentVersion: '1.0.0' ComponentDescription: Displays information about industrial equipment. ComponentPublisher: Amazon ComponentConfiguration: DefaultConfiguration: name: null mode: REQUEST network: useHttps: true port: http: 80 https: 443 tags: [] Manifests: - Platform: os: linux Lifecycle: Run: | python3 -u {artifacts:path}/industrial_dashboard.py - Platform: os: windows Lifecycle: Run: | py -3 -u {artifacts:path}/industrial_dashboard.py ``` ------ **Example 示例 1：合并更新** 您可以创建应用以下配置更新的部署，指定合并更新，但不指定重置更新。此配置更新会告知组件在 HTTP 端口 8080 上显示控制面板，其中包含来自两个锅炉的数据。 **要合并的配置** ``` { "name": "Factory 2A", "network": { "useHttps": false, "port": { "http": 8080 } }, "tags": [ "/boiler/1/temperature", "/boiler/1/pressure", "/boiler/2/temperature", "/boiler/2/pressure" ] } ``` 以下命令会创建对核心设备的部署。 ``` aws greengrassv2 create-deployment --cli-input-json file://dashboard-deployment.json ``` `dashboard-deployment.json` 文件包含以下 JSON 文档。 ``` { "targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore", "deploymentName": "Deployment for MyGreengrassCore", "components": { "com.example.IndustrialDashboard": { "componentVersion": "1.0.0", "configurationUpdate": { "merge": "{\"name\":\"Factory 2A\",\"network\":{\"useHttps\":false,\"port\":{\"http\":8080}},\"tags\":[\"/boiler/1/temperature\",\"/boiler/1/pressure\",\"/boiler/2/temperature\",\"/boiler/2/pressure\"]}" } } } } ``` 以下 [Greengrass CLI](greengrass-cli-component.md) 命令会在核心设备上创建本地部署。 ``` sudo greengrass-cli deployment create \ --recipeDir recipes \ --artifactDir artifacts \ --merge "com.example.IndustrialDashboard=1.0.0" \ --update-config dashboard-configuration.json ``` `dashboard-configuration.json` 文件包含以下 JSON 文档。 ``` { "com.example.IndustrialDashboard": { "MERGE": { "name": "Factory 2A", "network": { "useHttps": false, "port": { "http": 8080 } }, "tags": [ "/boiler/1/temperature", "/boiler/1/pressure", "/boiler/2/temperature", "/boiler/2/pressure" ] } } } ``` 此次更新后，控制面板组件具有以下配置。 ``` { "name": "Factory 2A", "mode": "REQUEST", "network": { "useHttps": false, "port": { "http": 8080, "https": 443 } }, "tags": [ "/boiler/1/temperature", "/boiler/1/pressure", "/boiler/2/temperature", "/boiler/2/pressure" ] } ``` **Example 示例 2：重置和合并更新** 然后，您可以创建应用以下配置更新的部署，指定重置更新和合并更新。这些更新指定在默认的 HTTPS 端口上显示控制面板，其中包含来自不同锅炉的数据。这些更新修改了上一个示例中配置更新所产生的配置。 **重置路径** ``` [ "/network/useHttps", "/tags" ] ``` **要合并的配置** ``` { "tags": [ "/boiler/3/temperature", "/boiler/3/pressure", "/boiler/4/temperature", "/boiler/4/pressure" ] } ``` 以下命令会创建对核心设备的部署。 ``` aws greengrassv2 create-deployment --cli-input-json file://dashboard-deployment2.json ``` `dashboard-deployment2.json` 文件包含以下 JSON 文档。 ``` { "targetArn": "arn:aws:iot:us-west-2:123456789012:thing/MyGreengrassCore", "deploymentName": "Deployment for MyGreengrassCore", "components": { "com.example.IndustrialDashboard": { "componentVersion": "1.0.0", "configurationUpdate": { "reset": [ "/network/useHttps", "/tags" ], "merge": "{\"tags\":[\"/boiler/3/temperature\",\"/boiler/3/pressure\",\"/boiler/4/temperature\",\"/boiler/4/pressure\"]}" } } } } ``` 以下 [Greengrass CLI](greengrass-cli-component.md) 命令会在核心设备上创建本地部署。 ``` sudo greengrass-cli deployment create \ --recipeDir recipes \ --artifactDir artifacts \ --merge "com.example.IndustrialDashboard=1.0.0" \ --update-config dashboard-configuration2.json ``` `dashboard-configuration2.json` 文件包含以下 JSON 文档。 ``` { "com.example.IndustrialDashboard": { "RESET": [ "/network/useHttps", "/tags" ], "MERGE": { "tags": [ "/boiler/3/temperature", "/boiler/3/pressure", "/boiler/4/temperature", "/boiler/4/pressure" ] } } } ``` 此次更新后，控制面板组件具有以下配置。 ``` { "name": "Factory 2A", "mode": "REQUEST", "network": { "useHttps": true, "port": { "http": 8080, "https": 443 } }, "tags": [ "/boiler/3/temperature", "/boiler/3/pressure", "/boiler/4/temperature", "/boiler/4/pressure", ] } ```