How to add an integration to a charm

For most integrations, you will now want to progress with using the charm library recommended by the charm that you are integrating with. Read the documentation for the other charm on Charmhub and follow the instructions, which will typically involve adding a requirer object in your charm’s __init__ and then observing custom events.

In most cases, the charm library will handle observing the Juju relation events, and your charm will only need to interact with the library’s custom API. Come back to this guide when you are ready to add tests.

See more: Charmhub

If you are developing your own interface - most commonly for charm-specific peer data exchange, then you will need to observe the Juju relation events and add appropriate handlers.

Set up a relation

To do initial setup work when a charm is first integrated with another charm (or, in the case of a peer relation, when a charm is first deployed) your charm will need to observe the relation-created event. For example, a charm providing a database relation might need to create the database and credentials, so that the requirer charm can use the database. In the src/charm.py file, in the __init__ function of your charm, set up relation-created event observers for the relevant relations and pair those with an event handler.

The name of the event to observe is combined with the name of the endpoint. With an endpoint named “db”, to observe relation-created, our code would look like:

framework.observe(self.on.db_relation_created, self._on_db_relation_created)

Now, in the body of the charm definition, define the event handler. In this example, if we are the leader unit, then we create a database and pass the credentials to use it to the charm on the other side via the relation data:

def _on_db_relation_created(self, event: ops.RelationCreatedEvent):
    if not self.unit.is_leader():
        return
    credentials = self.create_database(event.app.name)
    event.relation.data[event.app].update(credentials)

The event object that is passed to the handler has a relation property, which contains an ops.Relation object. Your charm uses this object to find out about the relation (such as which units are included, in the .units attribute, or whether the relation is broken, in the .active attribute) and to get and set data in the relation databag.

See more: ops.RelationCreatedEvent

To do additional setup work when each unit joins the relation (both when the charms are first integrated and when additional units are added to the charm), your charm will need to observe the relation-joined event. In the src/charm.py file, in the __init__ function of your charm, set up relation-joined event observers for the relevant relations and pair those with an event handler. For example:

framework.observe(self.on.smtp_relation_joined, self._on_smtp_relation_joined)

Now, in the body of the charm definition, define the event handler. In this example, a “smtp_credentials” key is set in the unit data with the ID of a secret:

def _on_smtp_relation_joined(self, event: ops.RelationJoinedEvent):
    smtp_credentials_secret_id = self.create_smtp_user(event.unit.name)
    event.relation.data[event.unit]["smtp_credentials"] = smtp_credentials_secret_id

See more: ops.RelationJoinedEvent

Exchange data with other units

To use data received through the relation, have your charm observe the relation-changed event. In the src/charm.py file, in the __init__ function of your charm, set up relation-changed event observers for each of the defined relations. For example:

framework.observe(self.on.replicas_relation_changed, self._update_configuration)

See more: [ops.RelationChangedEvent](Event '<relation name>-relation-changed'), Juju | Relation (integration)

Most of the time, you should use the same holistic handler as when receiving other data, such as secret-changed and config-changed. To access the relation(s) in your holistic handler, use the ops.Model.get_relation method or ops.Model.relations attribute.

See also: Juju | Holistic vs Delta Charms

If your change will have at most one relation on the endpoint, to get the Relation object use Model.get_relation; for example:

rel = self.model.get_relation("db")
if not rel:
    # Handle the case where the relation does not yet exist.

If your charm may have multiple relations on the endpoint, to get the relation objects use Model.relations rather than Model.get_relation with the relation ID; for example:

for rel in self.model.relations.get('smtp', ()):
    # Do something with the relation object.

Once your charm has the relation object, it can be used in exactly the same way as when received from an event.

Now, in the body of the charm definition, define the holistic event handler. In this example, we check if the relation exists yet, and for a provided secret using the ID provided in the relation data, and if we have both of those then we push that into a workload configuration:

def _update_configuration(self, _: ops.Eventbase):
    # This handles secret-changed and relation-changed.
    db_relation = self.model.get_relation('db')
    if not db_relation:
        # We’re not integrated with the database charm yet.
        return
    secret_id = db_relation.data[self.model.app]['credentials']
    if not secret_id:
        # The credentials haven’t been added to the relation by the remote app yet.
        return
    secret_contents = self.model.get_secret(id=secret_id).get_contents(refresh=True)
    self.push_configuration(
        username=secret['username'],
        password=secret['password'],
    )

Exchange data across the various relations

To add data to the relation databag, use the .data attribute much as you would a dictionary, after selecting whether to write to the app databag (leaders only) or unit databag. For example, to copy a value from the charm config to the relation data:

def _on_config_changed(self, event: ops.ConfigChangedEvent):
    if relation := self.model.get_relation('ingress'):
        relation.data[self.app]["domain"] = self.model.config["domain"]

To read data from the relation databag, again use the .data attribute, selecting the appropriate databag, and then using it as if it were a regular dictionary.

The charm can inspect the contents of the remote unit databags:

def _on_database_relation_changed(self, event: ops.RelationChangedEvent):
    remote_units_databags = {
        event.relation.data[unit] for unit in event.relation.units if unit.app is not self.app
    }

Or the peer unit databags:

def _on_database_relation_changed(self, e: ops.RelationChangedEvent):
    peer_units_databags = {
        event.relation.data[unit] for unit in event.relation.units if unit.app is self.app
    }

Or the remote leader databag:

def _on_database_relation_changed(self, event: ops.RelationChangedEvent):
    remote_app_databag = event.relation.data[relation.app]

Or the local application databag:

def _on_database_relation_changed(self, event: ops.RelationChangedEvent):
    local_app_databag = event.relation.data[self.app]

Or the local unit databag:

def _on_database_relation_changed(self, event: ops.RelationChangedEvent):
    local_unit_databag = event.relation.data[self.unit]

If the charm does not have permission to do an operation (e.g. because it is not the leader unit), an exception will be raised.

Clean up when a relation is removed

To do clean-up work when a unit in the relation is removed (for example, removing per-unit credentials), have your charm observe the relation-departed event. In the src/charm.py file, in the __init__ function of your charm, set up relation-departed event observers for the relevant relations and pair those with an event handler. For example:

framework.observe(self.on.smtp_relation_departed, self._on_smtp_relation_departed)

Now, in the body of the charm definition, define the event handler. For example:

def _on_smtp_relation_departed(self, event: ops.RelationDepartedEvent):
    if self.unit != event.departing_unit:
        self.remove_smtp_user(event.unit.name)

See more: ops.RelationDepartedEvent

To clean up after a relation is entirely removed, have your charm observe the relation-broken event. In the src/charm.py file, in the __init__ function of your charm, set up relation-broken events for the relevant relations and pair those with an event handler. For example:

framework.observe(self.on.db_relation_broken, self._on_db_relation_broken)

Now, in the body of the charm definition, define the event handler. For example:

def _on_db_relation_broken(self, event: ops.RelationBrokenEvent):
    if not self.is_leader():
        return
    self.drop_database(event.app.name)

See more: ops.RelationBrokenEvent