Discovery filters

Discovery filters exclude resources from being added to formae’s inventory. Use them to skip resources that shouldn’t be managed directly, typically resources that are managed by other resources.

Why Filter Resources?

Some cloud resources are created and managed by other resources. For example:

EC2 instances in an Auto Scaling Group are managed by the ASG
Node instances in an EKS Auto Mode cluster are managed by EKS
Resources created by CloudFormation are managed by the stack

These resources don’t belong in your infrastructure code because you don’t control them directly. You control the thing that manages them. Discovery filters prevent formae from cluttering your inventory with resources you shouldn’t touch. You might also filter resources that users have explicitly tagged to exclude from formae management.

How Filtering Works

During discovery:

Your plugin’s List() returns native IDs of resources
The agent calls Read() on each resource to get its properties
Filters evaluate JSONPath expressions against those properties
Resources matching a filter are skipped (not added to inventory)

Filters also apply during synchronization. The agent periodically re-reads each resource already in inventory. If an unmanaged resource now matches a filter, it’s removed from inventory on that pass, so a filter you add later retroactively cleans up matching resources that were discovered before the filter existed. Only unmanaged (discovered) entries are evicted this way; resources under formae management are never removed even if they match a filter, and eviction removes only the inventory entry, never the cloud resource.

Implementing Filters

Return filters from your plugin’s DiscoveryFilters() method:

func (p *Plugin) DiscoveryFilters() []plugin.MatchFilter {
    return []plugin.MatchFilter{
        {
            ResourceTypes: []string{"AWS::EC2::Instance"},
            Conditions: []plugin.FilterCondition{
                {
                    PropertyPath:  `$.Tags[?(@.Key=~'eks:automode:.*')]`,
                    PropertyValue: "", // empty = existence check
                },
            },
        },
    }
}

This filter excludes EC2 instances that have any tag key starting with eks:automode:.

Filter Logic

Within a filter: All conditions must match (AND). A resource is excluded only if every condition in the filter evaluates to true. Between filters: Any filter can exclude (OR). If you return multiple filters, a resource is excluded if it matches any one of them.

Condition Structure

type FilterCondition struct {
    PropertyPath  string // JSONPath expression
    PropertyValue string // Expected value (empty = existence check)
}

PropertyPath: A JSONPath expression evaluated against the resource properties
PropertyValue: If empty, the condition matches when the path returns any value. If non-empty, the condition matches when the path returns this exact string.

Examples

Exclude by tag value

{
    PropertyPath:  `$.Tags[?(@.Key=="formae:skip")].Value`,
    PropertyValue: "true",
}

Exclude by tag key pattern (regex)

{
    PropertyPath:  `$.Tags[?(@.Key=~'aws:cloudformation:.*')]`,
    PropertyValue: "",
}

Exclude by property value

{
    PropertyPath:  "$.Status",
    PropertyValue: "DELETED",
}

No Filters

If your plugin doesn’t need filters, return nil:

func (p *Plugin) DiscoveryFilters() []plugin.MatchFilter {
    return nil
}

Get started

Guides

Concepts

Reference

Discovery filters

Why Filter Resources?

How Filtering Works

Implementing Filters

Filter Logic

Condition Structure

Examples

Exclude by tag value

Exclude by tag key pattern (regex)

Exclude by property value

No Filters

​Why Filter Resources?

​How Filtering Works

​Implementing Filters

​Filter Logic

​Condition Structure

​Examples

​Exclude by tag value

​Exclude by tag key pattern (regex)

​Exclude by property value

​No Filters

Why Filter Resources?

How Filtering Works

Implementing Filters

Filter Logic

Condition Structure

Examples

Exclude by tag value

Exclude by tag key pattern (regex)

Exclude by property value

No Filters