# AWS IoT Device Management Software Package Catalog
With AWS IoT Device Management Software Package Catalog, you can maintain an inventory of software packages and their versions. You can associate package versions to individual things and AWS IoT dynamic thing groups, and deploy them through in-house processes or [AWS IoT jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html).
A software package contains one or more package versions, which is a collection of files that can be deployed as a single unit. Package versions can contain firmware, operating system updates, device applications, configurations, and security patches. As the software evolves over time, you can create a new package version and deploy it to your fleet.
The AWS IoT software package hub is located within AWS IoT Core. You can use the hub to centrally register and maintain your software package inventory and metadata, which creates a catalog of software packages and their versions. You can choose to group devices based on software packages and package versions deployed on the device. This feature provides the opportunity to keep device-side package inventory as a named shadow, associate and group devices based on versions, and visualize package version distribution across the fleet by using fleet metrics.
If you have an in-house software deployment system established, you can continue to use that process to deploy your package versions. If you don’t have a deployment process established or if you prefer, we recommend using [AWS IoT jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) to use the features in the Software Package Catalog. For more information, see [Preparing AWS IoT jobs](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html).
**Topics**
+ [Preparing to use Software Package Catalog](preparing-to-use-software-package-catalog.md)
+ [Preparing security](preparing-security.md)
+ [Preparing fleet indexing](preparing-fleet-indexing.md)
+ [Preparing AWS IoT Jobs](preparing-jobs-for-service-package-catalog.md)
+ [Getting started with Software Package Catalog](getting-started-with-software-package-catalog.md)
# Preparing to use Software Package Catalog
The following section provides an overview of the package version lifecycle and information for using AWS IoT Device Management Software Package Catalog.
## Package version lifecycle
A package version can evolve through the following lifecycle states: `draft`, `published`, and `deprecated`. It can also be `deleted`.
![\[The package version lifecycle with the draft, published,and deprecated. It can also be deleted.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/package-catalog-version-lifecycle.png)
+ **Draft**
When you create a package version, it’s in a `draft` state. This state indicates that the software package is being prepared or is incomplete.
While the package version in this state, you can’t deploy it. You can edit the package version’s description, attributes, and tags.
You can transition a package version that’s in the `draft` state to `published` or be `deleted` by using the console, or by issuing either the [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) or [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API operations.
+ **Published**
When your package version is ready to deploy, transition the package version to a `published` state. While in this state, you can choose to identify the package version as the default version by editing the software package in the console or through the [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html) API operation. In this state, you can edit only the description and tags.
You can transition a package version that’s in the `published` state to `deprecated` or be `deleted` by using the console, or issuing either the [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) or [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API operations.
+ **Deprecated**
If a new package version is available, you can transition earlier package versions to `deprecated`. You can still deploy jobs with a deprecated package version. You can also name a deprecated package version as the default version, and edit only the description and tags.
Consider transitioning a package version to `deprecated` when the version is outdated, but you still have devices in the field using the older version or needs to maintain it due to run-time dependency.
You can transition a package version that’s in the `deprecated `state to `published` or be `deleted` by using the console, or issuing either the [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) or [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API operattions.
+ **Deleted**
When you no longer intend to use a package version, you can delete it by using the console or issuing the [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html) API operation.
**Note**
If you delete a package version while there are pending jobs that reference it, you will receive an error message when the job successfully completes and attempts to update the reserved named shadow.
If the software package version you want to delete is named as the default package version, you must first update the package to name another version as default or leave the field unnamed. You can do this by using the console or the [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API operation. (To remove any named package version as default, set the [unsetDefaultVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html#iot-UpdatePackage-request-unsetDefaultVersion) parameter to true when you issue the [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html) API operation).
If you delete a software package through the console, it deletes all of the package versions associated with that package, unless one is named as the default version.
## Package version naming conventions
When you name package versions, it's important to plan and apply a logical naming strategy so that you and others can easily identify the latest package version and the version progression. You must provide a version name when creating the package version, but the strategy and format is largely up to your business case.
As a best practice, we recommend using the Semantic Versioning [SemVer](https://semver.org/) format. For example, `1.2.3` where `1` is the major version for functionally incompatible changes, `2` the major version for functionally compatible changes, and `3` is the patch version (for bug fixes). For more information, see [Semantic Versioning 2.0.0](https://semver.org/). For more information about the package version name requirements, see [versionName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) in the AWS IoT API reference guide.
## Default version
Setting a version as default is optional. You can add or remove default package versions. You can also deploy a package version that is not named as the default version.
When you create a package version, it’s placed in a `draft` state and can’t be named as the default version until you transition the package version to published. Software Package Catalog doesn’t automatically select a version as default or update a newer package version as the default. You must intentionally name the package version you choose through the console or by issuing the [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API operation.
## Version attributes
Version attributes and their values hold important information about your package versions. We recommend that you define general purpose attributes for a package or package version. For example, you might create a name-value pair for platform, architecture, operating system, release date, author, or Amazon S3 URL.
When you create an AWS IoT job with a job document, you can also choose to use a substitution variable (`$parameter`) that refers to an attribute’s value. For more information, see [Preparing AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html).
Version attributes that are used in package versions will not be automatically added to the reserved named shadow and can’t be indexed or queried through Fleet Indexing directly. To index or query package version attributes through Fleet Indexing, you can populate the version attribute in the reserved named shadow.
We recommend that the version attribute parameter in the reserved named shadow capture device-reported properties , such as operation system and installation time. They can also be indexed and queried through Fleet Indexing.
Version attributes aren't required to follow a specific naming convention. You can create name-value pairs to meet your business needs. The combined size of all the attributes on a package version is limited to 3KB. For more information, see [Software Package Catalog software package and package versions limits](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#software_package_catalog_limits).
**Using all attributes in a job document**
You can have all package version attributes automatically added to your job deployment for selected devices. To automatically use all package version attributes programmatically in an API or CLI command, refer to the following job document example:
```
"TestPackage": "${aws:iot:package:TestPackage:version:PackageVersion:attributes}"
```
## Software Bill of Materials
The software bill of materials (SBOM) provides a central repository for all aspects of your software package. In addition to storing software packages and package versions, you can store the software bill of materials (SBOM) associated with each package version in AWS IoT Device Management Software Package Catalog. A software package contains one or more package versions and each package version consists of one or more components. Each of those components supporting the composition of a specific package version can be described and cataloged using a software bill of materials. The industry standards for software bill of materials supported are SPDX and CycloneDX. When a SBOM is first created, it undergoes validation against the SPDX and CycloneDX industry standard format. For more information on SPDX, see [System Package Data Exchange](https://spdx.dev/). For more information on CycloneDX, see [CycloneDX](https://cyclonedx.org/).
The software bill of materials describes all aspects of a specific package version's components such as package information, file information, and other pertinent metadata. See the below example of a software bill of materials document structure in the SPDX format:
![\[An example of a SBOM in the SPDX format.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/spdx-2.3-document.png)
### Software Bill of Materials Benefits
One of the key benefits for adding your software bill of materials for a package version in Software Package Catalog is vulnerability management.
**Vulnerability management**
Assessing and mitigating your vulnerability to apparent security risks in software components remains critical to protecting the integrity of your device fleet. With the addition of the software bill of materials stored in Software Package Catalog for each package version, you can proactively expose gaps in security by knowing what devices are at risk based on their package version and SBOM using your own in-house vulnerability management solution. You can deploy fixes to those affected devices and protect your fleet of devices.
### Software Bill of Materials Storage
The software bill of materials (SBOM) for each software package version are stored in an Amazon S3 bucket using the Amazon S3 versioning feature. The Amazon S3 bucket storing the SBOM must be located in the same region where the package version was created. An Amazon S3 bucket using the versioning feature maintains multiple variants of an object in the same bucket. For more information on using versioning in an Amazon S3 bucket, see [Using versioning in Amazon S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html).
**Note**
Each software package version can have multiple SBOM files attached to it, but the SBOM files must be stored in a single zip archive file.
The specific Amazon S3 key and version ID for your bucket are used to uniquely identify each version of a software bill of materials for a package version.
**Note**
For a package version with a single SBOM file, you can store that SBOM file in your Amazon S3 bucket as a zip archive file.
For a package version with multiple SBOM files, you must place all SBOM files in a single zip archive file and then store that zip archive file in your Amazon S3 bucket.
All SBOM files stored in the single zip archive file in both scenarios are formatted as either SPDX or CycloneDX .json files.
**Permissions Policy**
In order for AWS IoT acting as the specified principal to access the SBOM zip archive files stored in the Amazon S3 bucket, you need a resource-based permissions policy. Refer to the following example for the correct resource-based permissions policy:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": [
"iot.amazonaws.com"
]
},
"Action": "s3:*",
"Resource": "arn:aws:s3:::bucketName/*"
}
]
}
```
For more information on resource-based permission policies, see [AWS IoT resource-based policies](security_iam_service-with-iam.md#security_iam_service-with-iam-resource-based-policies)
**Updating the SBOM**
You can update the software bill of materials as often as needed to protect and enhance your device fleet. Each time the software bill of materials is updated in your Amazon S3 bucket, the version ID changes and you must associate the new Amazon S3 bucket URL with the appropriate software package version. You will see the new version ID in the **Amazon S3 Object version ID** column on the package version page in the AWS Management Console. Additionally, you can use the API operation `[GetPackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_GetPackageVersion.html)` or the CLI command `[get-package-version](https://docs.aws.amazon.com/cli/latest/reference/iot/get-package-version.html)` to view the new version ID.
**Note**
Updating your software bill of materials, which will cause a new version ID, will not cause a new package version to be created.
For more information on Amazon S3 object keys, see [Creating object key names](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html).
## Enabling AWS IoT fleet indexing
Enabling AWS IoT fleet indexing is a requirement to use AWS IoT Device Management Software Package Catalog. To leverage AWS IoT fleet indexing with Software Package Catalog, set the reserved named shadow (`$package`) as the data source for each device you want to index on and gather metrics. For more information on reserved named shadows, see [Reserved named shadow](#reserved-named-shadow).
Fleet indexing provides support that enables AWS IoT things to be grouped through dynamic thing groups that are filtered by software package version. For example, fleet indexing can identify things that have or don’t have a specific package version installed, don’t have any package versions installed, or match specific name-value pairs. Finally, fleet indexing provides standard and custom metrics that you can use to gain insight about the state of your device fleet. For more information, see [Preparing fleet indexing](preparing-fleet-indexing.md).
**Note**
Enabling fleet indexing for Software Package Catalog incurs standard service costs. For more information, see [AWS IoT Device Management, Pricing](https://aws.amazon.com/iot-device-management/pricing/).
## Reserved named shadow
The reserved named shadow, `$package`, reflects the state of the device's installed software packages and package versions. Fleet indexing uses the reserved named shadow as a data source to build standard and custom metrics so you can query the state of your fleet. For more information, see [Preparing fleet indexing](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html).
A reserved named shadow is similar to a [named shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) with the exception that its name is predefined and you can’t change it. In addition, the reserved named shadow doesn’t update with metadata, and uses only the `version` and `attributes` keywords.
Update requests that include other keywords, such as `description`, will receive an error response under the `rejected` topic. For more information, see [Device Shadow error messages](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-error-messages.html).
It can be created when you create an AWS IoT thing through the console, when an AWS IoT job successfully completes and updates the shadow, and if you issue the [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) API operation. For more information, see [UpdateThingShadow](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-rest-api.html#API_UpdateThingShadow) in the AWS IoT Core developer guide.
**Note**
Indexing the reserved named shadow doesn’t count toward the number of named shadows that fleet indexing can index. For more information, see [AWS IoT Device Management fleet indexing limits and quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits). In addition, if you choose to have AWS IoT jobs update the reserved named shadow when a job successfully completes, the API call is counted toward your Device Shadow and registry operations and can incur a cost. For more information, see [AWS IoT Device Management jobs limits and quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#job-limits) and the [IndexingFilter](https://docs.aws.amazon.com/iot/latest/apireference/API_IndexingFilter.html) API data type.
**Structure of the `$package` shadow**
The reserved named shadow contains the following:
```
{
"state": {
"reported": {
"": {
"version": "",
"attributes": {
}
}
}
},
"version" : 1
"timestamp" : 1672531201
}
```
The shadow properties are updated with the following information:
+ ``: The name of the installed software package, which is updated with the [packageName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackage.html#API_CreatePackage_RequestSyntax) parameter.
+ `version`: The name of the installed package version, which is updated with the [versionName](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html#API_CreatePackageVersion_RequestSyntax) parameter.
+ `attributes`: Optional metadata stored by the device and indexed by Fleet indexing. This allows customers to query their indexes based on the data stored.
+ `version`: The shadow's version number. It's automatically incremented each time the shadow is updated and begins at `1`.
+ `timestamp`: Indicates when the shadow was last updated and is recorded in [Unix time](https://en.wikipedia.org/wiki/Unix_time).
For more information about the format and behavior of a named shadow, see [AWS IoT Device Shadow service Message order](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html#message-ordering).
## Deleting a software package and its package versions
Before you delete a software package, do the following:
+ Confirm that the package and its versions aren’t actively being deployed.
+ Delete all the associated versions first. If one of the versions is designated as the **default version**, you must remove the named default version from the package. Because designating a default version is optional, there is no conflict removing it. To remove the default version from the software package, edit the package through the console or use the [ UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API operation.
As long as there is no named default package version, you can use the console to delete a software package and all of its package versions will also be deleted. If you use an API call to delete software packages, you must delete the package versions first and then the software package.
# Preparing security
This section discusses the main security requirements for AWS IoT Device Management Software Package Catalog.
## Resource-based authentication
Software Package Catalog uses resource-based authorization to provide added security when updating software on your fleet. This means that you must create an AWS Identity and Access Management (IAM) policy that grants rights to perform `create`, `read`, `update`, `delete`, and `list` actions for software packages and package versions, and reference the specific software packages and package versions that you want to deploy in the `Resources` section. You also need these rights so that you can update the [ reserved named shadow](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow). You reference the software packages and package versions by including an Amazon Resource Name (ARN) for each entity.
**Note**
If you intend the policy to grant rights for package version API calls (such as [CreatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackageVersion.html), [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html), [DeletePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackageVersion.html)), then you need to include *both* the software package and the package version ARNs in the policy. If you intend the policy to grant rights for software package API calls (such as [CreatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_CreatePackage.html), [UpdatePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackage.html), and [DeletePackage](https://docs.aws.amazon.com/iot/latest/apireference/API_DeletePackage.html)) then you must include only the software package ARN in the policy.
Structure the software package and package version ARNs as follows:
+ Software package: `arn:aws:iot:::package//package`
+ Package version: `arn:aws:iot:::package//version/`
**Note**
There are other related rights that you might include in this policy. For example, you might include an ARN for the `job`, `thinggroup`, and `jobtemplate`. For more information and a complete listing of the policy options, see [Securing users and devices with AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs-security.html).
For example, if you have a software package and package version that’s named as follows:
+ AWS IoT thing: `myThing`
+ Package name: `samplePackage`
+ Version `1.0.0`
The policy might look like the following example:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:createPackage",
"iot:createPackageVersion",
"iot:updatePackage",
"iot:updatePackageVersion"
],
"Resource": [
"arn:aws:iot:us-east-1:111122223333:package/samplePackage",
"arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/1.0.0"
]
},
{
"Effect": "Allow",
"Action": [
"iot:GetThingShadow",
"iot:UpdateThingShadow"
],
"Resource": "arn:aws:iot:us-east-1:111122223333:thing/myThing/$package"
}
]
}
```
## AWS IoT Job rights to deploy package versions
For security purposes it’s important for you to grant rights to deploy packages and package versions, and name the specific packages and package versions they’re allowed to deploy. To do this, you create an IAM role and policy that grants permission to deploy jobs with package versions. The policy must specify the destination package versions as a resource.
**IAM policy**
The IAM policy grants the right to create a job that includes the package and version that are named in the `Resource` section.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:CreateJob",
"iot:CreateJobTemplate"
],
"Resource":[
"arn:aws:iot:*:111122223333:job/",
"arn:aws:iot:*:111122223333:thing//$package",
"arn:aws:iot:*:111122223333:thinggroup/",
"arn:aws:iot:*:111122223333:jobtemplate/",
"arn:aws:iot:*:111122223333:package//version/"
]
}
]
}
```
**Note**
If you want to deploy a job that uninstalls a software package and package version, you must authorize an ARN where the package version is `$null`, such as in the following:
```
arn:aws:iot::111122223333:package//version/$null
```
## AWS IoT Job rights to update the reserved named shadow
To allow jobs to update the thing’s reserved name shadow when the job successfully completes, you must create an IAM role and policy. There are two ways you can do this in the AWS IoT console. The first is when you create a software package in the console. If you see an **Enable dependencies for package management** dialog box, you can choose to use an existing role or create a new role. Or, in the AWS IoT console, choose **Settings**, choose **Manage indexing**, and then **Manage indexing for device packages and versions**.
**Note**
If you choose to have the AWS IoT Job service update the reserved named shadow when a job successfully completes, the API call is counted toward your **Device Shadow and registry operations** and can incur a cost. For more information, see [AWS IoT Core pricing](https://aws.amazon.com/iot-core/pricing/).
When you use the **Create role** option, the generated role’s name begins with `aws-iot-role-update-shadows` and contains the following policies:
**Setting up a role**
**Permissions**
The permissions policy grants the rights to query and update the thing shadow. The `$package` parameter in the resource ARN targets the reserved named shadow.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iot:DescribeEndpoint",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"iot:GetThingShadow",
"iot:UpdateThingShadow"
],
"Resource": [
"arn:aws:iot:us-east-1:111122223333:thing//$package"
]
}
]
}
```
**Trust relationship**
In addition to the permissions policy, the role requires a trust relationship with AWS IoT Core so that the entity can assume the role and update the reserved named shadow.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
**Setting up a user policy**
**iam:PassRole permission**
Finally, you must have the permission to pass the role to AWS IoT Core when you call the [ UpdatePackageConfiguration](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageConfiguration.html) API operation.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:PassRole",
"iot:UpdatePackageConfiguration"
],
"Resource": "arn:aws:iam::111122223333:role/"
}
]
}
```
## AWS IoT Jobs permissions to download from Amazon S3
The job document is saved in Amazon S3. You refer to this file when you dispatch through AWS IoT Jobs. You must provide AWS IoT Jobs with the rights to download the file (`s3:GetObject`). You must also set up a trust relationship between Amazon S3 and AWS IoT Jobs. For instructions to create these policies, see [ Presigned URLs](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-presigned-URLs) in [Managing Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html).
## Permissions to update the software bill of materials for a package version
To update the software bill of materials for a package version in the `Draft`, `Published`, or `Deprecated` lifecycle states, you need an AWS Identity and Access Management role and policies for locating the new software bill of materials in Amazon S3 and updating the package version in AWS IoT Core.
First, you will place the updated software bill of materials in your versioned Amazon S3 bucket and call the `[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)` API operation with the `sboms` parameter included. Next, your authorized principal will assume the IAM role you created, locate the updated software bill of materials in Amazon S3, and update the package verison in AWS IoT Core for Software Package Catalog.
The following policies are required to perform this update:
**Policies**
+ **Trust policy** Policy establishing a trust relationship with the authorized principal assuming the IAM role so it can locate the updated software bill of materials from your versioned bucket in Amazon S3 and update the package version in AWS IoT Core.
+
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "s3.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
+
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "iot.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
+ **Permissions policy**: Policy to access the Amazon S3 versioned bucket where the software bill of materials are stored for a package version and update the package version in AWS IoT Core.
+
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::awsexamplebucket1"
]
}
]
}
```
+
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:UpdatePackageVersion"
],
"Resource": [
"arn:aws:iot:*:111122223333:package//version/"
]
}
]
}
```
+ **Pass role permissions**: Policy granting permission to pass the IAM role to Amazon S3 and AWS IoT Core when you call the `[UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html)` API operation.
+
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:PassRole",
"s3:GetObject"
],
"Resource": [
"arn:aws:s3:::awsexamplebucket1"
]
}
]
}
```
+
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iam:PassRole",
"iot:UpdatePackageVersion"
],
"Resource": "arn:aws:iam::111122223333:role/"
}
]
}
```
**Note**
You can't update the software bill of materials on a package version that has transitioned to the `Deleted` lifecycle state.
For more information on creating an IAM role for an AWS service, see [Creating a role to delegate permission to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html).
For more information on creating an Amazon S3 bucket and uploading objects to it, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) and [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html).
# Preparing fleet indexing
With AWS IoT fleet indexing, you can search and aggregate data by using the reserved named shadow (`$package`). You can also group AWS IoT things by querying the [Reserved named shadow](preparing-to-use-software-package-catalog.md#reserved-named-shadow) and [dynamic thing groups](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html). For example, you can find information about which AWS IoT things use a specific package version, don't have a specific package version installed, or don’t have any package version installed. You can gain further insight by combining attributes. For example, identifying things that have a specific version and are of a specific thing type (such as version 1.0.0 and thing type of pump\$1sensor). For more information, see [Fleet indexing](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html).
## Setting the `$package` shadow as a data source
To use fleet indexing with Software Package Catalog, you must enable fleet indexing, set the named shadow as the data source, and define `$package` as the named shadow filter. If you haven’t enabled fleet indexing, you can enable it within this process. From [AWS IoT Core](https://console.aws.amazon.com/iot/home) in the console, open **Settings**, choose **Manage indexing**, then **Add named shadows**, **Add device software packages and versions**, and **Update**. For more information, see [Manage thing indexing](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#thing-index).
Alternately, you can enable fleet indexing when you create your first package. When the **Enable dependencies for package management** dialog box appears, choose the option to add device software packages and versions as data sources to fleet indexing. By selecting this option, you also enable fleet indexing.
**Note**
Enabling fleet indexing for Software Package Catalog incurs standard service costs. For more information, see [AWS IoT Device Management, Pricing](https://aws.amazon.com/iot-device-management/pricing/).
## Metrics displayed in the console
![\[Standard metrics image\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/package-catalog-discovery-metrics.png)
On the AWS IoT console software package details page, the **Discovery** panel displays standard metrics ingested through the `$package` shadow.
+ The **Current version distribution** chart shows the number of devices and percentage for the 10 most recent package versions that are associated to an AWS IoT thing from all the devices associated to this software package. **Note:** If the software package has more package versions than those labeled in the chart, you can find them grouped within **Other**.
+ The **Historical chart** shows the number of devices associated with selected package versions over a specified time period. The chart is initially empty until you select up to 5 package versions and define the date range and time interval. To select the chart’s parameters, choose **Settings**. The data displayed in the **Historical chart** might be different than the **Current version distribution** chart because of the difference in number of package versions that they display and also because you can choose which package versions to analyze in the **Historical chart**. **Note:** When you select a package version to visualize, it counts toward the maximum number of fleet metrics limits. For more information, see [Fleet indexing limits and quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits).
For another method to gain insight into collecting package version distribution, see [Collecting package version distribution through `getBucketsAggregation`](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-fleet-indexing.html#package-version-distribution).
## Query patterns
Fleet indexing with Software Package Catalog uses most standard supported features (such as terms, phrases, and search fields). However, comparison operators (for example, less than `<` and greater than `>`) and `range` queries are not available for the reserved named shadow (`$package`) `version` key. These queries are available for the `attributes` key. For more information, see [Query syntax](https://docs.aws.amazon.com/iot/latest/developerguide/query-syntax.html).
### Example data
**Note:** for information about the reserved named shadow and its structure, see [Reserved named shadow](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow).
In this example, a first device is named `AnyThing` and has the following packages installed:
+ Software package: `SamplePackage`
Package version: `1.0.0`
Package ID: `1111`
The shadow looks as follows:
```
{
"state": {
"reported": {
"SamplePackage": {
"version": "1.0.0",
"attributes": {
"s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
"packageID": "1111"
}
}
}
}
}
```
A second device is named `AnotherThing` and has the following package installed:
+ Software package: `SamplePackage`
Package version: `1.0.0`
Package ID: `1111`
+ Software package: `OtherPackage`
Package version: `1.2.5`
Package ID: `2222`
The shadow looks as follows:
```
{
"state": {
"reported": {
"SamplePackage": {
"version": "1.0.0",
"attributes": {
"s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
"packageID": "1111"
}
},
"OtherPackage": {
"version": "1.2.5",
"attributes": {
"s3UrlForOtherPackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile2",
"packageID": "2222"
}
},
}
}
}
```
### Sample queries
The following table lists sample queries based on the example device shadows for `AnyThing` and `AnotherThing`. For more information, see [Example thing queries](https://docs.aws.amazon.com/iot/latest/developerguide/example-queries.html).
**Latest version of AWS IoT Device Tester for FreeRTOS**
| **Requested information** | **Query** | **Result** |
| --- | --- | --- |
| Things that have a specific package version installed | `shadow.name.$package.reported.SamplePackage.version:1.0.0` | `AnyThing`, `OtherThing` |
| Things that don't have a specific package version installed | `NOT shadow.name.$package.reported.OtherPackage.version:1.2.5` | `AnyThing` |
| Any device using a package version whose package ID is greater than 1500 | `shadow.name.$package.reported.*.attributes.packageID>1500"` | `OtherThing` |
| Things that have a specific package installed and have more than one package installed | `shadow.name.$package.reported.SamplePackage.version:1.0.0 AND shadow.name.$package.reported.totalCount:2` | `OtherThing` |
## Collecting package version distribution through `getBucketsAggregation`
In addition to the **Discovery** panel within the AWS IoT console, you can also get package version distribution information by using the [https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetBucketsAggregation.html) API operation. To get the package version distribution information, you must do the following:
+ Define a custom field within fleet indexing for each software package. **Note:** Creating custom fields count toward [AWS IoT fleet indexing service quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#fleet-indexing-limits).
+ Format the custom field as follows:
`shadow.name.$package.reported..version`
For more information, see the [Custom fields](https://docs.aws.amazon.com/iot/latest/developerguide/managing-fleet-index.html#custom-field) section in AWS IoT fleet indexing.
# Preparing AWS IoT Jobs
AWS IoT Device Management Software Package Catalog extends AWS IoT Jobs through substitution parameters, and integration with AWS IoT fleet indexing, dynamic thing groups, and the AWS IoT thing’s reserved named shadow.
**Note**
To use all the functionality that Software Package Catalog offers, you must create these AWS Identity and Access Management (IAM) roles and policies: [AWS IoT Jobs rights to deploy package versions](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html#job-rights-deploy-versions) and [AWS IoT Jobs rights to update the reserved named shadow](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html#job-rights-update-reserved-named-shadow). For more information, see [Preparing security](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-security.html).
## Substitution parameters for AWS IoT jobs
You can use substitution parameters as a placeholder within your AWS 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 parameters should be formatted in the job document as follows:
+ **Software Package Name and Package Version**
+ The empty string between `package::version` represents the software package name substitution parameter. The empty string between `version::attribute` represents the software package version substitution parameter. Refer to the following example for using the package name and package verion substituion parameters in a job document: `${aws:iot:package::version::attributes:}`.
+ The job document will autofill these substituion parameters using the *Version ARN* from the package version details. If you're creating a job or job template for a single-package deployment using an API or CLI command, the *Version ARN* for a package version is represented by the `destinationPackageVersions` parameter in `CreateJob` and `DescribeJob`.
+ **All Attributes for a Software Package Version**
+ Refer to the following example for using the all attributes of a software package version substitution parameter in a job document: `${aws:iot:package::version::attributes}`
**Note**
The package name, package version, and all attributes substitution parameters can be used together. Refer to the following example for using all three substitution parameters in a job document: `${aws:iot:package::version::attributes}`
In the following 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](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-code-signing). **Note:** This attribute is an example and not required as part of Software Package Catalog or jobs.
For `s3URL`, 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"
]
}
}
```
**Substitution Parameters (Before and After View)**
Substitution parameters streamline the creation of a job document using various flags such as `$default` for the default package version. This eliminates the need to manually enter specific package version metadata for each job deployment as those flags are autofilled with the referenced metadata in the specific package verison. For more information on package version attributes such as `$default` for the default package version, see [Preparing the job document and package version for deployment](#preparing-to-deploy).
In the AWS Management Console, toggle the *Preview substitution* button in the *Deployment instruction file editor* window during a job deployment for a package version to view the job document with and without the substitution parameters.
Using the "before-substitution" parameter in the `DescribeJob` and `GetJobDocument` APIs, you can view the API response before and after the substitution parameters are removed. Refer to the following examples with the `DescribeJob` and `GetJobDocument` APIs:
+ `DescribeJob`
+ Default view
```
{
"jobId": "",
"description": "",
"destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/1.0.2"]
}
```
+ Before substituion view
```
{
"jobId": "",
"description": "",
"destinationPackageVersions": ["arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"]
}
```
+ `GetJobDocument`
+ Default view
```
{
"attributes": {
"location": "prod-artifacts.s3.us-east-1.amazonaws.com/mqtt-core",
"signature": "IQoJb3JpZ2luX2VjEIrwEaCXVzLWVhc3QtMSJHMEUCIAofPNPpZ9cI",
"streamName": "mqtt-core",
"fileId": "0"
},
}
```
+ Before substituion view
```
{
"attributes": "${aws:iot:package:TestPackage:version:$default:attributes}",
}
```
For more information about AWS IoT Jobs, creating job documents, and deploying jobs, see [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html).
## 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 create an AWS IoT Job or Job template for a single-package deployment, you have the following options to customize your job document:
**Deployment instruction file (`recipe`)**
+ The deployment instruction file for a package version contains the deployment instructions, including an inline job document, for deploying a package version to multiple devices. The file associates specific deployment instructions to a package version for a quick and efficient job deployment.
In the AWS Management Console, you can create the file in the *Deployment instructions file preview* window in the *Version deployment configurations* tab of the create new package workflow. You can leverage AWS IoT to automatically generate an instruction file from your package version attributes using *Start from AWS IoT recommended file* or use your existing job document stored in an Amazon S3 bucket using *Use your own deployment instruction file*.
**Note**
If you use your own job document, you can update it directly in the *Deployment instructions file preview* window, but it will not automatically update your original job document stored in your Amazon S3 bucket.
When using the AWS CLI or an API command such as `CreatePackageVersion`, `GetPackageVersion`, or `UpdatePackageVersion`, `recipe` represents the deployment instruction file, which includes an inline job document.
For more information on what a job document is, see [Basic concepts](key-concepts-jobs.md#basic-concepts-jobs).
Refer to the following example for the deployment instruction file as represented by `recipe`:
```
{
"packageName": "sample-package-name",
"versionName": "sample-package-version",
...
"recipe": "{...}"
}
```
**Note**
The deployment instruction file as represented by `recipe` can be updated when a package version is in the `published` status state as it's separate from the package version metadata. It become immutable during job deployment.
**`Artifact` version attribute**
+ Using the version attribute `artifact` in your software package version, you can add the Amazon S3 location for your package version artifacts. When a job deployment for your package version is triggered using AWS IoT Jobs, the presigned URL placeholder ` ${aws:iot:package::version::artifact-location:s3-presigned-url}` in the job document will be updated using the Amazon S3 bucket, bucket key, and version of the file stored in the Amazon S3 bucket. The Amazon S3 bucket storing the package version artifacts must be located in the same region where the package version was created.
**Note**
To store multiple object versions of the same file in your Amazon S3 bucket, you must enable versioning on your bucket. For more information, see [Enabling versioning on buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html).
To access the package version artifacts in the Amazon S3 bucket when using the `CreatePackageVersion` or `UpdatePackageVersion` API operation, you must have the following permissions:
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObjectVersion",
"Resource": "arn:aws:s3:::bucket-name/key-name"
}
]
}
```
For more information on the version attribute `artifact` in the `CreatePackageVersion` and `UpdatePackageVersion` API operations, see [CreatePackageVersion](https://amazonaws.com/iot/latest/apireference/API_CreatePackageVersion.html) and [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html).
Refer to the following example that shows the version attribute `artifact` supporting the artifact location in Amazon S3 when creating a new package version:
```
{
"packageName": "sample package name",
"versionName": "1.0",
"artifact": {
"s3Location": {
"bucket": "firmware",
"key": "image.bin",
"version": "12345"
}
}
}
```
**Note**
When a package version updates from a `draft` status state to a `published` status state, the package version attributes and artificats location become immutable. To update this informaiton, you need to create a new package version and perform those updates while in the `draft` status state.
**Package Version**
+ A default software package version can be denoted in the available versions of the software package providing a secure and stable package version. This serves as the baseline version of the software package when deploying the default package version to your device fleet using AWS IoT Jobs. When creating a job to deploy the `$default` package version for a software package, the package version in the job document and in the new job deployment must match as `$default`. The package version in the job deployment is represented by `destinationPackageVersions` for API and CLI commands and `VersionARN` in the AWS Management Console. The package version in the job document is represented by the following job document placeholder shown below:
```
arn:aws:iot::111122223333:package//version/$default
```
To create a job or job template using the default package version, use the `$default` flag in the `CreateJob` or `CreateJobTemplate` API command as shown below:
```
"$ aws iot create-job \
--destination-package-versions "arn:aws:iot:us-west-2:123456789012:package/TestPackage/version/$default"
--document file://jobdoc.json
```
**Note**
The `$default` package version attribute referencing the default version is an optional attribute that is only required when referencing the default package version for a job deployment via AWS IoT Jobs.
When you are satisfied with the package version, publish it either through the software package details page in the AWS IoT console or by issuing the [UpdatePackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdatePackageVersion.html) API operation. You can then reference the package version when you create the job either through the AWS IoT console or by issuing the [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API operation.
## Naming the packages and versions when deploying
To deploy a software package version to a device, confirm the software package and package version referenced in the job document match the software package and package version stated in the `destinationPackageVersions` parameter in the `CreateJob` API operation. If they don't match, you will receive an error message prompting you to make both references match. For more information on Software Package Catalog error messages, see [General Troubleshooting Error Messages](software-package-catalog-troubleshooting.md#spc-general-troubleshooting).
In addition to the software packages and package versions referenced in the job document, you can include additional software packages and package versions in the `destinationPackageVersions` parameter in the `CreateJob` API operation not referenced in the job document. Ensure the necessary installation information is included in the job document for devices to properly install the additional software package versions. For more information on the `CreateJob `API operation, see [CreateJob](https://amazonaws.com/iot/latest/apireference/API_CreateJob.html).
## Targeting jobs through AWS IoT dynamic thing groups
Software Package Catalog works with [fleet indexing](https://docs.aws.amazon.com/iot/latest/developerguide/iot-indexing.html), [AWS IoT jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html), and [AWS IoT dynamic thing groups](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html) 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 AWS 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](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group).
## Reserved named shadow and package versions
If configured, AWS 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 AWS IoT Core without associating the installed package version.
+ AWS 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 AWS IoT Core when it completes.
**Note**
We recommend you use AWS 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 AWS 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 [https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iotdata_UpdateThingShadow.html) API operation. For more information, see [Associating a package version to an AWS IoT thing](https://docs.aws.amazon.com/iot/latest/developerguide/associating-package-version.html).
**Note**
Associating a package version to an AWS 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 AWS 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.](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-to-use-software-package-catalog.html#reserved-named-shadow)
To use this feature, replace the version name at the end of the [destinationPackageVersion](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html#iot-CreateJobTemplate-request-destinationPackageVersions) 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::111122223333:package//version/$null
```
For example,
```
$ aws iot create-job \
... \
--destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]
```
# Getting started with Software Package Catalog
You can build and maintain the AWS IoT Device Management Software Package Catalog through the AWS Management Console, AWS IoT Core API operations, and AWS Command Line Interface (AWS CLI).
**Note**
Enabling AWS IoT fleet indexing is a requirement to use Software Package Catalog. Basic operations such as creating a software package version in the AWS Management Console and using the `CreatePackage` API command will fail without AWS IoT fleet indexing enabled.
For more information on using AWS IoT fleet indexing with Software Package Catalog, see [Preparing fleet indexing](preparing-fleet-indexing.md).
**Using the console**
To use the AWS Management Console, sign into your AWS account and navigate to [AWS IoT Core](https://console.aws.amazon.com/iot/home). In the navigation pane, choose **Software packages**. You can then create and manage packages and their versions from this section.
**Using API or CLI operations**
You can use the AWS IoT Core API operations to create and manage Software Package Catalog features. For more information, see [AWS IoT API Reference](https://docs.aws.amazon.com/iot/latest/apireference/) and [AWS SDKs and Toolkits](https://aws.amazon.com/developer/tools/). The AWS CLI commands also manage your catalog. For more information, see the [AWS IoT CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iot/index.html).
**Topics**
+ [Creating a software package and package version](creating-package-and-version.md)
+ [Deploying a package version through AWS IoT jobs](deploying-package-version.md)
+ [Associating a package version to an AWS IoT thing](associating-package-version.md)
# Creating a software package and package version
You can use the following steps to create a package and an initial version thing through the AWS Management Console.
**To create a software package**
1. Sign into your AWS account and navigate to the [AWS IoT console](https://console.aws.amazon.com/iot/home).
1. On the navigation pane, choose **Software packages**.
1. On the **AWS IoT software package** page, choose **Create package**. The **Enable dependencies for package management** dialog box appears.
1. Under **Fleet indexing**, select **Add device software packages and version**. This is required for Software Package Catalog and provides fleet indexing and metrics about your fleet.
1. [Optional] If you want AWS IoT jobs to update the reserved named shadow when jobs successfully complete, select **Auto update shadows from jobs**. If you do not want AWS IoT jobs to make this update, leave this check-box unselected.
1. [Optional] To grant AWS IoT jobs the rights to update the reserved named shadow, under **Select role**, choose **Create role**. If you don't want AWS IoT jobs to make this update, this role is not required.
1. Create or select a role.
1. If you **don’t have a role** for this purpose: When the **Create role** dialog box appears, enter a **Role name**, and then choose **Create**.
1. If you **do have a role** for this purpose: For **Select role**, choose your role and then make sure the **Attach policy to IAM role** check box is selected.
1. Choose **Confirm**. The **Create new package** page appears.
1. Under **Package detail**, enter a **Package name**.
1. Under **Package description**, enter information to help you identify and manage this package.
1. [Optional] You can use tags to help you categorize and manage this package. To add tags, expand **Tags**, choose **Add tag**, and enter a key-value pair. You can enter up to 50 tags. For more information, see [Tagging your AWS IoT resources](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html).
**To add a package version while creating a new package**
1. Under **Initial version**, enter a **Version name**.
We recommend using the [SemVer format](https://semver.org/) (for example, `1.0.0.0`) to uniquely identify your package version. You are also able to use a different formatting strategy that better suits your use case. For more information, see [Package version lifecycle](preparing-to-use-software-package-catalog.md#package-version-lifecycle).
1. Under **Version description**, enter information that will help you identify and manage this package version .
**Note**
The **Default version** check box is deactivated because package versions are created in a `draft` state. You can name the default version after you create the package version and when you change the state to `published`. For more information, see [Package version lifecycle](preparing-to-use-software-package-catalog.md#package-version-lifecycle).
1. [Optional] To help you manage this version or to communicate information to your devices, enter one or more name-value pairs for **Version attributes**. Choose **Add attribute** for each name-value pair you enter. For more information, see [Version attributes](preparing-to-use-software-package-catalog.md#version-attributes).
1. [Optional] You can use tags to help you categorize and manage this package. To add tags, expand **Tags**, choose **Add** tag, and enter a key-value pair. You can enter up to 50 tags. For more information, see [Tagging your AWS IoT resources](https://docs.aws.amazon.com/iot/latest/developerguide/tagging-iot.html).
1. Choose **Next**.
**Associate the Software Bill of Materials to a Package Version (Optional)**
1. On **Step 3: Version SBOMs (Optional)** in the **SBOM configurations** window, choose the default SBOM file format and validation mode used to validate your software bill of materials before it is associated to your package version.
1. In the **Add SBOM file** window, enter the Amazon Resource Name (ARN) representing your versioned Amazon S3 bucket and the preferred SBOM file format if the default type doesn't work.
**Note**
You can either add a single SBOM file or a single zip file containing multiple SBOMs if you have more than one software bill of material for your package version.
1. In the **Added SBOM file** window, you can view the SBOM file you added for your package version.
1. Choose **Create package and version**. The package version page appears and you can see the validation status of your SBOM file in the **Added SBOM file** window. The initial status will be `In progress` as the SBOM file undergoes validation.
**Note**
The SBOM file validation statuses are `Invalid file`, `Not started`, `In progress`, `Validated (SPDX)`, `Validated (CycloneDX)`, and the validation failure reasons.
# Deploying a package version through AWS IoT jobs
You can use the following steps to deploy a package version through the AWS Management Console.
**Prerequisites:**
Before you begin, do the following:
+ Register AWS IoT things with AWS IoT Core. For directions to add your devices to AWS IoT Core, see [Create a thing object](https://docs.aws.amazon.com/iot/latest/developerguide/create-iot-resources.html#create-aws-thing).
+ [Optional] Create an AWS IoT thing group or dynamic thing group to target the devices that you will deploy the package version. For directions to create a thing group, see [Create a static thing group](https://docs.aws.amazon.com/iot/latest/developerguide/thing-groups.html#create-thing-group). For directions to create a dynamic thing group, see [Create a dynamic thing group](https://docs.aws.amazon.com/iot/latest/developerguide/dynamic-thing-groups.html#create-dynamic-thing-group).
+ Create a software package and a package version. For more information, see [Creating a software package and package version](creating-package-and-version.md).
+ Create a job document. For more information, see [Preparing the job document and package version for deployment](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#preparing-to-deploy).
**To deploy an AWS IoT job**
1. On the [AWS IoT console](https://console.aws.amazon.com/iot/home), choose **Software packages**.
1. Choose the software package that you want to deploy. The **software package details** page appears.
1. Choose the package version that you want to deploy, under **Versions**, and choose **Deploy job version**.
1. If this is your first time deploying a job through this portal, a dialog box describing the requirements appears. Review the information and choose **Acknowledge**.
1. Enter a name for the deployment or leave the autogenerated name in the **Name** field.
1. [Optional] In the **Description** field, enter a description that identifies the purpose or contents of the deployment, or leave the autogenerated information.
**Note:** We recommend that you don't use personally identifiable information in the Job name and description fields.
1. [Optional] Add any tags to associate with this job.
1. Choose **Next**.
1. Under **Job targets**, choose the things or thing groups that should receive the job.
1. In the **Job file** field, specify the job document JSON file.
1. Open **Jobs integration with the Package Catalog service**.
1. Select the packages and versions that are specified within your job document.
**Note**
You are required to choose the same packages and package versions that are specified within the job document. You can include more, but the job will issue instructions only for the packages and versions included in the job document. For more information, see [Naming the packages and versions when deploying](https://docs.aws.amazon.com/iot/latest/developerguide/preparing-jobs-for-service-package-catalog.html#naming-package-versions).
1. Choose **Next**.
1. On the Job configuration page, select one of the following job types in the Job configuration dialog box:
+ **Snapshot job:** A snapshot job is complete when it's finished its run on the target devices and groups.
+ **Continuous job:** A continuous job applies to thing groups and runs on any device that you later add to a specified target group.
1. In the **Additional configurations - optional** dialog box, review the following optional job configurations and make your selections accordingly. For more information, see [Job rollout, scheduling, and abort configurations](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-rollout-abort-scheduling) and [Job execution timeout and retry configurations](https://docs.aws.amazon.com/iot/latest/developerguide/jobs-configurations-details.html#job-timeout-retry).
+ Rollout configuration
+ Scheduling configuration
+ Job executions timeout configuration
+ Job executions retry configuration
+ Abort configuration
1. Review the job selections and then choose **Submit**.
After you create the job, the console generates a JSON signature and places it in your job document. You can use the AWS IoT console to view the status of a job, or cancel or delete a job. To manage jobs, go to the [Job hub of the console](https://console.aws.amazon.com/iot/home#/jobhub).
# Associating a package version to an AWS IoT thing
After you install software on your device, you can associate a package version to an AWS IoT thing’s reserved named shadow. If AWS IoT jobs has been configured to update the thing’s reserved named shadow after the job deploys and successfully completes, you don’t need to complete this procedure. For more information, see [Reserved named shadow](preparing-to-use-software-package-catalog.md#reserved-named-shadow).
**Prerequisites:**
Before you begin, do the following:
+ Create an AWS IoT thing, or things, and establish telemetry through AWS IoT Core. For more information, see [Getting started with AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/iot-gs.html).
+ Create a software package and package version. For more information, see [Creating a software package and package version](creating-package-and-version.md).
+ Install the package version software on the device.
**Note**
Associating a package version to an AWS IoT thing doesn’t update or install software on the physical device. The package version must be deployed to the device.
**To associate a package version to an AWS IoT thing**
1. On the [AWS IoT console](https://console.aws.amazon.com/iot/home) navigation pane, expand the **All devices** menu and choose **Things**.
1. Identify the AWS IoT thing that you want to update from the list and choose the thing name to display its details page.
1. In the **Details** section, choose **Packages and versions**.
1. Choose **Add to package and version**.
1. For **Choose a device package**, choose the software package you want.
1. For **Choose a version**, choose the software version you want.
1. Choose **Add device package**.
The package and version appear on the **Selected packages and versions** list.
1. Repeat these steps for each package and version that you want to associate to this thing.
1. When you’re finished, choose **Add package and version details**. The **Thing details** page opens and you can see the new package and version in the list.