131 lines
4.3 KiB
ReStructuredText
131 lines
4.3 KiB
ReStructuredText
=============================
|
|
How-To Write a pebble handler
|
|
=============================
|
|
|
|
A pebble handler sits between a charm and a container it manages. A pebble
|
|
handler presents the charm with a consistent method of interaction with
|
|
the container. For example the charm can query the handler to check config
|
|
has been rendered and services started. It can call the `execute` method
|
|
to run commands in the container or call `write_config` to render the
|
|
defined files into the container.
|
|
|
|
Common Pebble handler changes
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
ASO provides a pebble handler base classes which provide the starting point
|
|
for writing a new handler. If the container runs a service then the
|
|
`ServicePebbleHandler` should be used. If the container does not provide a
|
|
service (perhaps it's just an environment for executing commands that affect
|
|
other containers) then `PebbleHandler` should be used.
|
|
|
|
.. code:: python
|
|
|
|
import ops_sunbeam.container_handlers as sunbeam_chandlers
|
|
|
|
class MyServicePebbleHandler(sunbeam_chandlers.ServicePebbleHandler):
|
|
"""Manage MyService Container."""
|
|
|
|
The handlers can create directories in the container once the pebble is
|
|
available.
|
|
|
|
.. code:: python
|
|
|
|
@property
|
|
def directories(self) -> List[sunbeam_chandlers.ContainerDir]:
|
|
"""Directories to create in container."""
|
|
return [
|
|
sunbeam_chandlers.ContainerDir(
|
|
'/var/log/my-service',
|
|
'root',
|
|
'root')]
|
|
|
|
In addition to directories the handler can list configuration files which need
|
|
to be rendered into the container. These will be rendered as templates using
|
|
all available contexts.
|
|
|
|
.. code:: python
|
|
|
|
def default_container_configs(
|
|
self
|
|
) -> List[sunbeam_core.ContainerConfigFile]:
|
|
"""Files to render into containers."""
|
|
return [
|
|
sunbeam_core.ContainerConfigFile(
|
|
'/etc/mysvc/mvsvc.conf',
|
|
'root',
|
|
'root')]
|
|
|
|
If a service should be running in the container the handler specifies the
|
|
layer describing the service that will be passed to pebble.
|
|
|
|
.. code:: python
|
|
|
|
def get_layer(self) -> dict:
|
|
"""Pebble configuration layer for MyService service."""
|
|
return {
|
|
"summary": "My service",
|
|
"description": "Pebble config layer for MyService",
|
|
"services": {
|
|
'my_svc': {
|
|
"override": "replace",
|
|
"summary": "My Super Service",
|
|
"command": "/usr/bin/my-svc",
|
|
"startup": "disabled",
|
|
},
|
|
},
|
|
}
|
|
|
|
|
|
Advanced Pebble handler changes
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
By default the pebble handler is the observer of pebble events. If this
|
|
behaviour needs to be altered then `setup_pebble_handler` method can be
|
|
changed.
|
|
|
|
.. code:: python
|
|
|
|
def setup_pebble_handler(self) -> None:
|
|
"""Configure handler for pebble ready event."""
|
|
pass
|
|
|
|
Or perhaps it is ok for the pebble handler to observe the event but a
|
|
different reaction is required. In this case the method associated
|
|
with the event can be overridden.
|
|
|
|
.. code:: python
|
|
|
|
def _on_service_pebble_ready(
|
|
self, event: ops.charm.PebbleReadyEvent
|
|
) -> None:
|
|
"""Handle pebble ready event."""
|
|
container = event.workload
|
|
container.add_layer(self.service_name, self.get_layer(), combine=True)
|
|
self.execute(["run", "special", "command"])
|
|
logger.debug(f"Plan: {container.get_plan()}")
|
|
self.ready = True
|
|
self.charm.configure_charm(event)
|
|
|
|
Configuring Charm to use custom pebble handler
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The charms `get_pebble_handlers` method dictates which pebble handlers are used.
|
|
|
|
.. code:: python
|
|
|
|
class MyCharmCharm(NeutronOperatorCharm):
|
|
|
|
def get_pebble_handlers(self) -> List[sunbeam_chandlers.PebbleHandler]:
|
|
"""Pebble handlers for the service."""
|
|
return [
|
|
MyServicePebbleHandler(
|
|
self,
|
|
'my-server-container',
|
|
self.service_name,
|
|
self.container_configs,
|
|
self.template_dir,
|
|
self.openstack_release,
|
|
self.configure_charm,
|
|
)
|
|
]
|