Discovery

formae continuously discovers, versions and stores new resources.

Discovery is enabled by default and automatically scans your infrastructure for new resources in targets that are discoverable (which is also the default). Simply apply your targets and formae will start discovering resources every 10 minutes.

Configuring discovery targets

Discovery requires you to mark targets as discoverable in your forma files. Targets are discoverable by default (discoverable = true), but you can explicitly disable discovery for specific targets by setting discoverable = false.

forma {
  // This target will be scanned for resources during discovery (default behavior)
  new formae.Target {
    label = "prod-us-east-1"
    // discoverable = true is the default - no need to specify explicitly
    config = new aws.Config {
      region = "us-east-1"
    }
  }

  // This target will NOT be scanned for resources
  new formae.Target {
    label = "dev-us-west-2"
    discoverable = false  // Explicitly disable discovery
    config = new aws.Config {
      region = "us-west-2"
    }
  }
}

Apply the forma to register the targets:

formae apply --mode reconcile target.pkl

Is this safe? Yes. When you apply a target-only forma (no stack, no resources), reconcile mode has nothing to destroy. Reconcile only removes resources that:

1. Were previously part of the same stack in a prior apply, AND
2. Are no longer defined in the current forma

Since a target-only forma contains no stack or resources, there's nothing to reconcile against. Your existing infrastructure remains untouched.

Once applied, targets that are discoverable (which is the default) will be included in periodic discovery scans.

How Discovery Works

To ensure formae can coexist with other tools and doesn't force a rapid migration, newly discovered resources are tracked internally but not managed. You cannot directly change them until you put them under management.

Example workflow:

1. View discovered resources:

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

2. Extract unmanaged resources:

Extract all unmanaged resources:

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

Or extract specific resource types:

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

1. Edit the extracted forma to add a stack label and description:

The extract command generates a stack with a commented-out label. Edit the file to provide a meaningful label and description:

local myStack = new formae.Stack {
  // Please provide a stack to bring the resources in this Forma under management
  label = "discovered-s3-buckets"  // Uncomment and set your label
  description = "S3 buckets discovered from existing infrastructure"  // Update with a meaningful description
}
myStack

1. Apply the forma:

   formae apply --mode reconcile discovered.pkl

Once applied, formae manages these resources as if they were created through formae.

Resource Labeling During Discovery

When formae discovers resources, it needs to assign a label to each one. You can control how these labels are generated using the labelTagKeys setting in your discovery configuration.

How it works:

The labelTagKeys setting specifies which cloud provider tags to use when creating resource labels. For example, a common AWS convention is to use a "Name" tag for resources.

Configuration example:

discovery {
  labelTagKeys = new Listing {
    "Name"
  }
}

With this configuration, if a discovered S3 bucket has a tag Name: my-app-bucket, the resource label will be set to my-app-bucket.

Using multiple tags:

You can specify multiple tags to create more descriptive labels:

discovery {
  labelTagKeys = new Listing {
    "Name"
    "Environment"
  }
}

If a resource has tags Name: web-server and Environment: production, the label will be web-server-production (tags are concatenated with a dash).

Tip: Choose tag keys that reflect your organization's tagging strategy. Using consistent tags across your infrastructure makes discovered resource labels more meaningful and easier to work with.

Handling duplicate labels:

If the resulting label is not unique, formae automatically appends an incrementing integer to ensure uniqueness. This is common with resources launched from the same template, like EC2 instances: - First instance: web-server-production - Second instance: web-server-production-1 - Third instance: web-server-production-2

Tip: Discovery is especially useful when adopting formae in an existing environment. You can gradually bring resources under management without disrupting your current workflows.

Resources managed by formae can still be managed by other tools at the same time. The synchronization process ensures formae stays up to date.