Deal with out-of-band changes

Infrastructure changes outside your code more often than you would like. A teammate tightens a setting in the console, an incident responder adds a tag, an autoscaler rewrites a value. formae’s job is to keep your code and your running infrastructure in agreement, so when reality drifts it tells you, and it does not silently paper over the difference. This guide walks a real drift end to end: you change a resource in the AWS console, formae detects it, and you either pull the change into your code or discard it. It uses the Lifeline foundation example, basic_infrastructure.pkl, which provisions a VPC, an internet gateway, subnets, routing, and security groups.

Set the scene

Apply the foundation so formae is managing it:

formae apply --mode reconcile basic_infrastructure.pkl

All fifteen resources come up, and the stack is now under management. Your code and your infrastructure agree.

Change something outside formae

Now make a change the way a teammate in a hurry would: in the AWS console, open the internet gateway that the foundation created and add a tag, Owner = platform-team. Leave everything else alone.

The AWS console tag editor adding an Owner tag to the lifeline internet gateway — Adding a tag to the internet gateway directly in the AWS console, outside formae.

The gateway now carries a tag that exists nowhere in your code. Your infrastructure has drifted from its source of truth.

formae detects the drift

The agent synchronizes with your cloud on an interval, reading the resources it manages and noticing anything that changed underneath it. Within a sync cycle it sees the new tag on the gateway.

CLI
AI assistants

Reconcile the foundation as you normally would. formae reads the live state first, sees that the stack changed since the last reconcile, and stops rather than overwriting the change blindly:

formae apply --mode reconcile basic_infrastructure.pkl

Instead of applying, formae opens an interactive screen listing every resource that drifted and lets you decide what to do, right here:

  formae apply                                                                                  reconcile rejected
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

  Your infrastructure changed outside formae since the last reconcile.

  Keep a change: extract the resource, fold it into your code, then re-apply.
  Press r to discard all out-of-band changes and re-apply your code with —force.

  Stack: lifeline (1 change)
  ──────────────────────────────────────────────────────────
  ▸ [x] update  lifeline-igw (AWS::EC2::InternetGateway)

  1 selected
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  e: extract selected  r: revert all (—force)  q: abort                                                   ?: help

formae will not clobber the change. From this screen you choose: press e to extract the selected resource and keep the change, or r to revert all out-of-band changes. You now decide: absorb the change or discard it.

With the formae MCP plugin connected, just ask whether your code still matches reality:

Conversation

You

Is my codebase still in sync with what’s actually running?

Assistant

Not quite. Since your last reconcile, one resource on the lifeline stack changed outside formae: the internet gateway lifeline-igw was updated. Something added a tag to it in the console. Do you want to absorb that change into your forma, or discard it?

Absorb the change into your code

The tag is worth keeping, so make your code describe it. This is the path formae offers on the rejection screen: extract the live resource, fold the change into your forma, and re-apply.

CLI
AI assistants

Extract the drifted resource

On the rejection screen, with lifeline-igw selected, press e. formae asks where to write the resource and extracts it live, tag and all:

  formae apply                                                                                  reconcile rejected
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

  Extracting 1 resource as code:
    lifeline-igw (AWS::EC2::InternetGateway)

  Extract to: ./extracted-drift.pkl█

  Don’t apply this file directly. It holds only the selected resource(s), so
  reconciling it would delete every other resource in the stack.

  Copy the values you want to keep into your forma, then re-apply with —force:
    formae apply —mode reconcile —force basic_infrastructure.pkl

Press enter to confirm. formae writes the file and reminds you that it holds only the selected resource, so you fold the values into your own forma rather than applying the file directly:

Extracted 1 resource(s) to ./extracted-drift.pkl
Fold the values you want to keep into your forma, then re-apply with —force:
formae apply —mode reconcile —force basic_infrastructure.pkl

Fold the change into your forma

Copy the tag into the gateway’s definition in your own code. In the Lifeline example the gateway lives in network_resources.pkl:

hidden igw: internetgateway.InternetGateway = new {
  label = "lifeline-igw"
  tags {
    new { key = "Name"; value = formae.value(name + "-igw").setOnce }
    new { key = "Owner"; value = "platform-team" }
  }
}

Re-apply, and the drift is gone

Reconcile again with --force. Your code now matches reality, so this re-applies your forma (tag included) and clears the drift flag on the stack:

formae apply --mode reconcile --force basic_infrastructure.pkl

The tag is now part of your committed infrastructure, not drift. Your code and your cloud describe the same thing again.

Conversation

You

Absorb it. That tag should be part of our code going forward.

Assistant

I extracted the live internet gateway and added its Owner = platform-team tag to the gateway definition in network_resources.pkl. Reconciling now reports no changes, so your forma and the running stack agree again and the tag is under management. Want me to commit the change?

You

Yes, commit it.

Or discard the change

If the change was a mistake or a temporary hack, do the opposite from the same rejection screen: press r to revert all out-of-band changes. formae shows exactly what it will undo, down to the field, and asks you to confirm:

  formae apply                                                                                  reconcile rejected
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

  This will revert ALL out-of-band changes by re-applying with —force:

    revert  lifeline-igw (AWS::EC2::InternetGateway)      Tags

  Are you sure? This cannot be undone. (y/N)

Confirm with y and formae re-applies your unchanged code with --force, removing the tag and returning the gateway to exactly what your code describes. You can also run formae apply --mode reconcile --force basic_infrastructure.pkl directly.

Reverting overwrites every out-of-band change on the stack, not just the one you have in mind. Extract and review the changes first if you are not certain what you are discarding.

Get started

Guides

Concepts

Reference

Deal with out-of-band changes

Set the scene

Change something outside formae

formae detects the drift

Absorb the change into your code

Or discard the change

See also

​Set the scene

​Change something outside formae

​formae detects the drift

​Absorb the change into your code

​Or discard the change

​See also

Set the scene

Change something outside formae

formae detects the drift

Absorb the change into your code

Or discard the change

See also