Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Ffleet-management%2Fconfiguration-deep-dive.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Ffleet-management%2Fconfiguration-deep-dive.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Configuration deep dive

Configurations in Fleet Management lets you centrally manage Collector configurations across your entire fleet, regardless of how they are deployed. It provides a single, consistent control point for updates and reduces the chance of configuration drift.

For predictable behavior, use a remote-only configuration flow.

* **Remote-only (recommended):** Avoids conflicts between local and remote configurations and ensures the Fleet Manager defines the source of truth.
* **Local-only: This read-only, optional mode** lets you monitor configuration attributes without the ability to push updates.

## Configuration modes[​](#configuration-modes "Direct link to Configuration modes")

The configuration mode determines how the Fleet Manager delivers configuration updates to your Collectors.

### Remote-only (recommended)[​](#remote-only-recommended "Direct link to Remote-only (recommended)")

Use this mode when you want the Fleet Manager to fully control Collector configuration remotely.

* **Activation:** Enable the Supervisor preset (`presets.fleetManagement.supervisor.enabled: true`) in the integration chart.
* **Behavior:** The Collector starts with a minimal configuration that contains only what it needs to run and connect to the Supervisor. All configuration beyond that comes from Fleet Manager—creating a single, authoritative configuration source.

### Local-only (read-only)[​](#local-only-read-only "Direct link to Local-only (read-only)")

Use this mode when you do not need remote configuration.

* **Activation:** The Supervisor preset is disabled.
* **Behavior:** Collectors report their attributes (e.g., OS, Kubernetes cluster name, etc.) and effective configuration to Fleet Manager, but Fleet Manager cannot update their configuration.

### Configuration merge precedence[​](#configuration-merge-precedence "Direct link to Configuration merge precedence")

The Supervisor merges configuration sources into the final configuration file used by the Collector. Merge order is:

| **Priority**    | **Configuration source**                 | **Description**                                                                                                  |
| --------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Lowest**      | Own telemetry configuration (internal)   | Supervisor-generated settings used for the Collector's self-telemetry.                                           |
| **Low–Medium**  | User-provided local configuration files  | Local files supplied by the user.                                                                                |
| **Medium–High** | OpAMP extension configuration (internal) | Supervisor-generated configuration required for OpAMP communication (for example, ports, endpoints, attributes). |
| **Highest**     | Remote configuration                     | Configuration delivered by the Fleet Manager over OpAMP.                                                         |

**Connection protection:** Settings required for Supervisor–Collector communication override anything that might break connectivity.

