Skip to content
Refactoring

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.

Coming from Terraform: Terraform’s state is one file per root, and 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 moved acts only when from is in Inventory and to is not. If from is gone and to exists, 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 moved raises an approval request of kind state_move, so you see it in plan and approve it in apply, as you did in the tutorial.
  • It moves the engine’s state first (for terraform, it copies the state object to where to’s state belongs), then transfers the Inventory record, then plans to as usual. If to’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:

main.hcl
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"
}
stacks/svc/main.hcl
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):

main.hcl
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.web

Four 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 appended
vect inventory
ADDRESS                  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):

main.hcl
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):

main.hcl
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.this

The 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.

A default you can swap: “no longer in the configuration” means “destroy” by default. If you want one specific address to be forgotten rather than destroyed, say so with 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 = false releases the node: the Inventory record is retired, PlanDestroy and Destroy are 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 = true destroys 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.

Coming from Terraform: this is Terraform’s 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:

  • from may leave off an instance key at any step, and then it covers every recorded instance there. removed { from = "terraform.cache" ... } covers every terraform.cache[...] record, and so does a keyless stack step for every instance of that stack (LANG-MOVED-2).
  • A removed whose from isn’t in Inventory is a no-op, so like moved the block can stay or go after it has acted (RUN-MOVED-11).
  • A removed for an address that the configuration still declares is a diagnostic. It’s checked by validate, because the two statements contradict each other. From examples/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 removed blocks with the same from, and a removed whose from also appears in a moved as 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 validate
Error: 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 appended

Both 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 thisvect seesYou wantWrite
Renamed a block or stackold address gone, new address addedthe same infrastructuremoved
Switched count to for_each (or re-keyed)instances removed and addedthe same infrastructureone moved per instance
Deleted a blockan orphandestroy itnothing
Deleted a blockan orphanstop managing it, keep the infrastructureremoved { destroy = false }
Want it gone, explicitlyan orphan, if you delete the blockdestroy it, with intent on recordremoved { destroy = true }
Want it off for nowenabled = falsedestroy it; null readsenabled = 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