It is recommended to first review the general concepts of manifests and chained manifests here.

A device manifest is generated and signed with organization keys to create a production release. This ensures security and immutability of the manifest. However, this creates a conflict: if the manifest cannot be altered, how can device-specific customization such as customer or location-specific content be added to the device?

Chained manifests solve this by allowing additional manifests to be attached to the primary device manifest. The software team creating the device image defines “Chained Section References” within the original manifest to specify which chained sections are approved for inclusion, and to identify the specific third-parties permitted to create them.

Only approved parties can add chained sections, maintaining a chain of trust. These references are analogous to import statements; developers indicate that if a corresponding chained section exists, it should be included in a specific manifest section. Chained section references can only define KABs to be included in new sections. They cannot modify existing sections, replace them, or be added as layers. This ensures that chained manifests cannot alter the tested and verified base software release, only add to it.

It may seem simpler to bypass this process by hosting assets at a static cloud URL for direct download. While this avoids a formal deployment, it breaks the principle of immutability. If a cloud asset becomes corrupted, it could break the newest release and trigger an automatic rollback. However, since the previous software release also references the same URL, the device would simply download the same corrupted asset again. Using immutable manifests ensures that each deployed manifest is locked. If an update fails, the device can reliably rollback to a previous stable manifest, which is essential for production devices.

In a production system, a third party contributor, such as a Content Management System team (CMS) coordinates with development teams to identify the necessary customizations for their devices. The two teams coordinate manifest names, section names and so on. The software team adds the chained section references to their release when then match up with the contents of the chained manifest from the CMS team. When a particular device is updated in the field, the CMS team uses information about that particular device to generate a device-specific chained manifest which is then sent to the device. On device, the manifests in the chain are merged into a single immutable state that the device boots into.

Once established, the following example automation flow would occur when a deployment is triggered:

1. The device management system is requested to update a particular device.
2. Device management determines the correct release to install on the device.
3. Information from the corresponding device manifest is extracted, including the manifestId and any properties contained in the manifest.
4. Device management passes this information to an external system such as CMS.
5. CMS uses the information to determine what it wants to add to the release for this particular device.
6. CMS constructs a chained manifest that references the previous manifest in the chain (the device manifest id in this case) and includes the device-specific content.
7. CMS returns the chained manifest to device management.
8. Device management stores the manifest kab in its blob store if it doesn’t already exist.
9. If there are additional parties that can contribute chained manifests, they are processed in similar way, each getting the manifest id of the previously generated manifest in the chain.
10. When all parties have contributed to the chained manifest, the final manifest id is sent to the device via the associated agent.
11. The device will request all the manifests in the chain, one at a time, starting with the final manifest in the chain, working back to the device manifest. This allows KOS to determine all the kabs that need to be installed.

To support information transfer between entities that generate chained manifests, manifest properties can be leveraged. Every manifest can contain custom properties that convey information to parties upstream. For example, CMS may provide content meta-data in multiple formats, but they need to know which version to add for a given software release. The software and CMS teams may agree to a property that identifies the desired schema version. For example, cms.content.version=2. This can be encoded in the device manifest using KOS Studio when the release is built. This way, when device management calls CMS to generate a chained manifest, it can simply include all the manifest properties without understanding their meaning, and CMS will use this information to package compatible content. If device management captures properties from each manifest in the chain as they are created and passes those properties to the next party, it allows different systems to generically pass critical data upstream without any custom integration between services.

It is important to understand that every deployment in KOS is a full release. There is on concept of pushing a single KAB to KOS to replace another as this would invalidate immutability and determinism guarantees. To change a single KAB on a device, a new manifest chain needs to be built that includes everything in the release, including the one alternate KAB. This implies that if a chained manifest is expected to supply multiple KABs, it should always include the entire set on every OTA, even if the purpose of the OTA is to replace only one KAB in particular.