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

# Charm architecture

The osquery charm is a subordinate machine charm. Rather than running a workload
in a container, it installs and manages the `osqueryd` daemon directly on the
principal’s machine as the `c-osquery` snap, managed through `snapd`.

<!-- vale Canonical.013-Spell-out-numbers-below-10 = NO -->
<!-- vale Canonical.500-Repeated-words = NO -->

## Architecture overview

The osquery charm is a machine charm, so it is not containerized: there is no OCI
image and no Pebble services. Both the Juju unit agent (which runs the charm code) and the
`osqueryd` workload it manages run directly on the principal’s host, sharing
the same machine as the principal unit. The charm’s only moving parts are the
charm code, the `osqueryd` snap service, and the files the charm writes
under `/var/snap/c-osquery/common/etc/osquery`.

## Workload

The charm installs the Canonical SecOps fork of osquery from the `c-osquery`
snap, with classic confinement, from the channel set in `snap-channel`. Once
installed, osquery runs as the snap’s `c-osquery.osqueryd` service (the
`snap.c-osquery.osqueryd.service` systemd unit). The daemon
reads its command-line flags from a flagfile on disk; the charm generates this
flagfile from the Juju configuration, so changing a configuration value and
restarting the daemon is how the charm applies changes to the workload.

The agent connects outward over TLS to a centrally managed osquery controller,
which supplies its configuration (query schedules, telemetry rules, and query
tasks) and collects its logs.

## Reconcile pattern

The charm follows a holistic reconcile pattern. A single handler,
`_reconcile`, is observed on every relevant lifecycle event —
`install`, `upgrade-charm`, `start`, `config-changed`,
`secret-changed`, and `update-status`. On each event the handler:

1. Ensures the osquery snap is installed and tracks the configured
   `snap-channel`, installing or refreshing it if it doesn’t.
2. Renders the current Juju configuration into the osquery flagfile and writes
   the file-backed secrets (the enrollment secret and TLS material) to disk.
3. Restarts the `osqueryd` daemon if necessary.
4. Reports the resulting unit status.

Because the handler is idempotent, it’s safe to run on every event. If a required
configuration value is missing or invalid, the charm sets a `blocked` status
with a descriptive message instead of failing the hook. The `stop` event is
handled separately to clean up the workload when the unit is removed.

## Code structure

The charm is organized into focused modules that separate the Juju-facing logic
from the host-facing logic:

| Module           | Responsibility                                                                                                                                                                                                                              |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `src/charm.py`   | The `OsqueryCharm` class. Observes Juju events, drives the reconcile<br/>loop, reads configuration and secrets, and sets unit status.                                                                                                       |
| `src/osquery.py` | Host workload management: installing, refreshing, and removing the<br/>`c-osquery` snap and managing its `c-osquery.osqueryd` service. The module contains no Juju<br/>or Ops imports, so it can be reasoned about and tested in isolation. |
| `src/flags.py`   | Translates Juju configuration values into the osquery flagfile and<br/>determines which required options are unset.                                                                                                                         |
| `src/errors.py`  | The charm’s exception hierarchy, including `OsqueryError`,<br/>`OsqueryConfigError`, and `OsqueryInstallError`.                                                                                                                             |

## Juju integration

As a subordinate, the charm attaches to a principal application through the
`general-info` relation (interface `juju-info`, `container` scope). This
places one osquery unit on each principal machine. See [Relation endpoints](https://canonical.com/juju/docs/osquery-charm/latest/reference/relation-endpoints/index.html.md#reference-relation-endpoints) for details.

<!-- vale Canonical.004-Canonical-product-names = NO -->

For the configuration options that drive the flagfile, see [Configurations](https://canonical.com/juju/docs/osquery-charm/latest/reference/configurations/index.html.md#reference-configurations). For the events the charm observes, see
[Juju events](https://canonical.com/juju/docs/osquery-charm/latest/reference/juju-events/index.html.md#reference-juju-events).

<!-- vale Canonical.004-Canonical-product-names = YES -->
