Core Concepts¶

The vocabulary Ampora uses across the UI, the REST API and these docs. If a phrase here is foreign, this is the page to skim first.

Agent¶

A long-lived process that runs the OpenTelemetry Collector binary (or any other OpAMP-capable agent) and connects to Ampora. An agent is identified by certificate fingerprint — not by hostname, not by instance_uid. Every agent stores:

• Identity — fingerprint, agent type, version, OS/platform.
• Description — labels reported via OpAMP AgentDescription (service.name, host.name, k8s.namespace.name, …).
• Capabilities — the OpAMP capability bitfield it advertised.
• Health — overall + per-component.
• Effective config — the YAML it is actually running, byte-for-byte as the agent reported it.
• Last seen — UTC timestamp of the last received frame.

Configuration & Configuration Version¶

A Configuration is a named container for a sequence of versions, e.g. edge-collectors-prod. A Configuration Version is the actual YAML at a point in time, with a content hash, status (Draft / Published / Archived), and an immutability flag once published.

Two configurations matter operationally:

Drift is the distance between those two — see Diffs.

Pipeline¶

A pipeline is one of traces, metrics, logs, or profiles inside a Collector config. Ampora's visualizer renders each pipeline as a swimlane showing receivers → processors → connectors → exporters. A single config can have many pipelines per signal.

Group¶

A bag of agents to target with a rollout. Groups come in two flavours:

• Static — explicit membership. Operator adds and removes agents.
• Dynamic — defined by a label-selector expression over AgentDescription keys. The reconciler re-evaluates membership every few seconds. See Dynamic groups.

Each agent belongs to exactly one group at a time (single-group invariant, ADR-025) — moving an agent to another group is a one-click action. This invariant keeps auto-apply unambiguous: there is always exactly one configuration that the agent should be running.

Rollout¶

A rollout binds a published Configuration Version to a target Group and a strategy. The lifecycle:

stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress: start
    InProgress --> Paused: gate triggered / operator pause
    Paused --> InProgress: resume
    InProgress --> Completed: all batches succeeded
    InProgress --> Failed: aborted by operator or gate
    Failed --> RolledBack: rollback to last stable
    Completed --> [*]
    RolledBack --> [*]

Strategies:

• Batch — fixed N agents per batch, manual advance.
• Percentage — 5 % → 25 % → 50 % → 100 %, manual or scheduled.
• Canary step-up — percentage with time-based dwell between steps.

Health Gate¶

A rule that auto-pauses a rollout when something looks bad. Defaults:

All four are configurable per rollout. See Reference: Health gates.

Capability¶

The OpAMP-defined bitfield an agent advertises on connect. Ampora uses it to gate every server-to-agent push. Some capabilities matter so much that we list them here:

Bootstrap Token¶

A short-lived, single-use credential that authenticates an agent's first connection only. After the first connection the agent's identity is its mTLS certificate. Tokens are issued from the Tokens UI, optionally pooled (ADR-040) for high-throughput auto-onboarding flows.

Tenant¶

The unit of isolation. In single-tenant deployments there is exactly one tenant; in multi-tenant deployments (ADR-015, ADR-036) every row carries a TenantId and PostgreSQL row-level security enforces isolation at the database layer.

Identity¶

A bootstrap-bound record that pairs an issued certificate to an agent. Identity != agent: an identity exists from token-issuance until the agent binds to it on first connect. After that the agent owns the identity until it is revoked (which also invalidates the cert via CRL/OCSP).

Federation¶

The relationship between two Ampora servers that mutually trust each other to expose a read-only view of their fleets. Federation is manual, bilateral, and authenticated by mTLS + a shared secret, not by joining a control plane. See Federation tutorial and ADR-050.

GitOps source¶

A registered Git repo + branch + path glob that Ampora polls every PollIntervalSeconds. Files matching the glob become Configuration drafts on every commit that changes their content. Configurations sourced from Git cannot be edited from the UI — Git is the source of truth. See GitOps tutorial and ADR-049.

Policy¶

A rule the rollout engine evaluates before pushing a config to an agent. Built-in policies (no destructive exporter swap, no removal of an exporter that has data in flight) ship out of the box. Custom policies are written in a small expression DSL and require a four-eyes approval to publish. See Policies and ADR-033.

Audit Event¶

An immutable record of who did what, when, against which entity, with what before/after values. Every login, configuration change, rollout action, group edit, policy change, certificate operation produces one. Audit events are kept hot for the configured retention (default 90 days), then moved to the archive table, then purged.