Rotations and upgrades

audience: operators

A lattice is a long-lived identity; the six organisms inside it need to rotate secrets, replace committee members, and upgrade TDX images on their own cadences. This page is the procedure checklist.

What rotates without a fingerprint change

Changes that do not touch the lattice’s on-wire identity. Integrators do not need to rebuild; existing bonds survive.

• Peer identity secrets per committee member (<ORG>_SECRET_FILE in env files). Rotating this changes the PeerId of that one member; peer catalogs re-converge without intervention. Do one member at a time.
• TDX image version for an organism, provided the new image produces the same MR_TD (reproducible build over a bit-for-bit identical codebase). Rolling restart.
• Committee-admission secrets (<ORG>_COMMITTEE_SECRET_FILE) within the same fingerprint, provided you distribute the new secret to every member in lockstep. Rare; usually part of a coordinated incident response.

What rotates with a fingerprint change

Changes that change the lattice’s on-wire identity. Integrators must rebuild against the new LatticeConfig; mid-flight bonds break.

• Any LatticeConfig field. Instance name, chain id, any organism’s schema, window, threshold, MR_TD.
• An organism’s StateMachine::signature() change (usually coincident with a crate version bump).
• DKG output for unseal or offer — new aggregate pubkey, new fingerprint.

When these change, the lattice effectively becomes a new lattice. See Lattice retirement.

Rotating a committee member’s peer identity

Per organism; repeat for each. Zero-downtime if n >= 3.

1. Generate a new secret file on the host.
2. Stop that member’s systemd unit.
3. Swap <ORG>_SECRET_FILE to point at the new file.
4. Start the unit. It joins with a new PeerId.
5. Monitor <org>_committee_size on the other members; when they have re-bonded (within a minute in the common case), the rotation is complete.

Repeat for the next member. Never rotate two members’ identities simultaneously in a committee of 3 or the remaining single member cannot achieve quorum.

Rolling a TDX image with the same MR_TD

This is the common case for TDX-gated organisms. The MR_TD is reproducible; the image’s kernel or user-space just got a patch whose bits are identical on reproducible builds.

1. Build the new image.
2. Verify mrtd.hex matches the pinned atelier::Config.mrtd. If not, the change requires a fingerprint-changing rotation.
3. Stop one member at a time. Swap the VM image. Start.
4. Confirm TDX attestation metrics green on the rotated member before rotating the next.

Rolling a TDX image with a new MR_TD

This is a fingerprint change. Follow Lattice retirement.

DKG rerun (unseal or offer)

Run at quarterly cadence by default, or on demand when a committee member is compromised.

1. Announce the retirement date in your release notes.
2. Run the DKG ceremony — every committee member participates online; the output is a new aggregate public key.
3. Produce a new LatticeConfig with the new public key.
4. Proceed to Lattice retirement.

You cannot do an in-place DKG re-run that preserves the lattice fingerprint — the aggregate public key is in the fingerprint.

Lattice retirement

Procedure when the LatticeConfig fingerprint changes:

1. Announce the retirement and the new lattice name (typically <current>.v<next>). Publish a timeline — four weeks is generous, two is tight.
2. Publish the new LatticeConfig to your operator-crate or release-notes channel alongside the old one. Both lattices coexist on the universe during the transition.
3. Stand up the new lattice per Quickstart — stand up a lattice.
4. Notify integrators with the new LatticeConfig and migration deadline.
5. After the deadline, stop the old lattice’s processes. Integrators still bonded to the old lattice get ConnectTimeout.

Both lattices share the same universe and the same discovery layer; they appear to the mosaik layer as two unrelated deployments. This is the same migration pattern zipnet documents; see rotations in the zipnet book.

Schedule recommendations

“Non-FP” = non-fingerprint. Every LatticeConfig change is a fingerprint change by construction; non-fingerprint changes happen at the systemd-env layer (peer identity, TLS certs, etc.) and do not touch the LatticeConfig at all.

Cross-references

• Incident response — rotations driven by security events.
• Running an atelier builder — the co-building Phase 2 onboarding procedure lives there; it is a lattice retirement in operational terms.
• zipnet rotations — the per-organism procedure for the zipnet organism, detailed.