deployments

Creates, updates, deletes, gets or lists a deployments resource.

Overview

Name	deployments
Type	Resource
Id	aws.greengrassv2.deployments

Fields

The following fields are returned by SELECT queries:

get_deployment

Name	Datatype	Description
components	object	The components to deploy. This is a dictionary, where each key is the name of a component, and each key's value is the version and configuration to deploy for that component.
creation_timestamp	string (date-time)	The time at which the deployment was created, expressed in ISO 8601 format.
deployment_id	string	The ID of the deployment.
deployment_name	string	The name of the deployment.
deployment_policies	object	Contains information about policies that define how a deployment updates components and handles failure.
deployment_status	string	The status of the deployment. (ACTIVE, COMPLETED, CANCELED, FAILED, INACTIVE)
iot_job_arn	string	The ARN of the IoT job that applies the deployment to target devices. (pattern: <code>arn:[^:]*:iot:[^:]+:[0-9]+:job/.+</code>)
iot_job_configuration	object	Contains information about an IoT job configuration.
iot_job_id	string	The ID of the IoT job that applies the deployment to target devices.
is_latest_for_target	boolean	Whether or not the deployment is the latest revision for its target.
parent_target_arn	string	The parent deployment's target ARN within a subdeployment. (pattern: <code>arn:[^:]:iot:[^:]:[0-9]+:thinggroup/.+</code>)
revision_id	string	The revision number of the deployment.
tags	object	A list of key-value pairs that contain metadata for the resource. For more information, see Tag your resources in the IoT Greengrass V2 Developer Guide.
target_arn	string	The ARN of the target IoT thing or thing group. (pattern: <code>arn:[^:]:iot:[^:]:[0-9]+:(thing|thinggroup)/.+</code>)

list_deployments

