Structuring your channels

The first real decision in Ampbase isn't a config — it's how many channels you create and what goes in each. Get this right and rollouts, defaults, and environment promotion all fall out naturally. Get it wrong and you'll fight the "what does a new agent get?" question forever.

A channel is a grouping of agents that share one deployed config and one rollout lifecycle.

This guide is the litmus test for what belongs in a channel and what doesn't.

Two axes, not one

Almost every setup is really a grid of two independent things:

                  clickhouse           vault
   signal      │  (config)         │  (config)      │
   staging     │  (config)         │  (config)      │
   prod        │  (config)         │  (config)      │
              └─ ROLE ──────────────────────────────
  ENVIRONMENT

• Role — what job the agent does and where its telemetry goes. A ClickHouse pipeline and a Vault pipeline are different roles. This is permanent: the two never share config lineage and you never route an agent from one to the other.
• Lifecycle — where an agent sits in your rollout. Environment (signal, staging, prod), region, canary cohort. This is transient: it's the same config lineage moving through stages.

The mistake that creates friction is trying to push both axes through the channel boundary. You only have one grouping level below the org, so pick the right axis for it.

The rule

Structural, permanent distinctions → separate channels. Lifecycle, rollout distinctions → agent attributes + feature flags within a channel.

• Role → channel. One channel per pipeline/destination.
• Environment, region, canary → attribute on the agent (set under agent.attributes in supervisor.yaml), routed by a flag.

A channel has exactly one deployed config — the version any agent receives if no flag matches it. Flags layer on top to send specific agents somewhere else. That single deployed config is your default, and it's the whole reason the role axis belongs on the channel.

Build components are not an axis you model. A component — exporter/kafka on a collector, output/kafka on a Fluent Bit — is a fact about the build an agent is running, reported by the agent itself. It isn't something you set under agent.attributes, and "some of my hosts run a custom build" is not a reason to split a channel. Ampbase reads each agent's build inventory and each config version's requirements and routes around the mismatch on its own: a flag variant whose target needs a component an agent's build lacks is simply withheld from that agent, which keeps running the channel default. Model the role, let the gate handle the builds — see Feature flags, under Build eligibility.

The "what's my default?" test

Every channel answers one question: "A brand-new agent connects here with no special targeting — what config should it get?" There must be exactly one good answer.

• If two configs have different right answers, they belong in different channels. A Vault agent must never fall back to the ClickHouse pipeline because a label was missing — that's a silent misroute, and it's the model telling you these are two channels.
• If one config is a sensible fallback for the other (stable vs. canary of the same pipeline), they belong in one channel, and a flag chooses between them.

When you feel unsure where a config goes, run this test. The discomfort of "I can't pick a default" means you're looking at two channels.

Worked example

Say you run two pipelines for your own telemetry, across three environments.

Roles → two channels. clickhouse and vault are separate channels. Neither is a sane default for the other, so they can't share.

Environments → one attribute, promoted by a flag. signal, staging, and prod are not channels. They're an env attribute every agent reports. Promotion is a flag rollout:

channel: clickhouse
  deployed config = otelcol-clickhouse  (the stable default — what prod runs)

  flag: clickhouse-rollout
    variant "stable":  weight 100  →  otelcol-clickhouse  (current)
    variant "next":    targeted    →  otelcol-clickhouse  v-NEW
       rule: { "==": [{ "var": "env" }, "signal"] }

Roll v-NEW to env=signal, watch it, then widen the rule to staging, then prod. When you're confident everywhere, deploy v-NEW as the channel's new default and retire the flag. The default always stays the safe config, so an agent that matches nothing fails safe — it keeps running stable.

Notice this only works because both variants are the same role. That's exactly the case flags are built for: gradual rollout of one lineage, not static dispatch between two unrelated pipelines.

Why not one channel per environment?

It's the tempting layout, and it's the one that bites:

• It forces unrelated roles to share a channel (your prod channel holds both ClickHouse and Vault configs), and now there's no sensible default — back to the silent-misroute problem.
• Promotion becomes copy-paste. Configs live inside a channel, so moving a tested config signal → staging → prod means copying it between three channels by hand, with no shared lineage or audit trail tying them together.

One channel per env × role (six channels: signal-clickhouse, prod-vault, …) avoids the bad-default trap and is a legitimate fallback — every channel has a clean default. But it sprawls, and you still promote across environments by hand. Prefer role channel + env attribute so promotion is a flag flip, not a copy.

Environments now, orgs later

During a trial you get one organization, so environments have to be attributes — which is exactly the model above, and it's the right call regardless.

When you upgrade and can provision multiple orgs, lift the environment axis up to the org, where it gets true isolation — each org is its own object-storage bucket and its own database partition, so prod telemetry stops sharing storage with signal:

The channel stays = role the whole way through. The migration is just retiring the env attribute as it gets promoted to org. Modeling environments as channels would instead be a dead-end you'd have to unwind.

Rules of thumb

• One channel per role / destination. If telemetry goes to a different place or does a different job, it's a different channel.
• Environment, region, and canary are attributes, not channels. Route them with feature flags.
• Every channel's "default" must have one good answer. If you can't pick one, you're holding two channels.
• Keep the deployed default = your stable config. Roll new versions forward to lower environments first; unmatched agents always land on something safe.

Where to go next

• Configurations — authoring, versioning, and deploys within a channel.
• Feature flags — the targeting and weighting that drive environment promotion.
• How Ampbase works — the org / channel / agent mental model.