Skip to content

Registering a peer

Federation peers are set up bilaterally and manually. Each side needs the other's mTLS thumbprint and a shared secret.

Steps

1. Generate a federation client cert (each side)

Settings → Federation → Issue client cert on each Ampora.

The dialog shows the public certificate PEM (copy this for the other side) and keeps the private key on this server only. Validity is 90 days by default.

2. Generate inbound and outbound shared secrets

Each peer entry has two secrets:

  • inbound — used by the remote server when calling us.
  • outbound — used by us when calling the remote.

Both are 32-byte CSPRNG tokens. Generated and shown once. Stored as SHA-256 hashes; constant-time compared on every request.

3. Create the peer rows

On Ampora-EU: New peer with name us-region, endpoint URL of US-Ampora, paste US's public cert PEM, generate inbound + outbound secrets, save.

On Ampora-US: New peer with name eu-region, endpoint URL of EU-Ampora, paste EU's public cert PEM. Swap the secrets: use EU's outbound as US's inbound, and EU's inbound as US's outbound.

The "swap inbound/outbound between sides" rule sounds odd at first. The way to remember it: "the secret I use outbound is what you check inbound."

4. Verify

Federation → {peer} → Ping calls GET /api/federation/ping across the link. A green response means:

  • TLS handshake succeeded (cert thumbprint matches the pinned value),
  • the outbound shared secret matched on the receiving side.

A red response says which factor failed; cross-reference with the remote audit log on the other side.

What is not shared

  • Tenant IDs. Each peer remains tenant-isolated. The federation surface only sees the caller's own tenant's agents on each side.
  • Audit logs. Local audit logs do not flow across the link; each peer keeps its own. Tranche 4 may add an OriginPeerId column on audit events for federation-originated writes.
  • Configurations. Each peer's configurations stay local. If you want the same configurations on both peers, ship them via the same GitOps repo on each side.

Permission model

  • Listing peers: Admin.
  • Inbound federation calls: federation auth handler (mTLS + secret), bypassing the normal user auth.
  • Aggregated Fleet view: Admin. The view shows a clear "Includes federation" badge so operators see the data is not local.

Heartbeat

Each Ampora pings each active peer every 30 seconds. The result is shown on the Federation page as the peer's Reachability chip:

  • Reachable — last ping returned 200 within the last minute.
  • Slow — last ping took > 1 s.
  • Unreachable — last successful ping older than 5 minutes.

The aggregated Fleet view degrades gracefully when a peer is Unreachable: the peer's rows are omitted but the rest of the view renders normally.

Rotating

  • Cert rotation: re-issue, re-distribute the new PEM to the other side, save the new thumbprint there. Old cert keeps working until you delete it on the issuing side.
  • Secret rotation: Rotate inbound secret / Rotate outbound secret on either side; copy the new plaintext to the matching field on the other side. Verify with Ping.

Removing a peer

Federation → {peer} → Delete. Both sides should delete; otherwise the side with the row continues to attempt connections that the other side will refuse.