Browse and search documentation
Agent upgrades and downgrades
Select a trusted release and online nodes, upgrade in batches and verify the new version. Distinguish failure rollback from an intentional downgrade.
On this page
Start an upgrade
- Open Agent management → Version upgrades and choose Start upgrade. Select the recommended stable release or another published release in your maintenance plan.
- Select online, compatible nodes running an older version. Ineligible nodes remain visible with a reason; they have not disappeared from inventory.
- Review batch size and failure threshold, starting with a small batch. Confirm targets and submit; ordinary upgrades do not require a separate approval workflow.
- Wait through preparation, delivery, switching and restart verification, then confirm a heartbeat from the target version. A completed download is not a completed upgrade.
Common upgrade states
| State | Meaning and next step |
|---|---|
| Waiting for preparation | The batch exists; keep the Agent online while it waits for scheduling |
| Preparing upgrade environment | An older Linux node may be registering the release public key automatically; no reinstall is needed |
| Awaiting restart verification | The version has switched; wait for its heartbeat and check service/network if delayed |
| Effective | The node is online on the target version |
| Failed or rollback failed | Inspect the failed stage with an administrator; do not repeatedly re-enroll the node |
Handle failures
Download, connection, preparation and pre-switch check failures stop the affected node. They do not require successful nodes to roll back. The failure threshold concerns failures that may occur after version switching, so inspect the stage rather than only a failed-node count.
No available releases usually means trusted releases have not been published into the environment or catalog verification failed. Ask the deployment administrator to check the catalog instead of deleting Agents or generating new enrollment tokens.
When to use a downgrade
Use Version downgrade only when an older version is intentionally required, and only with the separate downgrade permission. The target must be older, must be entered again for confirmation and requires separate high-risk approval. This differs from automatic rollback following an upgrade failure.
Send your deployment version, page and a redacted description so we can investigate and update the guide.
weiwendi@aiops.red