For more details on how the configuration is applied, refer to the [Fleet Management architecture](https://docs-docusaurus.kinsta.page/user-guides/fleet-management/architecture/.md) documentation.

### Configuration deactivation[​](#configuration-deactivation "Direct link to Configuration deactivation")

When you deactivate a configuration, Fleet Manager removes it from any agents that previously applied it. On their next check-in, those agents receive a no-operation (noop) configuration and revert to the minimal configuration required for Supervisor communication. The Collector stays running but no longer applies the deactivated configuration.

## Configuration types[​](#configuration-types "Direct link to Configuration types")

### Minimal Collector configuration[​](#minimal-collector-configuration "Direct link to Minimal Collector configuration")

When the Supervisor preset is enabled, Fleet Manager deploys a minimal configuration that lets the Collector start and connect to the Supervisor. The Supervisor then adds required internal settings—such as agent attributes, endpoints, and encoding—to ensure reliable startup.

### Effective configuration (UI view)[​](#effective-configuration-ui-view "Direct link to Effective configuration (UI view)")

The effective configuration is the configuration currently loaded and used by the OpenTelemetry Collector.

When you view the configuration through the Fleet Manager UI:

* The view shows the effective configuration, which is the result of the Supervisor successfully merging the remote, internal, and any local configurations.
* The effective configuration may differ from the YAML you provided due to required Supervisor modifications, local files or default configuration values injected by the Collector at runtime.

## Configuration groups, families, and versioning[​](#configuration-groups-families-and-versioning "Direct link to Configuration groups, families, and versioning")

Configuration groups contain multiple versions of a configuration. A configuration may be a single YAML file or a set of interdependent files, which form a configuration family. Families exist when changes must be coordinated—for example, enabling tail sampling may require changes to both gateway and agent configurations.

Any update to a configuration in the family creates a new family version, preserving a clear audit trail.

If you activate a configuration group with no active version, Fleet Manager automatically activates the most recent version.

## Archiving[​](#archiving "Direct link to Archiving")

When a configuration group or family is no longer needed, you can archive it to remove it from the active workspace. Archiving is a soft-delete operation—archived items are hidden from the default list view but preserved in full for audit and compliance purposes.

A configuration family must be deactivated before it can be archived. To archive an entire group, all families in the group must be inactive. Archiving a group cascades to all of its families. Archived configurations cannot be reactivated, but they can be cloned to create new configurations from the archived YAML and agent selector.

For step-by-step instructions, see [Archive configurations](https://docs-docusaurus.kinsta.page/user-guides/fleet-management/configuration-management/.md#archive-configurations).

## Handling failure scenarios and rollback[​](#handling-failure-scenarios-and-rollback "Direct link to Handling failure scenarios and rollback")

The Supervisor prevents configuration failures from interrupting monitoring.

| **Scenario**              | **Behavior**                                                                                                  | **Rollback and safety**                                                                                             |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Application failure**   | The new configuration causes the Collector to crash or become unhealthy (e.g., due to invalid configuration). | The Supervisor detects the failure and automatically reverts to the previous working configuration.                 |
| **Telemetry downtime**    | The Collector is fully stopped before the new version starts.                                                 | This restart introduces a brief interruption in data collection and delivery.                                       |
| **Communication failure** | Fleet Manager misses a status message (such as after a restart).                                              | The server requests full state (`ReportFullState`) to recover missing information and resend pending configuration. |

**Validation note:** Currently, the system validates YAML syntax. It does not validate the semantic correctness of the Collector configuration.

## Hybrid configuration mode for GitOps[​](#hybrid-configuration-mode-for-gitops "Direct link to Hybrid configuration mode for GitOps")

Hybrid mode is available for advanced users who need to combine local, GitOps-managed configuration with remote configuration from Fleet Management. It is intended as a solution for scenarios where GitOps workflows must remain the source of truth for part of the configuration, while still allowing certain settings to be managed remotely.

To enable hybrid mode, the Supervisor preset must be enabled and the minimal bootstrap configuration must be disabled (`minimalCollectorConfig: false`). In this setup, the Supervisor merges your local configuration with remote configuration delivered by Fleet Manager.

Hybrid mode requires extra caution. You are responsible for validating the final merged configuration, and merge behavior may change in upstream OpenTelemetry components.

## Permissions[​](#permissions "Direct link to Permissions")

To manage remote configurations in Fleet Management, you must have the proper permissions. Access can be granted in two ways:

* Assign an admin role (Legacy Admin, Organization Admin, or Data Admin), which automatically provides full Fleet Management permissions.

* Grant explicit remote configuration permissions using the **FleetManagement** permission preset or an individual permission.

  | Preset              | Action                        | Description                                                                |
  | ------------------- | ----------------------------- | -------------------------------------------------------------------------- |
  | **FleetManagement** | `REMOTE-CONFIGURATION:MANAGE` | Manage remote configurations (create, edit, activate, deactivate, archive) |

See [Permissions](https://docs-docusaurus.kinsta.page/user-guides/fleet-management/permissions/.md) for details.

## Next steps[​](#next-steps "Direct link to Next steps")

Set up S3-based resilience so agents always have a working configuration in [Set up configuration fallback for Fleet Management](https://docs-docusaurus.kinsta.page/user-guides/fleet-management/configuration-fallback/.md).