Discovery

formae continuously discovers new resources and adds them to its state. This lets you work with any style or workflow in your team and environment.

Discovery must be explicitly configured because every environment is different. Once configured, formae will periodically scan your infrastructure for new resources.

Configuring discovery targets

Discovery requires you to specify which targets (regions/accounts) to scan. This is done in your agent configuration using the scanTargets option:

agent {
  discovery {
    enabled = true
    interval = 10.min
    scanTargets = new Listing {
      new {
        label = "us-east-1-target"
        config = new aws.Config {
          region = "us-east-1"
        }
      }
      new {
        label = "eu-west-1-target"
        config = new aws.Config {
          region = "eu-west-1"
        }
      }
    }
  }
}

Important: Discovery targets are configured separately from the targets you define in your formae.

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