<a id="reference-backup-integrator-charm-architecture"></a>

# Charm architecture: backup integrator

The backup integrator charm is a subordinate charm that requires backup
on behalf of other charms. Usually this is necessary because the charm
needs backup functionality but either has not implemented the backup
relation itself or cannot implement it.

The design and functionality of the backup integrator are very simple.
Basically, the charm passes the its configuration values
to the backup relation. For the `fileset` configuration, the backup
integrator validates it before passing it to the relation. For the
`run-*` configurations, the backup integrator writes the configuration
content to a local file and passes the filename to the backup relation.

## High-level overview of backup charms deployment

Here’s a typical backup charm suite deployment in the machine charm
environment. It deploys the bacula-server charm as the backup server,
the bacula-fd charm as the backup agent, and the backup-integrator charm
as the backup relation provider.

The backup-integrator charm requests backups from the bacula-fd charm on
behalf of the backup source charm `source`. The bacula-fd charm then
integrates with the bacula-server charm to submit the backup files. The
bacula-server charm is integrated with the PostgreSQL charm for storing
backup metadata and with the s3-integrator charm to use S3 storage as
the destination for backup files.

## Juju events

For this charm, the following Juju events are observed:

1. [backup-relation-changed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-changed),
   [backup-relation-created](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-relation-created):
   Monitors changes and creation of the `backup` relation to update
   relation data when needed.
2. [config-changed](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-config-changed):
   Monitors changes to the backup integrator configuration to update the
   relation data with the latest configuration values.
3. `leader-elected`, `leader-settings-changed`:
   Monitors changes in the charm’s leadership. Since only the leader
   unit can modify application relation data, triggering a relation data
   update when leadership changes ensures the relation is updated
   regardless of leader status during relation establishment.
4. [upgrade-charm](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook-upgrade-charm):
   Triggered when the charm has been upgraded. This ensures that the new
   version of the backup integrator charm can update the relation data
   if needed.

#### NOTE
See more in the Juju docs: [Hook](https://canonical.com/juju/docs/juju-cli/3.6/reference/hook/#hook)

## Charm code overview

The `src/__main__.py` file is the default entry point for the backup
integrator charm; it creates an instance of the `BackupIntegratorCharm`
class (imported from the `charm` module), which inherits from
`ops.CharmBase`. `ops.CharmBase` is the base class from which all charms
are derived, provided
by [Ops](https://ops.readthedocs.io/en/latest/index.html) (the Python
framework for developing charms).

#### NOTE
See more in the Juju docs: [Charm](https://canonical.com/juju/docs/juju-cli/3.6/reference/charm/#charm)

The `__init__` method of `BackupIntegratorCharm` ensures that the charm
observes and handles all events relevant to its operation.

For example, when a configuration is changed via the CLI:

1. The user runs the configuration command:

```bash
juju config backup-integrator fileset=/var/backups
```

1. A `config-changed` event is emitted.
2. In the `__init__` method, the handler for this event is defined as
   follows:

```python
self.framework.observe(self.on.config_changed, self._reconcile)
```

1. The `_reconcile` method, in turn, takes the necessary actions, such
   as waiting for the backup relation(s) and updating the backup
   relation data.