Bosch IoT Rollouts

Mass cancel

Imagine following scenario: A new software update was distributed to many thousand devices using the auto assignment feature. After a few hundred devices have downloaded the update, a major issue within the software is detected and any further software rollout needs to be stopped immediately.

In Bosch IoT Rollouts it is possible to stop the rollout of an assigned distribution set and thus mass-cancel pending updates on further devices.

Table of contents:

Mass cancel through distribution set invalidation

The mass-canceling of running update actions can be achieved by invalidating the distribution set the major issue was detected on. The invalidation can be done either via the Management API or the UI.

The Management API provides an endpoint for invalidating a distribution set through the resource Distributionsets - HTTP API. In the UI, the invalidation of a distribution set is possible in the Deployment view, since canceling an update action is seen as part of the deployment itself. Whereas the general management of distribution sets is part of the Distribution view, where the software distributions are managed, versioned and grouped.

Consequences of invalidating a distribution set

An invalidated distribution set cannot be used for future deployments:

  • The distribution set cannot be assigned to targets, neither through a rollout, auto-assignment nor a single assignment.

  • Invalidated distribution sets cannot be valid again, but remain invalid.

  • The invalidation is not repeatable. If no cancelation type was selected during invalidation, it is not possible to execute the mass-cancel retrospectively.

Invalidating a distribution set will affect other entities that reference the distribution set, depending on the options that are selected during invalidation:

  • auto-assignment

  • rollouts

  • actions

The invalidation options and their effects on those entities are described in more detail in the next section.

Invalidation options

For the invalidation of a distribution set several options can be set to define the consequences the invalidation shall have of already existing entities, that relate to that distribution set. Those options allow to perform a mass-cancel on running updates, or keep running updates alive until finished by the target itself.

The following table provides an overview of the different scenarios and their effects on other entities:

Type of cancelation

Stop rollouts

Effects on other entities

None

false

  • Auto-assignments are removed

  • Rollouts remain running

  • Actions remain running

None

true

  • Auto-assignments are removed

  • Rollouts are stopped and put into state FINISHED

  • Actions remain running until the device finishes the update as usual

Soft

true

  • Auto-assignments are removed

  • Rollouts are stopped and put into state FINISHED

  • Regardless of the state, all open actions of this distribution set are soft-canceled

    • This option requires the device to support cancel flow

    • The device will be informed about the cancelation. The action remains running in state CANCELING. When the device confirms the cancelation, the action will be closed with state CANCELED

  • In the action history of the Deployment view this option corresponds to the cancel icon for a single action: images/confluence/download/attachments/1921235157/close-small-gray.png

Force

true

  • Auto-assignments are removed

  • Rollouts are stopped and put into state FINISHED

  • Regardless, of the state or whether the device supports the cancel flow, each action is force-quit

    • The action is closed and CANCELED state is displayed

    • No further feedback is expected from the device

    • The displayed status can differ from the actual status of the device

  • In the action history of the Deployment view this option corresponds to the force quit icon for a single action: images/confluence/download/attachments/1921235157/close-small.png

Visualization of invalidated distribution sets

An invalidated distribution set will be displayed accordingly in the different UI views to be able to distinguish them from valid distribution sets.

Deployment view

  • Invalidated distribution sets are displayed as strike-through (1)

  • Single assignment of that distribution set to a target is not possible

  • The distribution set cannot be edited

  • Actions, that were soft-canceled, will have the CANCELING (2) status in the action history. The action remains running until the device confirms the cancelation

  • Actions, that were force-quit, will have the CANCELED (3) status in the action history

images/confluence/download/attachments/1921235157/invalidDS_deploymentView.png

Rollout view

  • Invalidated distribution sets are displayed as strike-through (1)

  • The affected rollout is FINISHED (2) to indicate that the rollout itself is closed and won't address any further assignments. However, there might still be running actions on targets (3)

images/confluence/download/attachments/1921235157/invalidDS_rolloutView.png

Target Filters view

  • Invalidated distribution sets are removed from target filters

  • Creation of new auto-assignments with an invalidated distribution set is not possible

Distributions view

  • Invalidated distribution sets are displayed as strike-through

  • Assigning software modules is not possible, nor removing already assigned ones

  • The distribution set cannot be edited

images/confluence/download/attachments/1921235157/invalidDS_distributionsView.png

Required permissions

The invalidation of a distribution set requires different permissions, depending on the chosen options during invalidation:

  • UPDATE_REPOSITORY - always required to set the distribution state into the invalid state

  • UPDATE_TARGET - required, if running actions shall be canceled

  • UPDATE_ROLLOUT - required, if rollouts shall be stopped

The permissions can be adapted in the User management view. Read more about permissions in the Authorization chapter.