Hi folks, this is an overview of all the possible numbers we can assign to a charm and most importantly: when they can be helpful. An example is provided at the end.
(workload) Version
This is the workload version. If you are charming Discourse, for example, you would use the number that everyone else in the Discourse community (including non-charmers) would use to talk about different versions.
How to set workload version
-
If you are a charm developer, the Charmed Operator Framework will let you set the
versionusingset_workload_version(version). -
If you are deploying a charm, you can’t specify the workload
version. This is used for informational purposes only.
Where does it appear?
- When you run
juju status, that’s the app’sVersion.
(charm) Version
This is a version for the charm code itself. You can follow any pattern you want.
How to set charm version
-
If you are a charm developer, you can check how to set a charm version here.
-
If you are deploying a charm, you can’t specify the charm
version. This is used for informational purposes only.
Where does it appear?
Revisions
Every time a new binary is uploaded for a charm, a new revision is created on Charmhub. The value increments by 1.
The Juju team is currently working on changes to the way we work with revisions. Please refer to https://github.com/canonical/operator/pull/692 if you would like to chime in the conversation.
How to use revisions
-
If you are a charm developer, you can’t set it manually. It’s automatically assigned each time you upload to Charmhub.
-
If you are deploying a charm, there’s no way to specify a
revisionat deployment time. If you runjuju refresh, you will get the newest revision available in the channel you are tracking.
Where does it appear?
-
When you run
juju status, that’s the app’sRev. -
When you run
juju info charm_name, you can see all revisions available for a given charm in Charmhub.
Channel
This is composed of track and risk (channel = track/risk). A deployment will always track the channel set a deployment time (unless that id changed), meaning that when a human operator runs juju refresh, they will get the latest revision in that track.
Track - A sub-division of one charm. By default, all charms have a latest track, but developers might want to create an insider, for internal use, for example.
If the latest track always contains the latest version of a workload, users might inadvertently change the workload version when running juju refresh. As a charm developer, you should keep this in mind when selecting a track to release a charm and writing documentation.
The field track is the best way to express the workload version in a way that can be consumed by the user. It’s a good idea to keep the latest version of the workload in latest and create new tracks for new major releases of the workload.
Risk - Charms are installed using the stable risk-level by default. If a user specified a risk at deployment time and that is not available, the next most stable charm will be installed.
- stable: (default) This is the latest, tested, working stable version of the charmed operator.
- candidate: A release candidate. There is high confidence this will work fine, but there may be minor bugs.
- beta: A beta testing milestone release.
- edge: The very latest version - expect bugs!
How to use channels
- If you are a charm developer, you specify the channel at release
charmcraft release charm-name --channel=track/risk
- If you want to deploy a charm, you can specify the channel at deploy
juju deploy charm-name --channel=track/risk
Where does it appear?
-
When you run
juju status, that’s the app’sChannel. -
When you run
juju info charm_name, you can see all channels available for a given charm in charmhub.
A practical example
Example:
Each line represents a new upload to Charmhub. Please note how the revision will increment independently of other fields. Also note that this is not what Charmhub will show–this is a timeline: only the latest revision in a channel will be displayed.
| Workload version | workload_version | revision | channel | Comments |
|---|---|---|---|---|
| 0.8 | 0.8 | 1 | latest/beta | At the time of release, this workload version was the latest and it was beta. |
| 1.0 | 1.0 | 2 | latest/stable | At the time of release, this workload version was the latest and it was stable. |
| 1.0 | 1.0 | 3 | 1.0/stable | Same charm code and workload as above (rev 2), but a new track was created for users who would like to lock their workload versions on 1.0 |
| 1.2 | 1.2 | 4 | latest/stable | At the time of release, this workload version was the latest and it was stable. |
| 1.2.1 | 1.2.1 | 5 | 1.2/beta | For users who would like to use a beta version of major release 1.2. In this case the last digit (1) of the workload version maps to risk
|
| 1.2 | 1.2 | 6 | 1.2/stable | Same charm code and workload as rev 4, but a new track was created for users who would like to lock their workload versions on 1.2 |