Deliver your first software update

Finish with one staging device running the container version selected in a Software Build, with application health checked independently of assignment. This exercise uses a containers-only Build and leaves OS delivery for a later task.

Before you start

Use a connected staging device with a container-capable runtime and a product Device Class dedicated to testing. You need permission to configure Software and assign Builds. Check the runtime support matrix for your agent and OS.

The class must have an attached container with an existing known-good version and a tested replacement version for the same CPU architecture. Prepare those using Configure container software, or practise with an example simulator. Simulator values are synthetic.

1. Isolate the test target

1. Give the test device a distinctive tag, such as docs-software-test.
2. Confirm no other device has that tag.
3. Open Engineering > Software and select the test Device Class.
4. Check its current Build and existing cohort assignments.

A cohort is a selection of devices by tags. A device matching several cohorts receives the matching Build with the highest sequence number. Stop and resolve overlapping assignments if they would make this test affect the wrong device or select a different Build.

2. Create a containers-only Build

1. Open Builds and choose Create build.
2. Select a version for every attached container. Change only the container under test.
3. Choose no OS image.
4. Review the exact versions and add a changelog describing the expected change.
5. Create the Build. It starts in staging.

Expected result: the Build exists, but creating it has not made it the class default.

3. Assign it to the test device

Choose Assign cohort, name the cohort and select docs-software-test. Confirm the tag scope and the resulting effective Build for the test device. Keep the class default unchanged during this exercise.

Containers start reconciling when this Build becomes effective. Delivery controls the staged OS-image part of a Build; it is not an extra release button for this containers-only change.

Check it worked

Inspect the per-device deployment result and verify:

• the intended device resolves the new Build;
• the selected container version deploys successfully;
• an application health check or version response confirms the expected behaviour;
• required streams still publish and other attached containers remain healthy.

You are finished when both deployment and application checks pass. A saved Build or cohort assignment alone is not evidence that the application runs correctly.

If it does not work

Symptom	Next check
Wrong Build selected	Check tag matching and higher-sequence overlapping cohort assignments
Deployment pending	Check connectivity and the device's effective Build
Import or start fails	Check archive architecture, runtime support, required I/O and deployment errors
Deployment succeeds but application fails	Inspect application logs and configuration before expanding the target

To restore the previous container composition, create a newer Build selecting the known-good versions and assign it to the same test cohort. Check application data compatibility first, then repeat the deployment and health checks. A lower sequence Build may not win an overlapping cohort selection.

Next task

Use Software Builds and cohorts to plan promotion to a wider target. For managed OS updates, follow Software delivery and qualify the board-specific rollback path before starting a rollout.