Push configuration changes across your fleet with overlays
Configuration overlays are in public beta.
A configuration overlay applies a set of setting changes on top of the configuration your groups already run. Define the change once, select the groups it targets, and activate it. Your base configurations stay as they are, so you can lift the change back off by deactivating the overlay instead of editing every group back.
Why use an overlay
Changing one setting across twenty groups means twenty edits, twenty reviews, and twenty chances to leave one behind. An overlay turns that into one object you can reason about.
- Change once: one overlay covers every group you target.
- Preview: the editor compares the overlay against a chosen group and shows the resulting configuration.
- Undo: deactivating an overlay returns its targets to their base configuration.
- History: overlays are versioned, so you can compare two versions and see exactly which targets and settings differ.
What you need
- A Kubernetes agent fleet reporting to Fleet Management, organized into configuration groups. Overlays support Kubernetes only for now.
- Permission to manage remote configurations. See Fleet Management permissions.
- A configuration group in an active state. A group becomes active once at least one agent has applied its configuration; this is not a manual step. Activating a configuration by hand leaves the group Waiting for agents, and it cannot be targeted until an agent reports.
Create an overlay
-
Go to Fleet Management, then Configurations, then Configuration overlays.
-
Select New overlay.
-
Under Details, enter a name and an optional description.
-
Under Type, select Kubernetes. Overlays currently support Kubernetes agent fleets, with guided presets for common configurations. Custom is marked Coming soon and cannot be selected yet.
Type cannot be changed after you create the overlay.
-
Under Target, select the configuration groups this overlay applies to, then select Add. You can only target Kubernetes configuration groups. Who will be affected by this overlay lists what you have added so far, and stays empty until you select a group and then select Add.
-
Under Configuration, select the fields to override on those targets and set their values.
-
Check the preview panel, then select Create.
What an overlay can change
A Kubernetes overlay authors the same observability settings a configuration group exposes. Select only the fields you want to override; everything you leave alone keeps the value the base configuration gave it.
| Block | Fields you can override |
|---|---|
| APM & Tracing | Environment, Transactions, eBPF for APM, Span metrics, Sampling, Profiling |
| Logs & Events | Logs, Kubernetes events |
| Metrics | Host metrics, Kubelet metrics, Cluster metrics, Additional Kubernetes metrics, Collector metrics, StatsD |
| Additional | Reduce attributes, Resource catalog / Infra explorer |
Preview before you activate
The editor's preview panel answers two different questions, so use both.
Summary of changes compares the overlay against one target group and lists the settings that differ, with a count of how many will change. Use it to confirm you are changing what you meant to change, and nothing else.
Live preview shows what that group ends up with: its base configuration plus this overlay applied. Use it to sanity-check the final result rather than the delta. Pick which agent to preview against, then read the result either as Config navigator, a diagram of the resulting pipeline, or as YAML config, the file itself.
Both need a target group selected before they show anything.
Activate, deactivate, and archive
Overlays are inert until you activate them.
Applying an overlay creates a new version of the target's configuration, and every activate, deactivate, and edit creates another one. A group with overlays on it accumulates versions, which is expected rather than a sign that something went wrong.
Reactivating a configuration re-applies the overlays that target it. This happens automatically, with nothing to set up.
| Action | What it does |
|---|---|
| Activate | Applies the overlay to its target groups. |
| Deactivate | Lifts the overlay off its targets, which return to their base configuration. |
| Edit | Changes the overlay, creating a new version. |
| Duplicate | Copies the overlay so you can adapt it without touching the original. |
| View difference | Compares two versions and reports which targets and settings differ. Needs at least two versions. |
View difference opens a version comparison. Pick the two versions in Compare from and Compare to, and the panel reports how many of the settings differ, for example 0 of 14 settings differ. Turn on Show only differences to hide the settings that match. The header also carries the current version and when it was last activated.
| Archive | Hides an overlay, or a single version, from the list. You can still find archived items using filters. Archiving cannot be undone. |
A configuration group can have more than one active overlay. Overlays are merged in the order they appear in the list, from top to bottom, so an overlay lower in the list is applied last. If two active overlays change the same setting, the value from the lower overlay is the one that ends up in the configuration.
Deactivate before archiving. An overlay with an active version, or a version that is itself active, cannot be archived. Archiving the last remaining version of an overlay archives the overlay itself.
Editing a targeted configuration unlinks it
Editing a configuration group that an overlay targets breaks the link between them. When you activate the edited version, that group stops being maintained by the overlay, and re-linking it is a manual step.
The save dialog warns you before this happens and names the overlays the group is currently getting its active version from.
Order overlays in the list
Each overlay in the list carries a count of its versions, and Expand all and Collapse all open or close every overlay at once. The list records who created each version and when.
Drag a row to move an overlay up or down. The order is not cosmetic: it is the merge order. When two active overlays change the same setting on the same group, the one lower in the list is applied last and its value wins. Configuration management describes the same model for configuration groups.
Because reordering changes what gets delivered, the order is stored with the overlay and applies to everyone in your organization. It is not a personal view preference.
Agent version requirements
An overlay can depend on settings that only newer agents understand. When a target is behind the version an overlay needs, the editor blocks the save and offers to upgrade those targets, telling you which version they are on and which they need. Activation is unaffected: the block applies when you save the overlay.
Upgrading moves the targets to the required version, and agents pick it up as the change rolls out. If you skip the upgrade, the target stays where it is and the overlay cannot be saved against it.
Offline agents
An agent that is offline when you activate an overlay is not skipped. When it reconnects, it receives the configuration that is active at that moment, including any overlays that apply to its group. Nothing is queued per overlay, so an agent that misses several changes comes back to the current state rather than replaying each one.
Best practices
- One overlay, one concern: a narrow overlay is easier to reason about, and easier to deactivate when it turns out to be the cause.
- Preview against your least typical group, not your most typical one. The group where an override behaves unexpectedly is the one worth checking.
- Prefer deactivating over editing when you need to undo something quickly. Deactivation is one action and needs no review of what the previous values were.
- Leave the base configuration as the baseline: put the exception in the overlay, so the base stays readable as the thing most agents run.
Limitations
- Kubernetes only. The Custom type is marked Coming soon and cannot be selected.
- Several overlays can be active on the same configuration group. They are merged in list order, and the lower one wins.
- Type is fixed once the overlay is created.
- Only groups in an active state, with at least one agent reporting, can be targeted.
- An overlay cannot be archived while it, or one of its versions, is active.