Amazon ECS

Amazon Web Services

Overview

Integrates with Amazon Elastic Container Service (ECS) to synchronize container-orchestration inventory across the configured AWS accounts and regions. The connector reads ECS clusters, services, tasks, and task definitions via the AWS SDK for Java v2 EcsClient and emits one Brinqa object per resource. Each of the four models maps to the CloudResource UDM model. ECS list operations return only ARNs, so every model pairs a List* call (to enumerate ARNs) with a batched Describe* call (to hydrate the full resource), always requesting the TAGS field so resource tags are populated.

Data retrieved from Amazon ECS

Connector Object	Required	Maps to Data Model
EcsCluster	Yes	Cloud Resource
EcsService	Yes	Cloud Resource
EcsTask	Yes	Cloud Resource
EcsTaskDefinition	Yes	Cloud Resource

note

For detailed steps on how to view the data retrieved from Amazon ECS in the Brinqa Platform, see How to view your data.

Setup

Connection settings

When setting up a data integration, select Amazon ECS from the Connector dropdown and provide the following:

Setting	Required	Default	Description
Access key ID	No	—	AWS user access key ID, if not specified, the connector consults the default credentials provider chain to try and determine the \
Secret access key	No	—	AWS user secret access key, if not specified, the connector consults the default credentials provider chain to try and determine the \
Default region	No	—	Default AWS region, if not specified, the connector consults the default region provider chain to try and determine the region to use.
Assume role	No	—	Amazon Resource Name for the role to assume.
External ID	No	—	Optional STS external ID, sent when assuming the role named in the Assume role \
Session duration	No	900	Assume role session duration in seconds.
Page size	No	100	The maximum number of results to retrieve per operation.
Parallel requests	No	min(4, CPU cores)	Maximum number of parallel requests.

Authentication

Authentication is shared across the AWS connector bundle via the AwsConfiguration base class. The ECS sub-connector uses the AWS SDK for Java v2 EcsClient, which signs every request with AWS SigV4 using credentials resolved through the following chain (in order):

1. STS AssumeRole — if assumeRoleARN is configured, the connector assumes that role (using the credentials below as the principal) and uses the resulting temporary session credentials. Set externalId as well if the role's trust policy enforces an ExternalId condition; it is sent on the AssumeRole call and is required for cross-account confused-deputy protection.
2. Static access keys — if accessKey / secretKey are configured, they are used directly.
3. Default credentials provider chain — environment variables, ~/.aws/credentials, container role, or EC2 instance metadata.

Assumed-role sessions use the configurable sessionDuration (default 900 s) with a unique session name per sync. assumeRoleARN may be a comma-separated list to sync multiple accounts in one run. An EcsClient is constructed per role per region and is closed when its region has been fully synced.

Choosing an authentication path

The list above is the order the connector resolves credentials in. In terms of what to configure, three paths are supported:

Path	Configure	When to use
STS AssumeRole (recommended)	assumeRoleARN, plus externalId if the trust policy requires one	Cross-account access, and the only path that supports an ExternalId condition. Still needs a principal, from either of the paths below.
Default credentials provider chain (fully keyless)	nothing	The platform runs inside your AWS account on an EC2 instance profile or an EKS IRSA role. No long-lived keys exist anywhere.
Static access keys (optional)	accessKey, secretKey	The platform runs outside your AWS account and no role is available. Long-lived credentials — prefer either path above.

sts:AssumeRole is required only when assumeRoleARN is set.

Required AWS API permissions

Permission	Purpose
ecs:ListClusters	Enumerate cluster ARNs in a region
ecs:DescribeClusters	Hydrate cluster detail and tags (used by EcsCluster)
ecs:ListServices	Enumerate service ARNs within a cluster
ecs:DescribeServices	Hydrate service detail and tags
ecs:ListTasks	Enumerate task ARNs within a cluster (per desired status)
ecs:DescribeTasks	Hydrate task detail and tags
ecs:ListTaskDefinitions	Enumerate ACTIVE task-definition ARNs
ecs:DescribeTaskDefinition	Hydrate task-definition detail and tags
sts:AssumeRole	Only when assumeRoleARN is set

Sync Behavior

Each sync is a full sync. Every run enumerates all resources through the AWS APIs; the connector does not maintain a sync token or apply an incremental since date filter.

---

How to obtain Amazon ECS credentials

Create an IAM user for AWS access

For detailed steps on creating an IAM user and obtaining access keys, see the Amazon EC2 connector documentation. Follow the same process, but attach the required ECS permissions (ecs:ListClusters, ecs:DescribeClusters, ecs:ListServices, ecs:DescribeServices, ecs:ListTasks, ecs:DescribeTasks, ecs:ListTaskDefinitions, ecs:DescribeTaskDefinition) instead of the EC2 permissions.

