---
title: Move a Blueprint Deployment to a New Node
sidebarTitle: Move a blueprint to a new node
description: Relocate a Blueprint-managed stack from a node you're retiring to another node in the fleet, without letting the reconciler undo the move partway through.
---
Say a small stateless service, a status page, a metrics exporter, an internal API, runs as a [Blueprint](/features/blueprint-model)-managed deployment on one node in your fleet. That node is going away, for maintenance, decommissioning, or a hardware swap, and you need the workload running on a different node before you take the old one offline. This walks through doing that with **Federation**'s pin and cordon controls: pin the blueprint to the destination so the reconciler stops trusting its normal selector, cordon the source so it stops picking up anything new, then confirm the rollout that actually moves the workload.
Despite the name, Federation doesn't connect separate Sencho instances or fleets together, that's a different concept Sencho doesn't do at all. Federation is a tab inside a single fleet's **Fleet** view. It steers *where* that one fleet's Blueprint-managed deployments land; it has no notion of "other fleets."
By the end, the workload runs only on the new node, the old node is marked unschedulable, and you can confirm both from more than one place in the UI.
Both controls follow the same rule, and it's the part most likely to trip up a first-time user: **pinning and cordoning only declare intent.** Neither one deploys or withdraws a single container by itself. The reconciler stages what it *wants* to do next; you still open the blueprint and click **Confirm Apply** before anything on the fleet actually changes. That extra step is what makes this walkthrough three actions long instead of one.
This tutorial does not cover creating a Blueprint from scratch (see [Create and Approve a Blueprint](/tutorials/create-and-approve-a-blueprint)), draining a node of everything it runs, or evicting a stateful deployment. See the [Blueprints](/features/blueprint-model) and [Fleet Federation](/features/fleet-federation) feature pages for those last two.
## Prerequisites
- **An admin account.** Cordoning a node and pinning a blueprint both check the same permission, scoped to the node you're acting on; clearing a pin checks that same permission without a node scope. Delegating that permission to a non-admin role for one specific node is an Admiral-tier capability, so on Community you complete every step here as the instance's admin.
- **An existing Blueprint already deployed on at least one node.** Federation steers placement for Blueprints that exist; it does not create them. If you don't have one yet, walk through [Create and Approve a Blueprint](/tutorials/create-and-approve-a-blueprint) first.
- **At least two nodes in the fleet**, both online. Pinning only matters when there's somewhere else to pin to. Multi-node fleets and Federation are both Community-tier, no paid plan required.
![Fleet Federation tab showing Cordoned nodes 0 of 4 and a Pin policy table with one row for the edge-status blueprint, selector any=[dev], Pinned to (unpinned), Effective any=[dev].](/images/tutorials/set-up-fleet-federation/federation-tab-before-pin.png)
Open **Fleet → Federation** and find your blueprint's row in the **Pin policy** table. Open the **Pinned to** dropdown and select the node you're moving the workload to. A cordoned node would show inline as ` · cordoned` here, so you can see at a glance if you're about to pin onto something already out of rotation.
The selection saves immediately and a toast confirms it. The **Effective** column updates to `pin: `, overriding whatever the selector would otherwise resolve to. Nothing has deployed yet, this only changes what the reconciler wants to do next.
Go to **Fleet → Overview**. On the source node's card, click the kebab menu (`⋯`) and choose **Cordon node**.
A confirmation dialog opens with an optional reason field, up to 256 characters. Fill in something that will make sense to whoever looks at this node in a week.
Click **Cordon node**. The card gains a `Cordoned` pill immediately; this alone does not touch anything already running on the node, including the blueprint you're about to move off it.
Cordon only ever removes a node from consideration for *new* placements; it never touches what's already running, and it never overrides an explicit pin. If you pinned a blueprint to a node that happens to be cordoned, the pin still wins, the blueprint deploys there anyway once its rollout is confirmed. Cordon and pin answer different questions ("should this node pick up new work automatically" versus "where must this specific blueprint run"), and when they disagree, the explicit answer (pin) beats the general one (cordon).
Pinning and cordoning only declared intent, neither one deployed or withdrew anything by itself. Open **Fleet → Deployments**, select your blueprint, and click **Apply now**. Sencho opens a rollout preview.
You should see one **create** on the destination node and one **remove** on the source, both marked safe. If the destination were unreachable, that create would show as a blocker instead and **Confirm Apply** would stay disabled, see [If something goes wrong](#if-something-goes-wrong). Click **Confirm Apply**.
## Verify it worked
Check from more than one surface, since a single stale UI element could tell you the wrong thing.
**The Federation tab.** The Pin policy row's **Effective** column reads the pinned node, and the Cordoned nodes card lists the source node with its reason and a timestamp.
**The audit log.** Open **Audit** and search or scan for the actions you just took. Each mutating request gets its own row: the pin write, the cordon, and the apply.
## If something goes wrong
The most common first-time confusion is pinning or cordoning and then expecting the workload to move on its own. It won't. Both actions only change what the reconciler *wants*; the blueprint's catalog tile and detail sheet footer show **pending** or **reapproval required** until you open the blueprint and confirm a rollout.
If **Confirm Apply** is greyed out instead, a blocker is present, most often an offline or unreachable destination node. Check the destination's status in **Fleet → Overview** before retrying, or change the pin to a node that's actually reachable.
## Related
Cordon and pin mechanics, the confirm-before-mutate model, and full troubleshooting.
The declarative deployment model Federation steers, including selectors, drift policy, and the rollout-preview mechanic.
Author and deploy a Blueprint from scratch, the prerequisite this tutorial assumes.