Skip to main content

Upgrades & Operations

Manage upgrades and operations for Catalyst Enterprise Self-Hosted.

Supported Dapr Versions​

Each Catalyst Enterprise Self-Hosted release is built and tested against a single, pinned Dapr version. When you install or upgrade the Catalyst Helm chart, the Agent rolls out that exact Dapr version across the region — the Dapr control plane and the Catalyst Dapr Servers all move together. There is no separate Dapr upgrade path.

Version policy​

  • One Dapr version per Catalyst release. A given chart version ships exactly one Dapr version. Mixing Dapr versions within a region is not supported.
  • Latest stable Dapr. Catalyst tracks upstream Dapr closely. New Dapr minor and patch releases are picked up by the next Catalyst chart release after internal validation, so keeping your region on a recent Catalyst version is the recommended way to stay on a supported Dapr.
  • Catalyst fork for the Dapr control plane. Catalyst ships a hardened fork of the Dapr control plane tagged <version>-catalyst.<n> (for example 1.17.3-catalyst.1).
  • Upgrade Dapr by upgrading Catalyst. To adopt a new Dapr version, upgrade the Catalyst chart as described in Upgrade & Rollback Instructions. Rolling Dapr independently of the chart is not supported.

Version compatibility​

The Dapr version shipped with recent Catalyst chart releases:

Catalyst chart versionDapr version
1.39.0 and later1.17.3-catalyst.1
1.28.0 – 1.38.01.17.2-catalyst.1

Upgrade & Rollback Instructions​

Catalyst Enterprise Self-Hosted is distributed as a single Helm chart, so upgrades and rollbacks are standard helm upgrade and helm rollback operations. All Catalyst changes are backwards-compatible between adjacent versions, so rollback is always safe.

Before you upgrade​

  1. Review the Catalyst release notes for the target version.
  2. Back up your external dependencies:
    • Workflow PostgreSQL database.
    • Dapr Scheduler PostgreSQL database, if you run it separately.
    • Any external Kafka topics used by Managed Pub/Sub.
  3. If you mirror images to a private registry, mirror the new versions before running the upgrade.
  4. Test the upgrade in a non-production region first.

Upgrade​

Upgrade the chart in place:

helm upgrade catalyst oci://public.ecr.aws/diagrid/catalyst \
     -n cra-agent \
     --version <new-version> \
     -f catalyst-values.yaml

Re-apply the same values file you used at install time, including join_token. The token is only used during initial registration, but the chart requires it to be present on every upgrade — keep it in your values file alongside the rest of your configuration. See the Helm Chart Reference for the full set of chart values.

The Agent rolls out all Catalyst components — including the Dapr Servers — to the new versions automatically. No additional manual steps are required.

After the upgrade, verify pods are Ready in the cra-agent and prj-* namespaces and that your region is healthy in the Diagrid Cloud console.

Rollback​

To roll back to the previous release:

helm rollback catalyst <revision> -n cra-agent

Or, equivalently, redeploy a previous chart version with your values file:

helm upgrade catalyst oci://public.ecr.aws/diagrid/catalyst \
     -n cra-agent \
     --version <previous-version> \
     -f catalyst-values.yaml

Persistent state — PostgreSQL databases, Kafka topics, Kubernetes secrets, and project namespaces (prj-<project-id>) — is preserved across rollback. The Agent reconciles the runtime components back to the versions pinned in the older chart.

Chart values compatibility​

The values.yaml surface is stable within a major chart version. Breaking changes to values are reserved for major chart version bumps and will be documented in the release notes with migration instructions.

Region Lifecycle​

Once a region is deployed via the installation guide, the following CLI operations manage its lifecycle against the Diagrid Cloud control plane.

Rotate join tokens​

Regenerate the region's join token if it is exposed or needs rotation:

diagrid region regen-join-token my-region

After regeneration, re-run diagrid region deploy — or re-render the Helm chart with the new token and run helm upgrade — to push the new token into the cluster. See diagrid region regen-join-token.

Update a region​

Update a region's metadata, such as its ingress domain or location:

diagrid region update my-region --ingress updated-domain.company.com
diagrid region update my-region --location new-location

See diagrid region update for the full flag set.

Delete a region​

Deleting a region removes its projects, data plane registration, and all workloads running in it. Only delete a region after migrating or retiring its projects.

diagrid region delete my-region --wait

See diagrid region delete.

Last updated on