Docker Task
Resource Overview
A Docker Task represents an ECS task definition for running Docker containers on ephemeral, non-dedicated server instances using AWS Fargate.
Currently, AWS Fargate is only available in certain AWS Regions. Stacks with Docker Tasks will deploy successfully in regions not specified in that list, but any attempt to use the AWS API to run tasks will fail with an error.
Any task that requires more resources than a Lambda function provides, can be run using a Docker Task.
Tasks are executed by invoking the ECS RunTask action using the Docker Task's ARN. For example, a Docker task could transcode a video file from one Object Store into multiple different formats that are then uploaded to another Object Store. Connecting a Docker Task to a Function, with a service discovery wire, allows that function to invoke your Docker Task. The Function automatically populates and references the ARN and VPC subnets of the Docker Task when this connection occurs.
Docker images in public or private repositories hosted in AWS Elastic Container Registry can be used for your Docker Task.
Event Subscription
Event subscription wires (solid line) visualize and configure event subscription integrations between two resources.
The following resources can be subscribed to a Docker Task:
- Function
Service Discovery
A Docker Task is considered a Compute Resource; it adopts the permissions and environment variables required to perform actions using cloud resources within the stack. This occurs when a service discovery wire (dashed line) is connected from this resource to another cloud resource.
Docker Tasks are capable of environment-aware service discovery and permission scoping for the following resources:
- Function
- Docker Task
- GraphQL API
- Job Queue
- Object Store
- PubSub Topic
- REST API
- Stream
- Table
- Virtual Network (resources within a Virtual Network)
Configurable Properties
Logical ID
The unique identifier used to reference this resource in the stack template. Defining a custom Logical ID is recommended, as it allows you to quickly identify a resource and any associated sub-resources when working with your stack in AWS, or anywhere outside of the Stackery Dashboard. As a project grows, it becomes useful in quickly spotting this resource in template.yaml or while viewing a stack in Template View mode.
The Logical ID of all sub-resources associated with this Docker Task will be prefixed with this value.
The identifier you provide must only contain alphanumeric characters (A-Za-z0-9) and be unique within the stack.
Default Logical ID Example: DockerTask2
IMPORTANT : AWS uses the Logical ID of each resource to coordinate and apply updates to the stack when deployed. On any update of a resource's logical ID (or any modification that results in one), CloudFormation will delete the currently deployed resource and create a new one in its place when the updated stack is deployed.
Image
The repository and optional tag of the Docker Image to run. Examples:
- public/training
- quay.io/mycompany/api#master
CPU Units
The number of compute units to needed to run each instance of the task. One CPU is equivalent to 1,024 compute units.
Memory
The amount of memory, in MB, needed to run each instance of the task.
Environment Variables
Environment variables are key-value pairs that enable users to define variables in the runtime environment that will dynamically populate in your Docker Task. Environment variables are automatically populated when you connect a service discovery wire (dashed wire) from a Docker Task to another Cloud Resource. You also have the ability to manually define these environment variables that your Docker Task requires.
IAM Permissions
When connected by a service discovery wire (dashed wire), a Function or Docker Task will add the following IAM policy to its role and gain permission to access this resource.
- Statement:
- Effect: Allow
Action:
- ecs:RunTask
- ecs:DescribeTasks
- ecs:StopTask
Resource:
- !Ref DockerTask2
- !Sub arn:aws:ecs:${AWS::Region}:${AWS::AccountId}:task/*
- Statement:
- Effect: Allow
Action:
- iam:PassRole
Resource:
- !GetAtt DockerTask2ExecutionRole.Arn
- !GetAtt DockerTask2TaskRole.Arn
Environment Variables
When connected by a service discovery wire (dashed wire), a Function or Docker Task will automatically populate and reference the following environment variables in order to interact with this resource.
DOCKER_TASK_ARN
The Amazon Resource Name of the Docker Task.
DOCKER_TASK_SUBNETS
The Virtual Private Cloud's subnets that house your Docker Task.
AWS SDK Code Example
Language-specific examples of AWS SDK calls using the environment variables discussed above.
Run a Docker Task
// Load AWS SDK and create a new ECS object
const AWS = require("aws-sdk");
const ecs = new AWS.ECS();
const task = process.env.DOCKER_TASK_ARN; // supplied by Function service-discovery wire
exports.handler = async message => {
// Construct parameters for the run call
const params = {
taskDefinition: task
};
await ecs.runTask(params).promise();
console.log('Task ARN run: ', task);
}
import boto3
import os
# Create an ECS client
ecs = boto3.client('ecs')
docker_task = os.environ['DOCKER_TASK_ARN'] # Supplied by Function service-discovery wire
def handler(message, context):
# Run the docker task
response = ecs.run_task(
taskDefinition=docker_task
)
return response
Metrics & Logs
Double clicking a resource while viewing your stack's current deployment gives you access to your pre-configured resource properties, and the following metrics and logs.
- Logs
Related AWS Documentation
AWS Documentation: AWS::ECS::TaskDefinition