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_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, where results 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)

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?

You’re right! Fixed