How to upgrade¶

This guide shows how to upgrade an existing COS deployment to a newer track.

Find the section that matches the upgrade path you need:

Migrate from COS 2 to COS 3.0 (COS or COS Lite)
Migrate from COS Lite 1 to COS 2
Migrate from COS Lite 1 to COS Lite 2

COS 3.0¶

Migrate from COS 2 to COS 3.0¶

These steps apply to both COS 3.0 and COS Lite 3.0. Although COS and COS Lite are distinct products with separate Terraform modules and different component sets, the upgrade procedure is the same unless a step includes an Applies to note.

Choose the method that matches how you deployed COS:

Using Terraform (recommended)
Without Terraform

Using Terraform¶

This is the recommended upgrade method.

Before you begin, review How to configure COS for strict reproducibility to understand how to upgrade with version pinning.

Set the channel input to 2/stable, then apply:
```
terraform apply
```
Refresh all charms to the latest revision on 2/stable:
1. Check charmhub.io for the latest revision on 2/stable per component.
2. Pin all components to those revisions, then apply:
```
terraform apply
```
Remove the revision pins.
Review the breaking changes for the new track and update your inputs accordingly.
Update the Terraform module source ref to a release tag, for example tf-cos-3.0.n, then apply:
```
terraform init -upgrade
terraform apply
```
Apply again, repeating until no new resources are created:
```
terraform apply
```

Without Terraform¶

Use this method only if you have no Terraform state, for example if you deployed via the COS Lite Juju bundle. Otherwise, upgrade using Terraform.

Refresh all COS 2 charms to the latest revision on 2/stable:
```
juju refresh <charm-name> --channel 2/stable
```
Refresh each charm to its target track (major.minor) as listed in COS components:
```
juju refresh <charm-name> --channel major.minor/stable
```

Warning

There is a known issue when manually refreshing Grafana from track 2 to a later track, which can cause the application to enter an error state. Without Terraform, the only workaround is to redeploy the Grafana application and re-add its previous relations.

COS 2¶

Migrate from COS Lite 1 to COS 2¶

From a data perspective, the main difference between COS Lite and COS is that COS uses different charms for the logs and metrics backends:

For metrics, Prometheus is replaced with distributed Mimir.
For logs, monolithic Loki is replaced with distributed Loki.

Migrating data from Prometheus to Mimir, or between different Loki charms, is complex and nuanced. For this reason, we recommend a retention-based phase-out instead.

Migrate via retention-based phase-out¶

Deploy COS in a separate model, alongside COS Lite.
Relate the new COS charms to the same applications that COS Lite is related to.
Wait for the COS Lite retention period to elapse.
Verify that the same data is available in both COS Lite and COS.
Decommission COS Lite.

Migrate from COS Lite 1 to COS Lite 2¶

Refresh all COS Lite 1 charms to the latest revision on 1/stable.
Refresh each charm to track 2/stable.