2026/08/05 - Amazon EC2 Container Service - 9 updated api methods
Changes New enum values added for Agent Connectivity issues
{'containerInstance': {'healthStatus': {'details': {'type': {'AGENT_CONNECTIVITY'}}}}}
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, we recommend that you stop all of the tasks running on the container instance before deregistration. That prevents any orphaned tasks from consuming resources.
Deregistering a container instance removes the instance from a cluster, but it doesn't terminate the EC2 instance. If you are finished using the instance, be sure to terminate it in the Amazon EC2 console to stop billing.
See also: AWS API Documentation
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 ARN of the container instance to deregister. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.
boolean
Forces the container instance to be deregistered. 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're 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. They begin connection draining according to the settings on the load balancer or target group.
dict
Response Syntax
{
'containerInstance': {
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'capacityProviderName': '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',
'statusReason': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'registeredAt': datetime(2015, 1, 1),
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'healthStatus': {
'overallStatus': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'details': [
{
'type': 'CONTAINER_RUNTIME'|'ACCELERATED_COMPUTE'|'DAEMON'|'AGENT_CONNECTIVITY',
'status': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'statusReason': 'string',
'lastUpdated': datetime(2015, 1, 1),
'lastStatusChange': datetime(2015, 1, 1)
},
]
}
}
}
Response Structure
(dict) --
containerInstance (dict) --
The container instance that was deregistered.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.
ec2InstanceId (string) --
The ID of the container instance. For Amazon EC2 instances, this value is the Amazon EC2 instance ID. For external instances, this value is the Amazon Web Services Systems Manager managed instance ID.
capacityProviderName (string) --
The capacity provider that's associated with 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're 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 that's running on the container instance.
remainingResources (list) --
For CPU and memory resource types, this parameter describes the remaining CPU and memory that wasn't already allocated to tasks and is therefore available for new tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent (at instance registration time) and any task containers that have reserved port mappings on the host (with the host or bridge network mode). Any port that's 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 CPU and memory resource types, this parameter describes the amount of each resource that was available on the container instance when the container agent registered it with Amazon ECS. This value represents the total amount of CPU and memory that can be allocated on this container instance to 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 REGISTERING, REGISTRATION_FAILED, ACTIVE, INACTIVE, DEREGISTERING, or DRAINING.
If your account has opted in to the awsvpcTrunking account setting, then any newly registered container instance will transition to a REGISTERING status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance will transition to a REGISTRATION_FAILED status. You can describe the container instance and see the reason for failure in the statusReason parameter. Once the container instance is terminated, the instance transitions to a DEREGISTERING status while the trunk elastic network interface is deprovisioned. The instance then transitions to an INACTIVE status.
The ACTIVE status indicates that the container instance can accept tasks. The DRAINING indicates that new tasks aren't placed on the container instance and any service tasks running on the container instance are removed if possible. For more information, see Container instance draining in the Amazon Elastic Container Service Developer Guide.
statusReason (string) --
The reason that the container instance reached its current status.
agentConnected (boolean) --
This parameter returns true if the agent is connected to Amazon ECS. An instance with an agent that may be unhealthy or stopped return false. Only instances connected to an agent can accept task placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that have a desired status ( desiredStatus) of RUNNING.
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 wasn't ever requested, this value is NULL.
attributes (list) --
The attributes set for the container instance, either by the Amazon ECS container agent at instance registration or manually with the PutAttributes operation.
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
registeredAt (datetime) --
The Unix timestamp for the time when the container instance was registered.
attachments (list) --
The resources attached to a container instance, such as an elastic network interface.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
tags (list) --
The metadata that you apply to the container instance to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
healthStatus (dict) --
An object representing the health status of the container instance.
overallStatus (string) --
The overall health status of the container instance. This is an aggregate status of all container instance health checks.
details (list) --
An array of objects representing the details of the container instance health status.
(dict) --
An object representing the result of a container instance health status check.
type (string) --
The type of container instance health status that was verified.
status (string) --
The container instance health status.
statusReason (string) --
The reason for the container instance health status.
lastUpdated (datetime) --
The Unix timestamp for when the container instance health status was last updated.
lastStatusChange (datetime) --
The Unix timestamp for when the container instance health status last changed.
{'containerInstances': {'healthStatus': {'details': {'type': {'AGENT_CONNECTIVITY'}}}}}
Describes one or more container instances. Returns metadata about each container instance requested.
See also: AWS API Documentation
Request Syntax
client.describe_container_instances(
cluster='string',
containerInstances=[
'string',
],
include=[
'TAGS'|'CONTAINER_INSTANCE_HEALTH',
]
)
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. This parameter is required if the container instance or container instances you are describing were launched in any cluster other than the default cluster.
list
[REQUIRED]
A list of up to 100 container instance IDs or full Amazon Resource Name (ARN) entries.
(string) --
list
Specifies whether you want to see the resource tags for the container instance. If TAGS is specified, the tags are included in the response. If CONTAINER_INSTANCE_HEALTH is specified, the container instance health is included in the response. If this field is omitted, tags and container instance health status aren't included in the response.
(string) --
dict
Response Syntax
{
'containerInstances': [
{
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'capacityProviderName': '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',
'statusReason': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'registeredAt': datetime(2015, 1, 1),
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'healthStatus': {
'overallStatus': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'details': [
{
'type': 'CONTAINER_RUNTIME'|'ACCELERATED_COMPUTE'|'DAEMON'|'AGENT_CONNECTIVITY',
'status': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'statusReason': 'string',
'lastUpdated': datetime(2015, 1, 1),
'lastStatusChange': datetime(2015, 1, 1)
},
]
}
},
],
'failures': [
{
'arn': 'string',
'reason': 'string',
'detail': 'string'
},
]
}
Response Structure
(dict) --
containerInstances (list) --
The list of container instances.
(dict) --
An Amazon EC2 or External instance that's running the Amazon ECS agent and has been registered with a cluster.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.
ec2InstanceId (string) --
The ID of the container instance. For Amazon EC2 instances, this value is the Amazon EC2 instance ID. For external instances, this value is the Amazon Web Services Systems Manager managed instance ID.
capacityProviderName (string) --
The capacity provider that's associated with 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're 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 that's running on the container instance.
remainingResources (list) --
For CPU and memory resource types, this parameter describes the remaining CPU and memory that wasn't already allocated to tasks and is therefore available for new tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent (at instance registration time) and any task containers that have reserved port mappings on the host (with the host or bridge network mode). Any port that's 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 CPU and memory resource types, this parameter describes the amount of each resource that was available on the container instance when the container agent registered it with Amazon ECS. This value represents the total amount of CPU and memory that can be allocated on this container instance to 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 REGISTERING, REGISTRATION_FAILED, ACTIVE, INACTIVE, DEREGISTERING, or DRAINING.
If your account has opted in to the awsvpcTrunking account setting, then any newly registered container instance will transition to a REGISTERING status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance will transition to a REGISTRATION_FAILED status. You can describe the container instance and see the reason for failure in the statusReason parameter. Once the container instance is terminated, the instance transitions to a DEREGISTERING status while the trunk elastic network interface is deprovisioned. The instance then transitions to an INACTIVE status.
The ACTIVE status indicates that the container instance can accept tasks. The DRAINING indicates that new tasks aren't placed on the container instance and any service tasks running on the container instance are removed if possible. For more information, see Container instance draining in the Amazon Elastic Container Service Developer Guide.
statusReason (string) --
The reason that the container instance reached its current status.
agentConnected (boolean) --
This parameter returns true if the agent is connected to Amazon ECS. An instance with an agent that may be unhealthy or stopped return false. Only instances connected to an agent can accept task placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that have a desired status ( desiredStatus) of RUNNING.
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 wasn't ever requested, this value is NULL.
attributes (list) --
The attributes set for the container instance, either by the Amazon ECS container agent at instance registration or manually with the PutAttributes operation.
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
registeredAt (datetime) --
The Unix timestamp for the time when the container instance was registered.
attachments (list) --
The resources attached to a container instance, such as an elastic network interface.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
tags (list) --
The metadata that you apply to the container instance to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
healthStatus (dict) --
An object representing the health status of the container instance.
overallStatus (string) --
The overall health status of the container instance. This is an aggregate status of all container instance health checks.
details (list) --
An array of objects representing the details of the container instance health status.
(dict) --
An object representing the result of a container instance health status check.
type (string) --
The type of container instance health status that was verified.
status (string) --
The container instance health status.
statusReason (string) --
The reason for the container instance health status.
lastUpdated (datetime) --
The Unix timestamp for when the container instance health status was last updated.
lastStatusChange (datetime) --
The Unix timestamp for when the container instance health status last changed.
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource. For a list of common causes, see API failure reasons in the Amazon Elastic Container Service Developer Guide.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
detail (string) --
The details of the failure.
{'tasks': {'stopCode': {'InfrastructureHealth'}}}
Describes a specified task or tasks.
Currently, stopped tasks appear in the returned results for at least one hour.
If you have tasks with tags, and then delete the cluster, the tagged tasks are returned in the response. If you create a new cluster with the same name as the deleted cluster, the tagged tasks are not included in the response.
See also: AWS API Documentation
Request Syntax
client.describe_tasks(
cluster='string',
tasks=[
'string',
],
include=[
'TAGS',
]
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that hosts the task or tasks to describe. If you do not specify a cluster, the default cluster is assumed.
list
[REQUIRED]
A list of up to 100 task IDs or full ARN entries.
(string) --
list
Specifies whether you want to see the resource tags for the task. If TAGS is specified, the tags are included in the response. If this field is omitted, tags aren't included in the response.
(string) --
dict
Response Syntax
{
'tasks': [
{
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'availabilityZone': 'string',
'capacityProviderName': 'string',
'clusterArn': 'string',
'connectivity': 'CONNECTED'|'DISCONNECTED',
'connectivityAt': datetime(2015, 1, 1),
'containerInstanceArn': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'image': 'string',
'imageDigest': 'string',
'runtimeId': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp',
'containerPortRange': 'string',
'hostPortRange': 'string'
},
],
'networkInterfaces': [
{
'attachmentId': 'string',
'privateIpv4Address': 'string',
'ipv6Address': 'string'
},
],
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'managedAgents': [
{
'lastStartedAt': datetime(2015, 1, 1),
'name': 'ExecuteCommandAgent',
'reason': 'string',
'lastStatus': 'string'
},
],
'cpu': 'string',
'memory': 'string',
'memoryReservation': 'string',
'gpuIds': [
'string',
],
'neuronDeviceIds': [
'string',
]
},
],
'cpu': 'string',
'createdAt': datetime(2015, 1, 1),
'desiredStatus': 'string',
'enableExecuteCommand': True|False,
'executionStoppedAt': datetime(2015, 1, 1),
'group': 'string',
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'inferenceAccelerators': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'lastStatus': 'string',
'launchType': 'EC2'|'FARGATE'|'EXTERNAL'|'MANAGED_INSTANCES',
'memory': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
],
'environmentFiles': [
{
'value': 'string',
'type': 's3'
},
],
'cpu': 123,
'memory': 123,
'memoryReservation': 123,
'resourceRequirements': [
{
'value': 'string',
'type': 'GPU'|'InferenceAccelerator'|'NeuronDevice'
},
]
},
],
'cpu': 'string',
'inferenceAcceleratorOverrides': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'executionRoleArn': 'string',
'memory': 'string',
'taskRoleArn': 'string',
'ephemeralStorage': {
'sizeInGiB': 123
}
},
'platformVersion': 'string',
'platformFamily': 'string',
'pullStartedAt': datetime(2015, 1, 1),
'pullStoppedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'startedBy': 'string',
'stopCode': 'TaskFailedToStart'|'EssentialContainerExited'|'UserInitiated'|'ServiceSchedulerInitiated'|'SpotInterruption'|'TerminationNotice'|'InfrastructureHealth',
'stoppedAt': datetime(2015, 1, 1),
'stoppedReason': 'string',
'stoppingAt': datetime(2015, 1, 1),
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'taskArn': 'string',
'taskDefinitionArn': 'string',
'version': 123,
'ephemeralStorage': {
'sizeInGiB': 123
},
'fargateEphemeralStorage': {
'sizeInGiB': 123,
'kmsKeyId': 'string'
}
},
],
'failures': [
{
'arn': 'string',
'reason': 'string',
'detail': 'string'
},
]
}
Response Structure
(dict) --
tasks (list) --
The list of tasks.
(dict) --
Details on a task in a cluster.
attachments (list) --
The Elastic Network Adapter that's associated with the task if the task uses the awsvpc network mode.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
attributes (list) --
The attributes of the task
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
availabilityZone (string) --
The Availability Zone for the task.
capacityProviderName (string) --
The capacity provider that's associated with the task.
clusterArn (string) --
The ARN of the cluster that hosts the task.
connectivity (string) --
The connectivity status of a task.
connectivityAt (datetime) --
The Unix timestamp for the time when the task last went into CONNECTED status.
containerInstanceArn (string) --
The ARN of the container instances that host the task.
containers (list) --
The containers that's associated with the task.
(dict) --
A Docker container that's part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The ARN of the task.
name (string) --
The name of the container.
image (string) --
The image used for the container.
imageDigest (string) --
The container image manifest digest.
runtimeId (string) --
The ID of the Docker container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (1024 max characters) human-readable string to provide additional details 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's used with the network binding.
hostPort (integer) --
The port number on the host that's used with the network binding.
protocol (string) --
The protocol used for the network binding.
containerPortRange (string) --
The port number range on the container that's bound to the dynamically mapped host port range.
The following rules apply when you specify a containerPortRange:
You must use either the bridge network mode or the awsvpc network mode.
This parameter is available for both the EC2 and Fargate launch types.
This parameter is available for both the Linux and Windows operating systems.
The container instance must have at least version 1.67.0 of the container agent and at least version 1.67.0-1 of the ecs-init package
You can specify a maximum of 100 port ranges per container.
You do not specify a hostPortRange. The value of the hostPortRange is set as follows:
For containers in a task with the awsvpc network mode, the hostPortRange is set to the same value as the containerPortRange. This is a static mapping strategy.
For containers in a task with the bridge network mode, the Amazon ECS agent finds open host ports from the default ephemeral range and passes it to docker to bind them to the container ports.
The containerPortRange valid values are between 1 and 65535.
A port can only be included in one port mapping per container.
You cannot specify overlapping port ranges.
The first port in the range must be less than last port in the range.
Docker recommends that you turn off the docker-proxy in the Docker daemon config file when you have a large number of ports. For more information, see Issue #11185 on the Github website. For information about how to turn off the docker-proxy in the Docker daemon config file, see Docker daemon in the Amazon ECS Developer Guide.
You can call DescribeTasks to view the hostPortRange which are the host ports that are bound to the container ports.
hostPortRange (string) --
The port number range on the host that's used with the network binding. This is assigned is assigned by Docker and delivered by the Amazon ECS agent.
networkInterfaces (list) --
The network interfaces associated with the container.
(dict) --
An object representing the elastic network interface for tasks that use the awsvpc network mode.
attachmentId (string) --
The attachment ID for the network interface.
privateIpv4Address (string) --
The private IPv4 address for the network interface.
ipv6Address (string) --
The private IPv6 address for the network interface.
healthStatus (string) --
The health status of the container. If health checks aren't configured for this container in its task definition, then it reports the health status as UNKNOWN.
managedAgents (list) --
The details of any Amazon ECS managed agents associated with the container.
(dict) --
Details about the managed agent status for the container.
lastStartedAt (datetime) --
The Unix timestamp for the time when the managed agent was last started.
name (string) --
The name of the managed agent. When the execute command feature is turned on, the managed agent name is ExecuteCommandAgent.
reason (string) --
The reason for why the managed agent is in the state it is in.
lastStatus (string) --
The last known status of the managed agent.
cpu (string) --
The number of CPU units set for the container. The value is 0 if no value was specified in the container definition when the task definition was registered.
memory (string) --
The hard limit (in MiB) of memory set for the container.
memoryReservation (string) --
The soft limit (in MiB) of memory set for the container.
gpuIds (list) --
The IDs of each GPU assigned to the container.
(string) --
neuronDeviceIds (list) --
The IDs of each Neuron device assigned to the container.
(string) --
cpu (string) --
The number of CPU units used by the task as expressed in a task definition. It can be expressed as an integer using CPU units (for example, 1024). It can also be expressed as a string using vCPUs (for example, 1 vCPU or 1 vcpu). String values are converted to an integer that indicates the CPU units when the task definition is registered.
If you're using the EC2 launch type or the external launch type, this field is optional. Supported values are between 128 CPU units ( 0.125 vCPUs) and 196608 CPU units ( 192 vCPUs). If you do not specify a value, the parameter is ignored.
This field is required for Fargate. For information about the valid values, see Task size in the Amazon Elastic Container Service Developer Guide.
createdAt (datetime) --
The Unix timestamp for the time when the task was created. More specifically, it's for the time when the task entered the PENDING state.
desiredStatus (string) --
The desired status of the task. For more information, see Task Lifecycle.
enableExecuteCommand (boolean) --
Determines whether execute command functionality is turned on for this task. If true, execute command functionality is turned on all the containers in the task.
executionStoppedAt (datetime) --
The Unix timestamp for the time when the task execution stopped.
group (string) --
The name of the task group that's associated with the task.
healthStatus (string) --
The health status for the task. It's determined by the health of the essential containers in the task. If all essential containers in the task are reporting as HEALTHY, the task status also reports as HEALTHY. If any essential containers in the task are reporting as UNHEALTHY or UNKNOWN, the task status also reports as UNHEALTHY or UNKNOWN.
inferenceAccelerators (list) --
The Elastic Inference accelerator that's associated with the task.
(dict) --
Details on an Elastic Inference accelerator. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name. The deviceName must also be referenced in a container definition as a ResourceRequirement.
deviceType (string) --
The Elastic Inference accelerator type to use.
lastStatus (string) --
The last known status for the task. For more information, see Task Lifecycle.
launchType (string) --
The infrastructure where your task runs on. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The amount of memory (in MiB) that the task uses as expressed in a task definition. It can be expressed as an integer using MiB (for example, 1024). If it's expressed as a string using GB (for example, 1GB or 1 GB), it's converted to an integer indicating the MiB when the task definition is registered.
If you use the EC2 launch type, this field is optional.
If you use the Fargate launch type, this field is required. You must use one of the following values. The value that you choose determines the range of supported values for the cpu parameter.
512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) - Available cpu values: 256 (.25 vCPU)
1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) - Available cpu values: 512 (.5 vCPU)
2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) - Available cpu values: 1024 (1 vCPU)
Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) - Available cpu values: 2048 (2 vCPU)
Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) - Available cpu values: 4096 (4 vCPU)
Between 16 GB and 60 GB in 4 GB increments - Available cpu values: 8192 (8 vCPU) This option requires Linux platform 1.4.0 or later.
Between 32GB and 120 GB in 8 GB increments - Available cpu values: 16384 (16 vCPU) This option requires Linux platform 1.4.0 or later.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides that are sent to a task.
(dict) --
The overrides that are sent to a container. An empty container override can be passed in. An example of an empty container override is {"containerOverrides": [ ] }. If a non-empty container override is specified, the name parameter must be included.
You can use Secrets Manager or Amazon Web Services Systems Manager Parameter Store to store the sensitive data. For more information, see Retrieve secrets through environment variables in the Amazon ECS Developer Guide.
name (string) --
The name of the container that receives the override. This parameter is required if any override is specified.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name.
(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. You must also specify a container name.
(dict) --
A key-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.
environmentFiles (list) --
A list of files containing the environment variables to pass to a container, instead of the value from the container definition.
(dict) --
A list of files containing the environment variables to pass to a container. You can specify up to ten environment files. The file must have a .env file extension. Each line in an environment file should contain an environment variable in VARIABLE=VALUE format. Lines beginning with # are treated as comments and are ignored.
If there are environment variables specified using the environment parameter in a container definition, they take precedence over the variables contained within an environment file. If multiple environment files are specified that contain the same variable, they're processed from the top down. We recommend that you use unique variable names. For more information, see Use a file to pass environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply.
You must use the following platforms for the Fargate launch type:
Linux platform version 1.4.0 or later.
Windows platform version 1.0.0 or later.
Consider the following when using the Fargate launch type:
The file is handled like a native Docker env-file.
There is no support for shell escape handling.
The container entry point interperts the VARIABLE values.
value (string) --
The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file.
type (string) --
The file type to use. Environment files are objects in Amazon S3. The only supported value is s3.
cpu (integer) --
The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name.
memory (integer) --
The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name.
memoryReservation (integer) --
The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name.
resourceRequirements (list) --
The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices.
(dict) --
The type and amount of a resource to assign to a container. The supported resource types are GPUs, Neuron devices, and Elastic Inference accelerators. For more information, see Working with GPUs on Amazon ECS or Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide
value (string) --
The value for the specified resource type.
When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container.
When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devices on the instance to the container. Only one container in a task can specify NeuronDevice resources. This resource type is only supported on Managed Instances.
When the type is InferenceAccelerator, the value matches the deviceName for an InferenceAccelerator specified in a task definition.
type (string) --
The type of resource to assign to a container.
cpu (string) --
The CPU override for the task.
inferenceAcceleratorOverrides (list) --
The Elastic Inference accelerator override for the task.
(dict) --
Details on an Elastic Inference accelerator task override. This parameter is used to override the Elastic Inference accelerator specified in the task definition. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition.
deviceType (string) --
The Elastic Inference accelerator type to use.
executionRoleArn (string) --
The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The memory override for the task.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide.
ephemeralStorage (dict) --
The ephemeral storage setting override for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
platformVersion (string) --
The platform version where your task runs on. A platform version is only specified for tasks that use the Fargate launch type. If you didn't specify one, the LATEST platform version is used. For more information, see Fargate Platform Versions in the Amazon Elastic Container Service Developer Guide.
platformFamily (string) --
The operating system that your tasks are running on. A platform family is specified only for tasks that use the Fargate launch type.
All tasks that run as part of this service must use the same platformFamily value as the service (for example, LINUX.).
pullStartedAt (datetime) --
The Unix timestamp for the time when the container image pull began.
pullStoppedAt (datetime) --
The Unix timestamp for the time when the container image pull completed.
startedAt (datetime) --
The Unix timestamp for the time when the task started. More specifically, it's for the time when the task transitioned from the PENDING state to the RUNNING state.
startedBy (string) --
The tag specified when a task is started. If an Amazon ECS service started the task, the startedBy parameter contains the deployment ID of that service.
stopCode (string) --
The stop code indicating why a task was stopped. The stoppedReason might contain additional details.
For more information about stop code, see Stopped tasks error codes in the Amazon ECS Developer Guide.
stoppedAt (datetime) --
The Unix timestamp for the time when the task was stopped. More specifically, it's for the time when the task transitioned from the RUNNING state to the STOPPED state.
stoppedReason (string) --
The reason that the task was stopped.
stoppingAt (datetime) --
The Unix timestamp for the time when the task stops. More specifically, it's for the time when the task transitions from the RUNNING state to STOPPING.
tags (list) --
The metadata that you apply to the task to help you categorize and organize the task. Each tag consists of a key and an optional value. You define both the key and value.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
taskDefinitionArn (string) --
The ARN of the task definition that creates the task.
version (integer) --
The version counter for the task. Every time a task experiences a change that starts a CloudWatch event, the version counter is incremented. If you replicate your Amazon ECS task state with CloudWatch Events, you can compare the version of a task reported by the Amazon ECS API actions 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.
ephemeralStorage (dict) --
The ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
fargateEphemeralStorage (dict) --
The Fargate ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of the ephemeral storage to set for the task. The minimum supported value is 20 GiB and the maximum supported value is 200 GiB.
kmsKeyId (string) --
Specify an Key Management Service key ID to encrypt the ephemeral storage for the task.
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource. For a list of common causes, see API failure reasons in the Amazon Elastic Container Service Developer Guide.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
detail (string) --
The details of the failure.
{'containerInstance': {'healthStatus': {'details': {'type': {'AGENT_CONNECTIVITY'}}}}}
Registers an EC2 instance into the specified cluster. This instance becomes available to place containers on.
See also: AWS API Documentation
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',
'targetType': 'container-instance',
'targetId': 'string'
},
],
platformDevices=[
{
'id': 'string',
'type': 'GPU'|'NEURON_DEVICE'
},
],
tags=[
{
'key': 'string',
'value': 'string'
},
]
)
string
The short name or full Amazon Resource Name (ARN) of the cluster to register your container instance with. 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 that runs 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 that's running on the container instance.
string
The ARN of the container instance (if it was previously registered).
list
The container instance attributes that this container instance supports.
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) -- [REQUIRED]
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
list
The devices that are available on the container instance. The supported device types are GPUs and Neuron devices.
(dict) --
The devices that are available on the container instance. The supported device types are GPUs and Neuron devices.
id (string) -- [REQUIRED]
The ID for the GPU or Neuron device on the container instance. For GPUs, the available GPU IDs can also be obtained on the container instance in the /var/lib/ecs/gpu/nvidia_gpu_info.json file. For Neuron devices, the ID corresponds to the device index (for example, 0 for /dev/neuron0).
type (string) -- [REQUIRED]
The type of device that's available on the container instance. The supported values are GPU and NEURON_DEVICE.
list
The metadata that you apply to the container instance to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
dict
Response Syntax
{
'containerInstance': {
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'capacityProviderName': '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',
'statusReason': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'registeredAt': datetime(2015, 1, 1),
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'healthStatus': {
'overallStatus': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'details': [
{
'type': 'CONTAINER_RUNTIME'|'ACCELERATED_COMPUTE'|'DAEMON'|'AGENT_CONNECTIVITY',
'status': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'statusReason': 'string',
'lastUpdated': datetime(2015, 1, 1),
'lastStatusChange': datetime(2015, 1, 1)
},
]
}
}
}
Response Structure
(dict) --
containerInstance (dict) --
The container instance that was registered.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.
ec2InstanceId (string) --
The ID of the container instance. For Amazon EC2 instances, this value is the Amazon EC2 instance ID. For external instances, this value is the Amazon Web Services Systems Manager managed instance ID.
capacityProviderName (string) --
The capacity provider that's associated with 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're 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 that's running on the container instance.
remainingResources (list) --
For CPU and memory resource types, this parameter describes the remaining CPU and memory that wasn't already allocated to tasks and is therefore available for new tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent (at instance registration time) and any task containers that have reserved port mappings on the host (with the host or bridge network mode). Any port that's 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 CPU and memory resource types, this parameter describes the amount of each resource that was available on the container instance when the container agent registered it with Amazon ECS. This value represents the total amount of CPU and memory that can be allocated on this container instance to 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 REGISTERING, REGISTRATION_FAILED, ACTIVE, INACTIVE, DEREGISTERING, or DRAINING.
If your account has opted in to the awsvpcTrunking account setting, then any newly registered container instance will transition to a REGISTERING status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance will transition to a REGISTRATION_FAILED status. You can describe the container instance and see the reason for failure in the statusReason parameter. Once the container instance is terminated, the instance transitions to a DEREGISTERING status while the trunk elastic network interface is deprovisioned. The instance then transitions to an INACTIVE status.
The ACTIVE status indicates that the container instance can accept tasks. The DRAINING indicates that new tasks aren't placed on the container instance and any service tasks running on the container instance are removed if possible. For more information, see Container instance draining in the Amazon Elastic Container Service Developer Guide.
statusReason (string) --
The reason that the container instance reached its current status.
agentConnected (boolean) --
This parameter returns true if the agent is connected to Amazon ECS. An instance with an agent that may be unhealthy or stopped return false. Only instances connected to an agent can accept task placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that have a desired status ( desiredStatus) of RUNNING.
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 wasn't ever requested, this value is NULL.
attributes (list) --
The attributes set for the container instance, either by the Amazon ECS container agent at instance registration or manually with the PutAttributes operation.
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
registeredAt (datetime) --
The Unix timestamp for the time when the container instance was registered.
attachments (list) --
The resources attached to a container instance, such as an elastic network interface.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
tags (list) --
The metadata that you apply to the container instance to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
healthStatus (dict) --
An object representing the health status of the container instance.
overallStatus (string) --
The overall health status of the container instance. This is an aggregate status of all container instance health checks.
details (list) --
An array of objects representing the details of the container instance health status.
(dict) --
An object representing the result of a container instance health status check.
type (string) --
The type of container instance health status that was verified.
status (string) --
The container instance health status.
statusReason (string) --
The reason for the container instance health status.
lastUpdated (datetime) --
The Unix timestamp for when the container instance health status was last updated.
lastStatusChange (datetime) --
The Unix timestamp for when the container instance health status last changed.
{'tasks': {'stopCode': {'InfrastructureHealth'}}}
Starts a new task using the specified task definition.
You can allow Amazon ECS to place tasks for you, or you can customize how Amazon ECS places tasks using placement constraints and placement strategies. For more information, see Scheduling Tasks in the Amazon Elastic Container Service Developer Guide.
Alternatively, you can use StartTask to use your own scheduler or place tasks manually on specific container instances.
You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. For more information, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide.
The Amazon ECS API follows an eventual consistency model. This is because of the distributed nature of the system supporting the API. This means that the result of an API command you run that affects your Amazon ECS resources might not be immediately visible to all subsequent commands you run. Keep this in mind when you carry out an API command that immediately follows a previous API command.
To manage eventual consistency, you can do the following:
Confirm the state of the resource before you run a command to modify it. Run the DescribeTasks command using an exponential backoff algorithm to ensure that you allow enough time for the previous command to propagate through the system. To do this, run the DescribeTasks command repeatedly, starting with a couple of seconds of wait time and increasing gradually up to five minutes of wait time.
Add wait time between subsequent commands, even if the DescribeTasks command returns an accurate response. Apply an exponential backoff algorithm starting with a couple of seconds of wait time, and increase gradually up to about five minutes of wait time.
If you get a ConflictException error, the RunTask request could not be processed due to conflicts. The provided clientToken is already in use with a different RunTask request. The resourceIds are the existing task ARNs which are already associated with the clientToken.
To fix this issue:
Run RunTask with a unique clientToken.
Run RunTask with the clientToken and the original set of parameters
If you get a ClientException``error, the ``RunTask could not be processed because you use managed scaling and there is a capacity error because the quota of tasks in the PROVISIONING per cluster has been reached. For information about the service quotas, see Amazon ECS service quotas.
See also: AWS API Documentation
Request Syntax
client.run_task(
capacityProviderStrategy=[
{
'capacityProvider': 'string',
'weight': 123,
'base': 123
},
],
cluster='string',
count=123,
enableECSManagedTags=True|False,
enableExecuteCommand=True|False,
group='string',
launchType='EC2'|'FARGATE'|'EXTERNAL'|'MANAGED_INSTANCES',
networkConfiguration={
'awsvpcConfiguration': {
'subnets': [
'string',
],
'securityGroups': [
'string',
],
'assignPublicIp': 'ENABLED'|'DISABLED'
}
},
overrides={
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
],
'environmentFiles': [
{
'value': 'string',
'type': 's3'
},
],
'cpu': 123,
'memory': 123,
'memoryReservation': 123,
'resourceRequirements': [
{
'value': 'string',
'type': 'GPU'|'InferenceAccelerator'|'NeuronDevice'
},
]
},
],
'cpu': 'string',
'inferenceAcceleratorOverrides': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'executionRoleArn': 'string',
'memory': 'string',
'taskRoleArn': 'string',
'ephemeralStorage': {
'sizeInGiB': 123
}
},
placementConstraints=[
{
'type': 'distinctInstance'|'memberOf',
'expression': 'string'
},
],
placementStrategy=[
{
'type': 'random'|'spread'|'binpack',
'field': 'string'
},
],
platformVersion='string',
propagateTags='TASK_DEFINITION'|'SERVICE'|'NONE',
referenceId='string',
startedBy='string',
tags=[
{
'key': 'string',
'value': 'string'
},
],
taskDefinition='string',
clientToken='string',
volumeConfigurations=[
{
'name': 'string',
'managedEBSVolume': {
'encrypted': True|False,
'kmsKeyId': 'string',
'volumeType': 'string',
'sizeInGiB': 123,
'snapshotId': 'string',
'volumeInitializationRate': 123,
'iops': 123,
'throughput': 123,
'tagSpecifications': [
{
'resourceType': 'volume',
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'propagateTags': 'TASK_DEFINITION'|'SERVICE'|'NONE'
},
],
'roleArn': 'string',
'terminationPolicy': {
'deleteOnTermination': True|False
},
'filesystemType': 'ext3'|'ext4'|'xfs'|'ntfs'
}
},
]
)
list
The capacity provider strategy to use for the task.
If a capacityProviderStrategy is specified, the launchType parameter must be omitted. If no capacityProviderStrategy or launchType is specified, the defaultCapacityProviderStrategy for the cluster is used.
When you use cluster auto scaling, you must specify capacityProviderStrategy and not launchType.
A capacity provider strategy can contain a maximum of 20 capacity providers.
(dict) --
The details of a capacity provider strategy. A capacity provider strategy can be set when using the RunTask <https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html>`__or `CreateCluster APIs or as the default capacity provider strategy for a cluster with the CreateCluster API.
Only capacity providers that are already associated with a cluster and have an ACTIVE or UPDATING status can be used in a capacity provider strategy. The PutClusterCapacityProviders API is used to associate a capacity provider with a cluster.
If specifying a capacity provider that uses an Auto Scaling group, the capacity provider must already be created. New Auto Scaling group capacity providers can be created with the CreateClusterCapacityProvider API operation.
To use a Fargate capacity provider, specify either the FARGATE or FARGATE_SPOT capacity providers. The Fargate capacity providers are available to all accounts and only need to be associated with a cluster to be used in a capacity provider strategy.
With FARGATE_SPOT, you can run interruption tolerant tasks at a rate that's discounted compared to the FARGATE price. FARGATE_SPOT runs tasks on spare compute capacity. When Amazon Web Services needs the capacity back, your tasks are interrupted with a two-minute warning. FARGATE_SPOT supports Linux tasks with the X86_64 architecture on platform version 1.3.0 or later. FARGATE_SPOT supports Linux tasks with the ARM64 architecture on platform version 1.4.0 or later.
A capacity provider strategy can contain a maximum of 20 capacity providers.
capacityProvider (string) -- [REQUIRED]
The short name of the capacity provider.
weight (integer) --
The weight value designates the relative percentage of the total number of tasks launched that should use the specified capacity provider. The weight value is taken into consideration after the base value, if defined, is satisfied.
If no weight value is specified, the default value of 0 is used. When multiple capacity providers are specified within a capacity provider strategy, at least one of the capacity providers must have a weight value greater than zero and any capacity providers with a weight of 0 can't be used to place tasks. If you specify multiple capacity providers in a strategy that all have a weight of 0, any RunTask or CreateService actions using the capacity provider strategy will fail.
Weight value characteristics:
Weight is considered after the base value is satisfied
The default value is 0 if not specified
The valid range is 0 to 1,000
At least one capacity provider must have a weight greater than zero
Capacity providers with weight of 0 cannot place tasks
Task distribution logic:
Base satisfaction: The minimum number of tasks specified by the base value are placed on that capacity provider
Weight distribution: After base requirements are met, additional tasks are distributed according to weight ratios
Examples:
Equal Distribution: Two capacity providers both with weight 1 will split tasks evenly after base requirements are met.
Weighted Distribution: If capacityProviderA has weight 1 and capacityProviderB has weight 4, then for every 1 task on A, 4 tasks will run on B.
base (integer) --
The base value designates how many tasks, at a minimum, to run on the specified capacity provider for each service. Only one capacity provider in a capacity provider strategy can have a base defined. If no value is specified, the default value of 0 is used.
Base value characteristics:
Only one capacity provider in a strategy can have a base defined
The default value is 0 if not specified
The valid range is 0 to 100,000
Base requirements are satisfied first before weight distribution
string
The short name or full Amazon Resource Name (ARN) of the cluster to run your task on. If you do not specify a cluster, the default cluster is assumed.
Each account receives a default cluster the first time you use the service, but you may also create other clusters.
integer
The number of instantiations of the specified task to place on your cluster. You can specify up to 10 tasks for each call.
boolean
Specifies whether to use Amazon ECS managed tags for the task. For more information, see Tagging Your Amazon ECS Resources in the Amazon Elastic Container Service Developer Guide.
boolean
Determines whether to use the execute command functionality for the containers in this task. If true, this enables execute command functionality on all containers in the task.
If true, then the task definition must have a task role, or you must provide one as an override.
string
The name of the task group to associate with the task. The default value is the family name of the task definition (for example, family:my-family-name).
string
The infrastructure to run your standalone task on. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.
The FARGATE launch type runs your tasks on Fargate On-Demand infrastructure.
The EC2 launch type runs your tasks on Amazon EC2 instances registered to your cluster.
The EXTERNAL launch type runs your tasks on your on-premises server or virtual machine (VM) capacity registered to your cluster.
A task can use either a launch type or a capacity provider strategy. If a launchType is specified, the capacityProviderStrategy parameter must be omitted.
When you use cluster auto scaling, you must specify capacityProviderStrategy and not launchType.
dict
The network configuration for the task. This parameter is required for task definitions that use the awsvpc network mode to receive their own elastic network interface, and it isn't supported for other network modes. For more information, see Task networking in the Amazon Elastic Container Service Developer Guide.
awsvpcConfiguration (dict) --
The VPC subnets and security groups that are associated with a task.
subnets (list) -- [REQUIRED]
The IDs of the subnets associated with the task or service. There's a limit of 16 subnets that can be specified.
(string) --
securityGroups (list) --
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.
(string) --
assignPublicIp (string) --
Whether the task's elastic network interface receives a public IP address.
Consider the following when you set this value:
When you use create-service or update-service, the default is DISABLED.
When the service deploymentController is ECS, the value must be DISABLED.
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's 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.
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 that are sent to a task.
(dict) --
The overrides that are sent to a container. An empty container override can be passed in. An example of an empty container override is {"containerOverrides": [ ] }. If a non-empty container override is specified, the name parameter must be included.
You can use Secrets Manager or Amazon Web Services Systems Manager Parameter Store to store the sensitive data. For more information, see Retrieve secrets through environment variables in the Amazon ECS Developer Guide.
name (string) --
The name of the container that receives the override. This parameter is required if any override is specified.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name.
(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. You must also specify a container name.
(dict) --
A key-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.
environmentFiles (list) --
A list of files containing the environment variables to pass to a container, instead of the value from the container definition.
(dict) --
A list of files containing the environment variables to pass to a container. You can specify up to ten environment files. The file must have a .env file extension. Each line in an environment file should contain an environment variable in VARIABLE=VALUE format. Lines beginning with # are treated as comments and are ignored.
If there are environment variables specified using the environment parameter in a container definition, they take precedence over the variables contained within an environment file. If multiple environment files are specified that contain the same variable, they're processed from the top down. We recommend that you use unique variable names. For more information, see Use a file to pass environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply.
You must use the following platforms for the Fargate launch type:
Linux platform version 1.4.0 or later.
Windows platform version 1.0.0 or later.
Consider the following when using the Fargate launch type:
The file is handled like a native Docker env-file.
There is no support for shell escape handling.
The container entry point interperts the VARIABLE values.
value (string) -- [REQUIRED]
The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file.
type (string) -- [REQUIRED]
The file type to use. Environment files are objects in Amazon S3. The only supported value is s3.
cpu (integer) --
The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name.
memory (integer) --
The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name.
memoryReservation (integer) --
The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name.
resourceRequirements (list) --
The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices.
(dict) --
The type and amount of a resource to assign to a container. The supported resource types are GPUs, Neuron devices, and Elastic Inference accelerators. For more information, see Working with GPUs on Amazon ECS or Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide
value (string) -- [REQUIRED]
The value for the specified resource type.
When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container.
When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devices on the instance to the container. Only one container in a task can specify NeuronDevice resources. This resource type is only supported on Managed Instances.
When the type is InferenceAccelerator, the value matches the deviceName for an InferenceAccelerator specified in a task definition.
type (string) -- [REQUIRED]
The type of resource to assign to a container.
cpu (string) --
The CPU override for the task.
inferenceAcceleratorOverrides (list) --
The Elastic Inference accelerator override for the task.
(dict) --
Details on an Elastic Inference accelerator task override. This parameter is used to override the Elastic Inference accelerator specified in the task definition. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition.
deviceType (string) --
The Elastic Inference accelerator type to use.
executionRoleArn (string) --
The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The memory override for the task.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide.
ephemeralStorage (dict) --
The ephemeral storage setting override for the task.
sizeInGiB (integer) -- [REQUIRED]
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
list
An array of placement constraint objects to use for the task. You can specify up to 10 constraints for each task (including constraints in the task definition and those specified at runtime).
(dict) --
An object representing a constraint on task placement. For more information, see Task placement constraints in the Amazon Elastic Container Service Developer Guide.
type (string) --
The type of constraint. Use distinctInstance to ensure that each task in a particular group is running on a different container instance. Use memberOf to restrict the selection to a group of valid candidates.
expression (string) --
A cluster query language expression to apply to the constraint. The expression can have a maximum length of 2000 characters. You can't specify an expression if the constraint type is distinctInstance. For more information, see Cluster query language in the Amazon Elastic Container Service Developer Guide.
list
The placement strategy objects to use for the task. You can specify a maximum of 5 strategy rules for each task.
(dict) --
The task placement strategy for a task or service. For more information, see Task placement strategies in the Amazon Elastic Container Service Developer Guide.
type (string) --
The type of placement strategy. The random placement strategy randomly places tasks on available candidates. The spread placement strategy spreads placement across available candidates evenly based on the field parameter. The binpack strategy places tasks on available candidates that have the least available amount of the resource that's specified with the field parameter. For example, if you binpack on memory, a task is placed on the instance with the least amount of remaining memory but still enough to run the task.
field (string) --
The field to apply the placement strategy against. For the spread placement strategy, valid values are instanceId (or host, which has the same effect), or any platform or custom attribute that's applied to a container instance, such as attribute:ecs.availability-zone. For the binpack placement strategy, valid values are cpu and memory. For the random placement strategy, this field is not used.
string
The platform version the task uses. A platform version is only specified for tasks hosted on Fargate. If one isn't specified, the LATEST platform version is used. For more information, see Fargate platform versions in the Amazon Elastic Container Service Developer Guide.
string
Specifies whether to propagate the tags from the task definition to the task. If no value is specified, the tags aren't propagated. Tags can only be propagated to the task during task creation. To add tags to a task after task creation, use the TagResource API action.
string
This parameter is only used by Amazon ECS. It is not intended for use by customers.
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 128 letters (uppercase and lowercase), numbers, hyphens (-), forward slash (/), 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.
list
The metadata that you apply to the task to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
string
[REQUIRED]
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.
The full ARN value must match the value that you specified as the Resource of the principal's permissions policy.
When you specify a task definition, you must either specify a specific revision, or all revisions in the ARN.
To specify a specific revision, include the revision number in the ARN. For example, to specify revision 2, use arn:aws:ecs:us-east-1:111122223333:task-definition/TaskFamilyName:2.
To specify all revisions, use the wildcard (*) in the ARN. For example, to specify all revisions, use arn:aws:ecs:us-east-1:111122223333:task-definition/TaskFamilyName:*.
For more information, see Policy Resources for Amazon ECS in the Amazon Elastic Container Service Developer Guide.
string
An identifier that you provide to ensure the idempotency of the request. It must be unique and is case sensitive. Up to 64 characters are allowed. The valid characters are characters in the range of 33-126, inclusive. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
list
The details of the volume that was configuredAtLaunch. You can configure the size, volumeType, IOPS, throughput, snapshot and encryption in TaskManagedEBSVolumeConfiguration. The name of the volume must match the name from the task definition.
(dict) --
Configuration settings for the task volume that was configuredAtLaunch that weren't set during RegisterTaskDef.
name (string) -- [REQUIRED]
The name of the volume. This value must match the volume name from the Volume object in the task definition.
managedEBSVolume (dict) --
The configuration for the Amazon EBS volume that Amazon ECS creates and manages on your behalf. These settings are used to create each Amazon EBS volume, with one volume created for each task. The Amazon EBS volumes are visible in your account in the Amazon EC2 console once they are created.
encrypted (boolean) --
Indicates whether the volume should be encrypted. If you turn on Region-level Amazon EBS encryption by default but set this value as false, the setting is overridden and the volume is encrypted with the KMS key specified for Amazon EBS encryption by default. This parameter maps 1:1 with the Encrypted parameter of the CreateVolume API in the Amazon EC2 API Reference.
kmsKeyId (string) --
The Amazon Resource Name (ARN) identifier of the Amazon Web Services Key Management Service key to use for Amazon EBS encryption. When a key is specified using this parameter, it overrides Amazon EBS default encryption or any KMS key that you specified for cluster-level managed storage encryption. This parameter maps 1:1 with the KmsKeyId parameter of the CreateVolume API in the Amazon EC2 API Reference. For more information about encrypting Amazon EBS volumes attached to a task, see Encrypt data stored in Amazon EBS volumes attached to Amazon ECS tasks.
volumeType (string) --
The volume type. This parameter maps 1:1 with the VolumeType parameter of the CreateVolume API in the Amazon EC2 API Reference. For more information, see Amazon EBS volume types in the Amazon EC2 User Guide.
The following are the supported volume types.
General Purpose SSD: gp2``| ``gp3
Provisioned IOPS SSD: io1``| ``io2
Throughput Optimized HDD: st1
Cold HDD: sc1
Magnetic: standard
sizeInGiB (integer) --
The size of the volume in GiB. You must specify either a volume size or a snapshot ID. If you specify a snapshot ID, the snapshot size is used for the volume size by default. You can optionally specify a volume size greater than or equal to the snapshot size. This parameter maps 1:1 with the Size parameter of the CreateVolume API in the Amazon EC2 API Reference.
The following are the supported volume size values for each volume type.
gp2 and gp3: 1-16,384
io1 and io2: 4-16,384
st1 and sc1: 125-16,384
standard: 1-1,024
snapshotId (string) --
The snapshot that Amazon ECS uses to create the volume. You must specify either a snapshot ID or a volume size. This parameter maps 1:1 with the SnapshotId parameter of the CreateVolume API in the Amazon EC2 API Reference.
volumeInitializationRate (integer) --
The rate, in MiB/s, at which data is fetched from a snapshot of an existing Amazon EBS volume to create a new volume for attachment to the task. This property can be specified only if you specify a snapshotId. For more information, see Initialize Amazon EBS volumes in the Amazon EBS User Guide.
iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type.
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
This parameter is required for io1 and io2 volume types. The default for gp3 volumes is 3,000 IOPS. This parameter is not supported for st1, sc1, or standard volume types.
This parameter maps 1:1 with the Iops parameter of the CreateVolume API in the Amazon EC2 API Reference.
throughput (integer) --
The throughput to provision for a volume, in MiB/s, with a maximum of 1,000 MiB/s. This parameter maps 1:1 with the Throughput parameter of the CreateVolume API in the Amazon EC2 API Reference.
tagSpecifications (list) --
The tags to apply to the volume. Amazon ECS applies service-managed tags by default. This parameter maps 1:1 with the TagSpecifications.N parameter of the CreateVolume API in the Amazon EC2 API Reference.
(dict) --
The tag specifications of an Amazon EBS volume.
resourceType (string) -- [REQUIRED]
The type of volume resource.
tags (list) --
The tags applied to this Amazon EBS volume. AmazonECSCreated and AmazonECSManaged are reserved tags that can't be used.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
propagateTags (string) --
Determines whether to propagate the tags from the task definition to the Amazon EBS volume. Tags can only propagate to a SERVICE specified in ServiceVolumeConfiguration. If no value is specified, the tags aren't propagated.
roleArn (string) -- [REQUIRED]
The ARN of the IAM role to associate with this volume. This is the Amazon ECS infrastructure IAM role that is used to manage your Amazon Web Services infrastructure. We recommend using the Amazon ECS-managed AmazonECSInfrastructureRolePolicyForVolumes IAM policy with this role. For more information, see Amazon ECS infrastructure IAM role in the Amazon ECS Developer Guide.
terminationPolicy (dict) --
The termination policy for the volume when the task exits. This provides a way to control whether Amazon ECS terminates the Amazon EBS volume when the task stops.
deleteOnTermination (boolean) -- [REQUIRED]
Indicates whether the volume should be deleted on when the task stops. If a value of true is specified, Amazon ECS deletes the Amazon EBS volume on your behalf when the task goes into the STOPPED state. If no value is specified, the default value is true is used. When set to false, Amazon ECS leaves the volume in your account.
filesystemType (string) --
The Linux filesystem type for the volume. For volumes created from a snapshot, you must specify the same filesystem type that the volume was using when the snapshot was created. If there is a filesystem type mismatch, the task will fail to start.
The available filesystem types are ext3, ext4, and xfs. If no value is specified, the xfs filesystem type is used by default.
dict
Response Syntax
{
'tasks': [
{
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'availabilityZone': 'string',
'capacityProviderName': 'string',
'clusterArn': 'string',
'connectivity': 'CONNECTED'|'DISCONNECTED',
'connectivityAt': datetime(2015, 1, 1),
'containerInstanceArn': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'image': 'string',
'imageDigest': 'string',
'runtimeId': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp',
'containerPortRange': 'string',
'hostPortRange': 'string'
},
],
'networkInterfaces': [
{
'attachmentId': 'string',
'privateIpv4Address': 'string',
'ipv6Address': 'string'
},
],
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'managedAgents': [
{
'lastStartedAt': datetime(2015, 1, 1),
'name': 'ExecuteCommandAgent',
'reason': 'string',
'lastStatus': 'string'
},
],
'cpu': 'string',
'memory': 'string',
'memoryReservation': 'string',
'gpuIds': [
'string',
],
'neuronDeviceIds': [
'string',
]
},
],
'cpu': 'string',
'createdAt': datetime(2015, 1, 1),
'desiredStatus': 'string',
'enableExecuteCommand': True|False,
'executionStoppedAt': datetime(2015, 1, 1),
'group': 'string',
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'inferenceAccelerators': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'lastStatus': 'string',
'launchType': 'EC2'|'FARGATE'|'EXTERNAL'|'MANAGED_INSTANCES',
'memory': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
],
'environmentFiles': [
{
'value': 'string',
'type': 's3'
},
],
'cpu': 123,
'memory': 123,
'memoryReservation': 123,
'resourceRequirements': [
{
'value': 'string',
'type': 'GPU'|'InferenceAccelerator'|'NeuronDevice'
},
]
},
],
'cpu': 'string',
'inferenceAcceleratorOverrides': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'executionRoleArn': 'string',
'memory': 'string',
'taskRoleArn': 'string',
'ephemeralStorage': {
'sizeInGiB': 123
}
},
'platformVersion': 'string',
'platformFamily': 'string',
'pullStartedAt': datetime(2015, 1, 1),
'pullStoppedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'startedBy': 'string',
'stopCode': 'TaskFailedToStart'|'EssentialContainerExited'|'UserInitiated'|'ServiceSchedulerInitiated'|'SpotInterruption'|'TerminationNotice'|'InfrastructureHealth',
'stoppedAt': datetime(2015, 1, 1),
'stoppedReason': 'string',
'stoppingAt': datetime(2015, 1, 1),
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'taskArn': 'string',
'taskDefinitionArn': 'string',
'version': 123,
'ephemeralStorage': {
'sizeInGiB': 123
},
'fargateEphemeralStorage': {
'sizeInGiB': 123,
'kmsKeyId': 'string'
}
},
],
'failures': [
{
'arn': 'string',
'reason': 'string',
'detail': 'string'
},
]
}
Response Structure
(dict) --
tasks (list) --
A full description of the tasks that were run. The tasks that were successfully placed on your cluster are described here.
(dict) --
Details on a task in a cluster.
attachments (list) --
The Elastic Network Adapter that's associated with the task if the task uses the awsvpc network mode.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
attributes (list) --
The attributes of the task
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
availabilityZone (string) --
The Availability Zone for the task.
capacityProviderName (string) --
The capacity provider that's associated with the task.
clusterArn (string) --
The ARN of the cluster that hosts the task.
connectivity (string) --
The connectivity status of a task.
connectivityAt (datetime) --
The Unix timestamp for the time when the task last went into CONNECTED status.
containerInstanceArn (string) --
The ARN of the container instances that host the task.
containers (list) --
The containers that's associated with the task.
(dict) --
A Docker container that's part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The ARN of the task.
name (string) --
The name of the container.
image (string) --
The image used for the container.
imageDigest (string) --
The container image manifest digest.
runtimeId (string) --
The ID of the Docker container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (1024 max characters) human-readable string to provide additional details 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's used with the network binding.
hostPort (integer) --
The port number on the host that's used with the network binding.
protocol (string) --
The protocol used for the network binding.
containerPortRange (string) --
The port number range on the container that's bound to the dynamically mapped host port range.
The following rules apply when you specify a containerPortRange:
You must use either the bridge network mode or the awsvpc network mode.
This parameter is available for both the EC2 and Fargate launch types.
This parameter is available for both the Linux and Windows operating systems.
The container instance must have at least version 1.67.0 of the container agent and at least version 1.67.0-1 of the ecs-init package
You can specify a maximum of 100 port ranges per container.
You do not specify a hostPortRange. The value of the hostPortRange is set as follows:
For containers in a task with the awsvpc network mode, the hostPortRange is set to the same value as the containerPortRange. This is a static mapping strategy.
For containers in a task with the bridge network mode, the Amazon ECS agent finds open host ports from the default ephemeral range and passes it to docker to bind them to the container ports.
The containerPortRange valid values are between 1 and 65535.
A port can only be included in one port mapping per container.
You cannot specify overlapping port ranges.
The first port in the range must be less than last port in the range.
Docker recommends that you turn off the docker-proxy in the Docker daemon config file when you have a large number of ports. For more information, see Issue #11185 on the Github website. For information about how to turn off the docker-proxy in the Docker daemon config file, see Docker daemon in the Amazon ECS Developer Guide.
You can call DescribeTasks to view the hostPortRange which are the host ports that are bound to the container ports.
hostPortRange (string) --
The port number range on the host that's used with the network binding. This is assigned is assigned by Docker and delivered by the Amazon ECS agent.
networkInterfaces (list) --
The network interfaces associated with the container.
(dict) --
An object representing the elastic network interface for tasks that use the awsvpc network mode.
attachmentId (string) --
The attachment ID for the network interface.
privateIpv4Address (string) --
The private IPv4 address for the network interface.
ipv6Address (string) --
The private IPv6 address for the network interface.
healthStatus (string) --
The health status of the container. If health checks aren't configured for this container in its task definition, then it reports the health status as UNKNOWN.
managedAgents (list) --
The details of any Amazon ECS managed agents associated with the container.
(dict) --
Details about the managed agent status for the container.
lastStartedAt (datetime) --
The Unix timestamp for the time when the managed agent was last started.
name (string) --
The name of the managed agent. When the execute command feature is turned on, the managed agent name is ExecuteCommandAgent.
reason (string) --
The reason for why the managed agent is in the state it is in.
lastStatus (string) --
The last known status of the managed agent.
cpu (string) --
The number of CPU units set for the container. The value is 0 if no value was specified in the container definition when the task definition was registered.
memory (string) --
The hard limit (in MiB) of memory set for the container.
memoryReservation (string) --
The soft limit (in MiB) of memory set for the container.
gpuIds (list) --
The IDs of each GPU assigned to the container.
(string) --
neuronDeviceIds (list) --
The IDs of each Neuron device assigned to the container.
(string) --
cpu (string) --
The number of CPU units used by the task as expressed in a task definition. It can be expressed as an integer using CPU units (for example, 1024). It can also be expressed as a string using vCPUs (for example, 1 vCPU or 1 vcpu). String values are converted to an integer that indicates the CPU units when the task definition is registered.
If you're using the EC2 launch type or the external launch type, this field is optional. Supported values are between 128 CPU units ( 0.125 vCPUs) and 196608 CPU units ( 192 vCPUs). If you do not specify a value, the parameter is ignored.
This field is required for Fargate. For information about the valid values, see Task size in the Amazon Elastic Container Service Developer Guide.
createdAt (datetime) --
The Unix timestamp for the time when the task was created. More specifically, it's for the time when the task entered the PENDING state.
desiredStatus (string) --
The desired status of the task. For more information, see Task Lifecycle.
enableExecuteCommand (boolean) --
Determines whether execute command functionality is turned on for this task. If true, execute command functionality is turned on all the containers in the task.
executionStoppedAt (datetime) --
The Unix timestamp for the time when the task execution stopped.
group (string) --
The name of the task group that's associated with the task.
healthStatus (string) --
The health status for the task. It's determined by the health of the essential containers in the task. If all essential containers in the task are reporting as HEALTHY, the task status also reports as HEALTHY. If any essential containers in the task are reporting as UNHEALTHY or UNKNOWN, the task status also reports as UNHEALTHY or UNKNOWN.
inferenceAccelerators (list) --
The Elastic Inference accelerator that's associated with the task.
(dict) --
Details on an Elastic Inference accelerator. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name. The deviceName must also be referenced in a container definition as a ResourceRequirement.
deviceType (string) --
The Elastic Inference accelerator type to use.
lastStatus (string) --
The last known status for the task. For more information, see Task Lifecycle.
launchType (string) --
The infrastructure where your task runs on. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The amount of memory (in MiB) that the task uses as expressed in a task definition. It can be expressed as an integer using MiB (for example, 1024). If it's expressed as a string using GB (for example, 1GB or 1 GB), it's converted to an integer indicating the MiB when the task definition is registered.
If you use the EC2 launch type, this field is optional.
If you use the Fargate launch type, this field is required. You must use one of the following values. The value that you choose determines the range of supported values for the cpu parameter.
512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) - Available cpu values: 256 (.25 vCPU)
1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) - Available cpu values: 512 (.5 vCPU)
2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) - Available cpu values: 1024 (1 vCPU)
Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) - Available cpu values: 2048 (2 vCPU)
Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) - Available cpu values: 4096 (4 vCPU)
Between 16 GB and 60 GB in 4 GB increments - Available cpu values: 8192 (8 vCPU) This option requires Linux platform 1.4.0 or later.
Between 32GB and 120 GB in 8 GB increments - Available cpu values: 16384 (16 vCPU) This option requires Linux platform 1.4.0 or later.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides that are sent to a task.
(dict) --
The overrides that are sent to a container. An empty container override can be passed in. An example of an empty container override is {"containerOverrides": [ ] }. If a non-empty container override is specified, the name parameter must be included.
You can use Secrets Manager or Amazon Web Services Systems Manager Parameter Store to store the sensitive data. For more information, see Retrieve secrets through environment variables in the Amazon ECS Developer Guide.
name (string) --
The name of the container that receives the override. This parameter is required if any override is specified.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name.
(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. You must also specify a container name.
(dict) --
A key-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.
environmentFiles (list) --
A list of files containing the environment variables to pass to a container, instead of the value from the container definition.
(dict) --
A list of files containing the environment variables to pass to a container. You can specify up to ten environment files. The file must have a .env file extension. Each line in an environment file should contain an environment variable in VARIABLE=VALUE format. Lines beginning with # are treated as comments and are ignored.
If there are environment variables specified using the environment parameter in a container definition, they take precedence over the variables contained within an environment file. If multiple environment files are specified that contain the same variable, they're processed from the top down. We recommend that you use unique variable names. For more information, see Use a file to pass environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply.
You must use the following platforms for the Fargate launch type:
Linux platform version 1.4.0 or later.
Windows platform version 1.0.0 or later.
Consider the following when using the Fargate launch type:
The file is handled like a native Docker env-file.
There is no support for shell escape handling.
The container entry point interperts the VARIABLE values.
value (string) --
The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file.
type (string) --
The file type to use. Environment files are objects in Amazon S3. The only supported value is s3.
cpu (integer) --
The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name.
memory (integer) --
The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name.
memoryReservation (integer) --
The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name.
resourceRequirements (list) --
The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices.
(dict) --
The type and amount of a resource to assign to a container. The supported resource types are GPUs, Neuron devices, and Elastic Inference accelerators. For more information, see Working with GPUs on Amazon ECS or Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide
value (string) --
The value for the specified resource type.
When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container.
When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devices on the instance to the container. Only one container in a task can specify NeuronDevice resources. This resource type is only supported on Managed Instances.
When the type is InferenceAccelerator, the value matches the deviceName for an InferenceAccelerator specified in a task definition.
type (string) --
The type of resource to assign to a container.
cpu (string) --
The CPU override for the task.
inferenceAcceleratorOverrides (list) --
The Elastic Inference accelerator override for the task.
(dict) --
Details on an Elastic Inference accelerator task override. This parameter is used to override the Elastic Inference accelerator specified in the task definition. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition.
deviceType (string) --
The Elastic Inference accelerator type to use.
executionRoleArn (string) --
The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The memory override for the task.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide.
ephemeralStorage (dict) --
The ephemeral storage setting override for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
platformVersion (string) --
The platform version where your task runs on. A platform version is only specified for tasks that use the Fargate launch type. If you didn't specify one, the LATEST platform version is used. For more information, see Fargate Platform Versions in the Amazon Elastic Container Service Developer Guide.
platformFamily (string) --
The operating system that your tasks are running on. A platform family is specified only for tasks that use the Fargate launch type.
All tasks that run as part of this service must use the same platformFamily value as the service (for example, LINUX.).
pullStartedAt (datetime) --
The Unix timestamp for the time when the container image pull began.
pullStoppedAt (datetime) --
The Unix timestamp for the time when the container image pull completed.
startedAt (datetime) --
The Unix timestamp for the time when the task started. More specifically, it's for the time when the task transitioned from the PENDING state to the RUNNING state.
startedBy (string) --
The tag specified when a task is started. If an Amazon ECS service started the task, the startedBy parameter contains the deployment ID of that service.
stopCode (string) --
The stop code indicating why a task was stopped. The stoppedReason might contain additional details.
For more information about stop code, see Stopped tasks error codes in the Amazon ECS Developer Guide.
stoppedAt (datetime) --
The Unix timestamp for the time when the task was stopped. More specifically, it's for the time when the task transitioned from the RUNNING state to the STOPPED state.
stoppedReason (string) --
The reason that the task was stopped.
stoppingAt (datetime) --
The Unix timestamp for the time when the task stops. More specifically, it's for the time when the task transitions from the RUNNING state to STOPPING.
tags (list) --
The metadata that you apply to the task to help you categorize and organize the task. Each tag consists of a key and an optional value. You define both the key and value.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
taskDefinitionArn (string) --
The ARN of the task definition that creates the task.
version (integer) --
The version counter for the task. Every time a task experiences a change that starts a CloudWatch event, the version counter is incremented. If you replicate your Amazon ECS task state with CloudWatch Events, you can compare the version of a task reported by the Amazon ECS API actions 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.
ephemeralStorage (dict) --
The ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
fargateEphemeralStorage (dict) --
The Fargate ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of the ephemeral storage to set for the task. The minimum supported value is 20 GiB and the maximum supported value is 200 GiB.
kmsKeyId (string) --
Specify an Key Management Service key ID to encrypt the ephemeral storage for the task.
failures (list) --
Any failures associated with the call.
For information about how to address failures, see Service event messages and API failure reasons in the Amazon Elastic Container Service Developer Guide.
(dict) --
A failed resource. For a list of common causes, see API failure reasons in the Amazon Elastic Container Service Developer Guide.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
detail (string) --
The details of the failure.
{'tasks': {'stopCode': {'InfrastructureHealth'}}}
Starts a new task from the specified task definition on the specified container instance or instances.
Alternatively, you can use RunTask to place tasks for you. For more information, see Scheduling Tasks in the Amazon Elastic Container Service Developer Guide.
You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. For more information, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide.
See also: AWS API Documentation
Request Syntax
client.start_task(
cluster='string',
containerInstances=[
'string',
],
enableECSManagedTags=True|False,
enableExecuteCommand=True|False,
group='string',
networkConfiguration={
'awsvpcConfiguration': {
'subnets': [
'string',
],
'securityGroups': [
'string',
],
'assignPublicIp': 'ENABLED'|'DISABLED'
}
},
overrides={
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
],
'environmentFiles': [
{
'value': 'string',
'type': 's3'
},
],
'cpu': 123,
'memory': 123,
'memoryReservation': 123,
'resourceRequirements': [
{
'value': 'string',
'type': 'GPU'|'InferenceAccelerator'|'NeuronDevice'
},
]
},
],
'cpu': 'string',
'inferenceAcceleratorOverrides': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'executionRoleArn': 'string',
'memory': 'string',
'taskRoleArn': 'string',
'ephemeralStorage': {
'sizeInGiB': 123
}
},
propagateTags='TASK_DEFINITION'|'SERVICE'|'NONE',
referenceId='string',
startedBy='string',
tags=[
{
'key': 'string',
'value': 'string'
},
],
taskDefinition='string',
volumeConfigurations=[
{
'name': 'string',
'managedEBSVolume': {
'encrypted': True|False,
'kmsKeyId': 'string',
'volumeType': 'string',
'sizeInGiB': 123,
'snapshotId': 'string',
'volumeInitializationRate': 123,
'iops': 123,
'throughput': 123,
'tagSpecifications': [
{
'resourceType': 'volume',
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'propagateTags': 'TASK_DEFINITION'|'SERVICE'|'NONE'
},
],
'roleArn': 'string',
'terminationPolicy': {
'deleteOnTermination': True|False
},
'filesystemType': 'ext3'|'ext4'|'xfs'|'ntfs'
}
},
]
)
string
The short name or full Amazon Resource Name (ARN) of the cluster where to start your task. If you do not specify a cluster, the default cluster is assumed.
list
[REQUIRED]
The container instance IDs or full ARN entries for the container instances where you would like to place your task. You can specify up to 10 container instances.
(string) --
boolean
Specifies whether to use Amazon ECS managed tags for the task. For more information, see Tagging Your Amazon ECS Resources in the Amazon Elastic Container Service Developer Guide.
boolean
Whether or not the execute command functionality is turned on for the task. If true, this turns on the execute command functionality on all containers in the task.
string
The name of the task group to associate with the task. The default value is the family name of the task definition (for example, family:my-family-name).
dict
The VPC subnet and security group configuration for tasks that receive their own elastic network interface by using the awsvpc networking mode.
awsvpcConfiguration (dict) --
The VPC subnets and security groups that are associated with a task.
subnets (list) -- [REQUIRED]
The IDs of the subnets associated with the task or service. There's a limit of 16 subnets that can be specified.
(string) --
securityGroups (list) --
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.
(string) --
assignPublicIp (string) --
Whether the task's elastic network interface receives a public IP address.
Consider the following when you set this value:
When you use create-service or update-service, the default is DISABLED.
When the service deploymentController is ECS, the value must be DISABLED.
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 receives. You can override the default command for a container (that's 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.
containerOverrides (list) --
One or more container overrides that are sent to a task.
(dict) --
The overrides that are sent to a container. An empty container override can be passed in. An example of an empty container override is {"containerOverrides": [ ] }. If a non-empty container override is specified, the name parameter must be included.
You can use Secrets Manager or Amazon Web Services Systems Manager Parameter Store to store the sensitive data. For more information, see Retrieve secrets through environment variables in the Amazon ECS Developer Guide.
name (string) --
The name of the container that receives the override. This parameter is required if any override is specified.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name.
(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. You must also specify a container name.
(dict) --
A key-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.
environmentFiles (list) --
A list of files containing the environment variables to pass to a container, instead of the value from the container definition.
(dict) --
A list of files containing the environment variables to pass to a container. You can specify up to ten environment files. The file must have a .env file extension. Each line in an environment file should contain an environment variable in VARIABLE=VALUE format. Lines beginning with # are treated as comments and are ignored.
If there are environment variables specified using the environment parameter in a container definition, they take precedence over the variables contained within an environment file. If multiple environment files are specified that contain the same variable, they're processed from the top down. We recommend that you use unique variable names. For more information, see Use a file to pass environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply.
You must use the following platforms for the Fargate launch type:
Linux platform version 1.4.0 or later.
Windows platform version 1.0.0 or later.
Consider the following when using the Fargate launch type:
The file is handled like a native Docker env-file.
There is no support for shell escape handling.
The container entry point interperts the VARIABLE values.
value (string) -- [REQUIRED]
The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file.
type (string) -- [REQUIRED]
The file type to use. Environment files are objects in Amazon S3. The only supported value is s3.
cpu (integer) --
The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name.
memory (integer) --
The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name.
memoryReservation (integer) --
The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name.
resourceRequirements (list) --
The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices.
(dict) --
The type and amount of a resource to assign to a container. The supported resource types are GPUs, Neuron devices, and Elastic Inference accelerators. For more information, see Working with GPUs on Amazon ECS or Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide
value (string) -- [REQUIRED]
The value for the specified resource type.
When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container.
When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devices on the instance to the container. Only one container in a task can specify NeuronDevice resources. This resource type is only supported on Managed Instances.
When the type is InferenceAccelerator, the value matches the deviceName for an InferenceAccelerator specified in a task definition.
type (string) -- [REQUIRED]
The type of resource to assign to a container.
cpu (string) --
The CPU override for the task.
inferenceAcceleratorOverrides (list) --
The Elastic Inference accelerator override for the task.
(dict) --
Details on an Elastic Inference accelerator task override. This parameter is used to override the Elastic Inference accelerator specified in the task definition. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition.
deviceType (string) --
The Elastic Inference accelerator type to use.
executionRoleArn (string) --
The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The memory override for the task.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide.
ephemeralStorage (dict) --
The ephemeral storage setting override for the task.
sizeInGiB (integer) -- [REQUIRED]
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
string
Specifies whether to propagate the tags from the task definition or the service to the task. If no value is specified, the tags aren't propagated.
string
This parameter is only used by Amazon ECS. It is not intended for use by customers.
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 (-), forward slash (/), and underscores (_) are allowed.
If a task is started by an Amazon ECS service, the startedBy parameter contains the deployment ID of the service that starts it.
list
The metadata that you apply to the task to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
string
[REQUIRED]
The family and revision ( family:revision) or full ARN of the task definition to start. If a revision isn't specified, the latest ACTIVE revision is used.
list
The details of the volume that was configuredAtLaunch. You can configure the size, volumeType, IOPS, throughput, snapshot and encryption in TaskManagedEBSVolumeConfiguration. The name of the volume must match the name from the task definition.
(dict) --
Configuration settings for the task volume that was configuredAtLaunch that weren't set during RegisterTaskDef.
name (string) -- [REQUIRED]
The name of the volume. This value must match the volume name from the Volume object in the task definition.
managedEBSVolume (dict) --
The configuration for the Amazon EBS volume that Amazon ECS creates and manages on your behalf. These settings are used to create each Amazon EBS volume, with one volume created for each task. The Amazon EBS volumes are visible in your account in the Amazon EC2 console once they are created.
encrypted (boolean) --
Indicates whether the volume should be encrypted. If you turn on Region-level Amazon EBS encryption by default but set this value as false, the setting is overridden and the volume is encrypted with the KMS key specified for Amazon EBS encryption by default. This parameter maps 1:1 with the Encrypted parameter of the CreateVolume API in the Amazon EC2 API Reference.
kmsKeyId (string) --
The Amazon Resource Name (ARN) identifier of the Amazon Web Services Key Management Service key to use for Amazon EBS encryption. When a key is specified using this parameter, it overrides Amazon EBS default encryption or any KMS key that you specified for cluster-level managed storage encryption. This parameter maps 1:1 with the KmsKeyId parameter of the CreateVolume API in the Amazon EC2 API Reference. For more information about encrypting Amazon EBS volumes attached to a task, see Encrypt data stored in Amazon EBS volumes attached to Amazon ECS tasks.
volumeType (string) --
The volume type. This parameter maps 1:1 with the VolumeType parameter of the CreateVolume API in the Amazon EC2 API Reference. For more information, see Amazon EBS volume types in the Amazon EC2 User Guide.
The following are the supported volume types.
General Purpose SSD: gp2``| ``gp3
Provisioned IOPS SSD: io1``| ``io2
Throughput Optimized HDD: st1
Cold HDD: sc1
Magnetic: standard
sizeInGiB (integer) --
The size of the volume in GiB. You must specify either a volume size or a snapshot ID. If you specify a snapshot ID, the snapshot size is used for the volume size by default. You can optionally specify a volume size greater than or equal to the snapshot size. This parameter maps 1:1 with the Size parameter of the CreateVolume API in the Amazon EC2 API Reference.
The following are the supported volume size values for each volume type.
gp2 and gp3: 1-16,384
io1 and io2: 4-16,384
st1 and sc1: 125-16,384
standard: 1-1,024
snapshotId (string) --
The snapshot that Amazon ECS uses to create the volume. You must specify either a snapshot ID or a volume size. This parameter maps 1:1 with the SnapshotId parameter of the CreateVolume API in the Amazon EC2 API Reference.
volumeInitializationRate (integer) --
The rate, in MiB/s, at which data is fetched from a snapshot of an existing Amazon EBS volume to create a new volume for attachment to the task. This property can be specified only if you specify a snapshotId. For more information, see Initialize Amazon EBS volumes in the Amazon EBS User Guide.
iops (integer) --
The number of I/O operations per second (IOPS). For gp3, io1, and io2 volumes, this represents the number of IOPS that are provisioned for the volume. For gp2 volumes, this represents the baseline performance of the volume and the rate at which the volume accumulates I/O credits for bursting.
The following are the supported values for each volume type.
gp3: 3,000 - 16,000 IOPS
io1: 100 - 64,000 IOPS
io2: 100 - 256,000 IOPS
This parameter is required for io1 and io2 volume types. The default for gp3 volumes is 3,000 IOPS. This parameter is not supported for st1, sc1, or standard volume types.
This parameter maps 1:1 with the Iops parameter of the CreateVolume API in the Amazon EC2 API Reference.
throughput (integer) --
The throughput to provision for a volume, in MiB/s, with a maximum of 1,000 MiB/s. This parameter maps 1:1 with the Throughput parameter of the CreateVolume API in the Amazon EC2 API Reference.
tagSpecifications (list) --
The tags to apply to the volume. Amazon ECS applies service-managed tags by default. This parameter maps 1:1 with the TagSpecifications.N parameter of the CreateVolume API in the Amazon EC2 API Reference.
(dict) --
The tag specifications of an Amazon EBS volume.
resourceType (string) -- [REQUIRED]
The type of volume resource.
tags (list) --
The tags applied to this Amazon EBS volume. AmazonECSCreated and AmazonECSManaged are reserved tags that can't be used.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
propagateTags (string) --
Determines whether to propagate the tags from the task definition to the Amazon EBS volume. Tags can only propagate to a SERVICE specified in ServiceVolumeConfiguration. If no value is specified, the tags aren't propagated.
roleArn (string) -- [REQUIRED]
The ARN of the IAM role to associate with this volume. This is the Amazon ECS infrastructure IAM role that is used to manage your Amazon Web Services infrastructure. We recommend using the Amazon ECS-managed AmazonECSInfrastructureRolePolicyForVolumes IAM policy with this role. For more information, see Amazon ECS infrastructure IAM role in the Amazon ECS Developer Guide.
terminationPolicy (dict) --
The termination policy for the volume when the task exits. This provides a way to control whether Amazon ECS terminates the Amazon EBS volume when the task stops.
deleteOnTermination (boolean) -- [REQUIRED]
Indicates whether the volume should be deleted on when the task stops. If a value of true is specified, Amazon ECS deletes the Amazon EBS volume on your behalf when the task goes into the STOPPED state. If no value is specified, the default value is true is used. When set to false, Amazon ECS leaves the volume in your account.
filesystemType (string) --
The Linux filesystem type for the volume. For volumes created from a snapshot, you must specify the same filesystem type that the volume was using when the snapshot was created. If there is a filesystem type mismatch, the task will fail to start.
The available filesystem types are ext3, ext4, and xfs. If no value is specified, the xfs filesystem type is used by default.
dict
Response Syntax
{
'tasks': [
{
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'availabilityZone': 'string',
'capacityProviderName': 'string',
'clusterArn': 'string',
'connectivity': 'CONNECTED'|'DISCONNECTED',
'connectivityAt': datetime(2015, 1, 1),
'containerInstanceArn': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'image': 'string',
'imageDigest': 'string',
'runtimeId': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp',
'containerPortRange': 'string',
'hostPortRange': 'string'
},
],
'networkInterfaces': [
{
'attachmentId': 'string',
'privateIpv4Address': 'string',
'ipv6Address': 'string'
},
],
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'managedAgents': [
{
'lastStartedAt': datetime(2015, 1, 1),
'name': 'ExecuteCommandAgent',
'reason': 'string',
'lastStatus': 'string'
},
],
'cpu': 'string',
'memory': 'string',
'memoryReservation': 'string',
'gpuIds': [
'string',
],
'neuronDeviceIds': [
'string',
]
},
],
'cpu': 'string',
'createdAt': datetime(2015, 1, 1),
'desiredStatus': 'string',
'enableExecuteCommand': True|False,
'executionStoppedAt': datetime(2015, 1, 1),
'group': 'string',
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'inferenceAccelerators': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'lastStatus': 'string',
'launchType': 'EC2'|'FARGATE'|'EXTERNAL'|'MANAGED_INSTANCES',
'memory': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
],
'environmentFiles': [
{
'value': 'string',
'type': 's3'
},
],
'cpu': 123,
'memory': 123,
'memoryReservation': 123,
'resourceRequirements': [
{
'value': 'string',
'type': 'GPU'|'InferenceAccelerator'|'NeuronDevice'
},
]
},
],
'cpu': 'string',
'inferenceAcceleratorOverrides': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'executionRoleArn': 'string',
'memory': 'string',
'taskRoleArn': 'string',
'ephemeralStorage': {
'sizeInGiB': 123
}
},
'platformVersion': 'string',
'platformFamily': 'string',
'pullStartedAt': datetime(2015, 1, 1),
'pullStoppedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'startedBy': 'string',
'stopCode': 'TaskFailedToStart'|'EssentialContainerExited'|'UserInitiated'|'ServiceSchedulerInitiated'|'SpotInterruption'|'TerminationNotice'|'InfrastructureHealth',
'stoppedAt': datetime(2015, 1, 1),
'stoppedReason': 'string',
'stoppingAt': datetime(2015, 1, 1),
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'taskArn': 'string',
'taskDefinitionArn': 'string',
'version': 123,
'ephemeralStorage': {
'sizeInGiB': 123
},
'fargateEphemeralStorage': {
'sizeInGiB': 123,
'kmsKeyId': 'string'
}
},
],
'failures': [
{
'arn': 'string',
'reason': 'string',
'detail': '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 is described.
(dict) --
Details on a task in a cluster.
attachments (list) --
The Elastic Network Adapter that's associated with the task if the task uses the awsvpc network mode.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
attributes (list) --
The attributes of the task
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
availabilityZone (string) --
The Availability Zone for the task.
capacityProviderName (string) --
The capacity provider that's associated with the task.
clusterArn (string) --
The ARN of the cluster that hosts the task.
connectivity (string) --
The connectivity status of a task.
connectivityAt (datetime) --
The Unix timestamp for the time when the task last went into CONNECTED status.
containerInstanceArn (string) --
The ARN of the container instances that host the task.
containers (list) --
The containers that's associated with the task.
(dict) --
A Docker container that's part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The ARN of the task.
name (string) --
The name of the container.
image (string) --
The image used for the container.
imageDigest (string) --
The container image manifest digest.
runtimeId (string) --
The ID of the Docker container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (1024 max characters) human-readable string to provide additional details 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's used with the network binding.
hostPort (integer) --
The port number on the host that's used with the network binding.
protocol (string) --
The protocol used for the network binding.
containerPortRange (string) --
The port number range on the container that's bound to the dynamically mapped host port range.
The following rules apply when you specify a containerPortRange:
You must use either the bridge network mode or the awsvpc network mode.
This parameter is available for both the EC2 and Fargate launch types.
This parameter is available for both the Linux and Windows operating systems.
The container instance must have at least version 1.67.0 of the container agent and at least version 1.67.0-1 of the ecs-init package
You can specify a maximum of 100 port ranges per container.
You do not specify a hostPortRange. The value of the hostPortRange is set as follows:
For containers in a task with the awsvpc network mode, the hostPortRange is set to the same value as the containerPortRange. This is a static mapping strategy.
For containers in a task with the bridge network mode, the Amazon ECS agent finds open host ports from the default ephemeral range and passes it to docker to bind them to the container ports.
The containerPortRange valid values are between 1 and 65535.
A port can only be included in one port mapping per container.
You cannot specify overlapping port ranges.
The first port in the range must be less than last port in the range.
Docker recommends that you turn off the docker-proxy in the Docker daemon config file when you have a large number of ports. For more information, see Issue #11185 on the Github website. For information about how to turn off the docker-proxy in the Docker daemon config file, see Docker daemon in the Amazon ECS Developer Guide.
You can call DescribeTasks to view the hostPortRange which are the host ports that are bound to the container ports.
hostPortRange (string) --
The port number range on the host that's used with the network binding. This is assigned is assigned by Docker and delivered by the Amazon ECS agent.
networkInterfaces (list) --
The network interfaces associated with the container.
(dict) --
An object representing the elastic network interface for tasks that use the awsvpc network mode.
attachmentId (string) --
The attachment ID for the network interface.
privateIpv4Address (string) --
The private IPv4 address for the network interface.
ipv6Address (string) --
The private IPv6 address for the network interface.
healthStatus (string) --
The health status of the container. If health checks aren't configured for this container in its task definition, then it reports the health status as UNKNOWN.
managedAgents (list) --
The details of any Amazon ECS managed agents associated with the container.
(dict) --
Details about the managed agent status for the container.
lastStartedAt (datetime) --
The Unix timestamp for the time when the managed agent was last started.
name (string) --
The name of the managed agent. When the execute command feature is turned on, the managed agent name is ExecuteCommandAgent.
reason (string) --
The reason for why the managed agent is in the state it is in.
lastStatus (string) --
The last known status of the managed agent.
cpu (string) --
The number of CPU units set for the container. The value is 0 if no value was specified in the container definition when the task definition was registered.
memory (string) --
The hard limit (in MiB) of memory set for the container.
memoryReservation (string) --
The soft limit (in MiB) of memory set for the container.
gpuIds (list) --
The IDs of each GPU assigned to the container.
(string) --
neuronDeviceIds (list) --
The IDs of each Neuron device assigned to the container.
(string) --
cpu (string) --
The number of CPU units used by the task as expressed in a task definition. It can be expressed as an integer using CPU units (for example, 1024). It can also be expressed as a string using vCPUs (for example, 1 vCPU or 1 vcpu). String values are converted to an integer that indicates the CPU units when the task definition is registered.
If you're using the EC2 launch type or the external launch type, this field is optional. Supported values are between 128 CPU units ( 0.125 vCPUs) and 196608 CPU units ( 192 vCPUs). If you do not specify a value, the parameter is ignored.
This field is required for Fargate. For information about the valid values, see Task size in the Amazon Elastic Container Service Developer Guide.
createdAt (datetime) --
The Unix timestamp for the time when the task was created. More specifically, it's for the time when the task entered the PENDING state.
desiredStatus (string) --
The desired status of the task. For more information, see Task Lifecycle.
enableExecuteCommand (boolean) --
Determines whether execute command functionality is turned on for this task. If true, execute command functionality is turned on all the containers in the task.
executionStoppedAt (datetime) --
The Unix timestamp for the time when the task execution stopped.
group (string) --
The name of the task group that's associated with the task.
healthStatus (string) --
The health status for the task. It's determined by the health of the essential containers in the task. If all essential containers in the task are reporting as HEALTHY, the task status also reports as HEALTHY. If any essential containers in the task are reporting as UNHEALTHY or UNKNOWN, the task status also reports as UNHEALTHY or UNKNOWN.
inferenceAccelerators (list) --
The Elastic Inference accelerator that's associated with the task.
(dict) --
Details on an Elastic Inference accelerator. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name. The deviceName must also be referenced in a container definition as a ResourceRequirement.
deviceType (string) --
The Elastic Inference accelerator type to use.
lastStatus (string) --
The last known status for the task. For more information, see Task Lifecycle.
launchType (string) --
The infrastructure where your task runs on. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The amount of memory (in MiB) that the task uses as expressed in a task definition. It can be expressed as an integer using MiB (for example, 1024). If it's expressed as a string using GB (for example, 1GB or 1 GB), it's converted to an integer indicating the MiB when the task definition is registered.
If you use the EC2 launch type, this field is optional.
If you use the Fargate launch type, this field is required. You must use one of the following values. The value that you choose determines the range of supported values for the cpu parameter.
512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) - Available cpu values: 256 (.25 vCPU)
1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) - Available cpu values: 512 (.5 vCPU)
2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) - Available cpu values: 1024 (1 vCPU)
Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) - Available cpu values: 2048 (2 vCPU)
Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) - Available cpu values: 4096 (4 vCPU)
Between 16 GB and 60 GB in 4 GB increments - Available cpu values: 8192 (8 vCPU) This option requires Linux platform 1.4.0 or later.
Between 32GB and 120 GB in 8 GB increments - Available cpu values: 16384 (16 vCPU) This option requires Linux platform 1.4.0 or later.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides that are sent to a task.
(dict) --
The overrides that are sent to a container. An empty container override can be passed in. An example of an empty container override is {"containerOverrides": [ ] }. If a non-empty container override is specified, the name parameter must be included.
You can use Secrets Manager or Amazon Web Services Systems Manager Parameter Store to store the sensitive data. For more information, see Retrieve secrets through environment variables in the Amazon ECS Developer Guide.
name (string) --
The name of the container that receives the override. This parameter is required if any override is specified.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name.
(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. You must also specify a container name.
(dict) --
A key-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.
environmentFiles (list) --
A list of files containing the environment variables to pass to a container, instead of the value from the container definition.
(dict) --
A list of files containing the environment variables to pass to a container. You can specify up to ten environment files. The file must have a .env file extension. Each line in an environment file should contain an environment variable in VARIABLE=VALUE format. Lines beginning with # are treated as comments and are ignored.
If there are environment variables specified using the environment parameter in a container definition, they take precedence over the variables contained within an environment file. If multiple environment files are specified that contain the same variable, they're processed from the top down. We recommend that you use unique variable names. For more information, see Use a file to pass environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply.
You must use the following platforms for the Fargate launch type:
Linux platform version 1.4.0 or later.
Windows platform version 1.0.0 or later.
Consider the following when using the Fargate launch type:
The file is handled like a native Docker env-file.
There is no support for shell escape handling.
The container entry point interperts the VARIABLE values.
value (string) --
The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file.
type (string) --
The file type to use. Environment files are objects in Amazon S3. The only supported value is s3.
cpu (integer) --
The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name.
memory (integer) --
The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name.
memoryReservation (integer) --
The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name.
resourceRequirements (list) --
The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices.
(dict) --
The type and amount of a resource to assign to a container. The supported resource types are GPUs, Neuron devices, and Elastic Inference accelerators. For more information, see Working with GPUs on Amazon ECS or Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide
value (string) --
The value for the specified resource type.
When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container.
When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devices on the instance to the container. Only one container in a task can specify NeuronDevice resources. This resource type is only supported on Managed Instances.
When the type is InferenceAccelerator, the value matches the deviceName for an InferenceAccelerator specified in a task definition.
type (string) --
The type of resource to assign to a container.
cpu (string) --
The CPU override for the task.
inferenceAcceleratorOverrides (list) --
The Elastic Inference accelerator override for the task.
(dict) --
Details on an Elastic Inference accelerator task override. This parameter is used to override the Elastic Inference accelerator specified in the task definition. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition.
deviceType (string) --
The Elastic Inference accelerator type to use.
executionRoleArn (string) --
The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The memory override for the task.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide.
ephemeralStorage (dict) --
The ephemeral storage setting override for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
platformVersion (string) --
The platform version where your task runs on. A platform version is only specified for tasks that use the Fargate launch type. If you didn't specify one, the LATEST platform version is used. For more information, see Fargate Platform Versions in the Amazon Elastic Container Service Developer Guide.
platformFamily (string) --
The operating system that your tasks are running on. A platform family is specified only for tasks that use the Fargate launch type.
All tasks that run as part of this service must use the same platformFamily value as the service (for example, LINUX.).
pullStartedAt (datetime) --
The Unix timestamp for the time when the container image pull began.
pullStoppedAt (datetime) --
The Unix timestamp for the time when the container image pull completed.
startedAt (datetime) --
The Unix timestamp for the time when the task started. More specifically, it's for the time when the task transitioned from the PENDING state to the RUNNING state.
startedBy (string) --
The tag specified when a task is started. If an Amazon ECS service started the task, the startedBy parameter contains the deployment ID of that service.
stopCode (string) --
The stop code indicating why a task was stopped. The stoppedReason might contain additional details.
For more information about stop code, see Stopped tasks error codes in the Amazon ECS Developer Guide.
stoppedAt (datetime) --
The Unix timestamp for the time when the task was stopped. More specifically, it's for the time when the task transitioned from the RUNNING state to the STOPPED state.
stoppedReason (string) --
The reason that the task was stopped.
stoppingAt (datetime) --
The Unix timestamp for the time when the task stops. More specifically, it's for the time when the task transitions from the RUNNING state to STOPPING.
tags (list) --
The metadata that you apply to the task to help you categorize and organize the task. Each tag consists of a key and an optional value. You define both the key and value.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
taskDefinitionArn (string) --
The ARN of the task definition that creates the task.
version (integer) --
The version counter for the task. Every time a task experiences a change that starts a CloudWatch event, the version counter is incremented. If you replicate your Amazon ECS task state with CloudWatch Events, you can compare the version of a task reported by the Amazon ECS API actions 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.
ephemeralStorage (dict) --
The ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
fargateEphemeralStorage (dict) --
The Fargate ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of the ephemeral storage to set for the task. The minimum supported value is 20 GiB and the maximum supported value is 200 GiB.
kmsKeyId (string) --
Specify an Key Management Service key ID to encrypt the ephemeral storage for the task.
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource. For a list of common causes, see API failure reasons in the Amazon Elastic Container Service Developer Guide.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
detail (string) --
The details of the failure.
{'task': {'stopCode': {'InfrastructureHealth'}}}
Stops a running task. Any tags associated with the task will be deleted.
When you call StopTask on a task, the equivalent of docker stop is issued to the containers running in the task. This results in a stop signal value and a default 30-second timeout, after which the SIGKILL value is sent and the containers are forcibly stopped. This signal can be defined in your container image with the STOPSIGNAL instruction and will default to SIGTERM. If the container handles the SIGTERM value gracefully and exits within 30 seconds from receiving it, no SIGKILL value is sent.
For Windows containers, POSIX signals do not work and runtime stops the container by sending a CTRL_SHUTDOWN_EVENT. For more information, see Unable to react to graceful shutdown of (Windows) container #25982 on GitHub.
See also: AWS API Documentation
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]
Thefull Amazon Resource Name (ARN) of the task.
string
An optional message specified when a task is stopped. For example, if you're using a custom scheduler, you can use this parameter to specify the reason for stopping the task here, and the message appears in subsequent DescribeTasks> API operations on this task.
dict
Response Syntax
{
'task': {
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'availabilityZone': 'string',
'capacityProviderName': 'string',
'clusterArn': 'string',
'connectivity': 'CONNECTED'|'DISCONNECTED',
'connectivityAt': datetime(2015, 1, 1),
'containerInstanceArn': 'string',
'containers': [
{
'containerArn': 'string',
'taskArn': 'string',
'name': 'string',
'image': 'string',
'imageDigest': 'string',
'runtimeId': 'string',
'lastStatus': 'string',
'exitCode': 123,
'reason': 'string',
'networkBindings': [
{
'bindIP': 'string',
'containerPort': 123,
'hostPort': 123,
'protocol': 'tcp'|'udp',
'containerPortRange': 'string',
'hostPortRange': 'string'
},
],
'networkInterfaces': [
{
'attachmentId': 'string',
'privateIpv4Address': 'string',
'ipv6Address': 'string'
},
],
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'managedAgents': [
{
'lastStartedAt': datetime(2015, 1, 1),
'name': 'ExecuteCommandAgent',
'reason': 'string',
'lastStatus': 'string'
},
],
'cpu': 'string',
'memory': 'string',
'memoryReservation': 'string',
'gpuIds': [
'string',
],
'neuronDeviceIds': [
'string',
]
},
],
'cpu': 'string',
'createdAt': datetime(2015, 1, 1),
'desiredStatus': 'string',
'enableExecuteCommand': True|False,
'executionStoppedAt': datetime(2015, 1, 1),
'group': 'string',
'healthStatus': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
'inferenceAccelerators': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'lastStatus': 'string',
'launchType': 'EC2'|'FARGATE'|'EXTERNAL'|'MANAGED_INSTANCES',
'memory': 'string',
'overrides': {
'containerOverrides': [
{
'name': 'string',
'command': [
'string',
],
'environment': [
{
'name': 'string',
'value': 'string'
},
],
'environmentFiles': [
{
'value': 'string',
'type': 's3'
},
],
'cpu': 123,
'memory': 123,
'memoryReservation': 123,
'resourceRequirements': [
{
'value': 'string',
'type': 'GPU'|'InferenceAccelerator'|'NeuronDevice'
},
]
},
],
'cpu': 'string',
'inferenceAcceleratorOverrides': [
{
'deviceName': 'string',
'deviceType': 'string'
},
],
'executionRoleArn': 'string',
'memory': 'string',
'taskRoleArn': 'string',
'ephemeralStorage': {
'sizeInGiB': 123
}
},
'platformVersion': 'string',
'platformFamily': 'string',
'pullStartedAt': datetime(2015, 1, 1),
'pullStoppedAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'startedBy': 'string',
'stopCode': 'TaskFailedToStart'|'EssentialContainerExited'|'UserInitiated'|'ServiceSchedulerInitiated'|'SpotInterruption'|'TerminationNotice'|'InfrastructureHealth',
'stoppedAt': datetime(2015, 1, 1),
'stoppedReason': 'string',
'stoppingAt': datetime(2015, 1, 1),
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'taskArn': 'string',
'taskDefinitionArn': 'string',
'version': 123,
'ephemeralStorage': {
'sizeInGiB': 123
},
'fargateEphemeralStorage': {
'sizeInGiB': 123,
'kmsKeyId': 'string'
}
}
}
Response Structure
(dict) --
task (dict) --
The task that was stopped.
attachments (list) --
The Elastic Network Adapter that's associated with the task if the task uses the awsvpc network mode.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
attributes (list) --
The attributes of the task
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
availabilityZone (string) --
The Availability Zone for the task.
capacityProviderName (string) --
The capacity provider that's associated with the task.
clusterArn (string) --
The ARN of the cluster that hosts the task.
connectivity (string) --
The connectivity status of a task.
connectivityAt (datetime) --
The Unix timestamp for the time when the task last went into CONNECTED status.
containerInstanceArn (string) --
The ARN of the container instances that host the task.
containers (list) --
The containers that's associated with the task.
(dict) --
A Docker container that's part of a task.
containerArn (string) --
The Amazon Resource Name (ARN) of the container.
taskArn (string) --
The ARN of the task.
name (string) --
The name of the container.
image (string) --
The image used for the container.
imageDigest (string) --
The container image manifest digest.
runtimeId (string) --
The ID of the Docker container.
lastStatus (string) --
The last known status of the container.
exitCode (integer) --
The exit code returned from the container.
reason (string) --
A short (1024 max characters) human-readable string to provide additional details 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's used with the network binding.
hostPort (integer) --
The port number on the host that's used with the network binding.
protocol (string) --
The protocol used for the network binding.
containerPortRange (string) --
The port number range on the container that's bound to the dynamically mapped host port range.
The following rules apply when you specify a containerPortRange:
You must use either the bridge network mode or the awsvpc network mode.
This parameter is available for both the EC2 and Fargate launch types.
This parameter is available for both the Linux and Windows operating systems.
The container instance must have at least version 1.67.0 of the container agent and at least version 1.67.0-1 of the ecs-init package
You can specify a maximum of 100 port ranges per container.
You do not specify a hostPortRange. The value of the hostPortRange is set as follows:
For containers in a task with the awsvpc network mode, the hostPortRange is set to the same value as the containerPortRange. This is a static mapping strategy.
For containers in a task with the bridge network mode, the Amazon ECS agent finds open host ports from the default ephemeral range and passes it to docker to bind them to the container ports.
The containerPortRange valid values are between 1 and 65535.
A port can only be included in one port mapping per container.
You cannot specify overlapping port ranges.
The first port in the range must be less than last port in the range.
Docker recommends that you turn off the docker-proxy in the Docker daemon config file when you have a large number of ports. For more information, see Issue #11185 on the Github website. For information about how to turn off the docker-proxy in the Docker daemon config file, see Docker daemon in the Amazon ECS Developer Guide.
You can call DescribeTasks to view the hostPortRange which are the host ports that are bound to the container ports.
hostPortRange (string) --
The port number range on the host that's used with the network binding. This is assigned is assigned by Docker and delivered by the Amazon ECS agent.
networkInterfaces (list) --
The network interfaces associated with the container.
(dict) --
An object representing the elastic network interface for tasks that use the awsvpc network mode.
attachmentId (string) --
The attachment ID for the network interface.
privateIpv4Address (string) --
The private IPv4 address for the network interface.
ipv6Address (string) --
The private IPv6 address for the network interface.
healthStatus (string) --
The health status of the container. If health checks aren't configured for this container in its task definition, then it reports the health status as UNKNOWN.
managedAgents (list) --
The details of any Amazon ECS managed agents associated with the container.
(dict) --
Details about the managed agent status for the container.
lastStartedAt (datetime) --
The Unix timestamp for the time when the managed agent was last started.
name (string) --
The name of the managed agent. When the execute command feature is turned on, the managed agent name is ExecuteCommandAgent.
reason (string) --
The reason for why the managed agent is in the state it is in.
lastStatus (string) --
The last known status of the managed agent.
cpu (string) --
The number of CPU units set for the container. The value is 0 if no value was specified in the container definition when the task definition was registered.
memory (string) --
The hard limit (in MiB) of memory set for the container.
memoryReservation (string) --
The soft limit (in MiB) of memory set for the container.
gpuIds (list) --
The IDs of each GPU assigned to the container.
(string) --
neuronDeviceIds (list) --
The IDs of each Neuron device assigned to the container.
(string) --
cpu (string) --
The number of CPU units used by the task as expressed in a task definition. It can be expressed as an integer using CPU units (for example, 1024). It can also be expressed as a string using vCPUs (for example, 1 vCPU or 1 vcpu). String values are converted to an integer that indicates the CPU units when the task definition is registered.
If you're using the EC2 launch type or the external launch type, this field is optional. Supported values are between 128 CPU units ( 0.125 vCPUs) and 196608 CPU units ( 192 vCPUs). If you do not specify a value, the parameter is ignored.
This field is required for Fargate. For information about the valid values, see Task size in the Amazon Elastic Container Service Developer Guide.
createdAt (datetime) --
The Unix timestamp for the time when the task was created. More specifically, it's for the time when the task entered the PENDING state.
desiredStatus (string) --
The desired status of the task. For more information, see Task Lifecycle.
enableExecuteCommand (boolean) --
Determines whether execute command functionality is turned on for this task. If true, execute command functionality is turned on all the containers in the task.
executionStoppedAt (datetime) --
The Unix timestamp for the time when the task execution stopped.
group (string) --
The name of the task group that's associated with the task.
healthStatus (string) --
The health status for the task. It's determined by the health of the essential containers in the task. If all essential containers in the task are reporting as HEALTHY, the task status also reports as HEALTHY. If any essential containers in the task are reporting as UNHEALTHY or UNKNOWN, the task status also reports as UNHEALTHY or UNKNOWN.
inferenceAccelerators (list) --
The Elastic Inference accelerator that's associated with the task.
(dict) --
Details on an Elastic Inference accelerator. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name. The deviceName must also be referenced in a container definition as a ResourceRequirement.
deviceType (string) --
The Elastic Inference accelerator type to use.
lastStatus (string) --
The last known status for the task. For more information, see Task Lifecycle.
launchType (string) --
The infrastructure where your task runs on. For more information, see Amazon ECS launch types in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The amount of memory (in MiB) that the task uses as expressed in a task definition. It can be expressed as an integer using MiB (for example, 1024). If it's expressed as a string using GB (for example, 1GB or 1 GB), it's converted to an integer indicating the MiB when the task definition is registered.
If you use the EC2 launch type, this field is optional.
If you use the Fargate launch type, this field is required. You must use one of the following values. The value that you choose determines the range of supported values for the cpu parameter.
512 (0.5 GB), 1024 (1 GB), 2048 (2 GB) - Available cpu values: 256 (.25 vCPU)
1024 (1 GB), 2048 (2 GB), 3072 (3 GB), 4096 (4 GB) - Available cpu values: 512 (.5 vCPU)
2048 (2 GB), 3072 (3 GB), 4096 (4 GB), 5120 (5 GB), 6144 (6 GB), 7168 (7 GB), 8192 (8 GB) - Available cpu values: 1024 (1 vCPU)
Between 4096 (4 GB) and 16384 (16 GB) in increments of 1024 (1 GB) - Available cpu values: 2048 (2 vCPU)
Between 8192 (8 GB) and 30720 (30 GB) in increments of 1024 (1 GB) - Available cpu values: 4096 (4 vCPU)
Between 16 GB and 60 GB in 4 GB increments - Available cpu values: 8192 (8 vCPU) This option requires Linux platform 1.4.0 or later.
Between 32GB and 120 GB in 8 GB increments - Available cpu values: 16384 (16 vCPU) This option requires Linux platform 1.4.0 or later.
overrides (dict) --
One or more container overrides.
containerOverrides (list) --
One or more container overrides that are sent to a task.
(dict) --
The overrides that are sent to a container. An empty container override can be passed in. An example of an empty container override is {"containerOverrides": [ ] }. If a non-empty container override is specified, the name parameter must be included.
You can use Secrets Manager or Amazon Web Services Systems Manager Parameter Store to store the sensitive data. For more information, see Retrieve secrets through environment variables in the Amazon ECS Developer Guide.
name (string) --
The name of the container that receives the override. This parameter is required if any override is specified.
command (list) --
The command to send to the container that overrides the default command from the Docker image or the task definition. You must also specify a container name.
(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. You must also specify a container name.
(dict) --
A key-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.
environmentFiles (list) --
A list of files containing the environment variables to pass to a container, instead of the value from the container definition.
(dict) --
A list of files containing the environment variables to pass to a container. You can specify up to ten environment files. The file must have a .env file extension. Each line in an environment file should contain an environment variable in VARIABLE=VALUE format. Lines beginning with # are treated as comments and are ignored.
If there are environment variables specified using the environment parameter in a container definition, they take precedence over the variables contained within an environment file. If multiple environment files are specified that contain the same variable, they're processed from the top down. We recommend that you use unique variable names. For more information, see Use a file to pass environment variables to a container in the Amazon Elastic Container Service Developer Guide.
Environment variable files are objects in Amazon S3 and all Amazon S3 security considerations apply.
You must use the following platforms for the Fargate launch type:
Linux platform version 1.4.0 or later.
Windows platform version 1.0.0 or later.
Consider the following when using the Fargate launch type:
The file is handled like a native Docker env-file.
There is no support for shell escape handling.
The container entry point interperts the VARIABLE values.
value (string) --
The Amazon Resource Name (ARN) of the Amazon S3 object containing the environment variable file.
type (string) --
The file type to use. Environment files are objects in Amazon S3. The only supported value is s3.
cpu (integer) --
The number of cpu units reserved for the container, instead of the default value from the task definition. You must also specify a container name.
memory (integer) --
The hard limit (in MiB) of memory to present to the container, instead of the default value from the task definition. If your container attempts to exceed the memory specified here, the container is killed. You must also specify a container name.
memoryReservation (integer) --
The soft limit (in MiB) of memory to reserve for the container, instead of the default value from the task definition. You must also specify a container name.
resourceRequirements (list) --
The type and amount of a resource to assign to a container, instead of the default value from the task definition. The supported resources are GPUs and Neuron devices.
(dict) --
The type and amount of a resource to assign to a container. The supported resource types are GPUs, Neuron devices, and Elastic Inference accelerators. For more information, see Working with GPUs on Amazon ECS or Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide
value (string) --
The value for the specified resource type.
When the type is GPU, the value is the number of physical GPUs the Amazon ECS container agent reserves for the container. The number of GPUs that's reserved for all containers in a task can't exceed the number of available GPUs on the container instance that the task is launched on. You can also specify ALL to allocate all available GPUs on the instance to the container.
When the type is NeuronDevice, the value must be ALL. This allocates all available Neuron devices on the instance to the container. Only one container in a task can specify NeuronDevice resources. This resource type is only supported on Managed Instances.
When the type is InferenceAccelerator, the value matches the deviceName for an InferenceAccelerator specified in a task definition.
type (string) --
The type of resource to assign to a container.
cpu (string) --
The CPU override for the task.
inferenceAcceleratorOverrides (list) --
The Elastic Inference accelerator override for the task.
(dict) --
Details on an Elastic Inference accelerator task override. This parameter is used to override the Elastic Inference accelerator specified in the task definition. For more information, see Working with Amazon Elastic Inference on Amazon ECS in the Amazon Elastic Container Service Developer Guide.
deviceName (string) --
The Elastic Inference accelerator device name to override for the task. This parameter must match a deviceName specified in the task definition.
deviceType (string) --
The Elastic Inference accelerator type to use.
executionRoleArn (string) --
The Amazon Resource Name (ARN) of the task execution role override for the task. For more information, see Amazon ECS task execution IAM role in the Amazon Elastic Container Service Developer Guide.
memory (string) --
The memory override for the task.
taskRoleArn (string) --
The Amazon Resource Name (ARN) of the role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role. For more information, see IAM Role for Tasks in the Amazon Elastic Container Service Developer Guide.
ephemeralStorage (dict) --
The ephemeral storage setting override for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
platformVersion (string) --
The platform version where your task runs on. A platform version is only specified for tasks that use the Fargate launch type. If you didn't specify one, the LATEST platform version is used. For more information, see Fargate Platform Versions in the Amazon Elastic Container Service Developer Guide.
platformFamily (string) --
The operating system that your tasks are running on. A platform family is specified only for tasks that use the Fargate launch type.
All tasks that run as part of this service must use the same platformFamily value as the service (for example, LINUX.).
pullStartedAt (datetime) --
The Unix timestamp for the time when the container image pull began.
pullStoppedAt (datetime) --
The Unix timestamp for the time when the container image pull completed.
startedAt (datetime) --
The Unix timestamp for the time when the task started. More specifically, it's for the time when the task transitioned from the PENDING state to the RUNNING state.
startedBy (string) --
The tag specified when a task is started. If an Amazon ECS service started the task, the startedBy parameter contains the deployment ID of that service.
stopCode (string) --
The stop code indicating why a task was stopped. The stoppedReason might contain additional details.
For more information about stop code, see Stopped tasks error codes in the Amazon ECS Developer Guide.
stoppedAt (datetime) --
The Unix timestamp for the time when the task was stopped. More specifically, it's for the time when the task transitioned from the RUNNING state to the STOPPED state.
stoppedReason (string) --
The reason that the task was stopped.
stoppingAt (datetime) --
The Unix timestamp for the time when the task stops. More specifically, it's for the time when the task transitions from the RUNNING state to STOPPING.
tags (list) --
The metadata that you apply to the task to help you categorize and organize the task. Each tag consists of a key and an optional value. You define both the key and value.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
taskArn (string) --
The Amazon Resource Name (ARN) of the task.
taskDefinitionArn (string) --
The ARN of the task definition that creates the task.
version (integer) --
The version counter for the task. Every time a task experiences a change that starts a CloudWatch event, the version counter is incremented. If you replicate your Amazon ECS task state with CloudWatch Events, you can compare the version of a task reported by the Amazon ECS API actions 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.
ephemeralStorage (dict) --
The ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of ephemeral storage to set for the task. The minimum supported value is 21 GiB and the maximum supported value is 200 GiB.
fargateEphemeralStorage (dict) --
The Fargate ephemeral storage settings for the task.
sizeInGiB (integer) --
The total amount, in GiB, of the ephemeral storage to set for the task. The minimum supported value is 20 GiB and the maximum supported value is 200 GiB.
kmsKeyId (string) --
Specify an Key Management Service key ID to encrypt the ephemeral storage for the task.
{'containerInstance': {'healthStatus': {'details': {'type': {'AGENT_CONNECTIVITY'}}}}}
Updates the Amazon ECS container agent on a specified container instance. Updating the Amazon ECS container agent doesn't 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.
The UpdateContainerAgent API requires an Amazon ECS-optimized AMI or Amazon Linux AMI 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 Elastic Container Service Developer Guide.
See also: AWS API Documentation
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 ARN entries for the container instance where you would like to update the Amazon ECS container agent.
dict
Response Syntax
{
'containerInstance': {
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'capacityProviderName': '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',
'statusReason': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'registeredAt': datetime(2015, 1, 1),
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'healthStatus': {
'overallStatus': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'details': [
{
'type': 'CONTAINER_RUNTIME'|'ACCELERATED_COMPUTE'|'DAEMON'|'AGENT_CONNECTIVITY',
'status': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'statusReason': 'string',
'lastUpdated': datetime(2015, 1, 1),
'lastStatusChange': datetime(2015, 1, 1)
},
]
}
}
}
Response Structure
(dict) --
containerInstance (dict) --
The container instance that the container agent was updated for.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.
ec2InstanceId (string) --
The ID of the container instance. For Amazon EC2 instances, this value is the Amazon EC2 instance ID. For external instances, this value is the Amazon Web Services Systems Manager managed instance ID.
capacityProviderName (string) --
The capacity provider that's associated with 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're 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 that's running on the container instance.
remainingResources (list) --
For CPU and memory resource types, this parameter describes the remaining CPU and memory that wasn't already allocated to tasks and is therefore available for new tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent (at instance registration time) and any task containers that have reserved port mappings on the host (with the host or bridge network mode). Any port that's 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 CPU and memory resource types, this parameter describes the amount of each resource that was available on the container instance when the container agent registered it with Amazon ECS. This value represents the total amount of CPU and memory that can be allocated on this container instance to 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 REGISTERING, REGISTRATION_FAILED, ACTIVE, INACTIVE, DEREGISTERING, or DRAINING.
If your account has opted in to the awsvpcTrunking account setting, then any newly registered container instance will transition to a REGISTERING status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance will transition to a REGISTRATION_FAILED status. You can describe the container instance and see the reason for failure in the statusReason parameter. Once the container instance is terminated, the instance transitions to a DEREGISTERING status while the trunk elastic network interface is deprovisioned. The instance then transitions to an INACTIVE status.
The ACTIVE status indicates that the container instance can accept tasks. The DRAINING indicates that new tasks aren't placed on the container instance and any service tasks running on the container instance are removed if possible. For more information, see Container instance draining in the Amazon Elastic Container Service Developer Guide.
statusReason (string) --
The reason that the container instance reached its current status.
agentConnected (boolean) --
This parameter returns true if the agent is connected to Amazon ECS. An instance with an agent that may be unhealthy or stopped return false. Only instances connected to an agent can accept task placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that have a desired status ( desiredStatus) of RUNNING.
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 wasn't ever requested, this value is NULL.
attributes (list) --
The attributes set for the container instance, either by the Amazon ECS container agent at instance registration or manually with the PutAttributes operation.
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
registeredAt (datetime) --
The Unix timestamp for the time when the container instance was registered.
attachments (list) --
The resources attached to a container instance, such as an elastic network interface.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
tags (list) --
The metadata that you apply to the container instance to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
healthStatus (dict) --
An object representing the health status of the container instance.
overallStatus (string) --
The overall health status of the container instance. This is an aggregate status of all container instance health checks.
details (list) --
An array of objects representing the details of the container instance health status.
(dict) --
An object representing the result of a container instance health status check.
type (string) --
The type of container instance health status that was verified.
status (string) --
The container instance health status.
statusReason (string) --
The reason for the container instance health status.
lastUpdated (datetime) --
The Unix timestamp for when the container instance health status was last updated.
lastStatusChange (datetime) --
The Unix timestamp for when the container instance health status last changed.
{'containerInstances': {'healthStatus': {'details': {'type': {'AGENT_CONNECTIVITY'}}}}}
Modifies the status of an Amazon ECS container instance.
Once a container instance has reached an ACTIVE state, you can change the status of a container instance to DRAINING to manually remove an instance from a cluster, for example to perform system updates, update the Docker daemon, or scale down the cluster size.
When you set a container instance to DRAINING, Amazon ECS prevents new tasks from being scheduled for placement on the container instance and replacement service tasks are started on other container instances in the cluster if the resources are available. Service tasks on the container instance that are in the PENDING state are stopped immediately.
Service tasks on the container instance that are in the RUNNING state are stopped and replaced according to the service's deployment configuration parameters, minimumHealthyPercent and maximumPercent. You can change the deployment configuration of your service using UpdateService.
If minimumHealthyPercent is below 100%, the scheduler can ignore desiredCount temporarily during task replacement. For example, desiredCount is four tasks, a minimum of 50% allows the scheduler to stop two existing tasks before starting two new tasks. If the minimum is 100%, the service scheduler can't remove existing tasks until the replacement tasks are considered healthy. Tasks for services that do not use a load balancer are considered healthy if they're in the RUNNING state. Tasks for services that use a load balancer are considered healthy if they're in the RUNNING state and are reported as healthy by the load balancer.
The maximumPercent parameter represents an upper limit on the number of running tasks during task replacement. You can use this to define the replacement batch size. For example, if desiredCount is four tasks, a maximum of 200% starts four new tasks before stopping the four tasks to be drained, provided that the cluster resources required to do this are available. If the maximum is 100%, then replacement tasks can't start until the draining tasks have stopped.
Any PENDING or RUNNING tasks that do not belong to a service aren't affected. You must wait for them to finish or stop them manually.
A container instance has completed draining when it has no more RUNNING tasks. You can verify this using ListTasks.
When a container instance has been drained, you can set a container instance to ACTIVE status and once it has reached that status the Amazon ECS scheduler can begin scheduling tasks on the instance again.
See also: AWS API Documentation
Request Syntax
client.update_container_instances_state(
cluster='string',
containerInstances=[
'string',
],
status='ACTIVE'|'DRAINING'|'REGISTERING'|'DEREGISTERING'|'REGISTRATION_FAILED'
)
string
The short name or full Amazon Resource Name (ARN) of the cluster that hosts the container instance to update. If you do not specify a cluster, the default cluster is assumed.
list
[REQUIRED]
A list of up to 10 container instance IDs or full ARN entries.
(string) --
string
[REQUIRED]
The container instance state to update the container instance with. The only valid values for this action are ACTIVE and DRAINING. A container instance can only be updated to DRAINING status once it has reached an ACTIVE state. If a container instance is in REGISTERING, DEREGISTERING, or REGISTRATION_FAILED state you can describe the container instance but can't update the container instance state.
dict
Response Syntax
{
'containerInstances': [
{
'containerInstanceArn': 'string',
'ec2InstanceId': 'string',
'capacityProviderName': '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',
'statusReason': 'string',
'agentConnected': True|False,
'runningTasksCount': 123,
'pendingTasksCount': 123,
'agentUpdateStatus': 'PENDING'|'STAGING'|'STAGED'|'UPDATING'|'UPDATED'|'FAILED',
'attributes': [
{
'name': 'string',
'value': 'string',
'targetType': 'container-instance',
'targetId': 'string'
},
],
'registeredAt': datetime(2015, 1, 1),
'attachments': [
{
'id': 'string',
'type': 'string',
'status': 'string',
'details': [
{
'name': 'string',
'value': 'string'
},
]
},
],
'tags': [
{
'key': 'string',
'value': 'string'
},
],
'healthStatus': {
'overallStatus': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'details': [
{
'type': 'CONTAINER_RUNTIME'|'ACCELERATED_COMPUTE'|'DAEMON'|'AGENT_CONNECTIVITY',
'status': 'OK'|'IMPAIRED'|'INSUFFICIENT_DATA'|'INITIALIZING',
'statusReason': 'string',
'lastUpdated': datetime(2015, 1, 1),
'lastStatusChange': datetime(2015, 1, 1)
},
]
}
},
],
'failures': [
{
'arn': 'string',
'reason': 'string',
'detail': 'string'
},
]
}
Response Structure
(dict) --
containerInstances (list) --
The list of container instances.
(dict) --
An Amazon EC2 or External instance that's running the Amazon ECS agent and has been registered with a cluster.
containerInstanceArn (string) --
The Amazon Resource Name (ARN) of the container instance. For more information about the ARN format, see Amazon Resource Name (ARN) in the Amazon ECS Developer Guide.
ec2InstanceId (string) --
The ID of the container instance. For Amazon EC2 instances, this value is the Amazon EC2 instance ID. For external instances, this value is the Amazon Web Services Systems Manager managed instance ID.
capacityProviderName (string) --
The capacity provider that's associated with 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're 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 that's running on the container instance.
remainingResources (list) --
For CPU and memory resource types, this parameter describes the remaining CPU and memory that wasn't already allocated to tasks and is therefore available for new tasks. For port resource types, this parameter describes the ports that were reserved by the Amazon ECS container agent (at instance registration time) and any task containers that have reserved port mappings on the host (with the host or bridge network mode). Any port that's 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 CPU and memory resource types, this parameter describes the amount of each resource that was available on the container instance when the container agent registered it with Amazon ECS. This value represents the total amount of CPU and memory that can be allocated on this container instance to 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, PORTS_UDP, or a user-defined resource.
type (string) --
The type of the resource. Valid values: 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 REGISTERING, REGISTRATION_FAILED, ACTIVE, INACTIVE, DEREGISTERING, or DRAINING.
If your account has opted in to the awsvpcTrunking account setting, then any newly registered container instance will transition to a REGISTERING status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance will transition to a REGISTRATION_FAILED status. You can describe the container instance and see the reason for failure in the statusReason parameter. Once the container instance is terminated, the instance transitions to a DEREGISTERING status while the trunk elastic network interface is deprovisioned. The instance then transitions to an INACTIVE status.
The ACTIVE status indicates that the container instance can accept tasks. The DRAINING indicates that new tasks aren't placed on the container instance and any service tasks running on the container instance are removed if possible. For more information, see Container instance draining in the Amazon Elastic Container Service Developer Guide.
statusReason (string) --
The reason that the container instance reached its current status.
agentConnected (boolean) --
This parameter returns true if the agent is connected to Amazon ECS. An instance with an agent that may be unhealthy or stopped return false. Only instances connected to an agent can accept task placement requests.
runningTasksCount (integer) --
The number of tasks on the container instance that have a desired status ( desiredStatus) of RUNNING.
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 wasn't ever requested, this value is NULL.
attributes (list) --
The attributes set for the container instance, either by the Amazon ECS container agent at instance registration or manually with the PutAttributes operation.
(dict) --
An attribute is a name-value pair that's associated with an Amazon ECS object. Use attributes to extend the Amazon ECS data model by adding custom metadata to your resources. For more information, see Attributes in the Amazon Elastic Container Service Developer Guide.
name (string) --
The name of the attribute. The name must contain between 1 and 128 characters. The name may contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), forward slashes (/), back slashes (), or periods (.).
value (string) --
The value of the attribute. The value must contain between 1 and 128 characters. It can contain letters (uppercase and lowercase), numbers, hyphens (-), underscores (_), periods (.), at signs (@), forward slashes (/), back slashes (), colons (:), or spaces. The value can't start or end with a space.
targetType (string) --
The type of the target to attach the attribute with. This parameter is required if you use the short form ID for a resource instead of the full ARN.
targetId (string) --
The ID of the target. You can specify the short form ID for a resource or the full Amazon Resource Name (ARN).
registeredAt (datetime) --
The Unix timestamp for the time when the container instance was registered.
attachments (list) --
The resources attached to a container instance, such as an elastic network interface.
(dict) --
An object representing a container instance or task attachment.
id (string) --
The unique identifier for the attachment.
type (string) --
The type of the attachment, such as ElasticNetworkInterface, Service Connect, and AmazonElasticBlockStorage.
status (string) --
The status of the attachment. Valid values are PRECREATED, CREATED, ATTACHING, ATTACHED, DETACHING, DETACHED, DELETED, and FAILED.
details (list) --
Details of the attachment.
For elastic network interfaces, this includes the network interface ID, the MAC address, the subnet ID, and the private IPv4 address.
For Service Connect services, this includes portName, clientAliases, discoveryName, and ingressPortOverride.
For Elastic Block Storage, this includes roleArn, deleteOnTermination, volumeName, volumeId, and statusReason (only when the attachment fails to create or attach).
(dict) --
A key-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.
tags (list) --
The metadata that you apply to the container instance to help you categorize and organize them. Each tag consists of a key and an optional value. You define both.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
(dict) --
The metadata that you apply to a resource to help you categorize and organize them. Each tag consists of a key and an optional value. You define them.
The following basic restrictions apply to tags:
Maximum number of tags per resource - 50
For each resource, each tag key must be unique, and each tag key can have only one value.
Maximum key length - 128 Unicode characters in UTF-8
Maximum value length - 256 Unicode characters in UTF-8
If your tagging schema is used across multiple services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.
Tag keys and values are case-sensitive.
Do not use aws:, AWS:, or any upper or lowercase combination of such as a prefix for either keys or values as it is reserved for Amazon Web Services use. You cannot edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.
key (string) --
One part of a key-value pair that make up a tag. A key is a general label that acts like a category for more specific tag values.
value (string) --
The optional part of a key-value pair that make up a tag. A value acts as a descriptor within a tag category (key).
healthStatus (dict) --
An object representing the health status of the container instance.
overallStatus (string) --
The overall health status of the container instance. This is an aggregate status of all container instance health checks.
details (list) --
An array of objects representing the details of the container instance health status.
(dict) --
An object representing the result of a container instance health status check.
type (string) --
The type of container instance health status that was verified.
status (string) --
The container instance health status.
statusReason (string) --
The reason for the container instance health status.
lastUpdated (datetime) --
The Unix timestamp for when the container instance health status was last updated.
lastStatusChange (datetime) --
The Unix timestamp for when the container instance health status last changed.
failures (list) --
Any failures associated with the call.
(dict) --
A failed resource. For a list of common causes, see API failure reasons in the Amazon Elastic Container Service Developer Guide.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
detail (string) --
The details of the failure.