Create deployments

You can create a deployment that targets a thing or thing group.

When you create a deployment, you configure the software components to deploy and how the deployment job rolls out to target devices. You can define the deployment in the JSON file that you provide to the Amazon CLI.

The deployment target determines the devices on which you want to run your components. To deploy to one core device, specify a thing. To deploy to multiple core devices, specify a thing group that includes those devices. For more information about how to configure thing groups, see Static thing groups and Dynamic thing groups in the Amazon IoT Developer Guide.

Follow the steps in this section to create a deployment to a target. For more information about how to update the software components on a target that has a deployment, see Revise deployments.

Warning

The CreateDeployment operation can uninstall components from core devices. If a component is present in the previous deployment and not the new deployment, the core device uninstalls that component. To avoid uninstalling components, first use the ListDeployments operation to check if the target for the deployment already has an existing deployment. Then, use the GetDeployment operation to start from that existing deployment when you create a new deployment.

To create a deployment (Amazon CLI)

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 or thing group to target for the deployment. Thing and thing group ARNs have the following format:
- Thing: arn:aws-cn:iot:region:account-id:thing/thingName
- Thing group: arn:aws-cn:iot:region:account-id:thinggroup/thingGroupName
```
{
  "targetArn": "targetArn"
}
```
Check if the deployment target has an existing deployment that you want to revise. Do the following:
1. Run the following command to list the deployments for the deployment target. Replace targetArn with the ARN of the target Amazon IoT thing or thing group.
```
aws greengrassv2 list-deployments --target-arn targetArn
```
  The response contains a list with the latest deployment for the target. If the response is empty, the target doesn't have an existing deployment, and you can skip to Step 3. Otherwise, copy the deploymentId from the response to use in the next step.
  
  Note
  You can also revise a deployment other than the latest revision for the target. Specify the --history-filter ALL argument to list all deployments for the target. Then, copy the ID of the deployment that you want to revise.
2. Run the following command to get the deployment's details. These details include metadata, components, and job configuration. Replace deploymentId with the ID from the previous step.
```
aws greengrassv2 get-deployment --deployment-id deploymentId
```
  The response contains the deployment's details.
3. Copy any of the following key-value pairs from the previous command's response into deployment.json. You can change these values for the new deployment.
  - deploymentName – The deployment's name.
  - components – The deployment's components. To uninstall a component, remove it from this object.
  - deploymentPolicies – The deployment's policies.
  - iotJobConfiguration – The deployment's job configuration.
  - tags – The deployment's tags.
(Optional) Define a name for the deployment. Replace deploymentName with the name of the deployment.
```
{
  "targetArn": "targetArn",
  "deploymentName": "deploymentName"
}
```
Add each component to deploy the target devices. To do so, add key-value pairs to the components object, where the key is the component name, and the value is an object that contains the details for that component. Specify the following details for each component that you add:
- version – The component version to deploy.
- configurationUpdate – The configuration update to deploy. The update is a patch operation that modifies the component's existing configuration on each target device, or the component's default configuration if it doesn't exist on the target device. You can specify the following configuration updates:
  - Reset updates (reset) – (Optional) A list of JSON pointers that define the configuration values to reset to their default values on the target device. The Amazon IoT Greengrass Core software applies reset updates before it applies merge updates. For more information, see Reset updates.
  - Merge updates (merge) – (Optional) A JSON document that defines the configuration values to merge onto the target device. You must serialize the JSON document as a string. For more information, see Merge updates.
- runWith – (Optional) The system process options that the Amazon IoT Greengrass Core software uses to run this component's processes on the core device. If you omit a parameter in the runWith object, the Amazon IoT Greengrass Core software uses the default values that you configure on the Greengrass nucleus component.
  
  You can specify any of the following options:
  - posixUser – The POSIX system user and, optionally, group to use to run this component on Linux core devices. The user, and group if specified, must exist on each Linux core device. Specify the user and group separated by a colon (:) in the following format: user:group. The group is optional. If you don't specify a group, the Amazon IoT Greengrass Core software uses the primary group for the user. For more information, see Configure the user that runs components.
  - windowsUser – The Windows user to use to run this component on Windows core devices. The user must exist on each Windows core device, and its name and password must be stored in the LocalSystem account's Credentials Manager instance. For more information, see Configure the user that runs components.
    
    This feature is available for v2.5.0 and later of the Greengrass nucleus component.
  - systemResourceLimits – The system resource limits to apply to this component's processes. You can apply system resource limits to generic and non-containerized Lambda components. For more information, see Configure system resource limits for components.
    
    You can specify any of the following options:
    
    cpus – The maximum amount of CPU time that this component's processes can use on the core device. A core device's total CPU time is equivalent to the device's number of CPU cores. For example, on a core device with 4 CPU cores, you can set this value to 2 to limit this component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this value to 0.25 to limit this component's processes to 25 percent usage of the CPU. If you set this value to a number greater than the number of CPU cores, the Amazon IoT Greengrass Core software doesn't limit the component's CPU usage.
    
    memory – The maximum amount of RAM (in kilobytes) that this component's processes can use on the core device.
    
    This feature is available for v2.4.0 and later of the Greengrass nucleus component. Amazon IoT Greengrass doesn't currently support this feature on Windows core devices.
