Manage Amazon ECS or Fargate Tasks with Step Functions
Step Functions can control certain Amazon services directly from Amazon States Language (ASL). To learn more, see Working with other services and Pass parameters to a service API.
How the Optimized Amazon ECS/Fargate integration is different than the Amazon ECS or Fargate Amazon SDK integration
-
The Run a Job (.sync) integration pattern is supported.
ecs:runTask
can return an HTTP 200 response, but have a non-emptyFailures
field as follows:Request Response: Return the response and do not fail the task. This is the same as no optimization.
Run a Job or Task Token: If a non-empty
Failures
field is encountered, the task is failed with anAmazonECS.Unknown
error.
Supported Amazon ECS/Fargate APIs and syntax:
Parameters in Step Functions are expressed in PascalCase
Even if the native service API is in camelCase, for example the API action startSyncExecution
, you specify parameters in PascalCase, such as: StateMachineArn
.
-
RunTask
starts a new task using the specified task definition.
Passing Data to an Amazon ECS Task
Step Functions can control certain Amazon services directly from Amazon States Language (ASL). To learn more, see Working with other services and Pass parameters to a service API.
You can use overrides
to override the default
command for a container, and pass input to your Amazon ECS tasks. See ContainerOverride
. In the example, we have used JsonPath to pass
values to the Task
from the input to the Task
state.
The following includes a Task
state that runs an Amazon ECS task and waits for
it to complete.
{
"StartAt": "Run an ECS Task and wait for it to complete",
"States": {
"Run an ECS Task and wait for it to complete": {
"Type": "Task",
"Resource": "arn:aws:states:::ecs:runTask.sync",
"Parameters": {
"Cluster": "cluster-arn
",
"TaskDefinition": "job-id
",
"Overrides": {
"ContainerOverrides": [
{
"Name": "container-name
",
"Command.$": "$.commands"
}
]
}
},
"End": true
}
}
}
The "Command.$": "$.commands"
line in ContainerOverrides
passes the commands from the state input to the container.
For the previous example, each of the commands will be passed as a container override if the input to the execution is the following.
{
"commands": [
"test command 1",
"test command 2",
"test command 3"
]
}
The following includes a Task
state that runs an Amazon ECS task, and then
waits for the task token to be returned. See Wait for a Callback with the Task Token.
{
"StartAt":"Manage ECS task",
"States":{
"Manage ECS task":{
"Type":"Task",
"Resource":"arn:aws:states:::ecs:runTask.waitForTaskToken",
"Parameters":{
"LaunchType":"FARGATE",
"Cluster":"cluster-arn
",
"TaskDefinition":"job-id
",
"Overrides":{
"ContainerOverrides":[
{
"Name":"container-name
",
"Environment":[
{
"Name":"TASK_TOKEN_ENV_VARIABLE",
"Value.$":"$$.Task.Token"
}
]
}
]
}
},
"End":true
}
}
}
For information about how to configure IAM permissions when using Step Functions with other Amazon services, see IAM Policies for integrated services.