Name	Datatype	Description
creation_timestamp	string (date-time)	The time at which the deployment was created, expressed in ISO 8601 format.
deployment_id	string	The ID of the deployment.
deployment_name	string	The name of the deployment.
deployment_status	string	The status of the deployment. (ACTIVE, COMPLETED, CANCELED, FAILED, INACTIVE)
is_latest_for_target	boolean	Whether or not the deployment is the latest revision for its target.
parent_target_arn	string	The parent deployment's target ARN within a subdeployment. (pattern: <code>arn:[^:]:iot:[^:]:[0-9]+:thinggroup/.+</code>)
revision_id	string	The revision number of the deployment.
target_arn	string	The ARN of the target IoT thing or thing group. When creating a subdeployment, the targetARN can only be a thing group. (pattern: <code>arn:[^:]:iot:[^:]:[0-9]+:(thing|thinggroup)/.+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_deployment	select	deployment_id, region		Gets a deployment. Deployments define the components that run on Greengrass core devices.
list_deployments	select	region	targetArn, historyFilter, parentTargetArn, maxResults, nextToken	Retrieves a paginated list of deployments.
create_deployment	insert	region, targetArn		Creates a continuous deployment for a target, which is a Greengrass core device or group of core devices. When you add a new core device to a group of core devices that has a deployment, IoT Greengrass deploys that group's deployment to the new device. You can define one deployment for each target. When you create a new deployment for a target that has an existing deployment, you replace the previous deployment. IoT Greengrass applies the new deployment to the target devices. Every deployment has a revision number that indicates how many deployment revisions you define for a target. Use this operation to create a new revision of an existing deployment. For more information, see the Create deployments in the IoT Greengrass V2 Developer Guide.
delete_deployment	delete	deployment_id, region		Deletes a deployment. To delete an active deployment, you must first cancel it. For more information, see CancelDeployment. Deleting a deployment doesn't affect core devices that run that deployment, because core devices store the deployment's configuration on the device. Additionally, core devices can roll back to a previous deployment that has been deleted.
cancel_deployment	exec	deployment_id, region		Cancels a deployment. This operation cancels the deployment for devices that haven't yet received it. If a device already received the deployment, this operation doesn't change anything for that device.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
deployment_id	string	The ID of the deployment.
region	string	AWS region (default: us-east-1)
historyFilter	string	The filter for the list of deployments. Choose one of the following options: ALL – The list includes all deployments. LATEST_ONLY – The list includes only the latest revision of each deployment. Default: LATEST_ONLY
maxResults	integer	The maximum number of results to be returned per paginated request. Default: 50
nextToken	string	The token to be used for the next set of paginated results.
parentTargetArn	string	The parent deployment's target ARN within a subdeployment.
targetArn	string	The ARN of the target IoT thing or thing group.

SELECT examples

get_deployment

Gets a deployment. Deployments define the components that run on Greengrass core devices.

SELECT
components,
creation_timestamp,
deployment_id,
deployment_name,
deployment_policies,
deployment_status,
iot_job_arn,
iot_job_configuration,
iot_job_id,
is_latest_for_target,
parent_target_arn,
revision_id,
tags,
target_arn
FROM aws.greengrassv2.deployments
WHERE deployment_id = '{{ deployment_id }}' -- required
AND region = '{{ region }}' -- required
;

list_deployments

Retrieves a paginated list of deployments.

SELECT
creation_timestamp,
deployment_id,
deployment_name,
deployment_status,
is_latest_for_target,
parent_target_arn,
revision_id,
target_arn
FROM aws.greengrassv2.deployments
WHERE region = '{{ region }}' -- required
AND targetArn = '{{ targetArn }}'
AND historyFilter = '{{ historyFilter }}'
AND parentTargetArn = '{{ parentTargetArn }}'
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

INSERT examples

create_deployment

Creates a continuous deployment for a target, which is a Greengrass core device or group of core devices. When you add a new core device to a group of core devices that has a deployment, IoT Greengrass deploys that group's deployment to the new device. You can define one deployment for each target. When you create a new deployment for a target that has an existing deployment, you replace the previous deployment. IoT Greengrass applies the new deployment to the target devices. Every deployment has a revision number that indicates how many deployment revisions you define for a target. Use this operation to create a new revision of an existing deployment. For more information, see the Create deployments in the IoT Greengrass V2 Developer Guide.

INSERT INTO aws.greengrassv2.deployments (
targetArn,
deploymentName,
components,
iotJobConfiguration,
deploymentPolicies,
parentTargetArn,
tags,
clientToken,
region
)
SELECT 
'{{ targetArn }}' /* required */,
'{{ deploymentName }}',
'{{ components }}',
'{{ iotJobConfiguration }}',
'{{ deploymentPolicies }}',
'{{ parentTargetArn }}',
'{{ tags }}',
'{{ clientToken }}',
'{{ region }}'
RETURNING
deployment_id,
iot_job_arn,
iot_job_id
;

Manifest

# Description fields are for documentation purposes
- name: deployments
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the deployments resource.
  - name: targetArn
    value: "{{ targetArn }}"
  - name: deploymentName
    value: "{{ deploymentName }}"
  - name: components
    value: "{{ components }}"
  - name: iotJobConfiguration
    description: |
      Contains information about an IoT job configuration.
    value:
      jobExecutionsRolloutConfig:
        exponentialRate:
          baseRatePerMinute: {{ baseRatePerMinute }}
          incrementFactor: {{ incrementFactor }}
          rateIncreaseCriteria:
            numberOfNotifiedThings: {{ numberOfNotifiedThings }}
            numberOfSucceededThings: {{ numberOfSucceededThings }}
        maximumPerMinute: {{ maximumPerMinute }}
      abortConfig:
        criteriaList:
          - failureType: "{{ failureType }}"
            action: "{{ action }}"
            thresholdPercentage: {{ thresholdPercentage }}
            minNumberOfExecutedThings: {{ minNumberOfExecutedThings }}
      timeoutConfig:
        inProgressTimeoutInMinutes: {{ inProgressTimeoutInMinutes }}
  - name: deploymentPolicies
    description: |
      Contains information about policies that define how a deployment updates components and handles failure.
    value:
      failureHandlingPolicy: "{{ failureHandlingPolicy }}"
      componentUpdatePolicy:
        timeoutInSeconds: {{ timeoutInSeconds }}
        action: "{{ action }}"
      configurationValidationPolicy:
        timeoutInSeconds: {{ timeoutInSeconds }}
  - name: parentTargetArn
    value: "{{ parentTargetArn }}"
  - name: tags
    value: "{{ tags }}"
  - name: clientToken
    value: "{{ clientToken }}"

DELETE examples

delete_deployment

Deletes a deployment. To delete an active deployment, you must first cancel it. For more information, see CancelDeployment. Deleting a deployment doesn't affect core devices that run that deployment, because core devices store the deployment's configuration on the device. Additionally, core devices can roll back to a previous deployment that has been deleted.

DELETE FROM aws.greengrassv2.deployments
WHERE deployment_id = '{{ deployment_id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

cancel_deployment

Cancels a deployment. This operation cancels the deployment for devices that haven't yet received it. If a device already received the deployment, this operation doesn't change anything for that device.

EXEC aws.greengrassv2.deployments.cancel_deployment 
@deployment_id='{{ deployment_id }}' --required, 
@region='{{ region }}' --required
;