Preparing Amazon IoT Jobs - Amazon IoT Core
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Preparing Amazon IoT Jobs

Amazon IoT Device Management Software Package Catalog extends Amazon IoT Jobs through substitution parameters, and integration with Amazon IoT fleet indexing, dynamic thing groups, and the Amazon IoT thing’s reserved named shadow.

Note

To use all the functionality that Software Package Catalog offers, you must create these Amazon Identity and Access Management (IAM) roles and policies: Amazon IoT Jobs rights to deploy package versions and Amazon IoT Jobs rights to update the reserved named shadow. For more information, see Preparing security.

Substitution parameters for Amazon IoT jobs

You can use substitution parameters as a placeholder within your Amazon IoT job document. When the job service encounters a substitution parameter, it points the job to a named software version’s attribute for the parameter value. You can use this process to create a single job document and pass the metadata into the job through general-purpose attributes. For example, you might pass an Amazon Simple Storage Service(Amazon S3) URL, a software package Amazon Resource Name (ARN), or a signature into the job document through package version attributes.

The substitution parameter should be formatted in the job document as follows:

${aws:iot:package:<packageName>:version:<versionName>:attributes:<anyAttributeName>}

In this example, there is a software package named, samplePackage, and it has a package version named 2.1.5 that has the following attributes:

  • name: s3URL, value: https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile

    • This attribute identifies the location of the code file that’s stored within Amazon S3.

  • name: signature, value: aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj

    • This attribute provides a code signature value that the device requires as a security measure. For more information, see Code Signing for jobs. Note: This attribute is an example and not required as part of Software Package Catalog or jobs.

For downloads, the job document parameter is written as follows:

{ "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}" }

For signature, the job document parameter is written as follows:

{ "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}" }

The complete job document is written as follows:

{ ... "Steps": { "uninstall": ["samplePackage"], "download": [ { "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}" }, ], "signature": [ "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}" ] } }

After the substitution is made, the following job document is deployed to the devices:

{ ... "Steps": { "uninstall": ["samplePackage"], "download": [ { "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile" }, ], "signature": [ "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj" ] } }

For more information about Amazon IoT Jobs, creating job documents, and deploying jobs, see Jobs.

Preparing the job document and package version for deployment

When a package version is created, it’s in a draft state to indicate that it’s being prepared for deployment. To prepare the package version for deployment, you must create a job document, save the document in a location that the job can access (such as Amazon S3), and confirm that the package version has the attribute values that you want the job document to use. (Note: You can update attributes for a package version only while it’s in the draft state.)

When you are satisfied with the package version, publish it either through the software package details page in the Amazon IoT console or by issuing the UpdatePackageVersion API operation. You can then reference the package version when you create the job either through the Amazon IoT console or by issuing the CreateJob API operation.

Naming the packages and versions when deploying

When you deploy an Amazon IoT job, you must name the same software packages and package versions that are named in the job document in the job deployment (destinationPackageVersions). If you don’t, you'll receive an error message stating the missing package versions.

You can include additional software packages and package versions that aren't included within the job document. If you do this, the job doesn't provide instructions to the device about what to do with those files and the device is expected to know what to do. For example, you might send additional files to the device if they contain data that the device might reference.

Targeting jobs through Amazon IoT dynamic thing groups

Software Package Catalog works with fleet indexing, Amazon IoT jobs, and Amazon IoT dynamic thing groups to filter and target devices within your fleet to select which package version to deploy to your devices. You can run a fleet indexing query based on your device's current package information and target those things for an Amazon IoT job. You can also release software updates, but only to eligible target devices. For example, you can specify that you want to deploy a configuration only to those devices that currently run the iot-device-client 1.5.09. For more information, see Create a dynamic thing group.

Reserved named shadow and package versions

If configured, Amazon IoT Jobs can update a thing’s reserved named shadow ($package)when the job successfully completes. If you do so, you don’t need to manually associate a package version to a thing’s reserved named shadow.

You might choose to manually associate or update a package version to the thing’s reserved named shadow in the following situations:

  • You register a thing to Amazon IoT Core without associating the installed package version.

  • Amazon IoT Jobs isn’t configured to update the thing’s reserved named shadow.

  • You use an in-house process to dispatch package versions to your fleet and that process doesn’t update Amazon IoT Core when it completes.

Note

We recommend you use Amazon IoT Jobs to update the package version in the reserved named shadow ($package). Updating the version parameter in the $package shadow through other processes (such as, manual or programmatic API calls) when Amazon IoT Jobs is also configured to update the shadow, can cause inconsistencies between the actual version on device and version reported to the reserved named shadow.

You can add or update a package version to a thing’s reserved named shadow ($package) through the console or the UpdateThingShadow API operation. For more information, see Associating a package version to an Amazon IoT thing.

Note

Associating a package version to an Amazon IoT thing doesn’t directly update the device software. You must deploy the package version to the device to update the device software.

Uninstalling a software package and its package version

$null is a reserved placeholder that prompts the Amazon IoT Jobs service to remove the existing software package and package version from the device’s reserved named shadow $package. For more information, see Reserved named shadow.

To use this feature, replace the version name at the end of the destinationPackageVersion Amazon Resource Name (ARN) with $null. Afterward, you must instruct your service to remove the software from the device.

The authorized ARN uses the following format:

arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$null

For example,

$ aws iot create-job \ ... \ --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]