Example basic configuration update
The following example components object specifies to deploy a component, com.example.PythonRuntime, that expects a configuration parameter named pythonVersion.
```
{
  "targetArn": "targetArn",
  "deploymentName": "deploymentName",
  "components": {
    "com.example.PythonRuntime": {
      "componentVersion": "1.0.0",
      "configurationUpdate": {
        "merge": "{\"pythonVersion\":\"3.7\"}"
      }
    }
  }
}
```
Example configuration update with reset and merge updates
Consider an example industrial dashboard component, com.example.IndustrialDashboard, that has the following default configuration.
```
{
  "name": null,
  "mode": "REQUEST",
  "network": {
    "useHttps": true,
    "port": {
      "http": 80,
      "https": 443
    },
  },
  "tags": []
}
```
The following configuration update specifies the following instructions:
1. Reset the HTTPS setting to its default value (true).
2. Reset the list of industrial tags to an empty list.
3. Merge a list of industrial tags that identify temperature and pressure data streams for two boilers.
```
{
  "reset": [
    "/network/useHttps",
    "/tags"
  ],
  "merge": {
    "tags": [
      "/boiler/1/temperature",
      "/boiler/1/pressure",
      "/boiler/2/temperature",
      "/boiler/2/pressure"
    ]
  }
}
```
The following example components object specifies to deploy this industrial dashboard component and configuration update.
```
{
  "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\"]}"
      }
    }
  }
}
```
(Optional) Define deployment policies for the deployment. You can configure when core devices can safely apply a deployment or what to do if a core device fails to apply the deployment. To do so, add a deploymentPolicies object to deployment.json, and then do any of the following:
1. (Optional) Specify the component update policy (componentUpdatePolicy). This policy defines whether or not the deployment lets components defer an update until they are ready to update. For example, components may need to clean up resources or finish critical actions before they can restart to apply an update. This policy also defines the amount of time that components have to respond to an update notification.
  
  This policy is an object with the following parameters:
  - action – (Optional) Whether or not to notify components and wait for them to report when they're ready to update. Choose from the following options:
    
    NOTIFY_COMPONENTS – The deployment notifies each component before it stops and updates that component. Components can use the SubscribeToComponentUpdates IPC operation to receive these notifications.
    
    SKIP_NOTIFY_COMPONENTS – The deployment doesn't notify components or wait for them to be safe to update.
    
    Defaults to NOTIFY_COMPONENTS.
  - timeoutInSeconds The amount of time in seconds that each component has to respond to an update notification with the DeferComponentUpdate IPC operation. If the component doesn't respond within this amount of time, then the deployment proceeds on the core device.
    
    Defaults to 60 seconds.
2. (Optional) Specify the configuration validation policy (configurationValidationPolicy). This policy defines how long each component has to validate a configuration update from a deployment. Components can use the SubscribeToValidateConfigurationUpdates IPC operation to subscribe to notifications for their own configuration updates. Then, components can use the SendConfigurationValidityReport IPC operation to tell the Amazon IoT Greengrass Core software if the configuration update is valid. If the configuration update isn't valid, the deployment fails.
  
  This policy is an object with the following parameter:
  - timeoutInSeconds (Optional) The amount of time in seconds that each component has to validate a configuration update. If the component doesn't respond within this amount of time, then the deployment proceeds on the core device.
    
    Defaults to 30 seconds.
3. (Optional) Specify the failure handling policy (failureHandlingPolicy). This policy is a string that defines whether or not to roll back devices if the deployment fails. Choose from the following options:
  - ROLLBACK – If the deployment fails on a core device, then the Amazon IoT Greengrass Core software rolls back that core device to its previous configuration.
  - DO_NOTHING – If the deployment fails on a core device, then the Amazon IoT Greengrass Core software keeps the new configuration. This can result in broken components if the new configuration isn't valid.
  Defaults to ROLLBACK.
Your deployment in deployment.json may look similar to the following example:
```
{
  "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"
  }
}
```

(Optional) Define how the deployment stops, rolls out, or times out. Amazon IoT Greengrass uses Amazon IoT Core jobs to send deployments to core devices, so these options are identical to the configuration options for Amazon IoT Core jobs. For more information, see Job rollout and abort configuration in the Amazon IoT Developer Guide.

To define the job options, add an iotJobConfiguration object to deployment.json. Then, define the options to configure.

Your deployment in deployment.json may look similar to the following example:


{
  "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
    }
  }
}

(Optional) Add tags (tags) for the deployment. For more information, see Tag your Amazon IoT Greengrass Version 2 resources.
Run the following command to create the deployment from deployment.json.
```
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.

Deploy components to devices

Update component configurations

Create deployments

Warning

To create a deployment (Amazon CLI)

Note

Example basic configuration update

Example configuration update with reset and merge updates