System architecture

This guide describes the main components and responsibilities of the Generic Exporter operator.

At a high level, the charm:

• Manages the lifecycle of one exporter snap per unit
• Validates and applies charm configuration to the snap
• Exposes a configurable HTTP metrics endpoint (port and path)
• Integrates with COS via Grafana Agent using the metrics-endpoint relation
• Optionally consumes an alerts resource and forwards the contained rules to COS

Core components

Snap Manager

The charm uses charmlibs.snap to install, refresh, configure, and remove the exporter snap.

Responsibilities include:

• Ensuring the requested snap is present using SnapCache and snap.ensure
• Installing from either a channel or a revision (but not both simultaneously)
• Applying configuration via snap.set/snap.unset based on the snap-config charm option
• Managing snap removal during charm teardown

Snap Singleton

Ensures that the charm application can be safely scaled up and down without affecting peers:

• Tracks snap registrations by units in a lock file under /opt/singleton_snaps directory.
• Manages exclusive access to singleton snaps and configuration files using file-based locks.

Exporter Configurator

Charm configuration is validated and translated into a concrete snap configuration:

• Port and path: the charm exposes metrics on http://<unit-address>:<port>/<metrics-path>.
• Snap configuration: arbitrary exporter settings can be provided as a JSON blob in snap-config, which is parsed and passed to snap.set().
• Snap plugs: the snap-plugs option allows automatically connecting required interfaces after installation (for example, network access or system metrics).

Invalid configuration (for example, malformed JSON or conflicting snap-channel/snap-revision) is detected early and results in a Blocked status with a clear message.

COS integration layer

The Generic Exporter operator uses the COSAgentProvider abstraction from the cos_agent library to expose metrics and alert rules over the metrics-endpoint relation.

In effect, the charm:

• Registers a metrics endpoint (path and port) for Grafana Agent to scrape.
• Points Grafana Agent to an on-disk directory (for example, /run/<app>-<unit-id>/alerts.yaml) containing alert rule files.
• Triggers refreshes of scrape configuration and rules on relevant events (such as config-changed). Grafana Agent is responsible for forwarding telemetry to COS Lite and enriching metrics and alerts with Juju topology labels.

Resource Manager

The charm optionally consumes an alerts resource:

• When attached, the resource file (YAML) is fetched via self.model.resources.fetch("alerts").
• The content is parsed and written into a rules file, typically alerts.rules, under a dedicated directory like /run/<app>-<unit-id>/alerts.yaml.
• Missing resources are handled gracefully and logged at the warning level.

The design explicitly avoids shipping dashboards or snap files as resources:

• Dashboards are expected to be managed through COS and Grafana directly.
• Installing local snap files using --dangerous was rejected for security and supportability reasons.

Subordinate model

The Generic Exporter operator is implemented as a subordinate machine charm:

• It relates to any principal via juju-info (or an equivalent relation) and is co-located with the principal units.
• Operators can deploy multiple applications of the Generic Exporter operator (for example, one per exporter type) on the same machine.

Versioning

The charm’s workload version is aligned with the installed exporter snap version:

• The charm queries snap info for the exporter and sets workload_version accordingly (for example, node-exporter/1.6).
• The snap is pinned to the selected channel or revision; upgrading the exporter is performed explicitly by changing the charm configuration.

Limitations (design intent)

The current design assumes:

1. Machine-only: No Kubernetes support.
2. One exporter per unit: The charm does not orchestrate multiple exporters within the same subordinate.
3. Snap auto-start: The exporter snap is expected to start its service automatically upon installation and expose the metrics via an HTTP endpoint.
4. Config-driven updates: Snap updates are controlled via charm configuration rather than automatic refresh.
5. Port configuration: Exporters should allow their listening port to be configured to avoid conflicts when multiple exporters are deployed on the same machine.