Skip to main content

Roll out a version

Publishing a version, or moving the version an installation pins, changes the version new services and scopes are created with. The ones that already exist keep running the version they were created from. A rollout is how you move them: in waves, each one a batch you review before anything runs.

Current and desired version​

Every service or scope created from a package pins a version. Its current version is the one it runs: its specification, actions and links are read from that version, not from the live specification.

A rollout sets a desired version on each instance it targets. Setting it runs nothing by itself. From then on, the instance reads its specification, actions and links from the desired version, and the next action that succeeds on it, typically its update, makes the desired version current. A scope works the same way: the desired version is kept in its settings, its configuration form follows it from then on, and the settings show the version as current once an action succeeds on it.

For a service, a GET request to /service/{id} returns both: package_revision_id is the current version and desired_package_revision_id the desired one.

The desired version can be older than the current one: that's how you roll back. A deprecated version can still be rolled out, for the same reason, but it can't become the package default.

Where to find it​

Open Platform settings, then Services or Scopes, and pick the specification. In its Versions tab, every version offers Rollouts, which opens that version's rollout: the timeline of its waves. Right after you publish a version from the same page, the dialog offers Roll out for it directly.

Plan the waves​

Waves are ordered batches of the specification's instances. A common path is one wave for development, then one for staging, and one wave per production resource to finish. Each wave is created pending and runs only when you start it, so you can go as slow as you need between them.

Add a wave​

Add wave asks which instances belong to it. Everything you set combines: an instance joins the wave only when it matches all of it.

  • Resource: the account, namespace or application whose services or scopes the wave targets, descendants included.
  • Dimensions: optional. Narrow the wave to some dimension values, such as a single environment.
  • Current version: optional. Only instances running that version join the wave. This is the way to move everything still on an older version, without touching what already moved.

The wave is created pending: nothing changes yet. Open it to see the exact list of services or scopes it will touch, and delete it if the list isn't what you meant.

Start it​

Start sets the desired version on every target of the wave. The rollout page shows the progress of each wave, and the wave itself lists every target with its update status: succeeded, failed, pending or running. A target fails when nullplatform refuses the change; the row shows the response code and the message, with the details one click away.

The wave runs with the identity of whoever starts it, so the audit trail and any approvals attribute the changes to that person.

Continue with the next wave​

When a wave finishes healthy, check how its instances behave on the new version, then add and start the next one. Repeat until the fleet is covered.

Cancel, retry and resume​

  • Cancel stops a running wave: the targets not updated yet are skipped, the one in flight finishes, and nothing already applied is reverted. To undo a target that already moved, roll out the previous version to it.
  • Delete removes a wave that never ran, along with its staged list. A wave that ran stays as the record of what it changed.
  • Retry failed creates a new wave with only the failed targets of a wave, and starts it immediately.
  • Resume picks up a wave interrupted by a platform restart. If the wave is still executing, nothing changes.

Follow the fleet​

The services and scopes lists show the version of every instance, with the current and the desired one when they differ. Filter by specification and version, and choose whether the version matches the current or the desired one: the current version tells you what still runs an older version, the desired one what a rollout has already reached.

Next steps​

  • Install a package: set up the layers an installation needs, pin a release, and upgrade
  • Packages: what a package is, its versions and the default
  • Package API: read a package's versions and compare two of them