Release Upgrades

Upgrading a Helm release deploys a new chart version or updated values to an existing release. Each upgrade creates a new revision, enabling rollback if issues arise. The platform supports individual and batch upgrades.

Individual Upgrade

POST /api/v1/helm/releases/:releaseId/upgrade

{
  "chartVersion": "1.3.0",
  "appVersion": "2.1.0",
  "valuesOverride": {
    "replicaCount": 3,
    "image": { "tag": "v2.1.0" }
  },
  "description": "Upgrade for performance improvements"
}

The upgrade creates a new revision with the specified chart version and values. The previous revision remains in history for rollback.

Upgrade Behavior

Aspect	Behavior
Values merge	Override values are deep-merged with chart defaults
Revision tracking	New revision number is assigned
Status transition	`DEPLOYED` to `PENDING_UPGRADE` to `DEPLOYED` or `FAILED`
Rollback support	Previous revision remains available for rollback

Version Distribution

Platform administrators can check which chart versions are deployed across tenants:

GET /api/v1/helm/releases/chart/matih-query-engine/versions

Returns a map of version to count:

{
  "1.2.0": 15,
  "1.3.0": 8,
  "1.1.0": 2
}

Releases Needing Upgrade

GET /api/v1/helm/releases/chart/matih-query-engine/needs-upgrade?targetVersion=1.3.0

Returns all releases running a version older than the target, enabling administrators to identify and plan upgrades.

Batch Upgrade

POST /api/v1/helm/releases/chart/matih-query-engine/batch-upgrade?targetVersion=1.3.0

Upgrades all releases of the specified chart to the target version. This operation processes releases sequentially and returns the list of upgraded releases. Failed upgrades do not block subsequent ones.

Pre-Upgrade Checklist

Before performing upgrades, consider:

Review the chart changelog for breaking changes
Test the upgrade in a development environment first
Ensure sufficient cluster resources for the upgrade
Verify that values overrides are compatible with the new chart version
Plan the upgrade window to minimize impact on tenants

Release Management Release Rollbacks