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.

• 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 or DeletePackageVersion 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 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 or DeletePackageVersion 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 or DeletePackageVersion 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 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 API operation. (To remove any named package version as default, set the unsetDefaultVersion parameter to true when you issue the UpdatePackage 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 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. For more information about the package version name requirements, see versionName 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 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.

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.

Enabling AWS IoT fleet indexing

You must activate fleet indexing for Software Package Catalog to create or update software packages and package versions. Fleet indexing provides support that enables AWS IoT things to be grouped through dynamic thing groups that are filtered by 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 fleet. For more information, see Preparing fleet indexing.

Note

Enabling fleet indexing for Software Package Catalog incurs standard service costs. For more information, see AWS 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.

A reserved named shadow is similar to a named shadow 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.

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 UpdateThingShadow API operation. For more information, see 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. 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 and the IndexingFilter API data type.

Structure of the $package shadow

The reserved named shadow contains the following:

{
    "state": {
        "reported": {
            "<packageName>": {
                "version": "",
                "attributes": {
                }
            }
        }
    },
    "version" : 1
    "timestamp" : 1672531201
}

The shadow properties are updated with the following information:

• <packageName>: The name of the installed software package, which is updated with the packageName parameter.

• version: The name of the installed package version, which is updated with the versionName 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.

For more information about the format and behavior of a named shadow, see AWS IoT Device Shadow service Message order.

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 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.