Writing charms that use terms

Many applications require the acceptance of terms in order to be installed. Starting with Juju 2, charms can require a user accept its terms in order for it to be deployed.

Because of the nature of terms, the user must have a Launchpad account, and will be prompted to login when attempting to deploy a term-enabled charm.

How it works

When a user tries to deploy a term-enabled charm from the charm store, Juju will check if the terms have been agreed to. If they have, the charm will deploy as usual. If not, the user will be prompted to run the juju agree command in order to deploy.

Managing terms

Creating terms

As a charm developer, you may push and release terms owned by a group of which you are a member. Groups are mapped onto Launchpad teams, so you will need to join or create a team in Launchpad.

Install latest charm-tools

To use terms you will need at least v2.2 of charm tools.

Pushing terms

To push an initial or updated revision of a term, use charm push-term.

charm push-term term.txt my-group/my-term

This displays the assigned ID for the created term revision.

my-group/my-term/1

This pushes, or uploads, the contents in the local file terms.txt to the term my-group/my-term. Because this is a new term, revision 1 is created.

Testing unreleased terms

As a member of my-group, you can juju agree to your own unreleased term:

juju agree my-group/my-term/1

However, until this revision is released, the term cannot be agreed to by non-owners.

The term contents and metadata may also be viewed with charm show-term.

charm show-term my-group/my-term/1

Which returns output like this:

id: my-group/my-term/1
owner: my-group
name: my-term
revision: 1
createdon: 2016-04-20T13:28:54Z
published: false
content: |
  Your terms here...

Releasing terms

Use charm release-term to release a term revision for general availability. Note that until a term revision is released, non-owners will be unable to agree to it. If your charm requires agreement to an unreleased revision, or any revision of a new, never-before-released term, users will not be able to agree to it, and will be unable to deploy the charm.

When releasing, the revision to be released must be given:

charm release-term my-group/my-term/1

Requiring agreement to terms in your charm

In order to make a charm require terms, the terms key has been introduced to the charm's metadata.yaml. For example:

name: terms1
summary: "That's a dummy charm with terms."
description: |
    This is a longer description which
    potentially contains multiple lines.
terms: ["my-group/my-term"]

The terms key can include multiple terms to be required. It can also require specific versions of a term, i.e., my-group/my-term/2 would reference the second version of the my-group/my-term term. Omitting the version will require the latest version.

Listing terms

There two distinctions when considering terms. There are the terms that are linked to a charm, and terms that have been accepted by the user. Developer-facing subcommands are run against the charm command, which is installed via charm-tools, while users interact with juju.

charm terms shows the terms that you have created, and which charms they are associated with.

charm terms

This produces a listing of your terms.

TERM                CHARM
my-group/my-term/1  cs:trusty/terms-example-0

You can also view the terms associated with a specific charm.

charm show cs:trusty/terms-example-0 terms

This displays a subset of charm metadata; the terms required by the charm:

terms:
- my-group/my-term/1

A user can view the list of terms they've agreed to with juju agreements.

juju agreements

The output displays each term revision the user has agreed to:

[
    {
        "user": "aisrael",
        "owner": "my-group",
        "term": "my-term",
        "revision": 1,
        "created-on": "2016-04-20T21:01:24.84Z"
    }
]

Upgrading terms

Deployed charms will run under the terms they were installed with. If the terms have been revised, running juju upgrade-charm <application> will require the user to accept the new terms before the upgrade will run.

Caveats

Terms are only checked when the charm is deployed from the charm store, so deploying a local charm will bypass the term check and install.