The connector authenticates using the AWS SDK's credential resolution chain. If an assume-role ARN is configured, the connector assumes that IAM role using the provided credentials. Otherwise, it uses the provided access keys directly, falling back to the AWS Default Credential Provider Chain (environment variables, ~/.aws/credentials, or EC2 instance metadata).

Data & mappings

Attribute mappings

Expand the sections below to view the mappings between the source and the Brinqa data model attributes:

EcsCluster

Source Field Name	SDM Attribute
Cluster.activeServicesCount	ACTIVE_SERVICES_COUNT
Cluster.capacityProviders	CAPACITY_PROVIDERS (multivalued)
Cluster.clusterArn	UID
Cluster.clusterArn	CLUSTER_ARN
Cluster.clusterName	CLUSTER_NAME
Cluster.clusterName (fallback Cluster.clusterArn)	NAME
Cluster.pendingTasksCount	PENDING_TASKS_COUNT
Cluster.registeredContainerInstancesCount	REGISTERED_CONTAINER_INSTANCE_COUNT
Cluster.runningTasksCount	RUNNING_TASKS_COUNT
Cluster.status	SOURCE_STATUS
Cluster.tags[] (key:value)	TAGS (multivalued)
literal AWS	CLOUD_PROVIDER
region being synced	REGION
sync timestamp	LAST_CAPTURED

EcsService

Source Field Name	SDM Attribute
awsvpcConfiguration().securityGroups	SECURITY_GROUP_IDS (multivalued)
awsvpcConfiguration().subnets	SUBNET_IDS (multivalued)
literal AWS	CLOUD_PROVIDER
region being synced	REGION
Service.clusterArn	CLUSTER_ARN
Service.createdAt	FIRST_SEEN
Service.desiredCount	DESIRED_COUNT
Service.launchTypeAsString	LAUNCH_TYPE
Service.loadBalancers[].targetGroupArn	TARGET_GROUP_ARNS (multivalued)
Service.networkConfiguration().awsvpcConfiguration().assignPublicIp == ENABLED	ASSIGN_PUBLIC_IP
Service.pendingCount	PENDING_COUNT
Service.platformFamily	PLATFORM_FAMILY
Service.platformVersion	PLATFORM_VERSION
Service.roleArn	SERVICE_ROLE_ARN
Service.runningCount	RUNNING_COUNT
Service.schedulingStrategyAsString	SCHEDULING_STRATEGY
Service.serviceArn	UID
Service.serviceArn	SERVICE_ARN
Service.serviceName	SERVICE_NAME
Service.serviceName (fallback Service.serviceArn)	NAME
Service.status	SOURCE_STATUS
Service.tags[] (key:value)	TAGS (multivalued)
Service.taskDefinition	TASK_DEFINITION
sync timestamp	LAST_CAPTURED

EcsTask

Source Field Name	SDM Attribute
literal AWS	CLOUD_PROVIDER
region being synced	REGION
sync timestamp	LAST_CAPTURED
Task.attachments[].details[name=networkInterfaceId].value	NETWORK_INTERFACE_IDS (multivalued)
Task.attachments[].details[name=privateIPv4Address].value	PRIVATE_IP_ADDRESSES (multivalued)
Task.attachments[].details[name=subnetId].value	SUBNET_IDS (multivalued)
Task.availabilityZone	AVAILABILITY_ZONE
Task.clusterArn	CLUSTER_ARN
Task.containerInstanceArn	CONTAINER_INSTANCE_ARN
Task.containers[].image	CONTAINER_IMAGES (multivalued)
Task.cpu	CPU
Task.createdAt	FIRST_SEEN
Task.desiredStatus	DESIRED_STATUS
Task.group	GROUP
Task.lastStatus	SOURCE_STATUS
Task.launchTypeAsString	LAUNCH_TYPE
Task.memory	MEMORY
Task.platformVersion	PLATFORM_VERSION
Task.startedAt	LAST_STARTED
Task.stoppedAt	LAST_STOPPED
Task.tags[] (key:value)	TAGS (multivalued)
Task.taskArn	UID
Task.taskArn	NAME
Task.taskArn	TASK_ARN
Task.taskDefinitionArn	TASK_DEFINITION_ARN

EcsTaskDefinition

