Deploy Amazon IoT Greengrass components to devices
You can use Amazon IoT Greengrass to deploy components to devices or groups of devices. You use deployments to define the components and configurations that are sent to the devices. Amazon IoT Greengrass deploys to targets, Amazon IoT things or thing groups that represent Greengrass core devices. Amazon IoT Greengrass uses Amazon IoT Core jobs to deploy to your core devices. You can configure how the job rolls out to your devices.
Core device deployments
Each core device runs the components of the deployments for that device. A new deployment to the same target overwrites the previous deployment to the target. When you create a deployment, you define the components and configurations to apply to the core device's existing software.
When you revise a deployment for a target, you replace the components from the previous
revision with the components in the new revision. For example, you deploy the Log manager and Secret manager components to
the thing group TestGroup. Then you create another deployment for
TestGroup that specifies only the secret manager component. As a result, the
core devices in that group no longer run the log manager.
Platform dependency resolution
When a core device receives a deployment, it checks to make sure that the components are compatible with the core device. For example, if you deploy the Firehose to a Windows target, the deployment will fail.
Component dependency resolution
The core device also checks whether each components dependencies are compatible with version constraints for deployments of other components to this thing group. Where the version constraints for a component overlap, Greengrass uses the highest applicable version of the component. For example:
-
You deploy component A to
TestGroup. Component A depends on componentcom.example.PythonRuntimeversions 3.5 - 3.10. -
You then deploy component B to
TestGroup. Component B depends on componentcom.example.PythonRuntimeversions 3.7 to 3.8.
As a result, core devices in TestGroup determine that they can deploy version
3.8 of the com.example.PythonRuntime component because this version is the
highest applicable version where the version constraints overlap.
You then deploy component C to TestGroup. Component C depends on component
com.example.PythonRuntime versions 2.6 - 2.7. This deployment fails because
there's no component version that meets the constraint 2.6 - 2.7 and 3.7 - 3.8.
Removing a device from a thing group
When you remove a core device from a thing group, the component deployment behavior depends on the version of the Greengrass nucleus that the core device runs.
Deployments
Deployments are continuous. When you create a deployment, Amazon IoT Greengrass rolls out the deployment to target devices that are online. If a target device isn't online, then it receives the deployment the next time it connects to Amazon IoT Greengrass. When you add a core device to a target thing group, Amazon IoT Greengrass sends the device the latest deployment for that thing group.
Before a core device deploys a component, by default it notifies each component on the device. Greengrass components can respond to the notification to defer deployment. You might want to defer deployment if the device has a low battery level or is running a process that can't be interrupted. For more information, see Tutorial: Develop a Greengrass component that defers component updates. When you create a deployment you can configure it to deploy without notifying components.
Each target thing or thing group can have one deployment at a time. This means that when you create a deployment for a target, Amazon IoT Greengrass no longer deploys the previous revision of that target's deployment.
Deployment options
Deployments provide several options that let you control which devices receive an update and how the update deploys. When you create a deployment, you can configure the following options:
-
Amazon IoT Greengrass components
Define the components to install and run on the target devices. Amazon IoT Greengrass components are software modules that you deploy and run on Greengrass core devices. Devices receive components only if the component supports the device's platform. This lets you deploy to groups of devices even if the target devices run on multiple platforms. If a component doesn't support the device's platform, the component doesn't deploy to the device.
You can deploy custom components and Amazon-provided components to your devices. When you deploy a component, Amazon IoT Greengrass identifies any component dependencies and deploys them too. For more information, see Develop Amazon IoT Greengrass components and Amazon-provided components.
You define the version and configuration update to deploy for each component. The configuration update specifies how to modify the component's existing configuration on the core device, or the component's default configuration if the component doesn't exist on the core device. You can specify which configuration values to reset to default values and the new configuration values to merge onto the core device. When a core device receives deployments for different targets, and each deployment specifies compatible component versions, the core device applies configuration updates in order based on the timestamp of when you create the deployment. For more information, see Update component configurations.
Important
When you deploy a component, Amazon IoT Greengrass installs the latest supported versions of all of that component's dependencies. Because of this, new patch versions of Amazon-provided public components might be automatically deployed to your core devices if you add new devices to a thing group, or you update the deployment that targets those devices. Some automatic updates, such as a nucleus update, can cause your devices to restart unexpectedly.
To prevent unintended updates for a component that is running on your device, we recommend that you directly include your preferred version of that component when you create a deployment. For more information about update behavior for Amazon IoT Greengrass Core software, see Update the Amazon IoT Greengrass Core software (OTA).
-
Deployment policies
Define when it's safe to deploy a configuration and what to do if the deployment fails. You can specify whether or not to wait for components to report that they can update. You can also specify whether or not to roll back devices to their previous configuration if they apply a deployment that fails.
-
Stop configuration
Define when and how to stop a deployment. The deployment stops and fails if the criteria that you define are met. For example, you can configure a deployment to stop if a percentage of devices fail to apply that deployment after a minimum number of devices receive it.
-
Rollout configuration
Define the rate at which a deployments rolls out to the target devices. You can configure an exponential rate increase with minimum and maximum rate bounds.
-
Timeout configuration
Define the maximum amount of time each device has to apply a deployment. If a device exceeds the duration that you specify, then the device fails to apply the deployment.
Important
Custom components can define artifacts in S3 buckets. When the Amazon IoT Greengrass Core software deploys a component, it downloads the component's artifacts from the Amazon Web Services Cloud. Core device roles don't allow access to S3 buckets by default. To deploy custom components that define artifacts in an S3 bucket, the core device role must grant permissions to download artifacts from that bucket. For more information, see Allow access to S3 buckets for component artifacts.