Configuration Deep Dive
Overview
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
The configuration mode determines how the Fleet Manager delivers configuration updates to your Collectors.
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)
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
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 our Fleet Management architecture documentation.
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
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)
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 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.
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 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
To manage remote configurations in Fleet Management, users 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:MANAGEManage remote configurations (create, edit, activate, deactivate)
Support
Need help?
Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.
Feel free to reach out to us via our in-app chat or by sending us an email at support@coralogix.com.