Bring existing resources under management

You have resources created through the console, a CLI, or another tool, and you want formae to manage them: change them, tag them, evolve them through code. formae discovers them, then lets you extract them as Pkl and bring them under management without touching or recreating anything.

Before you start: discovery has to have run on a discoverable target. If you haven’t set one up yet, do Create a target first. The examples below adopt AWS internet gateways; use the equivalent types for your own resources.

CLI
AI assistants

Find the unmanaged resources

Discovery records the resources formae doesn’t manage yet. List what it found in your inventory:

formae inventory resources --query="managed:false"

The query matches resources by attribute, so add filters to home in on exactly what you want. Here, only the internet gateways:

formae inventory resources --query="managed:false type:AWS::EC2::InternetGateway"

  formae inventory
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
╭─────────────╮
│ 1 Resources │   2 Targets    3 Stacks    4 Policies
─╯             ╰────────────────────────────────────────────────────────────────────────────────────────────────────

Label ▲                   Stack            Type                          NativeID
────────────────────────────────────────────────────────────────────────────────────────────────────────────
formae-auto-recon-inline-1⚠ unmanaged      AWS::EC2::InternetGateway     igw-037caa5c87583128e
formae-auto-recon-standal…⚠ unmanaged      AWS::EC2::InternetGateway     igw-0555aa2884ab0d7a8
formae-lgtm-igw           ⚠ unmanaged      AWS::EC2::InternetGateway     igw-0ec4e39eb6bf0a348
igw-00fda294a8aa7d0ce     ⚠ unmanaged      AWS::EC2::InternetGateway     igw-00fda294a8aa7d0ce
igw-03ff9cdf7e484fcbe-2   ⚠ unmanaged      AWS::EC2::InternetGateway     igw-03ff9cdf7e484fcbe
igw-06c867a1939f44327     ⚠ unmanaged      AWS::EC2::InternetGateway     igw-06c867a1939f44327
igw-0e65d7a67d98849cf     ⚠ unmanaged      AWS::EC2::InternetGateway     igw-0e65d7a67d98849cf
lifeline-1558-igw-2       ⚠ unmanaged      AWS::EC2::InternetGateway     igw-03c849fb5154f7715
lifeline-abc1-igw-1       ⚠ unmanaged      AWS::EC2::InternetGateway     igw-0b9e65ff163e1b5ff

Showing 9 of 9 resources (filtered)
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
  / managed:false type:AWS::EC2::InternetGateway                                                     /: edit query
────────────────────────────────────────────────────────────────────────────────────────────────────────────────────

You can filter by attributes like type, label, and target, and use * wildcards. See the CLI reference for the full query syntax.

Extract the ones you want

Pull the resources you want into a forma:

formae extract --query="managed:false type:AWS::EC2::InternetGateway" networking.pkl

Initialized new Pkl project at .
Initialized pkl project at ’.’
Extracted 9 resources to networking.pkl

formae-auto-recon-inline-1 (AWS::EC2::InternetGateway) on stack

unmanaged</span><br/>&nbsp;&nbsp;<span style={{color:'rgb(129,209,219)'}}>formae-auto-recon-standalone-1</span>&nbsp;(<span style={{color:'rgb(170,170,170)'}}>AWS::EC2::InternetGateway</span>)&nbsp;on&nbsp;stack&nbsp;<span style={{color:'rgb(232,232,232)'}}>

unmanaged
formae-lgtm-igw (AWS::EC2::InternetGateway) on stack

unmanaged</span><br/>&nbsp;&nbsp;<span style={{color:'rgb(129,209,219)'}}>igw-00fda294a8aa7d0ce</span>&nbsp;(<span style={{color:'rgb(170,170,170)'}}>AWS::EC2::InternetGateway</span>)&nbsp;on&nbsp;stack&nbsp;<span style={{color:'rgb(232,232,232)'}}>

