Release channels

A release channel is a named stream of Catalyst data plane releases. Each region your organization owns follows one channel, and Diagrid uses that channel to work out which release the region should run next.

Who acts on that decision depends on how you run Catalyst:

• In a self-managed BYOC region, you choose the channel and you install each upgrade yourself.
• In a Dedicated Cloud or managed BYOC region, Diagrid installs upgrades for you from the stable channel. You can pause them, for example during a change freeze.
• On Catalyst Cloud and Cloud Plus, your projects run in shared regions that Diagrid operates and upgrades. There is no channel to choose and no upgrade to pause.

Channels

Channel	What it carries	Recommended for
stable	Releases Diagrid promotes after they have run on candidate. This is the default.	Production regions
candidate	Each release as soon as Diagrid publishes it, while it runs ahead of stable.	Staging and test regions

Release cadence

Every release reaches candidate first, once Diagrid deploys it to production. It can move to stable after it has run there for at least 24 hours without a rollback and passed Diagrid's test suites.

Diagrid promotes a new stable release about every two weeks, and a person approves each promotion. Each promotion takes the newest release that qualifies and skips the ones before it, so stable is usually up to two weeks behind candidate.

Diagrid supports the three newest stable lines, such as 1.136, 1.135 and 1.134, and backports fixes to each of them. A line leaves support when a newer promotion pushes it out of the three, about six weeks after it reached stable.

Upgrade modes

A region's release policy combines its channel with a mode:

• follow (the default) upgrades the region toward the newest release on its channel.
• hold pauses upgrades and keeps the region on the release it runs now, until you resume them.
• pin keeps the region on a named version. Only Diagrid can set a pin.

A region that follows its channel moves one tested upgrade at a time. When no tested upgrade leads straight from the release you run to the newest one, the next release on offer is an intermediate one. Once that release is running, the next one becomes available.

Some things stop a region upgrading even when it follows its channel: a freeze window or pin that Diagrid has set, a release Diagrid has blocked, or no tested upgrade path from your release. The CLI and the API report a reason code that says which one applies, such as ALREADY_AT_DESTINATION or FREEZE_WINDOW_ACTIVE.

Switching to a channel whose newest release is older than the one you run never downgrades the region. It stays on its release until the new channel catches up.

What you control by region type

	Self-managed BYOC	Dedicated Cloud and managed BYOC	Catalyst Cloud and Cloud Plus
Channel	stable or candidate, your choice	Always stable	Set by Diagrid
Who installs upgrades	You	Diagrid	Diagrid
What you can change	Channel, pause and resume	Pause and resume	Nothing

Self-managed regions

Diagrid tells you when a new release is waiting for a self-managed region, and you decide when to install it. Changing the channel only changes which releases the region is offered.

View the channel and upgrades in the console

1. In the Catalyst console, open Regions. A region with an upgrade waiting shows an arrow next to its Catalyst version. Hover over the arrow to see the release on offer.

   

2. Open the region. Its details show the Release channel and the newest release on that channel. When an upgrade is waiting, a banner at the top of the page names the release to install.

3. To switch channel, select the edit icon next to Release channel, or open the region's action menu (three dots) and select Change release channel.

4. Choose Stable or Candidate, then select Save.

View and change the channel with the CLI

Show the region's policy, the release it runs, and the release waiting for it:

diagrid region release get my-region

The table shows the channel and mode, currentVersion, nextVersion and upgradeReason. An empty nextVersion means nothing is waiting, and upgradeReason says why. Add --output json for every field, including when a freeze window lifts.

Switch the region to another channel:

diagrid region release set-channel my-region candidate

You can also pause upgrades on a self-managed region. While upgrades are paused, Diagrid offers the region no new release.

note

Diagrid learns which release a region runs from the region itself. A region older than 1.115.0 does not report it, so currentVersion stays empty and no upgrade is offered. Upgrade the region to fix this.

Install an upgrade

When a release is waiting, install it with helm upgrade as described in Lifecycle management. To feed the decision into your own tooling, such as Argo CD, see Automate upgrades.

Dedicated Cloud and managed BYOC regions

Diagrid upgrades Dedicated Cloud and managed BYOC regions for you. These regions always follow the stable channel, and you cannot change it.

The one control you have is to pause upgrades, for example during a change freeze. Use the CLI to check what the region runs and what is coming:

diagrid region release get my-region

Pause and resume upgrades

Pause upgrades with a reason and a review date:

diagrid region release hold my-region \
  --reason "Year-end change freeze" \
  --review-at 2027-01-05

• --reason and --review-at are both required.
• --review-at takes a date, read as midnight UTC, or an RFC 3339 timestamp such as 2027-01-05T09:00:00Z. It must be in the future and no more than 90 days away.
• To extend a pause, run hold again with a new review date. The new reason and date replace the old ones.

The review date does not resume upgrades

When the review date passes, upgrades stay paused and diagrid region release get reports decisionRequired as true. Upgrades start again only when you resume them.

Resume upgrades:

diagrid region release resume my-region

The region follows its channel again. If releases came out while upgrades were paused, it may move through several upgrades to catch up.

Pause and resume upgrades with the CLI or the Control Plane API. The console cannot do either.

Next steps

• Automate upgrades of a self-managed region from the API or an in-cluster ConfigMap.
• Lifecycle management to install, upgrade and roll back a self-managed region.
• Release notes for what changed in each release.