Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Container associations in Amazon Network Firewall

Amazon Network Firewall container associations collect the IP addresses of running containers in your Amazon Elastic Container Service and Amazon Elastic Kubernetes Service clusters. They maintain these addresses as a dynamic IP set. Reference this IP set in your Network Firewall rule groups. Write rules that match traffic by container source or destination IP without hardcoding addresses.

Container associations subscribe to container lifecycle events (task start and stop for Amazon ECS, pod start and stop for Amazon EKS) to learn which IPs are currently active. They have no direct interaction with cluster traffic or networking. Your Network Firewall endpoints in your VPC inspect all traffic, using the resolved IP set to evaluate rules.

How container associations work

A container association links monitoring configurations to a named Network Firewall resource. Each monitoring configuration targets one Amazon ECS or Amazon EKS cluster ARN. You can add optional attribute filters to narrow which containers are tracked.

When you create a container association, Network Firewall:

As containers start and stop, Network Firewall updates the IP set automatically. Network Firewall collects only IP information from lifecycle events and has no interaction with the cluster's data path. Your Network Firewall endpoints reference the container association's IP set to match packets by source or destination address.

Container types

Container associations support two container types:

You set the container type at creation and cannot change it afterward.

Monitoring configurations

Each container association can have up to 5 monitoring configurations. A monitoring configuration includes:

Networking requirements and limitations

Container associations have the following networking requirements and limitations:

Prerequisites for container associations

Before you create a container association, make sure that:

Using container associations in firewall rules

After you create a container association, reference it in stateful rule groups as a dynamic IP set. Use the container association's resolved IP addresses as an IPSet reference variable in your Suricata compatible rules.

Referencing a container association in a rule group

When you create or update a stateful rule group, add the container association ARN to the rule group's ReferenceSets configuration. This creates a named variable you can use in Suricata rules.

aws network-firewall create-rule-group \
    --rule-group-name my-container-rules \
    --type STATEFUL \
    --capacity 100 \
    --rule-group '{
        "RulesSource": {
            "RulesString": "alert tcp @CONTAINER_IPS any -> any any (sid:1; rev:1;)"
        },
        "ReferenceSets": {
            "IPSetReferences": {
                "CONTAINER_IPS": {
                    "ReferenceArn": "arn:aws:network-firewall:us-east-1:123456789012:container-association/my-ecs-monitor"
                }
            }
        }
    }'

Delete protection for container associations

After a rule group references a container association, you cannot delete the container association until you remove all references to it. If you attempt to delete a referenced container association, the API returns an InvalidOperationException with the message: "Unable to delete the object because it is still in use."

To delete a container association that is in use:

Creating a container association

You can create a container association using the Amazon Command Line Interface, Amazon SDKs, or the Network Firewall console.

aws network-firewall create-container-association \
    --container-association-name my-ecs-monitor \
    --type ECS \
    --container-monitoring-configurations '[
        {
            "ClusterArn": "arn:aws:ecs:us-east-1:123456789012:cluster/my-cluster",
            "AttributeFilters": [
                {"Key": "ecs.instance-type", "Value": "c5.xlarge"}
            ]
        }
    ]'

Updating a container association

You can update the monitoring configurations and description of a container association. The container type is fixed at creation and cannot be changed. Use the update token from the most recent describe response for optimistic concurrency.

aws network-firewall update-container-association \
    --container-association-arn arn:aws:network-firewall:us-east-1:123456789012:container-association/my-ecs-monitor \
    --type ECS \
    --update-token "your-update-token" \
    --container-monitoring-configurations '[...]'

Deleting a container association

When you delete a container association, Network Firewall:

Network Firewall deletes the container association asynchronously. The API returns immediately with DELETING status while cleanup proceeds in the background.

aws network-firewall delete-container-association \
    --container-association-arn arn:aws:network-firewall:us-east-1:123456789012:container-association/my-ecs-monitor

Tagging container associations

Container associations support Amazon resource tagging. You can add tags at creation or manage them later using the TagResource, UntagResource, and ListTagsForResource APIs.

Managed Rules (Amazon ECS)

For Amazon ECS-type container associations, Network Firewall creates an Managed Rule in your account to receive Amazon ECS task state change events. Network Firewall names these rules with the pattern NetworkFirewallManagedRule-cluster-name-hash and tags them as service-managed.

Service-linked role for container associations

Container associations require the Amazon Network Firewall service-linked role (AWSServiceRoleForNetworkFirewall) in your account. This role grants Network Firewall permission to monitor container lifecycle events on your behalf.

For more information, see Using service-linked roles for Network Firewall.

Container association status transitions

The following table describes each container association status value.

You cannot update a container association in DELETING state.

Container association quotas

The following table lists the quotas for container associations.

The limit of 5 IP set references per rule group does not apply to container association references.

For the most current quota values, see Amazon Network Firewall quotas.

Container association error reference

The following table describes the errors that container association API operations can return.