About 'assumes'

See also:

Since Juju 2.9.23, charm authors may explicitly state the set of features that a Juju model must be able to provide to ensure that a charm can be successfully deployed. This can be done by populating the assumes section of the V2 charm metadata.

This enables Juju to perform a pre-flight check before deploying the charm and to display user-friendly error messages when a feature requirement cannot be met by the model that the user is trying to deploy the charm to.

This is a purely opt-in feature. If the assumes section of the charm metadata is omitted, Juju will make a best-effort attempt to deploy the charm, and users must rely on the juju status output to figure out whether the deployment was successful.

The full list of supported feature names is outlined in Supported features.


The format of an assumes section

An assumes section consists of a list of feature names and/or nested sub-expressions. Sub-expressions such as “any-of” or “all-of” allow charm authors to specify more complex feature requirement use-cases. A typical assumes section would look as follows:

    - <feature_name>
    - any-of:
        - <feature_name>
        - <feature_name>
    - all-of:
        - <feature_name>
        - <feature_name>

In order for a charm to be deployed, all entries in the assumes block must be satisfied.

Feature names and version constraints

A feature name is an alphanumeric string that always begins with a letter and that may also contain dashes. For example: “juju” and “k8s-api”.

A feature name expression may also contain a version constraint to indicate that a particular version of the feature is required. A version constraint begins with a comparison predicate (“>=” or “<”) and is followed by a semantic version number. In the following example, the charm is only allowed to be deployed if the target model is running any 2.9 Juju agent binary:

    - juju >= 2.9
    - juju < 3.0

Note that any whitespace between the feature name and the version constraint is ignored, i.e. “juju>=2.9” and “juju >= 2.9” are functionally equivalent.

Nested expressions

To handle more complex use-cases, the assumes syntax also allows for boolean sub-expressions. The following types of sub-expressions are currently supported:

  • any-of: the sub-expression is satisfied if any of the provided child expressions is satisfied.
  • all-of: the sub-expression is satisfied if all of the provided child expressions are satisfied.

The child expressions may consist of feature expressions or other sub-expressions.

In the following example, the assumes expression is satisfied if the model runs Juju 2.9 agent binaries or the underlying substrate for the model is kubernetes.

    - any_of:
        - juju >= 2.9
        - K8s-api

Thanks for documenting this, @tmihoc!

I tried

  juju >= 2.9.24

and got an error

juju.errors.JujuError: {"error":"cannot upload charm: invalid charm archive: metadata: assumes: expected list, got string(\"juju \u003e= 2.9.24\")","error-code":"bad request"}

Changing to a list worked

  - juju >= 2.9.24

Thanks, @leon-mintz, fixed it now!

PS Credits for this are due especially to @achilleasa , who prepared the original draft for this doc.

Is it documented somewhere what can be used in this assumes block? juju is pretty straight forward, and I’m guessing k8s-api would require it to be a k8s cloud?

Hi @ca-scribner, this doc, also linked at the top, is the only other doc we have on this currently. It seems to support your hypothesis.