How to set the charm version

Contents:

• Set the charm version
• Test setting the charm version

Set the charm version

Charms can specify a version of the charm itself, so that a Juju admin can track the installed version of the charm back to the source tree that it was built from.

To set the version, in the root directory of your charm (at the same level as the charmcraft.yaml file) add a file called version (no extension). The content of the file is the version string, which is typically a major.minor.patch style version that’s manually updated, or a version control hash identifier.

For example, using the hash of the latest HEAD commit as the version:

$ git rev-parse HEAD > version
$ ls
lib      src    tox.ini charmcraft.yaml  LICENSE  requirements.txt  tests  version
$ cat version
0522e1fd009dac78adb3d0652d91a1e8ff7982ae

Juju admins using your charm can find this information with juju status in the YAML or JSON formats in the applications.<app name>.charm-version field. If there is no version, the key will not be present in the status output.

Note that this is distinct from the charm revision, which is set when uploading a charm to CharmHub (or when deploying/refreshing for local charms).

See more: Juju | Revision

Examples: container-log-archive-charm sets version to a version control hash

Test setting the charm version

See first: Get started with charm testing

Since the version isn’t set by the charm code itself, you’ll want to test that the version is correctly set with an integration test, and don’t need to write a unit test.

See first: How to write integration tests for a charm

To verify that setting the charm version works correctly in an integration test, in your tests/integration/test_charm.py file, add a new test after the test_build_and_deploy one that charmcraft init provides. In this test, get the status of the model, and check the charm_version attribute of the unit. For example:

# `charmcraft init` will provide this test for you.
async def test_build_and_deploy(ops_test: OpsTest):
    # Build and deploy charm from local source folder
    charm = await ops_test.build_charm(".")

    # Deploy the charm and wait for active/idle status
    await asyncio.gather(
        ops_test.model.deploy(charm, application_name=APP_NAME),
        ops_test.model.wait_for_idle(
            apps=[APP_NAME], status="active", raise_on_blocked=True, timeout=1000
        ),
    )

async def test_charm_version_is_set(ops_test: OpsTest):
    # Verify that the charm version has been set.
    status = await ops_test.model.get_status()
    version = status.applications[APP_NAME].charm_version
    expected_version = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode("utf8")
    assert version == expected_version

Examples: synapse checking that the unit’s workload version matches the one reported by the server

Contributors:@tmihoc, @tony-meyer