Event '<container name>-pebble-ready'

Event > List of events > Lifecycle events > <container name>-pebble-ready

Source: ops.charm.PebbleReadyEvent

The <container name>-pebble-ready event is emitted once the Pebble sidecar container has started and a socket is available. There is one X-pebble-ready event for each container defined in metadata.yaml file. This event allows the charm to configure how services should be launched.

This event is kubernetes-charm-specific and is only ever fired on kubernetes deployments.

WARNING: the pebble-ready event doesn’t guarantee the workload container is still up. For example, if you manually kubectl patch during e.g. install, then you may receive pebble-ready after the old workload is down but before the new one is up. For this reason it’s essential to, also in pebble-ready event handlers, to guard with Container.can_connect() to check that the socket is up. Do note that this is a point-in-time check, so can-connect = True doesn’t mean that 1 millisecond after it will still be.

Contents:

Emission sequence

Scenario Example Command Resulting Events
Create unit juju deploy foo or
juju add-unit foo 		install -> config-changed -> start -> bar-pebble-ready
  • When a charm is upgraded, pebble-ready is guaranteed to fire only after start (consequentially, it fires only after upgrade-charm and config-changed fired)
Scenario Example Command Resulting Events
Charm upgrade juju refresh foo --path=./foo.charm stop -> upgrade-charm -> config-changed -> start -> bar-pebble-ready
  • If the primary container restarts at any point (e.g. Kubernetes reschedules the pod after kubectl delete), then pebble-ready would be emitted again when the container starts (preceded by a start event and the whole upgrade sequence).
Operation Example Command Resulting Events
Pod churn k delete pod foo-0 -n foo stop -> upgrade-charm -> config-changed -> start -> bar-pebble-ready

Note: Pebble itself is likely to already be ready before the juju uniter has even downloaded the charm.

Observing this event in Ops

In Ops, you can observe the event like you would any other:

self.framework.observe(
    self.on.<container>_pebble_ready, 
    self._<container>_pebble_ready
)

The PebbleReadyEvent object exposes a workload attribute which returns a pointer to the ops.model.Container instance the event is associated with.

Note that while typically receiving X-pebble-ready means that X is ready to connect, one should always check whether the container can connect before interacting with it, and that check is atomic (i.e. if it returns True now, it might still return False an instant later). Therefore one should always be extra careful when talking to container instances.

See also: ops.model.Container.can_connect.

Last updated 2 months ago.

Help improve this document in the forum.