Lifecycle Management

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 and rollback instructions. Rolling Dapr independently of the chart is not supported.

Version compatibility

The Dapr version shipped with recent Catalyst chart releases:

Catalyst chart version	Dapr version
1.39.0 and later	1.17.3-catalyst.1
1.28.0 – 1.38.0	1.17.2-catalyst.1

Upgrade and 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 Quick Deployment, the following CLI operations manage its lifecycle against the Catalyst Control Plane.

Create a region

diagrid region deploy registers and deploys a Region in one step using sensible defaults. Use diagrid region create instead when you need to opt into the optional Region capabilities below before deploying the Catalyst data plane:

# Bring your own ingress and TLS (default)
diagrid region create my-region --ingress *.my-region.company.com

# Enable Diagrid managed region domains
diagrid region create my-region --enable-managed-domain --ingress my-lb.example.com

# Enable remote CLI and console access over a secure tunnel
diagrid region create my-region --enable-public-management-api --enable-managed-domain --ingress *.my-region.company.com

• --enable-managed-domain — Diagrid allocates the Region's public wildcard domain and TLS certificate, so --ingress only needs to resolve locally to the gateway. See the Helm Chart Reference for the matching Catalyst data plane configuration.
• --enable-public-management-api — lets the Diagrid CLI and Catalyst console manage the Region without direct network access to the cluster. See Remote CLI and console access for when to use it and how to enable it.

After creating the Region, run diagrid region deploy <region-id> (or apply the Helm chart manually with the values described in the linked reference sections) to deploy the Catalyst data plane. See diagrid region create for the full flag set.

Remote CLI and console access

Use this option when you need to manage a Region from the Diagrid CLI or Catalyst console, but your cluster cannot be reached directly from your workstation — for example, it sits behind a firewall or NAT, or you prefer not to expose a public endpoint for management traffic. No VPN or direct network peering is required.

The tunnel carries CLI and console traffic only. Your applications continue to reach the Region through its gateway as usual.

Enable:

1. Add --enable-public-management-api when creating or updating the region (see examples above). This flag works independently of --enable-managed-domain — you can enable either one, or both.
2. Run diagrid region deploy <region-id>. The CLI configures the tunnel automatically.
3. Verify with diagrid region get <region-id> — look for a non-empty tunnelEndpointId and a managementDiagrid URL in the output.

See the Helm Chart Reference for the corresponding dataplane configuration.

How it works: the Region's management service initiates an outbound HTTPS connection to a Diagrid-hosted reverse proxy (Piko). Requests from the CLI and console are routed back through that connection, so no inbound ports need to be opened on the cluster. Authentication is handled automatically using JWTs issued by Dapr Sentry. Outbound HTTPS to tunnel-upstream.r1.diagrid.io is required in addition to the standard networking requirements.

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

diagrid region update replaces the region's spec wholesale rather than patching individual fields. If the region was created with --enable-managed-domain or --enable-public-management-api, you must pass those same flags on every subsequent update — omitting them resets the region back to the defaults (no managed domain, no public management API tunnel) and the dataplane will fall out of sync with its Helm values.

# Update the ingress on a region that uses managed domain + public management API —
# both flags must be re-passed to preserve the original configuration.
diagrid region update my-region \
  --ingress my-lb.example.com \
  --enable-managed-domain \
  --enable-public-management-api

See the Helm Chart Reference for the corresponding dataplane configuration, and diagrid region update for the full flag set.

Delete a region

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

diagrid region delete my-region

See diagrid region delete.