Plan a Migration
Read an existing mesh with credentials that cannot write, then study the file that enumerates every change it describes.
On this page (5)
Plan a Migration Documentation
whisper whale migrate plan reads a mesh you already run and writes a plan file describing what the same fleet would look like here. It changes nothing on either side. Every call it makes is a GET, and the client behind it has no write method at all, so that is a structural property rather than a promise: re-read both sides afterwards and they are byte-identical. The one thing it writes is the file you name.
1. Put a read-only credential in the environment
export TS_OAUTH_CLIENT_ID='...'
export TS_OAUTH_CLIENT_SECRET='...'
A read-only OAuth client is preferred. A personal API access token in TS_API_KEY also works. The credential is read from the environment and never from a flag, so it is never written into the plan file, never logged and never echoed.
2. Write the plan
whisper whale migrate plan -o whalenet.plan.json
-o names the output file and defaults to whalenet.plan.json. By default the command reads the mesh the credential itself belongs to.
3. Read the fidelity classes
The plan enumerates every write it describes, in the order it would happen, and classes each line so you can see what survived the translation.
| Class | Means |
|---|---|
EXACT | The rule maps with nothing gained or lost. |
APPROX | The rule maps to something equivalent in effect but written differently. |
APPROX-WIDENING | The rule maps to something strictly broader than the source rule. Read every one of these. |
UNMAPPED | The rule has no counterpart here, so the plan carries it as a line you have to decide about. |
List the widening lines on their own:
jq '.fidelity[] | select(.class=="APPROX-WIDENING")' whalenet.plan.json
Each of those is a rule that would let more traffic through here than it does today. Decide about each one against the grammar it will land in: the access document is where a grant's src, dst and ip are defined, and acl test answers what a rewritten rule would do before it is ever published.
4. Know what the plan could not read
The plan names these before it starts, rather than halfway through, so you can decide how to carry them by hand.
| Not readable | Why it matters |
|---|---|
| Auth-key secrets | The source schema only ever returns them at creation. |
| Node private keys | They never leave the machine that holds them. |
| Directory-synced group membership | It lives in the identity provider, not in the mesh. |
| Per-node serve and funnel configuration | It is local state on each node. |
The last of these is the one worth a pass by hand, because it lives on each node rather than in any central record: walk the nodes and note which of them puts a port in front of an audience today. What the equivalent looks like here is serve and funnel.
What the plan is
The plan is a document you read and keep with the change it belongs to. Nothing in your account moves because one exists, and a node listed in it holds no address until something acts on the file. One detail shapes how it reads: an address here is drawn at random inside your own /64 and the canonical name follows from it, so the plan allocates both up front rather than letting you pick a name. Nodes, names and tags covers that derivation.