Tools

Reference

Actions for the Charm author

Actions are scripts, binaries, or other executables defined on a charm which may be invoked or queued remotely by the user on demand. For example, the Charm author might include a snapshot Action on a database Charm. See here for more on Actions and their use.

The user may give arguments when invoking the Action. Complex, nested arguments are possible. The Charm uses a file named actions.yaml to specify the type and parameters of these arguments. On juju-gui, the UI for an Action invocation will be automatically built based on actions.yaml.

Action Tools may be used by the author to define how Actions interact with Juju. Actions can retrieve params passed by the user, set responses in a map, or set a failure status with a message.

Defining Actions

To define the Actions available on a Charm, executables (scripts, binaries, etc.) for each Action must be included in the /actions directory in the Charm, and the name of each executable must be a top-level key in a YAML map in /actions.yaml in the Charm root:

pause:
description: Pause the database.
resume:
description: Resume a paused database.
snapshot:
description: Take a snapshot of the database.

Actions may be called with parameters. These parameters are specified as a child YAML map under a params key for each Action in actions.yaml. Note that Actions support JSON-Schema to enable nested schemas, and many other features.

Schema Requirements

actions.yaml must be included in the charm root, and must conform to the following requirements:

Each Action is defined as a top-level key of a YAML map, with the same name as the script it defines.

The value of each Action must be a map, which should include a description key and may include a params key to define a schema. If no description is given, a default empty description will be used.

The value of params, if it is included, must be a YAML map. Each key under params must be a string, and must have valid JSON-Schema as its value, transformed to a YAML map. JSON-Schema may be nested to create complex schemas.

JSON-Schema defines special keys such as required and additionalProperties, which may be given for the whole action at the same level as description and params, or within nested schemas at the usual level.

At this time, the $schema and $ref keys are not supported by Juju, as they may trigger resolution of remote objects and other issues.

additionalProperties: false should be included at the same level as the description key if additional params passed by the user should be rejected.

action-fail

action-fail causes the Action to finish as failed after completion. This might be used to indicate a full disk if a database dump was attempted, or perhaps to indicate that a remote service was unable to be resolved. The results set by action-set before or after failure are retained, and an Action fail status cannot be unset.

Params Transformation

This section specifies the transformation from params to JSON-Schema. This is meant as a clarifying aid to creating more complex schemas and should not be necessary for most Actions. If that is what the reader seeks, read on!

The params key of an action in actions.yaml defines a YAML map which is transformed to JSON-Schema as follows: