Migration + adoption

Bring existing infrastructure under formae management without breaking what's running.

Scenarios covered:

I want to turn existing cloud resources into infrastructure code

When to use this

Use this workflow when you:

  • Have resources created via the cloud console, CLI, or another tool and want them represented as code
  • Need to start managing existing resources — change them, tag them, evolve them through code

formae discovers your existing cloud resources, extracts them as Pkl code, and lets you bring them under management — all without touching or recreating anything.

What you'll do

  1. Discover and extract — set up discovery, review resources, extract to Pkl
  2. Add a stack label — assign resources to a stack
  3. Bring resources under management — apply and verify

Step-by-step

Before you begin: review the baseline prerequisites and confirm discovery is enabled (it is by default).

Step 1: Discover and extract your resources

Follow the First Steps guide to set up a discoverable target, wait for discovery, and view what's in your account. Then extract the resources you want to manage:

formae extract --query="managed:false" discovered.pkl

For large accounts, extract by type:

formae extract --query="managed:false type:AWS::EC2::VPC" networking.pkl
formae extract --query="managed:false type:AWS::S3::Bucket" storage.pkl

Step 2: Add a stack label

Open the extracted file and uncomment the stack label. This tells formae you want to manage these resources:

forma {
  new formae.Stack {
    label = "imported-networking"  // <-- uncomment and set this
  }

  // ... your extracted resources
}

Step 3: Bring resources under management

Apply the edited file:

formae apply --mode reconcile --watch networking.pkl

formae matches the extracted resources with the discovered ones by their cloud IDs. Nothing is recreated — the resources simply move from "unmanaged" to "managed" status.

Verify:

formae inventory resources --query="stack:imported-networking"

Your resources are now under formae management.

Tips + gotchas

Tip Details
Nothing is recreated Bringing resources under management is a metadata operation. Your live infrastructure isn't touched.
Extract is a snapshot The extracted file reflects the state at extraction time. If the resource changes before you apply, formae will detect the difference.

Common gotcha: The extracted stack label is commented out on purpose. If you apply without uncommenting it, the resources won't be assigned to a stack and won't become managed.

What's next

Goal Guide
Adopt gradually without risk I want to adopt formae incrementally (below)
Explore before importing First Steps → Explore your cloud account
Understand managed vs unmanaged Core Concepts → Unmanaged Resources
Configure discovery Configuration → Discovery

I want to adopt formae incrementally without breaking what's running

When to use this

Use this workflow when you:

  • Already have production infrastructure managed manually, by Terraform, or another tool
  • Can't do a big-bang migration — you need to onboard gradually, one piece at a time
  • Need zero downtime — nothing should break during adoption

The key insight: formae doesn't require you to import everything at once. You can manage some resources with formae, leave others alone, and expand scope over time.

What you'll do

  1. Start with discovery — observe without managing
  2. Import a low-risk subset — bring a few resources under management
  3. Grow with patch mode — add new resources without affecting what's already managed

Step-by-step

Before you begin: review the baseline prerequisites and complete the discovery setup from First Steps or the import guide above.

Step 1: Start with visibility (discovery only)

If you haven't already, set up discoverable targets and let discovery run. This gives you a full inventory without touching anything:

formae inventory resources --query="managed:false" --max-results=100

At this point, formae is purely observational. Your existing infrastructure is completely unaffected.

Step 2: Pick a low-risk starting point

Choose resources that are:

  • Standalone — few or no dependencies on other resources
  • Non-critical — dev/staging before production
  • Simple — S3 buckets, security groups, or DNS records are good candidates

Extract your candidates:

formae extract --query="managed:false type:AWS::S3::Bucket" s3-buckets.pkl

Step 3: Bring the first resources under management

Edit the extracted file to add a stack label, then apply:

formae apply --mode reconcile --watch s3-buckets.pkl

Verify:

formae inventory resources --query="stack:imported-s3"

These resources are now managed by formae. Everything else remains untouched and unmanaged.

Step 4: Add new resources alongside existing ones

Use patch mode to add new infrastructure to an existing stack without affecting what's already there:

formae apply --mode patch --watch new-resources.pkl

Patch mode creates and updates but never destroys — the safest way to grow your formae-managed footprint.

Tips + gotchas

Tip Details
Import dependencies together A subnet depends on a VPC. Import the VPC first (or together in the same forma) so references resolve.
One stack per concern Don't dump everything into one stack.

What's next

Goal Guide
Import specific resources I want to turn existing resources into code (above)
Automate deployments CI/CD Integration
Build self-service for teams Platform Engineering → Self-service infrastructure
Understand sync in depth Core Concepts → Synchronization