Disclaimer

Your use of this download is governed by Stonebranch's Terms of Use.

Version Information

Template Name	Extension Name	Version	Status
AWS ECS	ue-aws-ecs	1 (Current 1.0.0)	Fixes and new Features are introduced.

Refer to Changelog for version history information.

Overview

Amazon Elastic Container Service (AWS ECS) is a fully managed container orchestration service that simplifies the deployment, management, and scaling of containerized applications. ECS allows you to run and scale Docker containers on AWS infrastructure without needing to manage the underlying hardware or software, making it easier to build, deploy, and operate containerized applications. It integrates seamlessly with other AWS services, supports both serverless (AWS Fargate) and server-based (EC2) compute options, and provides robust security, networking, and monitoring capabilities.

In Amazon Elastic Container Service (AWS ECS), an ECS task is a running instance of a task definition. Tasks use case is ideal for one-time or short-lived jobs. For example:

Batch Jobs: Suitable for batch processing, data transformations, and other workloads that are completed after a certain period.
Task Scheduling: Useful for scheduled tasks, such as cron jobs, where you need to run a task at specific intervals.
Manual Execution: Good for tasks that you want to run on-demand or manually trigger through an event or user action

This integration provides the capability to run ECS Tasks allowing the above use cases to be fulfilled through UAC, where UAC has the role of an orchestrator.

Key Features

Feature	Description
Run Task	Run a single instance of a Task on AWS ECS.
Stop Task	Stop a single instance of a Task on AWS ECS.

Software Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task and comes bundled with Amazon Boto3 Python AWS SDK V.1.34.136.

Area	Details
Python Version	Requires Python 3.11 tested with Agent Bundled Python 3.11.6.
Universal Agent Compatibility	Compatible with Universal Agent for Windows x64 and version >= 7.6.0.0. Compatible with Universal Agent for Linux and version >= 7.6.0.0.
Universal Controller Compatibility	Universal Controller Version >= 7.6.0.0.
Network and Connectivity	Network connectivity and access rights are required for AWS ECS.

Supported Actions

Action: Run Task

This action allows the execution of a single ECS task instance from an ECS Task Definition.

Task Authors have full flexibility to provide Task Definition/container overrides, however in most cases the ECS Task default configuration (which is part of its definition on AWS) should be adequate. It is possible also to configure the UAC task in such a way that the Universal Task Instance is finished by the time the ECS Task is triggered or wait until the ECS Task is finished (STOPPED).

In the case where the UAC Task Instance only triggers the run of the Task, the Universal Task Instance is considered successful if the triggering of the run operations is successful.
In the case where the UAC Task Instance not only triggers the run of the Task but also waits until it is finished (STOPPED), then If the ECS Task is finished without a Task Error reported by AWS the UAC Task Instance is finished with Success, else with Failure.

Note that the ECS Task may be finished without errors, however some, or all the containers, can finish with an exit code different than zero.

Configuration examples

Scenario A Start an ECS Task with Role Assumption. The Network Configuration field is required if the intent is to run on FARGATE clusters. Group and Started By fields are also provided	Scenario B Start an ECS Task and wait for the Task to Stop. This configuration will also poll to acquire the Task description at defined intervals, in this case, every 60 seconds. It is suggested to avoid setting it too low to avoid rate limit flags. Role assumption is used in this case.
Scenario C Start an ECS Task with Additional optional Configuration as JSON Text. The list of all available options is available in the Boto3 documentation.	Scenario D Start an ECS Task providing the AWS Region and proxy to be used as an environment variable. Execution Metadata is not provided on EXTENSION Output

Action Output

Output Type

Description

Examples

EXTENSION

The extension output provides the following information:

exit_code, status_description: General info regarding the task execution. For more information, users can refer to the 792395793.
invocation.fields: The task configuration used for this task execution.
result.errors: List of errors that might have occurred during Universal Task Execution.
result.tasks: A list of Tasks that provides the latest information gathered related to the executed ECS Task(s). Information is retrieved from ECS, without additional processing. The output might vary depending on the AWS API version. The population of information on this JSON element is controlled by the Field Extension Output Options.

Successful Execution

