A/B Node Upgrades
Test a new ControlBird version on a candidate node, then promote it into production, with a safe way back.
Overview
Upgrading a live node used to mean an in-place swap: stop the node, apply the new version, hope it comes back up correctly, with no way to evaluate the new version first and no way back if it misbehaves. For a node running a live site, that is not an acceptable way to take an upgrade.
A/B node upgrades let you stand up a second node on a newer version next to your live one, prove it works, and only then hand it your environment's identity. Promotion is an identity swap, not a data migration: the environment's alias (its one stable, permanent address) simply starts resolving to the new node instead of the old one. Everything already pointing at that alias, from NFC tags on the wall to a kiosk's auto-login link to a field device reaching through a tunnel, keeps working with nothing to re-point. The retired node keeps running at its own permanent URL until you explicitly stop or delete it, so rolling back is just promoting it back.
Prefer a guided tutorial?
New to this? Follow the Upgrade with Live & Candidate Nodes walkthrough for a step-by-step tour, then come back here for the full reference.
Key Concepts
| Concept | What it means |
|---|---|
| Alias | The environment's own permanent hostname. It always resolves to whichever node is currently live. This is the address you hand out: on NFC tags, kiosk links, tunnel adapters, and anywhere else outside the product. |
| Live node | The node an environment's alias currently resolves to. There is exactly one live node per environment. Every node also keeps its own permanent URL, so you can open the live node directly instead of through the alias. |
| Candidate node | Any other node in the environment. A candidate is a completely independent node, with its own compute, its own copy of your configuration and data, reachable only at its own permanent URL until it is promoted. Nothing about a candidate is shared with, or copied from, the live node automatically. |
| Pinned version | A node can be pinned to a specific ControlBird version instead of following the fleet default, which is what lets a candidate run a newer version side by side with a live node on an older one. |
| Promotion | Moves the alias from the current live node to a candidate. Nothing about either node's configuration changes: no data moves, no subscription follows. The alias simply resolves somewhere else afterward. Promotion is safe to retry if it's interrupted. |
| Rollback | Promotion run in reverse: promote the previous live node back. The same identity-swap mechanics apply, so a rollback is exactly as fast and as safe as the original promotion. |
Before You Promote
Promotion moves your environment's public identity to a different, independent node. Read this before you promote: some of it can't be undone after the fact.
Read this before you promote
- Trend history does not move. Historical data lives only on the node that recorded it, as node-local files. A promoted candidate starts with empty trend history: every chart goes blank at cutover. There is no backfill. The retired node keeps running with its full history intact, so keep it around until you no longer need to look back past the promotion date.
- Config parity is your responsibility. Nothing copies your configuration from the live node to a candidate automatically. Export the configuration from the live node and import it into the candidate; that is the only supported way to bring a candidate's configuration in line with the node it's replacing.
- NFC tags need an exact match, and even config import doesn't fully cover it. A physical NFC tag only resolves on the candidate if the candidate has a tag record with the identical internal tag identifier the physical tag was written with. That identifier is random and cannot be reconstructed by hand, so a candidate you configured manually will never match; config export/import is the only route that carries it across. Even then, the automation that a tag is meant to trigger does not currently travel with the exported configuration, so an imported tag will scan successfully but fire nothing until you rebuild that automation on the candidate.
- Everyone is signed out at cutover. Each node keeps its own independent sign-in state, so promoting a candidate ends every session that was open against the old live node. Warn your users before you promote during working hours.
- Sealed secrets do not transfer. Passwords, tokens, and other secret fields are sealed to the node that holds them and cannot be moved to another node. A candidate needs its own copies of any secrets your configuration depends on.
- Links written before the alias existed stay bound to a node's own URL. If you have references (bookmarks, integrations, printed material) that predate your environment's alias, promotion does not retarget them: they keep pointing at the specific node they were written against.
- A candidate is billed as a full, ordinary node. Standing up a candidate to test a version starts a second, full subscription for as long as it exists; it is not a discounted trial charge. Delete it once you're done to stop paying for it.
- SSH tunnel access is shared across the whole environment. If SSH tunnel access is enabled anywhere in an environment, that access reaches every node in it: the live node and every candidate alike. Don't treat a candidate as isolated from your production node for SSH tunnel purposes.
Running an Upgrade
1. Deploy a candidate
From your environment, deploy a new node and pin it to the ControlBird version you want to test. Give it whatever tier it needs to represent your production load realistically. The candidate provisions as a completely ordinary node, reachable at its own permanent URL; it is not connected to the live node in any way.
2. Bring its configuration up to date
Export the configuration you want to test from the live node and import it into the candidate. This is the only supported way to carry your entity tree, schemas, and automations across; remember the NFC and trigger-wiring caveats above.
3. Test the candidate at its own URL
Open the candidate directly (not through the environment's alias, which still points at the live node) and verify it behaves the way you expect: devices connect, automations run, dashboards render. Take as long as you need: a candidate does not affect the live node in any way while you evaluate it, and the live node keeps serving the alias the whole time.
4. Promote
Once you're satisfied, promote the candidate from the environment's page in the control plane. The alias moves to the candidate; the previously-live node keeps running at its own URL, now effectively retired. Give it a few minutes for external caches (DNS, browsers) to pick up the change everywhere.
5. Roll back if something's wrong
If the newly-promoted node isn't behaving, promote the previous node back the same way. This is exactly the same operation run in reverse, and just as fast: the retired node was never stopped, so it's still there to take the alias back.
6. Delete the old node once you're satisfied
The retired node is not removed automatically. Keep it running for as long as you might want to reference its trend history or fall back to it; stop it once you're confident in the promoted node but still want the option to delete it later; delete it (and stop paying for it) once you're done.
Common Patterns
- Test on a realistic tier. A candidate on a smaller tier than production can behave differently under load. Match the live node's tier for a meaningful test.
- Keep the retired node around briefly after promotion. It's your only copy of pre-cutover trend history and your fastest rollback path. There's no rush to delete it.
- Schedule promotion for a quiet period. Every session on the outgoing node ends at cutover, so promoting during active use interrupts every logged-in user at once.
Troubleshooting & Limitations
- A candidate is fully isolated, except for SSH tunnel access. A candidate does not read or affect the live node's data, and vice versa, with the single exception of the shared SSH tunnel credential covered above.
- Promotion is one operation at a time per environment. You can't run two promotions, or a promotion and an environment deletion, against the same environment concurrently.
- An interrupted promotion is safe to retry. Every step of promotion is idempotent, so retrying after a failure never double-applies a step or leaves the alias pointing nowhere.
- A brand-new environment's first node becomes live automatically. The alias has nothing to resolve to until a node exists, so the first node to finish provisioning in a new environment takes over the alias without a separate promotion step. Every node after that is a candidate until you explicitly promote it.
- Deleting a candidate never affects the live node. The two are independent nodes; removing one has no effect on the other's identity, data, or availability.