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:

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

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
}