Skip to main content

Roll out software updates

This guide describes how to manually qualify new releases of Intrinsic software and roll them out to multiple systems in the field.

For automated testing in a CI/CD pipeline, see the CI/CD workflow guide.

Prerequisites​

This guide assumes you have:

  • The devcontainer set up (needed for inctl commands)
  • A solution that works in simulation and on hardware
  • A solution branch for each IPC you want to update
  • At least one IPC that you can use for validating the update on hardware

Qualify a new release​

Before rolling out an update to production systems, it is recommended to validate the new version using a leased Virtual Machine (VM). This allows you to test your solution against specific software versions without affecting physical hardware.

Step 1: Identify the versions to test​

You can find the latest released versions of IntrinsicOS and the runtime in the release notes or using inctl:

# List released versions of IntrinsicOS
inctl asset list_released_versions --asset_types=data ai.intrinsic.os

# List released versions of the Intrinsic Runtime
inctl asset list_released_versions --asset_types=data ai.intrinsic.runtime
note

The OS versions printed by inctl asset list_released_versions have the prefix 0.0.1+xfa., which must be removed before use with the commands below.

Step 2: Lease a VM​

Lease a VM from your pool with the specific versions you want to test. This environment is isolated and temporary. When leasing with inctl, the VM will expire after the specified duration, even if you have the Solution Editor open. Make sure to extend the lease if needed.

inctl vm lease --runtime <runtime-version> --intrinsic-os <os-version> --org <your-org> --duration 1h

Note down the ID (vmp-....-........) and the Frontend URL of the leased VM for future steps.

note

Leasing a VM with specific versions can take 3-10 minutes.

Step 3: Branch your solution​

Go to the Solutions page and create a new branch for your solution. This ensures any changes you make while validating the update will not affect the existing solution. After creating the branch, select the overflow menu (⋮) > Copy Solution ID.

Step 4: Start your solution​

Start your solution on the leased VM to verify compatibility. You'll need the copied Solution ID for your new branch from the previous step.

inctl solution start --cluster <vmp-....-........> --org <your-org> <solution-id>

Once started, verify that your solution operates as expected. If you need to take any steps to fix issues, note them down, as you will need to take the same steps for IPC-specific solution branches. Finally, save and commit your solution.

Step 5: Stop your solution​

Stop your solution, so that the VM can be re-used when preparing the IPC-specific branches.

inctl solution stop --cluster <vmp-....-........> --org <your-org> <solution-id>

Roll out to IPCs​

Once a release is qualified, you can roll it out to industrial PCs (IPCs).

Step 1: Branch your solution for specific IPCs​

Identify which IPCs you will update. You can list available IPCs and their current versions using inctl or the Flowstate Portal.

inctl cluster list --org <your-org>

For each IPC, create a branch from the older branch for this IPC to preserve its customizations. This is required because each branch can be deployed to at most one VM or IPC at a time. Repeat the qualification process for each IPC-specific solution branch on a leased VM to ensure compatibility.

Step 2: Check update policy​

Ensure updates are set to Manual to prevent automatic upgrades during or after the rollout process.

Additionally, we recommend disabling Require approval on the IPC to streamline the process. If enabled, you'll need to wait for operator approval before you can trigger the solution update.

warning

Notify the operator in advance of the rollout. Because the update process triggers an automatic system reboot, the IPC will be temporarily unavailable. Coordination is essential to ensure the update does not occur during active production cycles or halt critical machinery.

You can edit these settings in the Flowstate Portal (IPCs > overflow menu (⋮) > Edit details).

Step 3: Assign the update​

Assign the specific IntrinsicOS and runtime versions to each IPC.

inctl cluster upgrade run --org <your-org> --cluster <ipc-id-1> \
    --os <os-version> --runtime <runtime-version>
inctl cluster upgrade run --org <your-org> --cluster <ipc-id-2> \
    --os <os-version> --runtime <runtime-version>
...

Step 4: Wait for the update to complete​

The IPC(s) will download and apply the update. If an OS update is included, the IPC(s) will reboot.

You can monitor the progress in the Flowstate Portal or by running:

inctl cluster upgrade show --org <your-org> --cluster <ipc-id-1>
inctl cluster upgrade show --org <your-org> --cluster <ipc-id-2>
...

Step 5: Start and verify solution​

For each IPC, start the solution branch you created for it. You can do this from the Flowstate Portal on the Solutions page. Alternatively, you can select the overflow menu (⋮) > Copy Solution ID and use inctl:

inctl solution start --cluster <ipc-id-1> --org <your-org> <ipc-specific-solution-id-1>
inctl solution start --cluster <ipc-id-2> --org <your-org> <ipc-specific-solution-id-2>
...

Finally, use the Flowstate Portal to open the Solution Editor and verify the solution is running.