AWS ECS

Disclaimer

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

Version Information

Template Name

Extension Name

VersionStatus

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

DescriptionExamples
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

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.task: 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 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": {
        "task": {
            "attachments": null,
            "availabilityZone": "us-east-1c",
            "capacityProviderName": "FARGATE",
            "clusterArn": "arn:aws:ecs:us-east-1:169*****829:cluster/ue-aws-ecs",
            "connectivity": "CONNECTED",
            "connectivityAt": "2024-07-15 16:13:59.708000+03:00",
            "containers": null,
            "cpu": "1024",
            "createdAt": "2024-07-15 16:13:54.242000+03:00",
            "desiredStatus": "STOPPED",
            "enableExecuteCommand": false,
            "executionStoppedAt": "2024-07-15 16:14:15.122000+03:00",
            "group": "family:ue-aws-ecs",
            "lastStatus": "STOPPED",
            "launchType": "FARGATE",
            "memory": "3072",
            "overrides": null,
            "platformVersion": "1.4.0",
            "platformFamily": "Linux",
            "pullStartedAt": "2024-07-15 16:14:04.798000+03:00",
            "pullStoppedAt": "2024-07-15 16:14:10.161000+03:00",
            "startedAt": "2024-07-15 16:14:12.164000+03:00",
            "stopCode": "UserInitiated",
            "stoppedAt": "2024-07-15 16:14:38.461000+03:00",
            "stoppedReason": "Task stopped by user",
            "stoppingAt": "2024-07-15 16:14:23.898000+03:00",
            "tags": null,
            "taskArn": "arn:aws:ecs:us-east-1:1695******:task/ue-aws-ecs/43b2807b1eb44f42801d7be01dd2fe07",
            "taskDefinitionArn": "arn:aws:ecs:us-east-1:169*****29:task-definition/ue-aws-ecs:15",
            "version": 6,
            "ephemeralStorage": {
                "sizeInGiB": 20
            },
            "fargateEphemeralStorage": {
                "sizeInGiB": 20
            }
        },
        "ResponseMetadata": {
            "RequestId": "f2e4b5b4-6bf3-****8171-6e4a4b89da32",
            "HTTPStatusCode": 200,
            "HTTPHeaders": {
                "x-amzn-requestid": "f2e4b5b4-****-400a-8171-6e4a4b89da32",
                "content-type": "application/x-amz-json-1.1",
                "content-length": "1091",
                "date": "Mon, 15 Jul 2024 13:50:23 GMT"
            },
            "RetryAttempts": 0
        }
    }
}
Failed Execution
{
    "exit_code": 1,
    "status_description": "Execution Failed: An error occurred (InvalidParameterException) when calling the StopTask operation: The referenced task was not found",
    "invocation": {
        "extension": "ue-aws-ecs",
        "version": "1.0.0",
        "fields": {...}
    },
    "result": {
        "errors": [
            "Execution Failed: An error occurred (InvalidParameterException) when calling the StopTask operation: The referenced task was not found"
        ]
    }
}

Input Fields

NameTypeDescription

Version Information

ActionChoice

The action performed upon the task execution.

  • Run Task (Default)

  • Stop Task

Introduced in 1.0.0

AWS Credentials

Credentials

The Credentials definition should be as follows.

  • AWS Access Key ID as "Runtime User".

  • AWS Secret Access Key as "Runtime Password".

The field population is optional and applicable to all the Actions. When AWS Credentials is not populated as part of the task definition, during task execution the integration will look for AWS Credentials on the task execution environment. Refer to AWS Credential Configuration Options for more information

Introduced in 1.0.0

AWS Region

Text

Region for the Amazon Web Service i.e. "us-east-1"

The field population is optional and applicable to all the Actions. When AWS Region is not populated as part of the task definition, during task execution the integration will look for the AWS Region on the task execution environment (AWS configuration file or through AWS environment variables).

The field is applicable to all the Actions.

Introduced in 1.0.0

ClusterText

The short name or full Amazon Resource Name (ARN) of the cluster to run your task on.

Required for all Actions

Introduced in 1.0.0

Assume Role ARN

Large Text

Role ARN of the AWS Assume Role functionality. The Assume Role functionality in AWS (Amazon Web Services) allows a user or service to take on the permissions of another IAM (Identity and Access Management) role temporarily.

If the field is left empty Role Assumption is not performed.

Introduced in 1.0.0

Task Definition

Text

The family and revision (family:revision) or full ARN of the task definition to run. If a revision isn’t specified, the latest ACTIVE revision is used.

Required when Action = “Run Task”

Introduced in 1.0.0

Task ARN

Text

The Task ARN of the Task to Stop

Required when Action = “Stop Task”

Introduced in 1.0.0

Stop Reason

Text

An optional message specified when a task is stopped. This message appears on AWS Console, but also when a task is queried programmatically.

Introduced in 1.0.0

Network Configuration (JSON)

Large Text

The field could be required when Action = “Run Task” and represents the network configuration for the task. This parameter is required for task definitions that use the awsvpc network mode to receive their elastic network interface, and it isn’t supported for other network modes. 

Default Value
{
   "networkConfiguration": { 
      "awsvpcConfiguration": { 
         "assignPublicIp": "ENABLED|DISABLED",
         "securityGroups": [ "string" ],
         "subnets": [ "string" ]
      }
   }
}


The default value is a placeholder value meant to serve as a way to inform the user of what the available options are. It is not meant to be used directly as a default value for an execution of the integration. task authors can use the default value provided, as a template, however it needs to be modified according to the needs.

  • "subnets" : The IDs of the subnets associated with the task or service. There’s a limit of 16 subnets that can be specified per AwsVpcConfiguration. This parameter is required, so at least one needs to be provided.

  • "assignPublicIp" : Accepts values “ENABLED" or “DISABLED". If this JSON element is not provided the default value is considered to be DISABLED. However, in most cases it needs to be ENABLED.

  • The IDs of the security groups associated with the task or service. If you don’t specify a security group, the default security group for the VPC is used. There’s a limit of 5 security groups that can be specified per AwsVpcConfiguration