AWS Filters

This document provides guidance on filtering AWS zones using various strategies and flags.

Strategies for Scoping Zones

Without specifying these flags, management applies to all zones.

In order to manage specific zones, there is a possibility to combine multiple options

Argument	Description	Flow Control
--zone-id-filter	Specify multiple times if needed	OR
--domain-filter	By domain suffix - specify multiple times if needed	OR
--regex-domain-filter	By domain suffix but as a regex - overrides domain-filter	AND
--exclude-domains	To exclude a domain or subdomain	OR
--regex-domain-exclusion	Subtracts its matches from regex-domain-filter’s matches	AND
--aws-zone-type	Only sync zones of this type [public\|private]	OR
--aws-zone-tags	Only sync zones with this tag	AND

Minimum required configuration

args:
    --provider=aws
    --registry=txt
    --source=service

Filter by Zone Type

If this flag is not specified, management applies to both public and private zones.

args:
    --aws-zone-type=private|public # choose between public or private
    ...

Filter by Domain

Specify multiple times if needed.

args:
    --domain-filter=example.com
    --domain-filter=.paradox.example.com
    ...

Example --domain-filter=example.com will allow for zone example.com and any zones that end in .example.com, including an.example.com, i.e., the subdomains of example.com.

When there are multiple domains, filter --domain-filter=example.com will match domains example.com, ex.par.example.com, par.example.com, x.par.eu-west-1.example.com.

And if the filter is prepended with . e.g., --domain-filter=.example.com it will allow only zones that end in .example.com, i.e., the subdomains of example.com but not the example.com zone itself. Example result: ex.par.eu-west-1.example.com, ex.par.example.com, par.example.com.

Note: if you prepend the filter with “.”, it will not attempt to match parent zones.

Filter by Zone ID

Specify multiple times if needed, the flow logic is OR

args:
    --zone-id-filter=ABCDEF12345678
    --zone-id-filter=XYZDEF12345888
    ...

Filter by Tag

Specify multiple times if needed, the flow logic is AND

Keys only

args:
    --aws-zone-tags=owner
    --aws-zone-tags=vertical

Or specify keys with values

args:
    --aws-zone-tags=owner=k8s
    --aws-zone-tags=vertical=k8s

Can’t specify multiple or separate values with commas: key1=val1,key2=val2 at the moment.
Filter only by value --aws-zone-tags==tag-value is not supported.

args:
    --aws-zone-tags=team=k8s,vertical=platform # this is not supported
    --aws-zone-tags==tag-value # this is not supported

Filtering Workflows

Filtering Sequence

The diagram describes the sequence for filtering AWS zones.

flowchart TD
    A["zones"] --> B{"Is zonesCache valid?"}
    B -- Yes --> C["Return cached zones"]
    B -- No --> D["Initialize zones map"]
    D --> E["For each profile and client"]
    E --> F["Create paginator"]
    F --> G{"Has more pages?"}
    G -- Yes --> H["Get next page"]
    H --> I["For each zone in page"]
    I --> J{"Match zoneIDFilter?"}
    J -- No --> G
    J -- Yes --> K{"Match zoneTypeFilter?"}
    K -- No --> G
    K -- Yes --> L{"Match domainFilter?"}
    L -- No --> M{"zoneMatchParent?"}
    M -- No --> G
    M -- Yes --> N{"Match domainFilter parent?"}
    N -- No --> G
    N -- Yes --> O{"zoneTagFilter specified?"}
    O -- Yes --> P["Add zone to zonesToValidate"]
    O -- No --> Q["Add zone to zones map"]
    P --> Q
    Q --> G
    G -- No --> R{"zonesToValidate not empty?"}
    R -- Yes --> S["Get tags for zones"]
    S --> T["For each zone and tags"]
    T --> U{"Match zoneTagFilter?"}
    U -- No --> V["Delete zone from zones map"]
    U -- Yes --> W["Keep zone in zones map"]
    V --> W
    W --> R
    R -- No --> X["Update zonesCache"]
    X --> Y["Return zones"]

Filtering Flow

The is a sequence diagram that describes the interaction between external-dns, AWSProvider, and Route53Client
during the filtering process. Here is a high-level description:

sequenceDiagram
    participant external-dns
    participant AWSProvider
    participant Route53Client

    external-dns->>AWSProvider: zones
    alt Cache is valid
        AWSProvider-->>external-dns: return cached zones
    else

        AWSProvider->>Route53Client: ListHostedZonesPaginator
        loop While paginator.HasMorePages
            Route53Client->>AWSProvider: paginator.NextPage
            alt ThrottlingException
                AWSProvider->>external-dns: error
            else
                AWSProvider-->>external-dns: return error
            end
            AWSProvider->>AWSProvider: Filter zones
            alt Tags need validation
                AWSProvider->>Route53Client: ListTagsForResources
                Route53Client->>AWSProvider: return tags
                AWSProvider->>AWSProvider: Validate tags
            end
        end
        alt Cache duration > 0
            AWSProvider->>AWSProvider: Update cache
        end
        AWSProvider-->>external-dns: return zones
    end