Create subdeployments

Note

The subdeployment feature is available on Greengrass nucleus version 2.9.0 and later. It is not possible to deploy a configuration to a subdeployment with earlier component versions of Greengrass nucleus.

A subdeployment is a deployment that targets a smaller subset of devices within a parent deployment. You can use subdeployments to deploy a configuration to a smaller subset of devices. You can also create subdeployments to retry an unsuccessful parent deployment when one or more devices in that parent deployment fails. With this feature, you can select devices that failed in that parent deployment and create a subdeployment to test configurations until the subdeployment is successful. Once the subdeployment is successful, you can redeploy that configuration to the parent deployment.

Follow the steps in this section to create a subdeployment and check its status. For more information about how to create deployments, see Create deployments.

To create a subdeployment (Amazon CLI)

Run the following command to retrieve the latest deployments for a thing group. Replace the ARN in the command with the ARN of the thing group to query. Set --history-filter to LATEST_ONLY to see the latest deployment of that thing group.
```
aws greengrassv2 list-deployments --target-arn arn:aws-cn:iot:region:account-id:thinggroup/thingGroupName --history-filter LATEST_ONLY
```
Copy the deploymentId from the response to the list-deployments command to use in the next step.
Run the following command to retrieve the status of a deployment. Replace deploymentId with the ID of the deployment to query.
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
Copy the iotJobId from the response to the get-deployment command to use in the following step.
Run the following command to retrieve the list of job executions for the specified job. Replace jobID with the iotJobId from the previous step. Replace status with the status you want to filter for. You can filter results with the following statuses:
- QUEUED
- IN_PROGRESS
- SUCCEEDED
- FAILED
- TIMED_OUT
- REJECTED
- REMOVED
- CANCELED
```
aws iot list-job-executions-for-job --job-id jobID --status status
```
Create a new Amazon IoT thing group, or use an existing thing group, for your subdeployment. Then, add an Amazon IoT thing to this thing group. You use thing groups to manage fleets of Greengrass core devices. When you deploy software components to your devices, you can target either individual devices or groups of devices. You can add a device to a thing group with an active Greengrass deployment. Once added, you can then deploy that thing group's software components to that device.

To create a new thing group and add your devices to it, do the following:
1. Create an Amazon IoT thing group. Replace MyGreengrassCoreGroup with the name for the new thing group. You can't use a colon (:) in a thing group name.
  
  Note
  If a thing group for a subdeployment is used with one parentTargetArn, it can't be reused with a different parent fleet. If a thing group has already been used to create a subdeployment for another fleet, the API will return an error.
```
aws iot create-thing-group --thing-group-name MyGreengrassCoreGroup
```
  If the request succeeds, the response looks similar to the following example:
```
{
  "thingGroupName": "MyGreengrassCoreGroup",
  "thingGroupArn": "arn:aws-cn:iot:us-west-2:123456789012:thinggroup/MyGreengrassCoreGroup",
  "thingGroupId": "4df721e1-ff9f-4f97-92dd-02db4e3f03aa"
}
```
2. Add a provisioned Greengrass core to your thing group. Run the following command with these parameters:
  - Replace MyGreengrassCore with the name of your provisioned Greengrass core.
  - Replace MyGreengrassCoreGroup with the name of your thing group.
```
aws iot add-thing-to-thing-group --thing-name MyGreengrassCore --thing-group-name MyGreengrassCoreGroup
```
  The command doesn't have any output if the request succeeds.
Create a file called deployment.json, and then copy the following JSON object into the file. Replace targetArn with the ARN of the Amazon IoT thing group to target for the subdeployment. A subdeployment target can only be a thing group. Thing group ARNs have the following format:
- Thing group – arn:aws-cn:iot:region:account-id:thinggroup/thingGroupName
```
{
  "targetArn": "targetArn"
}
```
Run the following command again to get the original deployment's details. These details include metadata, components, and job configuration. Replace deploymentId with the ID from Step 1. You can use this deployment configuration to configure your subdeployment and make changes as needed.
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
The response contains the deployment's details. Copy any of the following key-value pairs from the get-deployment command's response into deployment.json. You can change these values for the subdeployment. For more information about the details of this command, see GetDeployment.
- components – The deployment's components. To uninstall a component, remove it from this object.
- deploymentName – The deployment's name.
- deploymentPolicies – The deployment's policies.
- iotJobConfiguration – The deployment's job configuration.
- parentTargetArn – The target of the parent deployment.
- tags – The deployment's tags.
Run the following command to create the subdeployment from deployment.json. Replace subdeploymentName with a name for the subdeployment.
```
aws greengrassv2 create-deployment --deployment-name subdeploymentName --cli-input-json file://deployment.json
```
The response includes a deploymentId that identifies this subdeployment. You can use the deployment ID to check the status of the deployment. For more information, see Check deployment status.
If the subdeployment is successful, you can use its configuration to revise the parent deployent. Copy the deployment.json that you used in the previous step. Replace the targetArn in the JSON file with the parent deployment's ARN and run the following command to create the parent deployment using this new configuration.

Note
If you create a new deployment revision of the parent fleet, it replaces all deployment revisions and subdeployments for that parent deployment. For more information, see Revise deployments.
```
aws greengrassv2 create-deployment --cli-input-json file://deployment.json
```
The response includes a deploymentId that identifies this deployment. You can use the deployment ID to check the status of the deployment. For more information, see Check deployment status.

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Update component configurations

Revise deployments