How to upgrade¶

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

COS 3¶

Migrate from COS 2 to COS 3¶

Using Terraform:

Update the channel input to track 2/stable and then:
```
terraform init -upgrade; terraform apply
```
Manually refresh all charms to the latest revision in 2/stable
```
juju refresh <charm-name> --channel 2/stable
```
Update the Terraform module source ref to tf-cos-3.0.0 and then:
```
terraform init -upgrade; terraform apply
```
Once Terraform has applied all resources, apply again until no new resources are applied:
```
terraform apply
```

Migrate from COS Lite 2 to COS Lite 3¶

Using Terraform:

Update the channel input to track 2/stable and then:
```
terraform init -upgrade; terraform apply
```
Manually refresh all charms to the latest revision in 2/stable
```
juju refresh <charm-name> --channel 2/stable
```
Update the Terraform module source ref to tf-cos-lite-3.0.0 and then:
```
terraform init -upgrade; terraform apply
```
Once Terraform has applied all resources, apply again until no new resources are applied:
```
terraform apply
```

Without Terraform:

Refresh all track 2 charms so they point to the latest revision on 2/stable.
```
juju refresh <charm-name> --channel 2/stable
```
Refresh each charm’s track (major.minor) to the ones in the release notes.
```
juju refresh <charm-name> --channel major.minor/stable
```

COS 2¶

Migrate from COS Lite 1 to COS 2¶

The main differences between COS Lite and COS from data perspective are 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 from one charm revision of Loki to another is complex and nuanced. At this point, we recommend a retention-based phase-out.

Migration via retention-based phase-out¶

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

Migrate from COS Lite 1 to COS Lite 2¶

Refresh all track 1 charms so they point to the latest revision on 1/stable.
Refresh to track 2.