# Scaling with Viam using fragment versions: Safer configuration management

Gain full control over machine configurations with structured versioning, safer rollouts, and easy rollbacks.

Natalia Jacobowitz

Product Manager

## Introduction: Why fragment versions matter

Managing machine configurations at scale is complex. Without version control, updates can quickly become unmanageable, and reversing mistakes can be challenging.

That’s why we built **fragment versions**.

Fragment Versions Demo - YouTube  
[Fragment Versions Demo](https://www.youtube.com/watch?v=sP8XmNm48yU) [Viam](https://www.youtube.com/channel/UCrWzoQBoTmYnF8mslOesUAw)

## What are fragment versions?

If you’ve worked with **fragments**, you know they simplify configuration management by enabling modular, reusable setups across machines. But what happens when you need to iterate on a fragment, test changes, or roll back to a previous version?

That’s where **fragment versions** come in.

Fragment versions allow teams to track changes, maintain machine stability, and deploy updates with confidence. They also work seamlessly with [**nested fragments**](/content/post/nested-fragments/index.html), making it easy to manage complex, layered configurations while maintaining version control across all dependencies. Instead of modifying a live fragment and risking unintended consequences, you can create new versions, test them in isolation via tags, and roll them out when ready.

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

This flexibility ensures teams can balance stability and iteration based on their needs.

## Why fragment versions matter and who benefits

Fragment versions provide structured version control, reducing risk and improving efficiency for a wide range of users:

- **Companies managing fleets** – Safe, gradual updates across machines with tracked version history and easy rollbacks.
- **Developers iterating frequently** – Enables fast prototyping while maintaining stability via A/B testing.
- **Collaborators & open-source users** – Allows controlled updates without affecting production environments.

To see how this works in practice, let's look at RoboHaul, a company using fragment versions to safely deploy updates across a fleet of robots.

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

## **Smarter updates, greater reliability**

Fragment versions provide structured version control, helping teams manage updates efficiently, minimize risk, and keep their machine configurations organized. Whether rolling out improvements to a single machine or a global fleet, this feature ensures a smooth and controlled process.

Start using fragment versions today and take the guesswork out of managing configurations at scale.