Upgrade configuration versions in Fleet Management

Upgrade your template and OpenTelemetry (OTel) Collector versions across your fleet without rebuilding configurations from scratch. Fleet Management uses a "Living Configuration" model--when a newer template or Collector version becomes available, a one-click upgrade workflow applies the update while preserving your existing preset toggles.

Upgrade notifications appear directly in the Fleet Management UI, giving you visibility into available updates and control over when to apply them.

What you need

REMOTE-CONFIGURATION:MANAGE permission, granted through the FleetManagement permission preset or an admin role (Legacy Admin, Organization Admin, or Data Admin). See Fleet Management permissions.
An existing template-based configuration created in preset mode. Template upgrades apply to preset-mode configurations only. For code-mode configurations, manually update the YAML to reflect the new template version.
OpenTelemetry Collectors deployed with the Supervisor preset enabled. See Enable Fleet Management for Kubernetes.

Upgrade notifications

When a newer template or OTel Collector version is available for a configuration, Fleet Management alerts you through two indicators:

Toast notification: A "New version available!" toast appears on the Configurations tab when a newer version is available for at least one configuration group.
Upgrade badge: An "Upgrade available" badge appears on the configuration group row in the Configurations tab.

Select the badge to open a tooltip that displays release notes for the new version and an Upgrade template button.

Upgrade an inactive configuration

When the configuration version you want to upgrade is not currently active (status is Draft or Inactive), the upgrade creates a new Draft version with the updated template.

In Coralogix, navigate to Integrations, then Fleet Management, then Configurations.
Expand the configuration group that shows the Upgrade available badge.
Select the badge on the inactive version to view the release notes.
Review the release notes, then select Upgrade template.
Fleet Management creates a new Draft version with the updated template and preserved preset toggles.
Review the new Draft version. When ready, select Activate to deploy it to your fleet.

Select Upgrade template in the tooltip. A confirmation dialog summarizes the changes before proceeding. Select Confirm upgrade to create the new version.

Upgrade an active configuration

When the configuration version you want to upgrade is currently active, the upgrade triggers a controlled version transition. The old version enters a Deactivating state while the new version enters an Activating state.

In Coralogix, navigate to Integrations, then Fleet Management, then Configurations.
Expand the configuration group that shows the Upgrade available badge.
Select the badge on the active version to view the release notes.
Review the release notes, then select Upgrade template.
The current active version transitions to Deactivating and the new version transitions to Activating.
Monitor the version states in the configuration group. The new version becomes Active once agents confirm they are running the updated configuration.

Select Upgrade template in the tooltip. A confirmation dialog summarizes the changes before proceeding. Select Confirm upgrade to create the new version.

What happens during the transition

Deactivating: The old version remains applied on agents that have not yet received the new configuration. No new agents receive the deactivating version. The Supervisor gradually rolls out the new version to agents.
Activating: The new version is being distributed to agents. Once at least one agent reports the new version as applied, the new version transitions to Active and the old version transitions to Inactive.

If the new version fails to apply on all agents, the Supervisor automatically reverts affected agents to the previous working configuration. The failed version transitions to Failed status.

Collector version requirements

Some configuration upgrades require a newer Collector version. When a new configuration family specifies a required Collector version that is higher than what an agent is running, the agent remains in the Deactivating state on the old configuration until the Collector is upgraded. The new configuration is not applied to agents with incompatible Collector versions.

To resolve this, upgrade the Collector on affected agents to the required version. Once the Collector version meets the requirement, the Supervisor applies the new configuration automatically.

Version states

Each configuration version has a status that reflects its current stage in the lifecycle.
Status Description
Draft Version has been created but not yet activated. Safe for review and testing.
Activating Version is being rolled out to agents. Appears during an upgrade or initial activation.
Active Version is the current configuration applied to agents matching the selector. Only one version per group can be active.
Deactivating Previous active version being phased out during an upgrade. Agents still running this version will transition to the new active version. If the new version requires a newer Collector version, agents on older Collector versions remain in Deactivating state until the Collector is upgraded.
Inactive Version was previously active and has been deactivated or superseded. Can be cloned or used as the basis for a new version.
Failed Version failed to apply on one or more agents. The Supervisor automatically reverts affected agents to the previous working configuration. See Handling failure scenarios and rollback.

The Failed status appears when one or more agents could not apply the new version. In the existing configuration management UI, this is represented by an Active (!) indicator on the configuration group.

How preset toggles are preserved

The one-click upgrade carries forward all preset toggle selections (such as Logs, Metrics) from the current version to the upgraded version. The upgrade applies the newer template while retaining your feature choices, so you do not need to reconfigure presets after each upgrade.

All observability feature preset toggles are preserved during upgrade, including APM and tracing, Logs and events, Metrics (with all sub-toggles), and Additional features. See Configuration templates for the full list of available presets.

Custom YAML modifications made after switching to Code mode are not preserved during a template upgrade. The upgrade creates a clean version from the new template with preset toggle states only.

Best practices

Test upgrades in a development or staging environment before applying them to production configurations. Create a clone of your production configuration, apply the upgrade to the clone, and validate agent behavior before upgrading the production version.
Monitor the Deactivating state during active version upgrades. Verify that agents transition to the new version within your expected timeframe. The configuration group displays the number of agents that have applied the new version alongside the total matching agents.
Review the release notes in the upgrade tooltip before upgrading. Release notes highlight breaking changes, new features, and bug fixes that might affect your configuration.
Keep your fleet on a consistent Collector version to avoid configuration drift and simplify troubleshooting. Upgrading multiple configuration groups simultaneously is not supported. Upgrade each group individually.

Limitations

Only one version upgrade per configuration group can be in progress at a time.
One-click upgrades are available for preset-mode configurations only. Code-mode configurations require manual YAML updates.
You can upgrade directly to the latest available version. Intermediate versions do not need to be applied.
All configurations in a configuration family must use compatible template versions. Upgrading one family member may require upgrading the others.
You cannot edit a configuration group while a version upgrade is in progress. Wait for the transition to complete before making additional changes.

Troubleshoot

Upgrade badge does not appear

Cause: The configuration uses code mode instead of preset mode, or the template is already on the latest version.
Fix: Verify the configuration uses a template-based preset and check the current template version in the configuration details.

New version stuck in Activating state

Cause: Agents are not checking in with Fleet Manager.
Fix: Verify agent connectivity and Supervisor health. Check the agent list in Agent management for offline or unhealthy agents. If agents remain unresponsive, deactivate the new version and investigate agent connectivity before retrying.

Preset toggles not preserved after upgrade

Cause: A preset toggle was deprecated or renamed in the new template version.
Fix: Review the release notes for the new version and reconfigure any presets that were changed or removed.

Agents revert to previous version after upgrade

Cause: The new configuration caused a failure and the Supervisor automatically rolled back.
Fix: Review the agent status for error details and check the Collector logs. See Handling failure scenarios and rollback.

Need help? Contact Support.

What's new? Find out here.

LLM? Read llms.txt.

Previous Configuration Fallback

Next Architecture

Status	Description
Draft	Version has been created but not yet activated. Safe for review and testing.
Activating	Version is being rolled out to agents. Appears during an upgrade or initial activation.
Active	Version is the current configuration applied to agents matching the selector. Only one version per group can be active.
Deactivating	Previous active version being phased out during an upgrade. Agents still running this version will transition to the new active version. If the new version requires a newer Collector version, agents on older Collector versions remain in Deactivating state until the Collector is upgraded.
Inactive	Version was previously active and has been deactivated or superseded. Can be cloned or used as the basis for a new version.
Failed	Version failed to apply on one or more agents. The Supervisor automatically reverts affected agents to the previous working configuration. See Handling failure scenarios and rollback.