Action

Actions are defined by a charm to allow a user with the right access level to interact with an application in ways specific to the application. This may include anything from creating a snapshot of a database, adding a user to a system, dumping debug information, etc.

An action is triggered via the juju CLI and applied to one or more units. It is run with parameters supplied by the user and records the success/fail status and any results for subsequent perusal.

The default behaviour is that the juju CLI blocks and waits for the action to complete. This synchronous behaviour allows actions to be easily included in command-line pipelines. As an action is executing, any progress messages as reported by the action are logged to the terminal. When the action completes, the result is printed. An action result is a map of key values, containing data set by the action as it runs, plus the overall exit code of the action process itself, as well as the content of stdout and stderr.

The execution of an action is organised into tasks and operations. (If an action defines a named unit of work – e.g., back up the database – that can be executed on selected units, a task is the execution of the action on each target unit, and an operation is the group of tasks queued by running an action across one or more units.)

The code used to implement an action can call any hook command as well as the following action commands:

  • action-log: to report a progress message

  • action-get: to get the value of a named action parameter as supplied by the user

  • action-set: to set a value in the action results map

  • action-fail: to mark the action as failed along with a failure message

Tip

In many cases, an action only has a need to run hook commands such as config-get to supplement the configuration passed in via the action parameters. A action may also commonly use status-set to update the unit or application status while it is running. If the action does use a hook command like relation-set, after the action completes successfully, a <endpoint>-relation-changed event will be emitted afterwards on the affected units.

Action execution

Actions operate in an execution environment similar to a hook, with additional environment variables available:

  • JUJU_ACTION_NAME holds the name of the action.

  • JUJU_ACTION_UUID holds the UUID of the action.