{
    "exit_code": 0,
    "status_description": "Task executed successfully.",
    "invocation": {
	    "extension": "ue-aws-ecs",
        "version": "1.0.0",
        "fields": {...}
    },
    "result": {
        "tasks": [
            {
                "attachments": [
                    {
                        "id": "b0350d15-bdd9-4df8-b0ad-9bcd35f896ce",
                        "type": "ElasticNetworkInterface",
                        "status": "DELETED",
                        "details": [
                            {
                                "name": "subnetId",
                                "value": "subnet-00a16a28786e7806c"
                            },
                            {
                                "name": "networkInterfaceId",
                                "value": "eni-05e6e4860d1e0911d"
                            },
                            {
                                "name": "macAddress",
                                "value": "0a:ff:e9:cb:8b:71"
                            },
                            {
                                "name": "privateDnsName",
                                "value": "ip-112-11-21-123.ec2.internal"
                            },
                            {
                                "name": "privateIPv4Address",
                                "value": "112.11.21.123"
                            }
                        ]
                    }
                ],
                "attributes": [
                    {
                        "name": "ecs.cpu-architecture",
                        "value": "x86_64"
                    }
                ],
                "availabilityZone": "us-east-1d",
                "capacityProviderName": "FARGATE",
                "clusterArn": "arn:aws:ecs:us-east-1:1**********9:cluster/ue-aws-ecs",
                "connectivity": "CONNECTED",
                "connectivityAt": "2024-05-24T17:50:57.377000+02:00",
                "containers": [
                    {
                        "containerArn": "arn:aws:ecs:us-east-1:1**********9:container/ue-aws-ecs/d31a0aef2feb49c3af17982fb3c708eb/abaaceb9-3118-4f3d-97e4-510a992f11d9",
                        "taskArn": "arn:aws:ecs:us-east-1:1**********9:task/ue-aws-ecs/d31a0aef2feb49c3af17982fb3c708eb",
                        "name": "ls-nonexistentfile",
                        "image": "1**********9.dkr.ecr.us-east-1.amazonaws.com/ue-aws-ecs:latest",
                        "imageDigest": "sha256:d7bec506d9764a8d6f0ffac50b5a9dc9c316fbce69a4372028da66ea6ba8ce36",
                        "runtimeId": "d31a0aef2feb49c3af17982fb3c708eb-1540407552",
                        "lastStatus": "STOPPED",
                        "exitCode": 2,
                        "networkBindings": [],
                        "networkInterfaces": [
                            {
                                "attachmentId": "b0350d15-bdd9-4df8-b0ad-9bcd35f896ce",
                                "privateIpv4Address": "112.11.21.123"
                            }
                        ],
                        "healthStatus": "UNKNOWN",
                        "cpu": "0"
                    },
                    {
                        "containerArn": "arn:aws:ecs:us-east-1:1**********9:container/ue-aws-ecs/e31a0aee2feb49c3af17982fb3c708eb/d800fa8b-70f5-49ab-804f-00157535c929",
                        "taskArn": "arn:aws:ecs:us-east-1:1**********9:task/ue-aws-ecs/e31a0aef2eeb49c3af17982fb3c708eb",
                        "name": "ls-tmp",
                        "image": "1**********9.dkr.ecr.us-east-1.amazonaws.com/ue-aws-ecs:latest",
                        "imageDigest": "sha256:d7bec506d9764a8d6f0ffac50b5a9dc9c316fbce69a4372028da66ea6ba8ce36",
                        "runtimeId": "d31a0aef2feb49c3af17982fb3c708eb-1659398764",
                        "lastStatus": "STOPPED",
                        "exitCode": 0,
                        "networkBindings": [],
                        "networkInterfaces": [
                            {
                                "attachmentId": "b0350d15-bdd9-4df8-b0ad-9bcd35f896ce",
                                "privateIpv4Address": "112.11.21.123"
                            }
                        ],
                        "healthStatus": "UNKNOWN",
                        "cpu": "0"
                    }
                ],
                "cpu": "1024",
                "createdAt": "2024-05-24T17:50:53.682000+02:00",
                "desiredStatus": "STOPPED",
                "enableExecuteCommand": false,
                "executionStoppedAt": "2024-05-24T17:51:16.355000+02:00",
                "group": "family:ue-aws-ecs",
                "healthStatus": "UNKNOWN",
                "lastStatus": "STOPPED",
                "launchType": "FARGATE",
                "memory": "3072",
                "overrides": {
                    "containerOverrides": [
                        {
                            "name": "ls-tmp"
                        },
                        {
                            "name": "ls-nonexistentfile"
                        }
                    ],
                    "inferenceAcceleratorOverrides": []
                },
                "platformVersion": "1.4.0",
                "platformFamily": "Linux",
                "pullStartedAt": "2024-05-24T17:51:05.966000+02:00",
                "pullStoppedAt": "2024-05-24T17:51:10.983000+02:00",
                "startedAt": "2024-05-24T17:51:13.388000+02:00",
                "stopCode": "EssentialContainerExited",
                "stoppedAt": "2024-05-24T17:51:39.726000+02:00",
                "stoppedReason": "Essential container in task exited",
                "stoppingAt": "2024-05-24T17:51:26.400000+02:00",
                "tags": [],
                "taskArn": "arn:aws:ecs:us-east-1:1**********9:task/ue-aws-ecs/d31a0aef2feb49c3af17982fb3c708eb",
                "taskDefinitionArn": "arn:aws:ecs:us-east-1:1**********9:task-definition/ue-aws-ecs:15",
                "version": 5,
                "ephemeralStorage": {
                    "sizeInGiB": 20
                }
            }
        ],
		"failures": [],
        "errors": []
    }
}

Failed Execution

{
    "exit_code": 1,
    "status_description": "Execution Failed: You must specify a region.",
    "invocation": {
        "extension": "ue-aws-ecs",
        "version": "1.0.0",
        "fields": {...}
    },
    "result": {
        "errors": [
            "Execution Failed: : You must specify a region."
        ]
    }
}

Action: Stop Task

This action stops the execution of a single ECS task. If the ECS task is already stopped the Universal Task Instance will exit with success. It is possible also to configure the UAC task in such a way that the Universal Task Instance is finished by the time the ECS Task Stop is triggered or wait until the ECS Task is stopped.

In the case where the UAC Task Instance only triggers the stop of the Task, the Universal Task Instance is considered successful if the triggering of the stop operations is successful.
In the case where the UAC Task Instance not only triggers the stop of the Task but also waits until it is stopped, If the ECS Task is finished without a Task Error reported by AWS the UAC Task Instance is finished with Success, else with Failure.

Note that the ECS Task may be finished without errors, however some, or all the containers, can finish with an exit code different than zero.

Configuration examples

The configuration from Run Task also applies here. The only difference is that the Stop Task action also requires a Task ARN.

Scenario A

Stop an ECS Task with Role Assumption. A Task ARN is required. Optional field Stop Reason is populated.

Scenario B

Stop an ECS Task and wait for the Task to Stop. Polling Interval is set to 60 seconds. Execution Metadata is not provided on EXTENSION Output