Scaling with Viam using fragment versions: Safer configuration management

Managing fragment versions with tags

To provide even greater control over updates, fragment versions support tagging. Tags allow you to reference specific fragment versions in your machine configurations and provide flexibility in managing updates.

How to create and apply tags:

• When managing a fragment version, you can create and assign a tag (e.g., stable, testing, beta).
• Tags can be applied to any version of a fragment to organize updates.
• If a tested fragment version is successful, you can move a tag (e.g., stable) to that version, ensuring all machines using that tag update automatically.
• If an issue arises, you can roll back by moving the tag to a previous, known-good version.

Once you've assigned tags to different versions of a fragment, the next step is deciding how machines reference them.

Choosing how to use fragment versions

When you add a fragment to a machine, you can choose how the machine updates to new versions:

• Latest version (default) – The machine always updates to the latest version of the fragment as soon as a new version becomes available.
• Specific version – The machine stays on a fixed version of the fragment and does not update automatically.

Tag-based versioning – The machine always uses the version of the fragment associated with a selected tag, such as stable.

Real-world example: Optimizing RoboHaul's fleet

RoboHaul, a logistics automation company, operates a fleet of 200 heavy-duty transport robots in warehouses across the country. Their lead engineer, Alex, needs a structured way to introduce updates without disrupting operations. He uses fragment versions and tags to manage updates:

1. All machines use the latest fragment – By default, all 200 robots are assigned to the latest version of the navigation fragment.
2. Preparing for a test – Alex wants to test new changes while keeping most machines stable.
3. Setting up version tags – He tags the current fragment version as stable and also assigns canary to the same version. Then, he configures 195 machines to use stable and 5 machines to use canary.
4. Creating a new version – Alex makes updates to the navigation fragment, creating a new version.
5. Testing with canary – Once he feels the new version is ready to test, he moves the canary tag to this updated fragment version. The 5 canary machines now receive the latest changes for testing.
6. Validation and full rollout – If the new version performs well, Alex moves the stable tag to the same version, updating the remaining 195 machines.
7. Rollback if needed – If issues arise at any stage, Alex can move canary or stable back to the previous version, instantly reverting affected machines to a working state.

This structured approach ensures smooth, low-risk updates, allowing RoboHaul to test and deploy changes with confidence.