Step 21: Upgrade with Live & Candidate Nodes
Test a new ControlBird version on a candidate node, then promote it into production without downtime.
Full reference
For complete details, field tables, and limitations, see the A/B Node Upgrades reference.
Your Environment Has an Address of Its Own
Every environment owns a stable address, its alias, that always resolves to whichever node is currently live. That's the address you've been handing out: on NFC tags, kiosk auto-login links, tunnel adapters in the field, anywhere outside the product. Every node also has its own permanent URL, so you can still open any node directly.
Cloud nodes in an environment do not stay in sync with each other. A second node you add is called a candidate: a completely independent node with its own copy of your configuration, useful for trying a newer ControlBird version before you commit your live traffic to it. Nothing is shared between a candidate and the live node until you explicitly promote it: moving the alias so the candidate becomes live.
Deploy a Candidate
From your environment's page, deploy a new node the same way you deployed your first one, but pin it to the newer ControlBird version you want to evaluate. It provisions as an ordinary node, reachable at its own URL, alongside the node that's currently live.
Bring Its Configuration Up to Date
A candidate starts with none of your configuration. Export the configuration you want to test from the live node, then import it into the candidate; this is the only supported way to carry your entity tree, schemas, and automations across.
Test the Candidate
Open the candidate at its own URL (not the alias, which still points at the live node) and put it through its paces: confirm devices connect, automations fire, and dashboards render the way you expect. The live node keeps serving the alias the entire time, so there's no pressure to rush: a candidate cannot affect production traffic while you evaluate it.
Before You Promote
Promotion hands your environment's public identity to the candidate. Before you do it:
- Trend history does not move. History lives only on the node that recorded it. The candidate starts with an empty history, so every chart goes blank right after promotion. Keep the retired node running if you need to look further back.
- NFC tags need an exact match. A tag only resolves on the candidate if the candidate has the identical (randomly generated) tag identifier, achievable only through config export/import, and even then the automation a tag triggers doesn't currently travel with it, so an imported tag scans but does nothing until you rebuild that automation.
- Everyone gets signed out. Each node has independent sign-in state, so promotion ends every session on the outgoing node. Pick a quiet moment.
- Sealed secrets do not transfer. Passwords and tokens are sealed to the node holding them; the candidate needs its own copies of anything secret.
- Old links stay bound to the node they were written against. Anything that predates your environment's alias keeps pointing at a specific node's own URL.
- You're paying for the candidate the whole time. It's billed as a full, ordinary node for as long as it exists, not a discounted trial.
- SSH tunnel access isn't isolated between nodes in the same environment. If it's enabled anywhere in the environment, treat it as access to every node in that environment, live node included.
Promote
Satisfied with the candidate? Promote it from the environment's page. The alias moves to the candidate; the previous live node keeps running at its own URL rather than being torn down. Give external caches (DNS, browsers) a few minutes to catch up everywhere.
Roll Back If Needed
If something's wrong after promotion, promote the previous node back. It's the same operation run in reverse, and just as fast, because the retired node was never stopped; it was simply waiting.
Delete the Old Node When You're Done
The retired node keeps running, and keeps billing, until you act on it. Once you no longer need its history as a reference or its presence as a rollback path, stop or delete it to stop paying for it.
No Automatic Data Sync
Unlike a self-hosted peered cluster, cloud nodes never synchronize data with each other, promoted or not. Everything a candidate needs (configuration, devices, secrets) has to be put there deliberately, as described above.
Troubleshooting
My charts are empty right after promotion
Expected. Trend history is node-local and does not move with promotion. The retired node still has the full history if you need to look back: it's still running at its own URL until you stop or delete it.
An NFC tag scans but nothing happens on the candidate
Config export/import carries the tag record itself but not the automation wired to it today. Rebuild that automation on the candidate (or on whichever node is now live) so the tag has something to trigger.
Everyone got logged out after I promoted
Expected: each node has its own independent sign-in state. Users sign back in against whichever node the alias now points at.
Can I test a candidate without affecting production?
Yes. A candidate is a fully independent node reachable only at its own URL until you promote it: the live node keeps serving the alias untouched the whole time you test.