Refactoring: moved, removed, and orphans
Configuration changes. You rename an executor, move one into a stack, turn a count into a for_each, or retire a node you don’t want any more. The question each time is the same: does vect see “the same thing under a new name”, or “one thing gone and another thing new”? In Terraform you answer with terraform state mv, moved blocks, removed blocks, and a careful reading of the plan. This guide explains vect’s version: what it does when you just edit the configuration, the two blocks that tell it what you meant, and the edge cases around them.
The examples are small projects under docs/site/examples/topics/refactoring/ in the vect repository. They use only the built-in terraform_data resource, so they run against a local Temporal dev server. IDs, run IDs, and approval request IDs in the output will differ from yours. The commands show vect plan and vect apply output trimmed to vect’s own summary lines. The engine’s output for each executor is left out.
Part 5 of First steps showed one moved block renaming one executor. We start from there and go further.
Inventory is the thing being refactored
To see why vect needs these blocks at all, recall what it compares. A plan doesn’t compare your configuration to the cloud. It compares it to Inventory, the per-address records of what vect applied. Each executor instance has one record, keyed by its address, such as terraform.cache[0] or stack.data.terraform.db. The engine’s own state (the .tfstate file, or your S3 object) lives beside that record and is found through it.
Rename a block and the address changes, so the record no longer matches anything. With no further information, vect sees two facts: an address in Inventory that the configuration no longer declares, and an address in the configuration that Inventory has never seen. That’s a destroy and a create. Everything below is about saying something other than that.
terraform state mv edits it by hand, outside any plan. In vect there is no editing step. You write the intent in the configuration, plan shows what it will do (including an approval request for the move), and apply does it. The record of the move stays in Inventory’s version history.Moving an address with moved
A moved block names the old address and the new one:
moved {
from = "terraform.api"
to = "terraform.web"
}Both are string literals in the address grammar, for executor instances, and both are relative to the stack that contains the block. The rules that matter:
- A
movedacts only whenfromis in Inventory andtois not. Iffromis gone andtoexists, it does nothing, so the block can stay in your configuration after it has done its job, or you can delete it (RUN-MOVED-1). - An acting
movedraises an approval request of kindstate_move, so you see it inplanand approve it inapply, as you did in the tutorial. - It moves the engine’s state first (for
terraform, it copies the state object to whereto’s state belongs), then transfers the Inventory record, then planstoas usual. Ifto’s inputs also changed, you get the move and the update in one run.
Renaming across a stack
The move can cross stack boundaries as well as names. Here is a project (examples/topics/refactoring/keys-before) with a root-level executor and a stack:
executor "terraform" "cache" {
source = "./roots/unit"
count = 2
inputs = {
name = "cache"
}
}
executor "terraform" "api" {
source = "./roots/unit"
inputs = {
name = "api"
}
}
stack "svc" {
source = "./stacks/svc"
}executor "terraform" "db" {
source = "../../roots/unit"
inputs = {
name = "db"
}
}We apply it, and Inventory has four records: terraform.cache[0], terraform.cache[1], terraform.api, and stack.svc.terraform.db. Now we want three changes: api becomes web, the svc stack becomes data, and the two cache nodes get meaningful keys instead of numbers. This is the whole refactor (examples/topics/refactoring/keys):
executor "terraform" "cache" {
source = "./roots/unit"
for_each = { east = "cache", west = "cache" }
inputs = {
name = each.value
}
}
executor "terraform" "web" {
source = "./roots/unit"
inputs = {
name = "api"
}
}
stack "data" {
source = "./stacks/data"
}
moved {
from = "terraform.cache[0]"
to = "terraform.cache[\"east\"]"
}
moved {
from = "terraform.cache[1]"
to = "terraform.cache[\"west\"]"
}
moved {
from = "terraform.api"
to = "terraform.web"
}
moved {
from = "stack.svc.terraform.db"
to = "stack.data.terraform.db"
}(The stacks/svc folder is renamed to stacks/data, and its contents don’t change.) The instance keys follow the address grammar: [0] for count, ["east"] for for_each, with the quotes escaped inside the HCL string (LANG-ADDR-5). A move from a keyed instance to a different key is how you convert count to for_each, or re-key a for_each when the keys you chose turn out to be wrong. Each instance is its own address, so each gets its own moved block.
The stack’s address step stack.svc also changed, and the executor db didn’t. You say so with the full address on both sides, relative to the root. A moved block inside a stack uses addresses relative to that stack, so it can rename the stack’s own executors but not reach outside it. To move something across stack boundaries, put the block in a stack that contains both ends, which usually means the root.
Plan it:
vect plan…
plan of workspace "dev": succeeded (run 01a1e26a-a78b-75a1-84ac-bc385adce4e5)
stack.data.terraform.db no-op move stack.svc.terraform.db → stack.data.terraform.db; no changes
terraform.cache["east"] no-op move terraform.cache[0] → terraform.cache["east"]; no changes
terraform.cache["west"] no-op move terraform.cache[1] → terraform.cache["west"]; no changes
terraform.web no-op move terraform.api → terraform.web; no changes
approval requests:
apr_6bf33e48445f4c8a0de6cd17 state_move stack.data.terraform.db move stack.svc.terraform.db → stack.data.terraform.db
apr_ee98c445d2c9cafb01049333 state_move terraform.cache["east"] move terraform.cache[0] → terraform.cache["east"]
apr_05a1efea4b8d52210e068d14 state_move terraform.cache["west"] move terraform.cache[1] → terraform.cache["west"]
apr_3db0ef05dfa94b5a94c67363 state_move terraform.web move terraform.api → terraform.webFour no-ops and four approval requests, and no creates and no destroys. That’s the check you want from a refactoring plan: if you see a create next to a destroy where you meant a rename, you missed a moved block. Apply it (the tutorial answered each prompt by hand; --auto-approve answers them all):
vect apply --auto-approve…
apply of workspace "dev": succeeded (run 01a1e26a-aea4-7589-af00-ad779dbe6e7a)
stack.data.terraform.db unchanged no changes
terraform.cache["east"] unchanged no changes
terraform.cache["west"] unchanged no changes
terraform.web unchanged no changes
approval requests:
apr_6bf33e48445f4c8a0de6cd17 state_move stack.data.terraform.db move stack.svc.terraform.db → stack.data.terraform.db [approved by auto-approve]
apr_ee98c445d2c9cafb01049333 state_move terraform.cache["east"] move terraform.cache[0] → terraform.cache["east"] [approved by auto-approve]
apr_05a1efea4b8d52210e068d14 state_move terraform.cache["west"] move terraform.cache[1] → terraform.cache["west"] [approved by auto-approve]
apr_3db0ef05dfa94b5a94c67363 state_move terraform.web move terraform.api → terraform.web [approved by auto-approve]
deployment pointer 2 appendedvect inventoryADDRESS VERSION STATUS
stack.data.terraform.db 1 converged
stack.svc.terraform.db 2 destroyed
terraform.api 2 destroyed
terraform.cache["east"] 1 converged
terraform.cache["west"] 1 converged
terraform.cache[0] 2 destroyed
terraform.cache[1] 2 destroyed
terraform.web 1 converged
…The new addresses start with their own records. Each old address ends with a final version that’s a tombstone: a marker that says the record is retired, not a live record. Inventory shows a tombstoned record with the status destroyed. As in the tutorial, that means “the record was retired”, and nothing in the real world was touched. (The excerpt leaves out the POINTER table that vect inventory prints below the records.) The moved executors kept their engine state: for db, the terraform_data ID in the engine’s output is the same before and after the move.
Plan once more and the moves still show as notes (move terraform.api → terraform.web) but there are no approval requests, because there is nothing left to act on. The note reads from the moved_from marker the move left on the new record. You can delete the moved blocks whenever you like.
Coming from Terraform: Terraform’s moved addresses resources inside one state, so it can rename aws_instance.a to module.x.aws_instance.a. vect’s moved works one level up: it addresses executor instances, and the state of the whole root moves with them. It can’t reach inside an executor. We tried terraform.api::terraform_data.this as an address (the :: form that --target accepts) and got an error, captured from examples/topics/refactoring/invalid-moved-sub:
Error: Invalid from address
on main.hcl line 9, in moved:
9: from = "terraform.api::terraform_data.this"
"terraform.api::terraform_data.this" is not an executor instance address: Expected an attribute
access or an index operator.
Error: Invalid to address
on main.hcl line 10, in moved:
10: to = "terraform.web::terraform_data.this"
"terraform.web::terraform_data.this" is not an executor instance address: Expected an attribute
access or an index operator.Renaming a resource inside a root is still Terraform’s job, in that root: its own moved block, in its own .tf files, which the engine applies when the executor runs. vect plans a root whose only change is such a moved (or an import block) as an update, so the node is applied and the state really moves (EXEC-TF-13).
When state can’t just be copied
An executor whose state needs to be migrated needs one of two things. For terraform, vect copies the state object itself, as above. For anything else, moved accepts a third argument, using, naming a task executor in the same stack that does the migration. While from is still in Inventory, the task runs before to is planned and before from is retired, and the move’s approval is requested before the task runs (RUN-MOVED-5, RUN-MOVED-9). using is a bare reference to the task executor block, not a string (examples/topics/refactoring/using):
executor "temporal_activity" "mig" {
task_queue = "migrations"
activity = "MigrateApiState"
start_to_close_timeout = "5m"
input = {
from = "terraform.api"
to = "terraform.web"
}
}
moved {
from = "terraform.api"
to = "terraform.web"
using = temporal_activity.mig
}Here the activity (which your own worker on the migrations queue implements) does the migration, and vect transfers ownership of the record when it succeeds. Once from is gone, using is skipped. The compiler rejects a string in using, a name that isn’t declared in the stack, and an executor that isn’t a task (LANG-MOVED-1, EXEC-TASK-1). A plan of such a move shows the using task in its note and raises one state_move approval. The example validates and graphs, but we didn’t run it, because the activity needs a worker of yours.
If the move fails partway, vect writes the new record before it tombstones the old one, and a later run that finds both records and the marker finishes the job instead of failing (RUN-MOVED-10).
What the compiler rejects
Some mistakes are caught by validate before any run: two moved blocks with the same from, a from equal to its to, or a chain of blocks that forms a cycle (LANG-MOVED-4). Others are only visible against Inventory. If both from and to exist in Inventory, the move can’t know which wins. The run reports a diagnostic and doesn’t plan to (RUN-MOVED-8). A moved whose from the configuration still declares is a diagnostic (LANG-MOVED-3); we meet it in the last section.
Deleting a block: orphans
Now the case with no hint at all. You delete an executor block, or set enabled = false, or drop a key from a count or for_each. The Inventory record is still there, and the configuration has nothing to say about it. vect calls it an orphan and plans it for destroy (RUN-ORPHAN-1). That’s the same rule as Terraform’s, with one difference that matters: the destroy runs from Inventory alone. The record carries the bundle it was applied from, so vect doesn’t need the deleted block or the old source folder to destroy it (RUN-ORPHAN-2). Orphans are destroyed in reverse dependency order.
Because that can destroy infrastructure, each orphan’s destroys are approval requests like any other destroy. Here is the project examples/topics/refactoring/retire-before after a first apply, with five independent executors: keep, old, adopted, scratch, and canary. We change it to this (examples/topics/refactoring/retire):
executor "terraform" "keep" {
source = "./roots/unit"
inputs = {
name = "keep"
}
}
executor "terraform" "canary" {
source = "./roots/unit"
enabled = false
inputs = {
name = "canary"
}
}
removed {
from = "terraform.adopted"
destroy = false
}
removed {
from = "terraform.scratch"
destroy = true
}
output "canary" {
value = terraform.canary == null ? "disabled" : terraform.canary.name
}Three things happened to the file. The old block was deleted outright, canary was disabled, and adopted and scratch were replaced by removed blocks, which we’ll get to. The plan:
vect plan…
plan of workspace "dev": succeeded (run 01a1e26a-c49c-7bfe-9f83-13894777376a)
terraform.adopted release removed block (destroy = false)
terraform.canary destroy orphan: block is disabled (enabled = false)
terraform.keep no-op inputs unchanged
terraform.old destroy orphan: block no longer exists
terraform.scratch destroy removed block (destroy = true)
approval requests:
apr_7d101f3e0b9570cc3cedd6f1 destroy terraform.canary::terraform_data.this destroy terraform.canary::terraform_data.this
apr_3266a90c4e5dfb2e9243cd9e destroy terraform.old::terraform_data.this destroy terraform.old::terraform_data.this
apr_4000a67c4b36e8b442f0d236 destroy terraform.scratch::terraform_data.this destroy terraform.scratch::terraform_data.thisThe reason column says which rule applied. A release means vect retires the record without touching the infrastructure; the removed section below explains it. old is an orphan because its block no longer exists. canary is an orphan because its block is disabled. scratch is a destroy by request. adopted is a release, and it has no approval request at all, which is the point of the next section. Applying it ends with these Inventory rows (the POINTER table is left out):
ADDRESS VERSION STATUS
terraform.adopted 2 destroyed
terraform.canary 2 destroyed
terraform.keep 1 converged
terraform.old 2 destroyed
terraform.scratch 2 destroyed
…enabled = false
enabled is a meta-argument on executor, data, ephemeral, and stack blocks, and it must be known at plan time: a literal, a global, or a plan-time data value (COMP-PLANTIME-1). A disabled block produces no node that runs. Its address evaluates to a typed null of the block’s output type, so other blocks that read it see a null, and a disabled stack makes all its blocks disabled and its outputs null (COMP-ENABLED-1, COMP-ENABLED-2).
That null is the part to design for. Reading an attribute of a disabled executor is an error, and validate catches it. This is examples/topics/refactoring/invalid-disabled-read:
Error: Attempt to get attribute from null value
on main.hcl line 27, in output "canary":
27: value = terraform.canary.name
This value is null, so it does not have any attributes.The guard in the retire example above (terraform.canary == null ? ... : terraform.canary.name) is the fix. If you have a feature flag that turns an executor on and off, everything downstream of it needs to handle both.
Like Terraform’s count = 0, disabling a block that exists in Inventory destroys it: it becomes an orphan, with the reason block is disabled. Unlike count = 0, there’s no address change to think about.
removed { destroy = false }, below.Targeted runs and orphans
A run with --target looks for orphans only inside the scope you targeted, and a run whose targets are all :: sub-addresses looks for none (RUN-ORPHAN-3). So vect apply --target terraform.keep won’t destroy old. That’s what you want for a quick change in a big project, and it means a targeted run isn’t a way to find out what’s orphaned.
If an orphan’s stored bundle is missing from the CAS, the orphan fails with a diagnostic naming its address and the bundle’s digest, and its record is left unchanged (RUN-ORPHAN-4). A stack composed from a pinned bundle that can’t be loaded is the other special case. Its records are excluded from orphan detection, so a bad pin doesn’t read as “everything under it was deleted” (RUN-ORPHAN-5).
Dropping a node with removed
removed is for the node you want vect to stop managing, and it makes you say whether the infrastructure goes with it:
removed {
from = "terraform.adopted"
destroy = false
}destroy is required, with no default. Deleting the block would destroy, and removed does exactly what you write, so the choice is yours to make.
destroy = falsereleases the node: the Inventory record is retired,PlanDestroyandDestroyare never called, and there’s no approval request (RUN-MOVED-6). The real infrastructure, and the engine’s state file, stay where they are. Use it to hand a resource to another configuration.destroy = truedestroys the node from its recorded version, in reverse dependency order, under the normal approval rules (RUN-MOVED-7). It’s the same result as deleting the block, with a configuration that says so.
In the plan above, adopted was a release with no approval request, and scratch a destroy with one. In Inventory both end as destroyed. That status means “the record is retired” in both cases, so the plan, and the approval requests, are where you see which happened.
removed block, whose lifecycle { destroy = false } forgets a resource. Two differences. vect’s destroy is explicit in both directions, where Terraform’s default is to destroy. And removed here addresses a whole executor, so it replaces terraform state rm for an entire root. Terraform’s state rm for a single resource inside a root is still done in the root.Some details are worth knowing before you use it:
frommay leave off an instance key at any step, and then it covers every recorded instance there.removed { from = "terraform.cache" ... }covers everyterraform.cache[...]record, and so does a keylessstackstep for every instance of that stack (LANG-MOVED-2).- A
removedwhosefromisn’t in Inventory is a no-op, so likemovedthe block can stay or go after it has acted (RUN-MOVED-11). - A
removedfor an address that the configuration still declares is a diagnostic. It’s checked byvalidate, because the two statements contradict each other. Fromexamples/topics/refactoring/invalid-removed-declared:
Error: Removed address is still declared
on main.hcl line 8, in removed:
8: removed {
terraform.cache is still declared in the configuration; delete its block or this removed block
(LANG-MOVED-3).- Two
removedblocks with the samefrom, and aremovedwhosefromalso appears in amovedas either end, are diagnostics too (LANG-MOVED-6). - A targeted run won’t destroy a node that an active node outside the scope still depends on. A release isn’t a destroy for this check, so releasing never gets stuck behind that guard (RUN-TARGET-7).
Re-declaring an address that moved retired
There is one more case. After the move in the first example, terraform.api is a tombstone in Inventory. What if you declare a new executor at that address? You might do this when you split a service in two: api becomes web, and later a brand-new api comes along.
The address is free, because its record is a tombstone and a tombstone isn’t a live record. And the engine’s state at api’s old location is gone, because when a move commits its tombstone, vect deletes the source state object (if the object’s version hasn’t changed under it), so that “a later re-declaration of the old address starts from empty state” (EXEC-TF-8).
Here is the case, from the state at the end of the first example, with a new api block that has its own input (examples/topics/refactoring/invalid-redeclare-with-moved, which is the earlier keys project plus this):
executor "terraform" "api" {
source = "./roots/unit"
inputs = {
name = "api-reborn"
}
}Applied, the new api is created from scratch. (To follow along, copy that example’s main.hcl over yours. As written the example is invalid, as the next paragraphs show; we apply the corrected version, redeclare, at the end of this section.)
But that example still contains the moved block from api to web. That block’s from is now declared again, and vect refuses it before anything runs:
vect validateError: Moved address is still declared
on main.hcl line 31, in moved:
30: moved {
31: from = "terraform.api"
terraform.api is still declared in the configuration; delete its block or this moved block
(LANG-MOVED-3).The same check runs at the start of plan and apply, so no node is touched. The rule is LANG-MOVED-3: a moved.from that the configuration still declares is a diagnostic. The fix is the one the earlier section offered: delete the moved block once it has acted. With the block gone (examples/topics/refactoring/redeclare):
vect apply --auto-approve…
apply of workspace "dev": succeeded (run 01a1e26a-d643-74e5-8a05-d9369511e0aa)
stack.data.terraform.db unchanged no changes
terraform.api applied (run) will run
terraform.cache["east"] unchanged no changes
terraform.cache["west"] unchanged no changes
terraform.web unchanged no changes
deployment pointer 3 appendedBoth api and web are converged. The practical rule: remove a moved block as soon as it has applied, and certainly before you re-use its from address. A moved block you keep around is harmless until you re-declare its from.
Choosing between them
| You did this | vect sees | You want | Write |
|---|---|---|---|
| Renamed a block or stack | old address gone, new address added | the same infrastructure | moved |
Switched count to for_each (or re-keyed) | instances removed and added | the same infrastructure | one moved per instance |
| Deleted a block | an orphan | destroy it | nothing |
| Deleted a block | an orphan | stop managing it, keep the infrastructure | removed { destroy = false } |
| Want it gone, explicitly | an orphan, if you delete the block | destroy it, with intent on record | removed { destroy = true } |
| Want it off for now | enabled = false | destroy it; null reads | enabled = false |
If you’re ever unsure which one a change needs, the plan will tell you, and since plan changes nothing and records approvals without waiting for them, it’s cheap to ask (RUN-PLAN-1). Look at the reason column. A create and a destroy that you think are one thing mean a missing moved.
Where to go from here
- Stacks and projects explains the stack addresses that
movedandremovedare written in. - Inventory, bundles, and storage shows what the records and tombstones are.
- How runs work covers approvals and what a run leaves behind.
- The runtime spec lists every rule above with its ID, including the lease and crash-recovery behavior of moves that this guide doesn’t go into.