2016/11/21 - Amazon EC2 Container Service - 8 updated api methods
Changes ECS will include a new field named `version` in API responses relating to tasks and container instances. Version is a number that increments every time a change has been made to the associated resource. Users replicating their ECS resource state can use the version field reported by the ECS APIs to determine if their local state is fresh.
{'containerInstance': {'version': 'long'}}
Deregisters an Amazon ECS container instance from the specified cluster. This instance is no longer available to run tasks.
If you intend to use the container instance for some other purpose after deregistration, you should stop all of the tasks running on the container instance before deregistration to avoid any orphaned tasks from consuming resources.
Deregistering a container instance removes the instance from a cluster, but it does not terminate the EC2 instance; if you are finished using the instance, be sure to terminate it in the Amazon EC2 console to stop billing.
Note
If you terminate a running container instance, Amazon ECS automatically deregisters the instance from your cluster (stopped container instances or instances with disconnected agents are not automatically deregistered when terminated).
Request Syntax
client.deregister_container_instance(
cluster='string',
containerInstance='string',
force=True|False
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instance to deregister. If you do not specify a cluster, the default cluster is assumed.
string
[REQUIRED]
The container instance ID or full Amazon Resource Name (ARN) of the container instance to deregister. The ARN contains the arn:aws:ecs namespace, followed by the region of the container instance, the AWS account ID of the container instance owner, the container-instance namespace, and then the container instance ID. For example, ``arn:aws:ecs:region :aws_account_id :container-instance/container_instance_ID `` .
boolean
Forces the deregistration of the container instance. If you have tasks running on the container instance when you deregister it with the force option, these tasks remain running until you terminate the instance or the tasks stop through some other means, but they are orphaned (no longer monitored or accounted for by Amazon ECS). If an orphaned task on your container instance is part of an Amazon ECS service, then the service scheduler starts another copy of that task, on a different container instance if possible.
Any containers in orphaned service tasks that are registered with a Classic load balancer or an Application load balancer target group are deregistered, and they will begin connection draining according to the settings on the load balancer or target group.
dict
Response Syntax
{
'containerInstance': {
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'version': 123,
'versionInfo': {
'agentVersion': 'string',
'agentHash': 'string',
'dockerVersion': 'string'
},
'remainingResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'registeredResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'status': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string'
},
]
}
}
Response Structure
(dict) --
containerInstance (dict) --
The container instance that was deregistered.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. The ARN contains the arn:aws:ecs namespace, followed by the region of the container instance, the AWS account ID of the container instance owner, the container-instance namespace, and then the container instance ID. For example, ``arn:aws:ecs:region :aws_account_id :container-instance/container_instance_ID `` .
ec2InstanceId (string) --
The EC2 instance ID of the container instance.
version (integer) --
The version counter for the container instance. Every time a container instance experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS container instance state with CloudWatch events, you can compare the version of a container instance reported by the Amazon ECS APIs with the version reported in CloudWatch events for the container instance (inside the detail object) to verify that the version in your event stream is current.
versionInfo (dict) --
The version information for the Amazon ECS container agent and Docker daemon running on the container instance.
agentVersion (string) --
The version number of the Amazon ECS container agent.
agentHash (string) --
The Git commit hash for the Amazon ECS container agent build on the amazon-ecs-agent GitHub repository.
dockerVersion (string) --
The Docker version running on the container instance.
remainingResources (list) --
For most resource types, this parameter describes the remaining resources of the container instance that are available for new tasks. For port resource types, this parameter describes the ports that are reserved by the Amazon ECS container agent and any containers that have reserved port mappings; any port that is not specified here is available for new tasks.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
registeredResources (list) --
For most resource types, this parameter describes the registered resources on the container instance that are in use by current tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent when it registered the container instance with Amazon ECS.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
status (string) --
The status of the container instance. The valid values are ACTIVE or INACTIVE . ACTIVE indicates that the container instance can accept tasks.
agentConnected (boolean) --
This parameter returns true if the agent is actually connected to Amazon ECS. Registered instances with an agent that may be unhealthy or stopped return false , and instances without a connected agent cannot accept placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that are in the RUNNING status.
pendingTasksCount (integer) --
The number of tasks on the container instance that are in the PENDING status.
agentUpdateStatus (string) --
The status of the most recent agent update. If an update has never been requested, this value is NULL .
attributes (list) --
The attributes set for the container instance by the Amazon ECS container agent at instance registration.
(dict) --
The attributes applicable to a container instance when it is registered.
name (string) --
The name of the container instance attribute.
value (string) --
The value of the container instance attribute (at this time, the value here is Null , but this could change in future revisions for expandability).
{'containerInstances': {'version': 'long'}}
Describes Amazon EC2 Container Service container instances. Returns metadata about registered and remaining resources on each container instance requested.
Request Syntax
client.describe_container_instances(
cluster='string',
containerInstances=[
'string',
]
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instances to describe. If you do not specify a cluster, the default cluster is assumed.
list
[REQUIRED]
A space-separated list of container instance IDs or full Amazon Resource Name (ARN) entries.
(string) --
dict
Response Syntax
{
'containerInstances': [
{
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'version': 123,
'versionInfo': {
'agentVersion': 'string',
'agentHash': 'string',
'dockerVersion': 'string'
},
'remainingResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'registeredResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'status': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'failures': [
{
'arn': 'string',
'reason': 'string'
},
]
}
Response Structure
(dict) --
containerInstances (list) --
The list of container instances.
(dict) --
An EC2 instance that is running the Amazon ECS agent and has been registered with a cluster.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. The ARN contains the arn:aws:ecs namespace, followed by the region of the container instance, the AWS account ID of the container instance owner, the container-instance namespace, and then the container instance ID. For example, ``arn:aws:ecs:region :aws_account_id :container-instance/container_instance_ID `` .
ec2InstanceId (string) --
The EC2 instance ID of the container instance.
version (integer) --
The version counter for the container instance. Every time a container instance experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS container instance state with CloudWatch events, you can compare the version of a container instance reported by the Amazon ECS APIs with the version reported in CloudWatch events for the container instance (inside the detail object) to verify that the version in your event stream is current.
versionInfo (dict) --
The version information for the Amazon ECS container agent and Docker daemon running on the container instance.
agentVersion (string) --
The version number of the Amazon ECS container agent.
agentHash (string) --
The Git commit hash for the Amazon ECS container agent build on the amazon-ecs-agent GitHub repository.
dockerVersion (string) --
The Docker version running on the container instance.
remainingResources (list) --
For most resource types, this parameter describes the remaining resources of the container instance that are available for new tasks. For port resource types, this parameter describes the ports that are reserved by the Amazon ECS container agent and any containers that have reserved port mappings; any port that is not specified here is available for new tasks.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
registeredResources (list) --
For most resource types, this parameter describes the registered resources on the container instance that are in use by current tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent when it registered the container instance with Amazon ECS.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
status (string) --
The status of the container instance. The valid values are ACTIVE or INACTIVE . ACTIVE indicates that the container instance can accept tasks.
agentConnected (boolean) --
This parameter returns true if the agent is actually connected to Amazon ECS. Registered instances with an agent that may be unhealthy or stopped return false , and instances without a connected agent cannot accept placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that are in the RUNNING status.
pendingTasksCount (integer) --
The number of tasks on the container instance that are in the PENDING status.
agentUpdateStatus (string) --
The status of the most recent agent update. If an update has never been requested, this value is NULL .
attributes (list) --
The attributes set for the container instance by the Amazon ECS container agent at instance registration.
(dict) --
The attributes applicable to a container instance when it is registered.
name (string) --
The name of the container instance attribute.
value (string) --
The value of the container instance attribute (at this time, the value here is Null , but this could change in future revisions for expandability).
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
{'tasks': {'version': 'long'}}
Describes a specified task or tasks.
Request Syntax
client.describe_tasks(
cluster='string',
tasks=[
'string',
]
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that hosts the task to describe. If you do not specify a cluster, the default cluster is assumed.
list
[REQUIRED]
A space-separated list of task IDs or full Amazon Resource Name (ARN) entries.
(string) --
dict
Response Syntax
{
'tasks': [
{
'taskArn': 'string',
'clusterArn': 'string',
'taskDefinitionArn': 'string',
'containerInstanceArn': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'taskRoleArn': 'string'
},
'lastStatus': 'string',
'desiredStatus': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp'
},
]
},
],
'startedBy': 'string',
'version': 123,
'stoppedReason': 'string',
'createdAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'stoppedAt': datetime(2015, 1, 1)
},
],
'failures': [
{
'arn': 'string',
'reason': 'string'
},
]
}
Response Structure
(dict) --
tasks (list) --
The list of tasks.
(dict) --
Details on a task in a cluster.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
clusterArn (string) --
The Amazon Resource Name (ARN) of the cluster that hosts the task.
taskDefinitionArn (string) --
The Amazon Resource Name (ARN) of the task definition that creates the task.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instances that host the task.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides sent to a task.
(dict) --
The overrides that should be sent to a container.
name (string) --
The name of the container that receives the override.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition.
(string) --
environment (list) --
The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition.
(dict) --
A key and value pair object.
name (string) --
The name of the key value pair. For environment variables, this is the name of the environment variable.
value (string) --
The value of the key value pair. For environment variables, this is the value of the environment variable.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
lastStatus (string) --
The last known status of the task.
desiredStatus (string) --
The desired status of the task.
containers (list) --
The containers associated with the task.
(dict) --
A Docker container that is part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
name (string) --
The name of the container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (255 max characters) human-readable string to provide additional detail about a running or stopped container.
networkBindings (list) --
The network bindings associated with the container.
(dict) --
Details on the network bindings between a container and its host container instance. After a task reaches the RUNNING status, manual and automatic host and container port assignments are visible in the networkBindings section of DescribeTasks API responses.
bindIP (string) --
The IP address that the container is bound to on the container instance.
containerPort (integer) --
The port number on the container that is be used with the network binding.
hostPort (integer) --
The port number on the host that is used with the network binding.
protocol (string) --
The protocol used for the network binding.
startedBy (string) --
The tag specified when a task is started. If the task is started by an Amazon ECS service, then the startedBy parameter contains the deployment ID of the service that starts it.
version (integer) --
The version counter for the task. Every time a task experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS task state with CloudWatch events, you can compare the version of a task reported by the Amazon ECS APIs with the version reported in CloudWatch events for the task (inside the detail object) to verify that the version in your event stream is current.
stoppedReason (string) --
The reason the task was stopped.
createdAt (datetime) --
The Unix timestamp for when the task was created (the task entered the PENDING state).
startedAt (datetime) --
The Unix timestamp for when the task was started (the task transitioned from the PENDING state to the RUNNING state).
stoppedAt (datetime) --
The Unix timestamp for when the task was stopped (the task transitioned from the RUNNING state to the STOPPED state).
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
{'containerInstance': {'version': 'long'}}
Note
This action is only used by the Amazon EC2 Container Service agent, and it is not intended for use outside of the agent.
Registers an EC2 instance into the specified cluster. This instance becomes available to place containers on.
Request Syntax
client.register_container_instance(
cluster='string',
instanceIdentityDocument='string',
instanceIdentityDocumentSignature='string',
totalResources=[
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
versionInfo={
'agentVersion': 'string',
'agentHash': 'string',
'dockerVersion': 'string'
},
containerInstanceArn='string',
attributes=[
{
'name': 'string',
'value': 'string'
},
]
)
string
The short name or full Amazon Resource Name (ARN) of the cluster with which to register your container instance. If you do not specify a cluster, the default cluster is assumed.
string
The instance identity document for the EC2 instance to register. This document can be found by running the following command from the instance: curl http://169.254.169.254/latest/dynamic/instance-identity/document/
string
The instance identity document signature for the EC2 instance to register. This signature can be found by running the following command from the instance: curl http://169.254.169.254/latest/dynamic/instance-identity/signature/
list
The resources available on the instance.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
dict
The version information for the Amazon ECS container agent and Docker daemon running on the container instance.
agentVersion (string) --
The version number of the Amazon ECS container agent.
agentHash (string) --
The Git commit hash for the Amazon ECS container agent build on the amazon-ecs-agent GitHub repository.
dockerVersion (string) --
The Docker version running on the container instance.
string
The Amazon Resource Name (ARN) of the container instance (if it was previously registered).
list
The container instance attributes that this container instance supports.
(dict) --
The attributes applicable to a container instance when it is registered.
name (string) -- [REQUIRED]
The name of the container instance attribute.
value (string) --
The value of the container instance attribute (at this time, the value here is Null , but this could change in future revisions for expandability).
dict
Response Syntax
{
'containerInstance': {
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'version': 123,
'versionInfo': {
'agentVersion': 'string',
'agentHash': 'string',
'dockerVersion': 'string'
},
'remainingResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'registeredResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'status': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string'
},
]
}
}
Response Structure
(dict) --
containerInstance (dict) --
The container instance that was registered.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. The ARN contains the arn:aws:ecs namespace, followed by the region of the container instance, the AWS account ID of the container instance owner, the container-instance namespace, and then the container instance ID. For example, ``arn:aws:ecs:region :aws_account_id :container-instance/container_instance_ID `` .
ec2InstanceId (string) --
The EC2 instance ID of the container instance.
version (integer) --
The version counter for the container instance. Every time a container instance experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS container instance state with CloudWatch events, you can compare the version of a container instance reported by the Amazon ECS APIs with the version reported in CloudWatch events for the container instance (inside the detail object) to verify that the version in your event stream is current.
versionInfo (dict) --
The version information for the Amazon ECS container agent and Docker daemon running on the container instance.
agentVersion (string) --
The version number of the Amazon ECS container agent.
agentHash (string) --
The Git commit hash for the Amazon ECS container agent build on the amazon-ecs-agent GitHub repository.
dockerVersion (string) --
The Docker version running on the container instance.
remainingResources (list) --
For most resource types, this parameter describes the remaining resources of the container instance that are available for new tasks. For port resource types, this parameter describes the ports that are reserved by the Amazon ECS container agent and any containers that have reserved port mappings; any port that is not specified here is available for new tasks.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
registeredResources (list) --
For most resource types, this parameter describes the registered resources on the container instance that are in use by current tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent when it registered the container instance with Amazon ECS.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
status (string) --
The status of the container instance. The valid values are ACTIVE or INACTIVE . ACTIVE indicates that the container instance can accept tasks.
agentConnected (boolean) --
This parameter returns true if the agent is actually connected to Amazon ECS. Registered instances with an agent that may be unhealthy or stopped return false , and instances without a connected agent cannot accept placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that are in the RUNNING status.
pendingTasksCount (integer) --
The number of tasks on the container instance that are in the PENDING status.
agentUpdateStatus (string) --
The status of the most recent agent update. If an update has never been requested, this value is NULL .
attributes (list) --
The attributes set for the container instance by the Amazon ECS container agent at instance registration.
(dict) --
The attributes applicable to a container instance when it is registered.
name (string) --
The name of the container instance attribute.
value (string) --
The value of the container instance attribute (at this time, the value here is Null , but this could change in future revisions for expandability).
{'tasks': {'version': 'long'}}
Start a task using random placement and the default Amazon ECS scheduler. To use your own scheduler or place a task on a specific container instance, use StartTask instead.
Warning
The count parameter is limited to 10 tasks per call.
Request Syntax
client.run_task(
cluster='string',
taskDefinition='string',
overrides={
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'taskRoleArn': 'string'
},
count=123,
startedBy='string'
)
string
The short name or full Amazon Resource Name (ARN) of the cluster on which to run your task. If you do not specify a cluster, the default cluster is assumed.
string
[REQUIRED]
The family and revision (family:revision ) or full Amazon Resource Name (ARN) of the task definition to run. If a revision is not specified, the latest ACTIVE revision is used.
dict
A list of container overrides in JSON format that specify the name of a container in the specified task definition and the overrides it should receive. You can override the default command for a container (that is specified in the task definition or Docker image) with a command override. You can also override existing environment variables (that are specified in the task definition or Docker image) on a container or add new environment variables to it with an environment override.
Note
A total of 8192 characters are allowed for overrides. This limit includes the JSON formatting characters of the override structure.
containerOverrides (list) --
One or more container overrides sent to a task.
(dict) --
The overrides that should be sent to a container.
name (string) --
The name of the container that receives the override.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition.
(string) --
environment (list) --
The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition.
(dict) --
A key and value pair object.
name (string) --
The name of the key value pair. For environment variables, this is the name of the environment variable.
value (string) --
The value of the key value pair. For environment variables, this is the value of the environment variable.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
integer
The number of instantiations of the specified task to place on your cluster.
Warning
The count parameter is limited to 10 tasks per call.
string
An optional tag specified when a task is started. For example if you automatically trigger a task to run a batch process job, you could apply a unique identifier for that job to your task with the startedBy parameter. You can then identify which tasks belong to that job by filtering the results of a ListTasks call with the startedBy value. Up to 36 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
If a task is started by an Amazon ECS service, then the startedBy parameter contains the deployment ID of the service that starts it.
dict
Response Syntax
{
'tasks': [
{
'taskArn': 'string',
'clusterArn': 'string',
'taskDefinitionArn': 'string',
'containerInstanceArn': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'taskRoleArn': 'string'
},
'lastStatus': 'string',
'desiredStatus': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp'
},
]
},
],
'startedBy': 'string',
'version': 123,
'stoppedReason': 'string',
'createdAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'stoppedAt': datetime(2015, 1, 1)
},
],
'failures': [
{
'arn': 'string',
'reason': 'string'
},
]
}
Response Structure
(dict) --
tasks (list) --
A full description of the tasks that were run. Each task that was successfully placed on your cluster are described here.
(dict) --
Details on a task in a cluster.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
clusterArn (string) --
The Amazon Resource Name (ARN) of the cluster that hosts the task.
taskDefinitionArn (string) --
The Amazon Resource Name (ARN) of the task definition that creates the task.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instances that host the task.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides sent to a task.
(dict) --
The overrides that should be sent to a container.
name (string) --
The name of the container that receives the override.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition.
(string) --
environment (list) --
The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition.
(dict) --
A key and value pair object.
name (string) --
The name of the key value pair. For environment variables, this is the name of the environment variable.
value (string) --
The value of the key value pair. For environment variables, this is the value of the environment variable.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
lastStatus (string) --
The last known status of the task.
desiredStatus (string) --
The desired status of the task.
containers (list) --
The containers associated with the task.
(dict) --
A Docker container that is part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
name (string) --
The name of the container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (255 max characters) human-readable string to provide additional detail about a running or stopped container.
networkBindings (list) --
The network bindings associated with the container.
(dict) --
Details on the network bindings between a container and its host container instance. After a task reaches the RUNNING status, manual and automatic host and container port assignments are visible in the networkBindings section of DescribeTasks API responses.
bindIP (string) --
The IP address that the container is bound to on the container instance.
containerPort (integer) --
The port number on the container that is be used with the network binding.
hostPort (integer) --
The port number on the host that is used with the network binding.
protocol (string) --
The protocol used for the network binding.
startedBy (string) --
The tag specified when a task is started. If the task is started by an Amazon ECS service, then the startedBy parameter contains the deployment ID of the service that starts it.
version (integer) --
The version counter for the task. Every time a task experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS task state with CloudWatch events, you can compare the version of a task reported by the Amazon ECS APIs with the version reported in CloudWatch events for the task (inside the detail object) to verify that the version in your event stream is current.
stoppedReason (string) --
The reason the task was stopped.
createdAt (datetime) --
The Unix timestamp for when the task was created (the task entered the PENDING state).
startedAt (datetime) --
The Unix timestamp for when the task was started (the task transitioned from the PENDING state to the RUNNING state).
stoppedAt (datetime) --
The Unix timestamp for when the task was stopped (the task transitioned from the RUNNING state to the STOPPED state).
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
{'tasks': {'version': 'long'}}
Starts a new task from the specified task definition on the specified container instance or instances. To use the default Amazon ECS scheduler to place your task, use RunTask instead.
Warning
The list of container instances to start tasks on is limited to 10.
Request Syntax
client.start_task(
cluster='string',
taskDefinition='string',
overrides={
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'taskRoleArn': 'string'
},
containerInstances=[
'string',
],
startedBy='string'
)
string
The short name or full Amazon Resource Name (ARN) of the cluster on which to start your task. If you do not specify a cluster, the default cluster is assumed.
string
[REQUIRED]
The family and revision (family:revision ) or full Amazon Resource Name (ARN) of the task definition to start. If a revision is not specified, the latest ACTIVE revision is used.
dict
A list of container overrides in JSON format that specify the name of a container in the specified task definition and the overrides it should receive. You can override the default command for a container (that is specified in the task definition or Docker image) with a command override. You can also override existing environment variables (that are specified in the task definition or Docker image) on a container or add new environment variables to it with an environment override.
Note
A total of 8192 characters are allowed for overrides. This limit includes the JSON formatting characters of the override structure.
containerOverrides (list) --
One or more container overrides sent to a task.
(dict) --
The overrides that should be sent to a container.
name (string) --
The name of the container that receives the override.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition.
(string) --
environment (list) --
The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition.
(dict) --
A key and value pair object.
name (string) --
The name of the key value pair. For environment variables, this is the name of the environment variable.
value (string) --
The value of the key value pair. For environment variables, this is the value of the environment variable.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
list
[REQUIRED]
The container instance IDs or full Amazon Resource Name (ARN) entries for the container instances on which you would like to place your task.
Warning
The list of container instances to start tasks on is limited to 10.
(string) --
string
An optional tag specified when a task is started. For example if you automatically trigger a task to run a batch process job, you could apply a unique identifier for that job to your task with the startedBy parameter. You can then identify which tasks belong to that job by filtering the results of a ListTasks call with the startedBy value. Up to 36 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
If a task is started by an Amazon ECS service, then the startedBy parameter contains the deployment ID of the service that starts it.
dict
Response Syntax
{
'tasks': [
{
'taskArn': 'string',
'clusterArn': 'string',
'taskDefinitionArn': 'string',
'containerInstanceArn': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'taskRoleArn': 'string'
},
'lastStatus': 'string',
'desiredStatus': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp'
},
]
},
],
'startedBy': 'string',
'version': 123,
'stoppedReason': 'string',
'createdAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'stoppedAt': datetime(2015, 1, 1)
},
],
'failures': [
{
'arn': 'string',
'reason': 'string'
},
]
}
Response Structure
(dict) --
tasks (list) --
A full description of the tasks that were started. Each task that was successfully placed on your container instances are described here.
(dict) --
Details on a task in a cluster.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
clusterArn (string) --
The Amazon Resource Name (ARN) of the cluster that hosts the task.
taskDefinitionArn (string) --
The Amazon Resource Name (ARN) of the task definition that creates the task.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instances that host the task.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides sent to a task.
(dict) --
The overrides that should be sent to a container.
name (string) --
The name of the container that receives the override.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition.
(string) --
environment (list) --
The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition.
(dict) --
A key and value pair object.
name (string) --
The name of the key value pair. For environment variables, this is the name of the environment variable.
value (string) --
The value of the key value pair. For environment variables, this is the value of the environment variable.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
lastStatus (string) --
The last known status of the task.
desiredStatus (string) --
The desired status of the task.
containers (list) --
The containers associated with the task.
(dict) --
A Docker container that is part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
name (string) --
The name of the container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (255 max characters) human-readable string to provide additional detail about a running or stopped container.
networkBindings (list) --
The network bindings associated with the container.
(dict) --
Details on the network bindings between a container and its host container instance. After a task reaches the RUNNING status, manual and automatic host and container port assignments are visible in the networkBindings section of DescribeTasks API responses.
bindIP (string) --
The IP address that the container is bound to on the container instance.
containerPort (integer) --
The port number on the container that is be used with the network binding.
hostPort (integer) --
The port number on the host that is used with the network binding.
protocol (string) --
The protocol used for the network binding.
startedBy (string) --
The tag specified when a task is started. If the task is started by an Amazon ECS service, then the startedBy parameter contains the deployment ID of the service that starts it.
version (integer) --
The version counter for the task. Every time a task experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS task state with CloudWatch events, you can compare the version of a task reported by the Amazon ECS APIs with the version reported in CloudWatch events for the task (inside the detail object) to verify that the version in your event stream is current.
stoppedReason (string) --
The reason the task was stopped.
createdAt (datetime) --
The Unix timestamp for when the task was created (the task entered the PENDING state).
startedAt (datetime) --
The Unix timestamp for when the task was started (the task transitioned from the PENDING state to the RUNNING state).
stoppedAt (datetime) --
The Unix timestamp for when the task was stopped (the task transitioned from the RUNNING state to the STOPPED state).
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
{'task': {'version': 'long'}}
Stops a running task.
When StopTask is called on a task, the equivalent of docker stop is issued to the containers running in the task. This results in a SIGTERM and a 30-second timeout, after which SIGKILL is sent and the containers are forcibly stopped. If the container handles the SIGTERM gracefully and exits within 30 seconds from receiving it, no SIGKILL is sent.
Request Syntax
client.stop_task(
cluster='string',
task='string',
reason='string'
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that hosts the task to stop. If you do not specify a cluster, the default cluster is assumed.
string
[REQUIRED]
The task ID or full Amazon Resource Name (ARN) entry of the task to stop.
string
An optional message specified when a task is stopped. For example, if you are using a custom scheduler, you can use this parameter to specify the reason for stopping the task here, and the message will appear in subsequent DescribeTasks API operations on this task. Up to 255 characters are allowed in this message.
dict
Response Syntax
{
'task': {
'taskArn': 'string',
'clusterArn': 'string',
'taskDefinitionArn': 'string',
'containerInstanceArn': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'taskRoleArn': 'string'
},
'lastStatus': 'string',
'desiredStatus': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp'
},
]
},
],
'startedBy': 'string',
'version': 123,
'stoppedReason': 'string',
'createdAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'stoppedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
task (dict) --
The task that was stopped.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
clusterArn (string) --
The Amazon Resource Name (ARN) of the cluster that hosts the task.
taskDefinitionArn (string) --
The Amazon Resource Name (ARN) of the task definition that creates the task.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instances that host the task.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides sent to a task.
(dict) --
The overrides that should be sent to a container.
name (string) --
The name of the container that receives the override.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition.
(string) --
environment (list) --
The environment variables to send to the container. You can add new environment variables, which are added to the container at launch, or you can override the existing environment variables from the Docker image or the task definition.
(dict) --
A key and value pair object.
name (string) --
The name of the key value pair. For environment variables, this is the name of the environment variable.
value (string) --
The value of the key value pair. For environment variables, this is the value of the environment variable.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
lastStatus (string) --
The last known status of the task.
desiredStatus (string) --
The desired status of the task.
containers (list) --
The containers associated with the task.
(dict) --
A Docker container that is part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
name (string) --
The name of the container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (255 max characters) human-readable string to provide additional detail about a running or stopped container.
networkBindings (list) --
The network bindings associated with the container.
(dict) --
Details on the network bindings between a container and its host container instance. After a task reaches the RUNNING status, manual and automatic host and container port assignments are visible in the networkBindings section of DescribeTasks API responses.
bindIP (string) --
The IP address that the container is bound to on the container instance.
containerPort (integer) --
The port number on the container that is be used with the network binding.
hostPort (integer) --
The port number on the host that is used with the network binding.
protocol (string) --
The protocol used for the network binding.
startedBy (string) --
The tag specified when a task is started. If the task is started by an Amazon ECS service, then the startedBy parameter contains the deployment ID of the service that starts it.
version (integer) --
The version counter for the task. Every time a task experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS task state with CloudWatch events, you can compare the version of a task reported by the Amazon ECS APIs with the version reported in CloudWatch events for the task (inside the detail object) to verify that the version in your event stream is current.
stoppedReason (string) --
The reason the task was stopped.
createdAt (datetime) --
The Unix timestamp for when the task was created (the task entered the PENDING state).
startedAt (datetime) --
The Unix timestamp for when the task was started (the task transitioned from the PENDING state to the RUNNING state).
stoppedAt (datetime) --
The Unix timestamp for when the task was stopped (the task transitioned from the RUNNING state to the STOPPED state).
{'containerInstance': {'version': 'long'}}
Updates the Amazon ECS container agent on a specified container instance. Updating the Amazon ECS container agent does not interrupt running tasks or services on the container instance. The process for updating the agent differs depending on whether your container instance was launched with the Amazon ECS-optimized AMI or another operating system.
UpdateContainerAgent requires the Amazon ECS-optimized AMI or Amazon Linux with the ecs-init service installed and running. For help updating the Amazon ECS container agent on other operating systems, see Manually Updating the Amazon ECS Container Agent in the Amazon EC2 Container Service Developer Guide .
Request Syntax
client.update_container_agent(
cluster='string',
containerInstance='string'
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that your container instance is running on. If you do not specify a cluster, the default cluster is assumed.
string
[REQUIRED]
The container instance ID or full Amazon Resource Name (ARN) entries for the container instance on which you would like to update the Amazon ECS container agent.
dict
Response Syntax
{
'containerInstance': {
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'version': 123,
'versionInfo': {
'agentVersion': 'string',
'agentHash': 'string',
'dockerVersion': 'string'
},
'remainingResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'registeredResources': [
{
'name': 'string',
'type': 'string',
'doubleValue': 123.0,
'longValue': 123,
'integerValue': 123,
'stringSetValue': [
'string',
]
},
],
'status': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string'
},
]
}
}
Response Structure
(dict) --
containerInstance (dict) --
The container instance for which the container agent was updated.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. The ARN contains the arn:aws:ecs namespace, followed by the region of the container instance, the AWS account ID of the container instance owner, the container-instance namespace, and then the container instance ID. For example, ``arn:aws:ecs:region :aws_account_id :container-instance/container_instance_ID `` .
ec2InstanceId (string) --
The EC2 instance ID of the container instance.
version (integer) --
The version counter for the container instance. Every time a container instance experiences a change that triggers a CloudWatch event, the version counter is incremented. If you are replicating your Amazon ECS container instance state with CloudWatch events, you can compare the version of a container instance reported by the Amazon ECS APIs with the version reported in CloudWatch events for the container instance (inside the detail object) to verify that the version in your event stream is current.
versionInfo (dict) --
The version information for the Amazon ECS container agent and Docker daemon running on the container instance.
agentVersion (string) --
The version number of the Amazon ECS container agent.
agentHash (string) --
The Git commit hash for the Amazon ECS container agent build on the amazon-ecs-agent GitHub repository.
dockerVersion (string) --
The Docker version running on the container instance.
remainingResources (list) --
For most resource types, this parameter describes the remaining resources of the container instance that are available for new tasks. For port resource types, this parameter describes the ports that are reserved by the Amazon ECS container agent and any containers that have reserved port mappings; any port that is not specified here is available for new tasks.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
registeredResources (list) --
For most resource types, this parameter describes the registered resources on the container instance that are in use by current tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent when it registered the container instance with Amazon ECS.
(dict) --
Describes the resources available for a container instance.
name (string) --
The name of the resource, such as CPU , MEMORY , PORTS , or a user-defined resource.
type (string) --
The type of the resource, such as INTEGER , DOUBLE , LONG , or STRINGSET .
doubleValue (float) --
When the doubleValue type is set, the value of the resource must be a double precision floating-point type.
longValue (integer) --
When the longValue type is set, the value of the resource must be an extended precision floating-point type.
integerValue (integer) --
When the integerValue type is set, the value of the resource must be an integer.
stringSetValue (list) --
When the stringSetValue type is set, the value of the resource must be a string type.
(string) --
status (string) --
The status of the container instance. The valid values are ACTIVE or INACTIVE . ACTIVE indicates that the container instance can accept tasks.
agentConnected (boolean) --
This parameter returns true if the agent is actually connected to Amazon ECS. Registered instances with an agent that may be unhealthy or stopped return false , and instances without a connected agent cannot accept placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that are in the RUNNING status.
pendingTasksCount (integer) --
The number of tasks on the container instance that are in the PENDING status.
agentUpdateStatus (string) --
The status of the most recent agent update. If an update has never been requested, this value is NULL .
attributes (list) --
The attributes set for the container instance by the Amazon ECS container agent at instance registration.
(dict) --
The attributes applicable to a container instance when it is registered.
name (string) --
The name of the container instance attribute.
value (string) --
The value of the container instance attribute (at this time, the value here is Null , but this could change in future revisions for expandability).