Upgrading
Before You Begin
Before upgrading, review the release notes for the target version. Note any breaking changes. Running RestoreTest jobs are not interrupted by a controller upgrade — the sandbox TTL failsafe ensures cleanup regardless.
Standard Upgrade with Helm
1. Update the chart repository
helm repo update
2. Check the current installed version
helm list -n kymaros-system
3. Upgrade CRDs manually
Helm does not upgrade CRDs automatically. If the release notes mention CRD changes, apply the updated CRDs before running helm upgrade:
kubectl apply --server-side -f https://github.com/kymorahq/kymora/releases/download/v<VERSION>/crds.yaml
Replace <VERSION> with the target chart version. If the release notes do not mention CRD changes, skip this step.
4. Upgrade the release
helm upgrade kymaros kymaros/kymaros \
--namespace kymaros-system \
--reuse-values
Use --reuse-values to preserve your existing configuration. To apply new chart defaults at the same time, use --reset-then-reuse-values (Helm 3.14+) or explicitly pass your overrides with --set.
5. Verify the rollout
kubectl rollout status deploy/kymaros-controller -n kymaros-system
kubectl rollout status deploy/kymaros-api -n kymaros-system
kubectl rollout status deploy/kymaros-frontend -n kymaros-system
All three deployments must reach successfully rolled out before the upgrade is complete.
CRD Considerations
Helm has a deliberate policy of not upgrading CRDs during helm upgrade to prevent accidental data loss. The implications for Kymaros:
- New fields added to a CRD — apply the updated CRD manifest manually before upgrading the chart. The controller will begin using the new fields immediately.
- Fields removed or renamed — treat this as a breaking change. Check the migration notes for the specific version.
- New CRDs added — Helm installs new CRDs on the first deploy only. If a new CRD is added in a chart version, you must apply it manually.
To check which CRD version is currently installed:
kubectl get crd restoretests.restore.kymaros.io -o jsonpath='{.metadata.annotations}'
Breaking Changes
v0.x to v1.0 (future)
Not yet applicable. Track the v1.0 milestone on GitHub.
General guidance
Any field removal or rename in RestoreTest, RestoreReport, or HealthCheckPolicy is a breaking change and will be announced in the release notes with a migration path. Additive changes (new optional fields) are not breaking and do not require migration.
Rollback Procedure
If the upgrade produces unexpected behavior, roll back to the previous chart revision:
# List revision history
helm history kymaros -n kymaros-system
# Roll back to the previous revision
helm rollback kymaros -n kymaros-system
If CRDs were upgraded manually before the rollback, the CRD schema may be ahead of the rolled-back controller. In that case, re-apply the previous CRD version:
kubectl apply --server-side -f https://github.com/kymorahq/kymora/releases/download/v<PREVIOUS_VERSION>/crds.yaml
Check controller logs after rollback to confirm reconciliation is functioning:
kubectl logs -n kymaros-system deploy/kymaros-controller --since=5m
Upgrading from Source
If you deployed from source using make deploy:
git fetch origin
git checkout v<VERSION>
make install # applies updated CRDs
make deploy IMG=your-registry/kymaros-controller:v<VERSION>
Version Compatibility Matrix
| Kymaros | Kubernetes | Velero |
|---|---|---|
| 0.1.x | 1.28 – 1.31 | 1.12+ |
| 0.2.x | 1.28 – 1.31 | 1.12+ |
Kymaros is tested against Kubernetes 1.28, 1.29, 1.30, and 1.31 in CI. Versions outside this range may work but are not officially supported. Velero 1.12 is the minimum required version; newer Velero versions are supported as they are released.
Cloud distributions (EKS, GKE, AKS, OKE) are supported as long as the underlying Kubernetes version falls within the compatibility range.