# Upgrade your solution

> Pull a more recent release, sync updated images, and redeploy using the vpctl tool

> **Warning:**
>
> The upgrade process generates new configuration files and charts. Before you upgrade, commit your current configuration to source control so that you can roll back to the previous configuration if necessary.

The upgrade process uses the vpctl tool to pull a more recent release and redeploy the solution.

To upgrade your solution, complete these steps:

## 1. Update the manifest version

Update the `releaseVersion` key in your `manifest.yaml` file to the desired version:

```yaml
releaseVersion: 0.13.0
```

> **Note:**
>
> Each release declares the minimum required version of the vpctl tool in the `compatibility.yaml` file. If your vpctl tool is too old, the `release generate` and `secret generate` commands stop with an upgrade message. Reinstall the vpctl tool to a compatible version before continuing.

## 2. Pull the new release

Run this command:

```sh
vpctl release pull --clean-output
```

## 3. Review the changelog

In the extracted release, compare the changes between the two versions and check for any required changes in configuration:

```sh
cat extracted-release/CHANGELOG.md
```

If you need to change any configuration, update your `manifest.yaml` file. For details about manifest fields and examples, see the [Manifest reference](../../vpctl/manifest). For a history of vpctl command changes, including new flags and breaking changes, see the [vpctl Changelog](../../vpctl/changelog).

> **Warning:**
>
> If the changelog calls out a breaking change with required migration steps, complete them before continuing with the rest of this guide. For example, upgrading to release `0.13.0` replaces RustFS with Garage and requires you to either drain the RustFS persistent volumes or mirror their contents to Garage before you run `vpctl release deploy`. Refer to the [On-Premises release notes](/cloud/virtual-private-cloud/on-premises/release-notes.md) for the full procedure that applies to your target release.

## 4. Sync the updated artifacts

Authenticate to both registries, then sync Docker images and ORAS artifacts to your private registry:

```sh
docker login uccmpprivatecloud.azurecr.io
docker login <your-registry-url>

vpctl artifact sync preflight
vpctl artifact sync images --skip-existing --cleanup
vpctl artifact sync oras
```

The `--skip-existing` flag skips images that are already in your registry, and `--cleanup` removes local images after each push.

If your manifest opts in to the `deployment.helmChartMode: remote` preview, also mirror the OCI Helm charts that are published to the Unity registry. Not all charts are available yet, so this command syncs only the charts that are published so far:

```sh
vpctl artifact sync charts
```

## 5. Regenerate and deploy the secrets

If the new release introduces new secrets, regenerate the secrets:

```sh
vpctl secret generate --import secrets.import.yaml --use-defaults
vpctl secret deploy
```

To preserve the previously generated values across upgrades, add the `--persist` flag. The process writes back the persisted values to the import file and reuses them on subsequent runs without regeneration:

```sh
vpctl secret generate --import secrets.import.yaml --use-defaults --persist
```

## 6. Regenerate and deploy the charts

### Helm deployment

```sh
vpctl release generate --clean-output
vpctl release deploy --dry-run
vpctl release deploy
```

### ArgoCD deployment

```sh
vpctl release generate --format argocd --clean-output
git add generated-charts/
git commit -m "Upgrade to release v0.13.0"
git push
vpctl release deploy --format argocd
```

## 7. Verify the upgrade

Check that all pods are running:

```sh
kubectl get pods --all-namespaces --watch
```

Ensure that all pods eventually move to the **Running** state. If a pod isn't running, describe it and check its logs to find the issue.

The upgrade process results in these changes:

* Updated container images are deployed.
* New or modified Helm charts are applied.
* Configuration changes from the new release take effect.