Event > List of events >
<action name>-action
See also: How to handle charm actions
Source:ops.charm.ActionEvent
This document describes the <action name>-action
event. Actions are methods of a charm designed to be directly called by the cloud administrator when the charm is deployed, in contrast with events, which are fired by juju and allow the charm to automatically respond to changing circumstances.
An action can have “parameters” (passed by the cloud admin to the charm) and “results” (passed by the charm back to the cloud admin, once the handler returns).
Note: If hyphens are used in action names, they are replaced with underscores in the corresponding event names. For example, an action named
snapshot-database
would result in an event namedsnapshot_database_action
being triggered when the action is invoked.
Contents:
Emission sequence
The <action name>-action
event will trigger after a user invokes the action-name
from the Juju CLI. It can be emmited to a single unit:
Scenario | Example Command | Resulting Events |
---|---|---|
Invoke action | juju run <unit/0> foo |
foo_action (on unit/0) |
Or to several units of a same application:
Scenario | Example Command | Resulting Events |
---|---|---|
Invoke action | juju run <unit/0> <unit/1> foo |
foo_action (on units 0 and 1) |
Note that the action handler in the charm can in principle cause other events to be fired. For example:
- Deferred events will trigger before the action.
- If the action handler updates relation data, a
<relation name>_relation_changed
will be emitted afterwards on the affected units.
Observing this event in Ops
You can subscribe to the event:
self.framework.observe(
charm.on.<action name>_action,
self.<action name>_action
)
Actions are surfaced as events that a charm can observe, similarly to lifecycle events. Action names are parsed by the Charmed Operator Framework and surfaced as events named <action_name>_action
.
If hyphens are used in action names, they are replaced with underscores in the corresponding event names. For example, an action named snapshot-database
would result in an event named snapshot_database_action
being triggered when the action is invoked.
Action handlers are passed an ActionEvent
as their first parameter, and thus have access to the action parameter values through the <event>.params
construct. In addition to the params
dict, the ActionEvent
class provides three convenience methods to the developer:
-
<event>.fail(message="")
: Report to the administrator that the action has failed, optionally providing a message indicating why the failure occured. -
<event>.log(message)
: Log a message for the administrator (available while the action is running). -
<event>.set_results(results)
: Report the result of the action, whereresults
is a dictionary. The maximum size must be under the maximum size allowed by the OS for arguments (typically around 100KB).
Note that any stderr output logged during the action handler execution will be injected into the results under the ‘Stdout’ key. For this reason, we don’t allow a “Stdout” key to be used in set_results
's argument.
def do_something_action(self, event):
"""Handle *do-something* action."""
result_dict = _my_results_getter()
event.set_results(result_dict)