Skip to content

Dynamic groups

A dynamic group's membership is defined by a label-selector expression over agent_description keys. The reconciler re-evaluates membership periodically; matching agents are added, non-matching are removed.

When to use a dynamic group

  • The set of agents that should run a given config is determined by a label (environment=prod, region=eu-central-1, service.name=checkout).
  • Agents come and go (autoscaling, ephemeral workloads).
  • You do not want to manually add new agents to a static group.

Creating a dynamic group

Groups → New group, mode Dynamic:

  • Selector: an expression. Examples:
  • service.name = "checkout"
  • region in ("eu-central-1", "eu-west-1")
  • service.name matches "checkout-.*"
  • service.name = "checkout" and environment = "prod"
  • not (capability matches "experimental-.*")

The full grammar is on Custom policy DSL — selectors share the same expression language.

Autocomplete

The selector field auto-completes label keys from the agent_description corpus you have already received. Type service. to see service.name, service.namespace, service.version, etc.

Reconciliation cadence

Dynamic groups are reconciled by a background service on the leader instance. Default cadence: every 30 seconds. The reconciler:

  1. Loads the selector AST.
  2. Loads candidate agents (filtered by tenant and life-cycle).
  3. Evaluates the selector against each.
  4. Computes the diff between current membership and selector match.
  5. Applies the diff atomically.

For 10 000 agents, a full reconciliation completes in well under 30 seconds. The expression engine fails closed: if a selector throws (for example an attempted regex against a missing label), affected agents are not added — the agent remains in its current group.

Single-group invariant

A dynamic group still respects the single-group invariant: an agent that newly matches selector A is moved from its current group, not duplicated. If multiple dynamic groups would match the same agent, the priority field on the group breaks the tie.

Force rebuild

Group detail → Force rebuild runs the reconciler synchronously for this one group and shows a before/after count. Use it when you have just edited the selector and want to see the effect immediately rather than waiting up to 30 seconds.

Diagnostics

If a selector seems wrong, the Match preview panel runs the selector against the current corpus and shows a small sample of matched and unmatched agents with the labels that drove the decision.

Performance

Dynamic group selectors compile once into an AST and re-use it across agents. Containment-style selectors translate to JSONB GIN-index queries (@> operator) — the migration Phase11_JsonbIndexes introduced these indexes for exactly this case.

For very large fleets, prefer selectors that hit indexed keys (service.name, region, environment) over full-text regex over arbitrary keys.