Event '<action name>-action'

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 named snapshot_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_event (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_event (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
)

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: str = ""): Report to the administrator that the action has failed, optionally providing a message indicating why the failure occured.
  • <event>.log(message: str): Log a message to update the administrator as to the progress of the action.
  • <event>.set_results(results: Dict[str, str]): Report the result of the action.

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)

Would an action trigger deferred events to fire before the action event itself?

1 Like

I just tested with a simple charm and it seems like that. Deferred events will trigger before the action.

2 Likes

Thanks! Updated accordingly.

Under “Resulting Events”, should foo_event be replaced with foo_action?