In Juju, a hook is a notification from the controller agent through the unit agent to the charm that the internal representation of Juju has changed in a way that requires a reaction from the charm so that the unit’s state and the controller’s state can be reconciled.
In the charm SDK, in Ops, Juju hooks are translated into Ops events = ‘events’, specifically, into classes that inherit from HookEvent.
Contents:
List of hooks
Lifecycle hooks
collect-metrics
config-changed
The config-changed hook always runs once immediately after the install hook, and likewise after the upgrade-charm hook. It also runs whenever the service configuration changes, and when recovering from transient unit agent errors.
install
The install hook always runs once, and only once, before any other hook.
leader-deposed
leader-elected
leader-settings-changed
post-series-upgrade
Removed in Juju 4.
pre-series-upgrade
Removed in Juju 4.
remove
start
The start hook always runs once immediately after the first config-changed hook; there are currently no other circumstances in which it will be called, but this may change in the future.
stop
The stop hook is the last hook to be run before the unit is destroyed. In the future, it may be called in other situations.
update-status
upgrade-charm
The upgrade-charm hook always runs once immediately after the charm directory contents have been changed by an unforced charm upgrade operation, and may do so after a forced upgrade; but will not be run after a forced upgrade from an existing error state. (Consequently, neither will the config-changed hook that would ordinarily follow the upgrade-charm.
Action hooks
For each action, a hook named on the template <action name>-action.
Pebble hooks
These hooks require an associated workload/container, and the name of the workload/container whose change triggered the hook. The hook file names that these kinds represent will be prefixed by the workload/container name; for example,
mycontainer-pebble-ready.
<container>-pebble-change-updated
<container>-pebble-check-failed
Added in Juju 3.6.
<container>-pebble-check-recovered
Added in Juju 3.6.
<container>-pebble-custom-notice
<container>-pebble-ready
Relation hooks
These hooks require an associated relation, and the name of the relation unit whose change triggered the hook. The hook file names that these kinds represent will be prefixed by the relation name; for example,
db-relation-joined.
<endpoint>-relation-broken
The relation-broken hook is not specific to any unit, and always runs once when the local unit is ready to depart the relation itself. Before this hook is run, a relation-departed hook will be executed for every unit known to be related; it will never run while the relation appears to have members, but it may be the first and only hook to run for a given relation. The stop hook will not run while relations remain to be broken.
<endpoint>-relation-changed
The relation-changed hook for a given unit always runs once immediately following the relation-joined hook for that unit, and subsequently whenever the related unit changes its settings (by calling relation-set and exiting without error). Note that immediately only applies within the context of this particular runtime relation – that is, when foo-relation-joined is run for unit bar/99 in relation id foo:123, the only guarantee is that/ the next hook to be run in relation id foo:123 will be foo-relation-changed for bar/99. Unit hooks may intervene, as may hooks for other relations, and even for other foo relations.
<endpoint>-relation-created
<endpoint>-relation-departed
The “relation-departed” hook for a given unit always runs once when a related unit is no longer related. After the “relation-departed” hook has run, no further notifications will be received from that unit; however, its settings will remain accessible via relation-get for the complete lifetime of the relation.
<endpoint>-relation-joined
The “relation-joined” hook always runs once when a related unit is first seen.
Storage hooks
These hooks require an associated storage. The hook file names that these kinds represent will be prefixed by the storage name; for example,
shared-fs-storage-attached.
<storage>-storage-attached
<storage>-storage-detaching
Secret hooks
These hooks require an associated secret.
secret-changed
Triggered by Juju on a secret’s observer when the secret’s owner changes the secret’s contents.
secret-expired
Currently supported only for charm secrets.
Triggered by Juju on a secret’s owner when a secret’s expiration time elapses.
secret-remove
Currently supported only for charm secrets.
Triggered by Juju on a secret’s owner when one of the secret’s revisions can be removed.
secret-rotate
Currently supported only for charm secrets.
Triggered by Juju on a secret’s owner when the secret’s rotation policy elapses .
Contributors: @anvial, @hmlanigan, @ppasotti , @simonrichardson, @tmihoc