Skip to content

Cross-cluster handover

Handover lets a single agent migrate from one Ampora server to another while keeping its identity — its history, audit trail references, group membership, and configuration assignment travel with it.

This is different from re-bootstrapping (which severs the old identity and creates a new one). Handover is for the case where the migration is intentional and the audit trail should remain continuous.

When to use

  • Region migration (an agent moves from eu-region to eu-west-region).
  • Tenant reorganisation that splits or merges peers.
  • Disaster failover of a region — handover the affected agents to a surviving peer for the duration of the outage, then handover back.

Pre-requisites

  • Federation peers registered between source and target.
  • The Configuration the agent was running must exist on the target peer (handover does not migrate Configurations themselves).
  • The agent must signal AcceptsConnectionSettings so it can pick up the new Ampora endpoint.

Mechanism

  1. Originating peer (source) issues a signed handover token. The token contains:
  2. the agent's identity reference,
  3. the target peer's name and endpoint,
  4. the target peer's CA trust bundle,
  5. a fingerprint of the agent's existing leaf cert,
  6. a TTL (default 1 hour).
  7. The token is signed by the source peer's active CA and pinned to the agent's existing leaf cert via the fingerprint.
  8. The target peer redeems the token: it verifies the signature against its known peer trust, checks the fingerprint matches the incoming agent on first connect, and creates a local agent row linked to the source's identity.
  9. The agent reconnects to the target peer's OpAMP endpoint using its existing leaf cert (still valid until the next rotation; the target peer trusts the source peer's CA via the bundle that shipped in the token).
  10. On the source peer, the agent's row is marked MovedToPeer <target> and a new audit event records the handover.

This whole flow takes seconds, end-to-end. The agent never has to re-bootstrap.

Initiating

On the source peer:

  1. Fleet → Agent details → Move → Handover to peer.
  2. Pick the target peer.
  3. The target peer's name appears with its current reachability.
  4. Click Generate handover token. Copy.

On the target peer:

  1. Settings → Federation → Handover → Redeem token with the token paste-in.
  2. The target shows the agent's identity for confirmation.
  3. Click Confirm — the target waits for the agent to reconnect.

The agent picks up the new endpoint via ConnectionSettings on its next heartbeat.

Identity continuity

What survives the handover:

  • the agent's display name,
  • its agent_description,
  • its capabilities,
  • its instance_uid,
  • its mTLS client cert (still valid until rotation),
  • a back-reference to the source peer's audit trail.

What is new on the target:

  • the agent row's local UUID (the audit trail records the source UUID in the handover event),
  • the agent's group (mapped per the handover form's choice),
  • its assigned configuration (mapped to the same name on the target, or chosen at handover time).

Reverse handover

Handing the agent back is the same flow in reverse. The audit trail on both peers shows two handover events; the agent's history is reconstructable across peers by following the references.

Failure modes

Symptom Cause
Token redemption refuses with "fingerprint mismatch" The agent's leaf cert was rotated between token issuance and redemption. Generate a new token after the rotation completes
Agent never reconnects to target The target endpoint URL is wrong, or the target's CA trust bundle was not propagated. Check the agent's opamp_extension logs
Target peer has no Configuration named X Pre-condition failed; create the Configuration on the target before handover

Audit

Both source and target write audit events. The token issuance, the redemption, and the agent reconnect each produce a row. Filter by the agent's identity on each peer to see the full story; cross-peer correlation uses the OriginPeerId field that handover events carry.

Why this is safer than re-bootstrap

A re-bootstrap creates a new identity — the audit trail before and after is split. For migrations done in normal operation, that is fine. For migrations forced by an incident, you want continuity for post-incident review; handover gives you that without weakening trust.