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
candidate	Each release as soon as Diagrid publishes it, while it runs ahead of stable.	Staging and test regions
stable	Releases Diagrid promotes after they have run on candidate. This is the default.	Production regions
lts	A stable release that Diagrid promotes about once a quarter. It is never newer than stable.	Self-managed production regions that want fewer upgrades

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.

About once a quarter, Diagrid promotes a stable release to lts, and a person approves each promotion. The lts channel is never ahead of stable.

How a release moves between channelsEach promotion takes the newest release that qualifies and skips older ones, so stable is usually up to two weeks behind candidate. lts is never ahead of stable.

Supported release lines

A release line is a minor version, such as 1.135, together with its patch releases, such as 1.135.1. Diagrid backports fixes to every supported line.

Channel	Supported lines	Support ends
stable	The three newest lines, such as 1.136, 1.135 and 1.134	When a newer promotion pushes the line out of the three, about six weeks after it reached stable
lts	Every line that reached lts in the last 12 months	12 months after the line first reached lts, even when lts has moved on to a newer line

These are the supported release lines on Catalyst today. A stable release line goes out of support when three subsequent release lines are out. A new release line is promoted to stable approximately every two weeks. See additional details in the release notes.

Release line	Supported on stable until	Supported on lts until
1.137	Three more new release lines reach stable	Not on lts
1.136	Two more new release lines reach stable	Not on lts
1.135	The next new release line reaches stable	9 October 2027

A release line that isn't in the table gets no more bugfixes or vulnerability updates. To find the release line a region runs, check its Catalyst version on the Regions page of the console, or the currentVersion in the output of diagrid region release get.

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. Because lts is never ahead of stable, this is the usual case when a region moves from stable to lts.

What you control by region type

	Self-managed BYOC	Dedicated Cloud and managed BYOC	Catalyst Cloud and Cloud Plus
Channel	candidate, stable or lts, 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 Candidate, Stable or LTS, 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 candidate, stable or lts:

diagrid region release set-channel my-region lts

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.