Event '<container>-pebble-ready'

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

Source: ops.PebbleReadyEvent

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

The pebble-ready event doesn’t guarantee the workload container is still up. For example, if you manually kubectl patch during (for example) install, then you may receive this event after the old workload is down but before the new one is up. For this reason it’s essential, even in pebble-ready event handlers, to catch ConnectionError when using Pebble to make container changes. There is a Container.can_connect() method, but note that this is a point-in-time check, so just because can_connect() returns True doesn’t mean it will still return True moments later. So, code defensively to avoid race conditions.

Moreover, as pod churn can occur at any moment, pebble-ready events can be received throughout any phase of a charm’s lifecycle. Each container could churn multiple times, and they all can do so independently from one another. In short, the charm should make no assumptions at all about the moment in time at which it may or may not receive pebble-ready events, or how often that can occur. The fact that the charm receives a pebble-ready event indicates that the container has just become ready (for the first time, or again, after pod churn), therefore you typically will need to reconfigure your workload from scratch every single time.

This feature of pebble-ready events make them especially suitable for a holistic handling pattern.

Observing this event in ops

When using the ops library, you can observe the event like you would any other:

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

The PebbleReadyEvent class is a subclass of WorkloadEvent, so it exposes a workload attribute which returns the ops.Container instance the event is associated with.