unmanaged
igw-03ff9cdf7e484fcbe-2 (AWS::EC2::InternetGateway) on stack

unmanaged</span><br/>&nbsp;&nbsp;<span style={{color:'rgb(129,209,219)'}}>igw-06c867a1939f44327</span>&nbsp;(<span style={{color:'rgb(170,170,170)'}}>AWS::EC2::InternetGateway</span>)&nbsp;on&nbsp;stack&nbsp;<span style={{color:'rgb(232,232,232)'}}>

unmanaged
igw-0e65d7a67d98849cf (AWS::EC2::InternetGateway) on stack

unmanaged</span><br/>&nbsp;&nbsp;<span style={{color:'rgb(129,209,219)'}}>lifeline-1558-igw-2</span>&nbsp;(<span style={{color:'rgb(170,170,170)'}}>AWS::EC2::InternetGateway</span>)&nbsp;on&nbsp;stack&nbsp;<span style={{color:'rgb(232,232,232)'}}>

unmanaged
lifeline-abc1-igw-1 (AWS::EC2::InternetGateway) on stack $unmanaged

This writes networking.pkl with the resources you selected. formae creates a PklProject only when there is none anywhere in the directory hierarchy where you extract. Run extract in a fresh, empty directory and it scaffolds a starter project (a PklProject pinning the formae and provider schema packages the resources need, plus a main.pkl) and prints an “Initialized new Pkl project” line. Run it inside a directory already covered by a PklProject and formae writes just networking.pkl, reusing the dependencies already declared there.Usually you extract straight into your existing formae project. When you do, make sure the new file is reachable: either import networking.pkl somewhere in your main.pkl include hierarchy, or copy the extracted resources into a file that is already included. A forma file that nothing imports is written to disk but never applied.

Extracted files need formae 0.88.0 or greater (they use extends "@formae/forma.pkl"). If your project’s PklProject pins an older version, extract still writes the file but prints a notice to bump the formae dependency and run pkl project resolve. See Schema version compatibility.

Move them onto a managed stack

Discovered resources sit on formae’s built-in unmanaged stack, so extract comments the stack label out and leaves you a prompt. Uncomment it and give the resources a stack of your own (the description comes pre-filled by extract; keep it or change it):

local myStack = new formae.Stack {
  // Please provide a stack to bring the resources in this Forma under management
  label = "imported-networking"
  description = "Resources imported with formae extract"
}

Applying moves them off the unmanaged stack and onto imported-networking, where formae manages them.

Apply, then verify

formae apply --mode reconcile networking.pkl

formae recognizes these as the resources discovery already found, so nothing is recreated. It puts each one under management, moving them off the unmanaged stack and onto imported-networking. Confirm:

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

With the formae MCP plugin connected, you drive the same flow as a conversation. Ask what discovery turned up, name what you want to adopt, and let the assistant’s formae-import skill extract, simulate, and apply:

Conversation

You

Do we have any unmanaged resources?

Assistant

Discovery has six unmanaged internet gateways on the unmanaged stack: legacy-igw-inline, legacy-igw-standalone, igw-0a1b2c3d4e5f6a7b8, igw-0f9e8d7c6b5a4f3e2, webapp-1558-igw-1, and webapp-abc1-igw. Want me to bring them under management?

You

Bring the internet gateways under management.

Assistant

I’ll extract the six into a new imported-networking stack and simulate first. The simulation creates the stack and moves 6 resources from unmanaged to imported-networking, putting them under management with nothing recreated. Apply it?

You

Yes.

Assistant

Applied. The six internet gateways are now managed on imported-networking, and nothing was recreated.

The assistant always simulates and confirms before applying, so you see exactly what will happen first. Narrow the request however you like (“just the internet gateways”, “the ones whose name starts with webapp-”) or name the target stack yourself.

Get started

Guides

Concepts

Reference

Bring existing resources under management

See also

​See also

See also