Upgrades

This guide covers the general procedures, checklists, and strategies for upgrading UDS Core. For version-specific breaking changes, notable features, and upgrade considerations, see the Release Notes.

Why upgrades matter

Regularly upgrading UDS Core is essential for:

• Security patches: CVE fixes for UDS Core components and underlying open source tooling
• Bug fixes: resolving issues in UDS Core and integrated components
• New features: access to new capabilities and improvements
• Compatibility: continued compatibility with the broader UDS ecosystem

Release cadence and versioning

UDS Core publishes new versions every two weeks, with patch releases for critical issues as needed. Before upgrading, review the versioning policy for details on release cadence, version support, breaking changes, and deprecation guarantees.

Caution

Review the release notes carefully for every upgrade. Breaking changes and required upgrade steps are documented there.

Upgrade strategies

Sequential minor version upgrades (recommended)

UDS Core is designed and tested for sequential minor version upgrades (e.g., 0.61.0 → 0.62.0 → 0.63.0). This approach:

• Follows the tested upgrade path
• Allows incremental validation at each step
• Reduces complexity during troubleshooting

Direct version jumps

Jumping multiple minor versions (e.g., 0.58.0 → 0.63.0) is not directly tested and requires additional caution:

• May encounter unforeseen compatibility issues
• Complicates troubleshooting since multiple changes are applied at once
• Requires more extensive testing in staging

Danger

If you must jump multiple versions, thoroughly review all release notes for intermediate versions and perform comprehensive testing in a staging environment before upgrading production.

Pre-upgrade checklist

1. Review release notes

   Read the release notes for all versions between your current and target version. Pay special attention to:

   • Breaking changes
   • Deprecated features
   • Configuration changes
   • New security policies and restrictions

2. Check for deprecations

   Resolve any active deprecations before upgrading, especially before major version upgrades.

3. Review Keycloak upgrade steps

   Check for Keycloak realm configuration changes required by the target version.

4. Test in staging

   Perform the upgrade in a staging environment that mirrors production. Validate all functionality before proceeding to production. Document any issues encountered and their resolutions.

5. Verify high availability

   If you require minimal downtime during upgrades:

   • Confirm your applications are deployed with proper HA configurations
   • Identify which UDS Core components may experience brief unavailability
   • Plan maintenance windows accordingly

6. Create a backup

   Back up your deployment before upgrading. See Backup & Restore for guidance.

Upgrade process

1. Update the UDS Core bundle reference

   Update the version ref in your uds-bundle.yaml:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream

   Tip

   Avoid other concurrent package upgrades (e.g., zarf init or other UDS packages) or larger changes like switching flavors. Perform upgrades independently to simplify troubleshooting.

2. Update configurations

   Before creating the new bundle, update configuration as needed:

   • UDS Core configuration changes: review any changes required for UDS Core custom resources, Helm chart values, and Zarf variables
   • Upstream tool configuration changes: review release notes for upstream tools, especially if major version updates are included, and update bundle overrides accordingly

3. Build and deploy the bundle

   uds create <path-to-bundle-dir>
   uds deploy uds-bundle-<name>-<arch>-<version>.tar.zst

   Depending on your configuration and process, this may include additional steps with variables or dynamic environment configuration.

Post-upgrade verification

After the bundle deployment completes, verify the health and functionality of your environment:

1. Verify UDS Core components

   The deployment performs basic health checks automatically. Additionally, confirm all UDS Core components are accessible at their endpoints with SSO login working.

   uds zarf tools kubectl get pods -A | grep -Ev 'Running|Completed'

   This command filters out healthy pods. If it produces output, investigate those pods before proceeding.

2. Verify Package resource status

   Confirm all UDS Package resources are Ready:

   uds zarf tools kubectl get packages -A

   All packages should show Ready in the STATUS column before proceeding.

3. Verify mission applications

   Check that your applications are still running and healthy. Validate endpoint accessibility and confirm monitoring and SSO are working as expected.

Rollback guidance

Caution

UDS Core does not officially test or support rollback procedures. Individual open source applications included in UDS Core may not behave well during a rollback.

Rather than attempting a rollback, use the following approaches:

1. Roll forward: address issues by applying fixes or configuration changes to the current version
2. Manual intervention: where necessary, perform manual one-time fixes to restore access. Report persistent issues as GitHub Issues for the team to address
3. Restore from backup: in critical situations, restore from backups rather than attempting a version rollback. See Backup & Restore for guidance

Additional resources

Configuration Changes Apply config changes to bundle overrides on a running platform.

Keycloak Realm Upgrades Version-specific steps for Keycloak realm configuration changes.

Release Notes Breaking changes, notable features, and upgrade considerations for each version.

Troubleshooting & Runbooks Diagnose and resolve common issues on a running platform.