Panel | ||||
---|---|---|---|---|
|
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 |
|
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:
|
|
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:
|
|
Input Fields
Name | Type | Description | Version Information | |||||||
---|---|---|---|---|---|---|---|---|---|---|
Action | Choice | The action performed upon the task execution.
| Introduced in 1.0.0 | |||||||
AWS Credentials | Credentials | The Credentials definition should be as follows.
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 | |||||||
Cluster | Text | 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 notperformed. | 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
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.
| Introduced in 1.0.0 | |||||||
Group | Text | The name of the ECS task group to associate with the ECS task. The default value used by AWS is the family name of the task definition (for example, The field is optional | Introduced in 1.0.0 | |||||||
Started By | Text | An optional tag specified when a ECS Task is started. Useful on AWS console for filtering Tasks based on the triggering source. Available when Action = “Run Task” | Introduced in 1.0.0 | |||||||
Provide Additional Configuration As | Choice | Specifies if and how additional configuration options can be defined. Available options are:
Available if Action = “Run Task” | Introduced in 1.0.0 | |||||||
Additional Configuration (Text) | Large Text | The field could be required when Action = “Run Task” and provides additional configuration options for the ECS Task execution.
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.
Required when Provide Additional Configuration As = “As JSON Text” | Introduced in 1.0.0 | |||||||
Additional Configuration (Script) | Script | Provides the same functionality as Additional Configuration (Text) option with the added benefit of being reusable by saving the configuration as a UAC script. Required when Provide Additional Configuration As = “As JSON UAC Script” | Introduced in 1.0.0 | |||||||
Wait for Task to Finish | Checkbox | If selected, the UAC task instance will run until the triggered ECS Task reaches the status "STOPPED" Available for “Run Task” and “Stop Task” Actions. | Introduced in 1.0.0 | |||||||
Polling Interval (sec) | Integer | The field is required when Wait for Task to Finish is “true” and represents the time interval between retries for getting the status of the ECS Task. As a best practice, if the Task Execution expected completion duration is long, set the polling Interval to a larger value. A short value will trigger frequent checks towards AWS which in the case of long-duration Tasks is inefficient in terms of resources. The default value is 60. | Introduced in 1.0.0 | |||||||
Extension Output Options | Multiple Choice | Option to control the visibility of information that appears on UAC Task Instance Extension Output. If “Include ECS Task Execution Metadata” is selected then Related information is printed on Universal Task Instance Extension Output. | Introduced in 1.0.0 |
Output Fields
The following output-only fields provide better visibility during the execution of Universal Task Instances.
Name | Type | Description | Version Information |
---|---|---|---|
Task ARN | Text | The Task ARN. | Introduced on 1.0.0 |
Task Status | Text | The Last Status Retrieved by the Universal Task Instance. | Introduced on 1.0.0 |
Environment Variables
Environment Variables can be set in the Environment Variables task definition table. For variables that relate to AWS please refer to the AWS Boto3 documentation. For proxies as environment variables, refer to the Proxy Configuration section of this document.
Proxy Configuration
HTTPS_PROXY
environment variables can be used to specify a required proxy server (which could be operating either on HTTP or HTTPS)
HTTP Proxy Configuration You can set the desired proxy address through the HTTPS_PROXY Environment Variable. Note that the Proxy operates on HTTP mode and not HTTPS | HTTPS Proxy Configuration Configuration of HTTPS Proxy with a CA Bundle for SSL verification purposes (if required) |
Proxies with authentication are also supported. To maximize security, it is strongly recommended to create a Resolvable Credentials entity in the Universal Controller and then configure the environment variable as follows.
Code Block | ||||
---|---|---|---|---|
| ||||
http://${_credentialUser('Proxy Credentials')}:${_credentialPwd('Proxy_Credentials')}@userproxyaddress.com:8080 |
Exit Codes
Exit Code | Status | Status Description | Meaning |
---|---|---|---|
0 | Success | “SUCCESS: Task executed successfully.“ | Successful Execution. |
1 | Failure | “Execution Failed: <<Error Description>>” | Generic Error or in case Task is finished with reported Error. |
2 | Failure | “Authentication Error: Account cannot be authenticated.“ | Bad credentials. |
3 | Failure | “Authorization Error: Account is not authorized to perform the requested action.“ | Insufficient permissions. |
20 | Failure | “Data Validation Error: <<Error Description>>“ | Input fields validation error. |
STDOUT and STDERR
STDOUT of this integration is empty and STDERR provides additional information to the user, the detail of it is tuned by Log Level Task Definition field.
Note |
---|
Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice. |
How To
Import Universal Template
To use the Universal Template, you first must perform the following steps.
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.
Configure Universal Task
For a new Universal Task, create a new task, and enter the required input fields.
Anchor | ||||
---|---|---|---|---|
|
Integration Modifications
Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.
Python code modifications should not be done.
Template Modifications
General Section
"Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
Universal Template Details Section
"Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
Result Processing Defaults Section
Success and Failure Exit codes should not be changed.
Success and Failure Output processing should not be changed.
Fields Restriction Section
The setup of the template does not impose any restrictions. However, concerning the "Exit Code Processing Fields" section.Success/Failure exit codes need to be respected.
In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Document References
This document references the following documents:
Document Link | Description |
---|---|
User documentation for creating, working with, and understanding Universal Templates and Integrations. | |
User documentation for creating Universal Tasks in the Universal Controller user interface. | |
Official AWS Guide on how Credentials are evaluated by Boto3. | |
Official AWS Guide on how AWS Configuration file is used by Boto3. | |
Official AWS Guide on how AWS Environment Variables are used by Boto3. | |
Official AWS Guide parameters to run an ECS Task. This guide comes in handy in case of complex configurations and helps in the population of Network Configuration (JSON), Additional Configuration (Text) & Additional Configuration (Script) fields. |
Anchor | ||||
---|---|---|---|---|
|
Changelog
ue-aws-ecs-1.0.0 (2024-08-14)
Initial Version