Source Field Name	SDM Attribute
containerDefinitions[].environment[].name	ENVIRONMENT_KEYS (multivalued)
containerDefinitions[].secrets[] encoded as name=valueFrom	SECRET_REFS (multivalued)
literal AWS	CLOUD_PROVIDER
region being synced	REGION
sync timestamp	LAST_CAPTURED
TaskDefinition.containerDefinitions[].image	CONTAINER_IMAGES (multivalued)
TaskDefinition.cpu	CPU
TaskDefinition.executionRoleArn	EXECUTION_ROLE_ARN
TaskDefinition.family	FAMILY
TaskDefinition.family + : + TaskDefinition.revision (fallback taskDefinitionArn)	NAME
TaskDefinition.memory	MEMORY
TaskDefinition.networkModeAsString	NETWORK_MODE
TaskDefinition.registeredAt	FIRST_SEEN
TaskDefinition.requiresCompatibilitiesAsStrings	REQUIRES_COMPATIBILITIES (multivalued)
TaskDefinition.revision	REVISION
TaskDefinition.statusAsString	SOURCE_STATUS
TaskDefinition.taskDefinitionArn	UID
TaskDefinition.taskDefinitionArn	TASK_DEFINITION_ARN
TaskDefinition.taskRoleArn	TASK_ROLE_ARN

Operations & API

Operations & API

Expand each connector object to see its operation options, delta-sync behavior, and the API it uses. See connector operation options for how to apply operation options (keys and values are case-sensitive).

EcsCluster

Operation options

Option	Type	Default	Description
region / regions	Comma-separated list of regions to query (one client per region).	Resolved from configuration / default region provider chain
maxResults	Page size for each ListClusters call.	Shared pageSize configuration (100)

Delta sync

Not supported. The connector performs a full sync of EcsCluster on every run and applies no incremental date filter.

API

• Type: AWS SDK for Java v2 (EcsClient) · Endpoint: ecs:ListClusters

EcsService

Operation options

Option	Type	Default	Description
region / regions	Comma-separated list of regions to query (one client per region).	Resolved from configuration / default region provider chain
maxResults	Page size for ListClusters/ListServices (services capped at 10).	Shared pageSize configuration (100)

Delta sync

Not supported. The connector performs a full sync of EcsService on every run and applies no incremental date filter.

API

• Type: AWS SDK for Java v2 (EcsClient) · Endpoint: ecs:ListClusters

EcsTask

Operation options

Option	Type	Default	Description
region / regions	Comma-separated list of regions to query (one client per region).	Resolved from configuration / default region provider chain
maxResults	Page size for ListClusters/ListTasks (tasks capped at 100).	Shared pageSize configuration (100)
fetchStoppedTasks	When true, also retrieves STOPPED tasks in addition to RUNNING.	false (RUNNING only)

Delta sync

Not supported. The connector performs a full sync of EcsTask on every run and applies no incremental date filter.

API

• Type: AWS SDK for Java v2 (EcsClient) · Endpoint: ecs:ListClusters

EcsTaskDefinition

Operation options

Option	Type	Default	Description
region / regions	Comma-separated list of regions to query (one client per region).	Resolved from configuration / default region provider chain
maxResults	Page size for each ListTaskDefinitions call.	Shared pageSize configuration (100)

Delta sync

Not supported. The connector performs a full sync of EcsTaskDefinition on every run and applies no incremental date filter.

API

• Type: AWS SDK for Java v2 (EcsClient) · Endpoint: ecs:ListTaskDefinitions
• Default filters: ListTaskDefinitions is called with status=ACTIVE, so only active task-definition revisions are synced.

Changelog

Changelog

The Amazon ECS connector has undergone the following changes:

Version	Description	Migration Steps
3.2.3	New Features - Roles that require an External ID can now be used. A new optional External ID setting is sent when assuming the role named in the connector's Assume role setting, so roles whose trust policy enforces an ExternalId condition — the standard protection against cross-account confused-deputy access — can now be assumed. Existing configurations are unaffected: leave it blank and the role is assumed exactly as before. The connector's authentication documentation now also describes all three supported paths — assuming a role, running fully keyless from an EC2 instance profile or EKS IRSA role, and static access keys. Bug Fixes - The Parallel requests setting is now labeled on the configuration screen. The setting was shown without its proper name or help text. It now displays its label and description. The setting's behavior and default are unchanged.	N/A
3.2.2	No changes in this release.	N/A
3.2.1	No changes in this release.	N/A
3.2.0	No changes in this release.	N/A
3.1.0	New Features - New connector — syncs ECS clusters, services, tasks, and task definitions. - fetchStoppedTasks operation option (default false). When enabled, sync also returns recently stopped tasks (visible to AWS for ~1 hour after exit), supporting historical-reachability and blast-radius reconstruction. Improvements - Sync failures are now visible. Previously, certain AWS API errors (throttling, server errors, transient network failures, validation errors) could be silently swallowed during multi-region sync, producing empty results without indicating a problem. These now surface as sync failures with a clear log entry detailing the HTTP status, AWS error code, request id, and service name. Per-region permission gaps (HTTP 401 / 403) still allow the sync to continue across other regions, but are now visible in logs.	N/A