Table Of Contents

Feedback

User Guide

First time using the AWS CLI? See the User Guide for help getting started.

[ aws . ecs ]

describe-task-sets

Description

Describes the task sets in the specified cluster and service. This is used when a service uses the EXTERNAL deployment controller type. For more information, see Amazon ECS Deployment Types in the Amazon Elastic Container Service Developer Guide .

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.

Synopsis

  describe-task-sets
--cluster <value>
--service <value>
[--task-sets <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]

Options

--cluster (string)

The short name or full Amazon Resource Name (ARN) of the cluster that hosts the service that the task sets exist in.

--service (string)

The short name or full Amazon Resource Name (ARN) of the service that the task sets exist in.

--task-sets (list)

The ID or full Amazon Resource Name (ARN) of task sets to describe.

Syntax:

"string" "string" ...

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.

Examples

To describe a task set

The following describe-task-sets example describes a task set in a service that uses an external deployer.

aws ecs describe-task-sets \
    --cluster MyCluster \
    --service MyService \
    --task-sets arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789

Output:

{
    "taskSets": [
        {
            "id": "ecs-svc/1234567890123456789",
            "taskSetArn": "arn:aws:ecs:us-west-2:123456789012:task-set/MyCluster/MyService/ecs-svc/1234567890123456789",
            "status": "ACTIVE",
            "taskDefinition": "arn:aws:ecs:us-west-2:123456789012:task-definition/sample-fargate:2",
            "computedDesiredCount": 0,
            "pendingCount": 0,
            "runningCount": 0,
            "createdAt": 1557207715.195,
            "updatedAt": 1557207740.014,
            "launchType": "EC2",
            "networkConfiguration": {
                "awsvpcConfiguration": {
                    "subnets": [
                        "subnet-12344321"
                    ],
                    "securityGroups": [
                        "sg-1234431"
                    ],
                    "assignPublicIp": "DISABLED"
                }
            },
            "loadBalancers": [],
            "serviceRegistries": [],
            "scale": {
                "value": 0.0,
                "unit": "PERCENT"
            },
            "stabilityStatus": "STEADY_STATE",
            "stabilityStatusAt": 1557207740.014
        }
    ],
    "failures": []
}

Output

taskSets -> (list)

The list of task sets described.

(structure)

Information about a set of Amazon ECS tasks in either an AWS CodeDeploy or an EXTERNAL deployment. An Amazon ECS task set includes details such as the desired number of tasks, how many tasks are running, and whether the task set serves production traffic.

id -> (string)

The ID of the task set.

taskSetArn -> (string)

The Amazon Resource Name (ARN) of the task set.

serviceArn -> (string)

The Amazon Resource Name (ARN) of the service the task set exists in.

clusterArn -> (string)

The Amazon Resource Name (ARN) of the cluster that the service that hosts the task set exists in.

startedBy -> (string)

The tag specified when a task set is started. If the task set is created by an AWS CodeDeploy deployment, the startedBy parameter is CODE_DEPLOY . For a task set created for an external deployment, the startedBy field isn't used.

externalId -> (string)

The external ID associated with the task set.

If a task set is created by an AWS CodeDeploy deployment, the externalId parameter contains the AWS CodeDeploy deployment ID.

If a task set is created for an external deployment and is associated with a service discovery registry, the externalId parameter contains the ECS_TASK_SET_EXTERNAL_ID AWS Cloud Map attribute.

status -> (string)

The status of the task set. The following describes each state:

PRIMARY

The task set is serving production traffic.

ACTIVE

The task set is not serving production traffic.

DRAINING

The tasks in the task set are being stopped and their corresponding targets are being deregistered from their target group.

taskDefinition -> (string)

The task definition the task set is using.

computedDesiredCount -> (integer)

The computed desired count for the task set. This is calculated by multiplying the service's desiredCount by the task set's scale percentage. The result is always rounded up. For example, if the computed desired count is 1.2, it rounds up to 2 tasks.

pendingCount -> (integer)

The number of tasks in the task set that are in the PENDING status during a deployment. A task in the PENDING state is preparing to enter the RUNNING state. A task set enters the PENDING status when it launches for the first time or when it is restarted after being in the STOPPED state.

runningCount -> (integer)

The number of tasks in the task set that are in the RUNNING status during a deployment. A task in the RUNNING state is running and ready for use.

createdAt -> (timestamp)

The Unix timestamp for when the task set was created.

updatedAt -> (timestamp)

The Unix timestamp for when the task set was last updated.

launchType -> (string)

The launch type the tasks in the task set are using. For more information, see Amazon ECS Launch Types in the Amazon Elastic Container Service Developer Guide .

platformVersion -> (string)

The platform version on which the tasks in the task set are running. A platform version is only specified for tasks using the Fargate launch type. If one is not specified, the LATEST platform version is used by default. For more information, see AWS Fargate Platform Versions in the Amazon Elastic Container Service Developer Guide .

networkConfiguration -> (structure)

The network configuration for the task set.

awsvpcConfiguration -> (structure)

The VPC subnets and security groups associated with a task.

Note

All specified subnets and security groups must be from the same VPC.

subnets -> (list)

The subnets associated with the task or service. There is a limit of 16 subnets that can be specified per AwsVpcConfiguration .

Note

All specified subnets must be from the same VPC.

(string)

securityGroups -> (list)

The security groups associated with the task or service. If you do not specify a security group, the default security group for the VPC is used. There is a limit of 5 security groups that can be specified per AwsVpcConfiguration .

Note

All specified security groups must be from the same VPC.

(string)

assignPublicIp -> (string)

Whether the task's elastic network interface receives a public IP address. The default value is DISABLED .

loadBalancers -> (list)

Details on a load balancer that is used with a task set.

(structure)

Details on the load balancer or load balancers to use with a service or task set.

targetGroupArn -> (string)

The full Amazon Resource Name (ARN) of the Elastic Load Balancing target group or groups associated with a service or task set.

A target group ARN is only specified when using an Application Load Balancer or Network Load Balancer. If you are using a Classic Load Balancer this should be omitted.

For services using the ECS deployment controller, you can specify one or multiple target groups. For more information, see Registering Multiple Target Groups with a Service in the Amazon Elastic Container Service Developer Guide .

For services using the CODE_DEPLOY deployment controller, you are required to define two target groups for the load balancer. For more information, see Blue/Green Deployment with CodeDeploy in the Amazon Elastic Container Service Developer Guide .

Warning

If your service's task definition uses the awsvpc network mode (which is required for the Fargate launch type), you must choose ip as the target type, not instance , when creating your target groups because tasks that use the awsvpc network mode are associated with an elastic network interface, not an Amazon EC2 instance.

loadBalancerName -> (string)

The name of the load balancer to associate with the Amazon ECS service or task set.

A load balancer name is only specified when using a Classic Load Balancer. If you are using an Application Load Balancer or a Network Load Balancer this should be omitted.

containerName -> (string)

The name of the container (as it appears in a container definition) to associate with the load balancer.

containerPort -> (integer)

The port on the container to associate with the load balancer. This port must correspond to a containerPort in the task definition the tasks in the service are using. For tasks that use the EC2 launch type, the container instance they are launched on must allow ingress traffic on the hostPort of the port mapping.

serviceRegistries -> (list)

The details of the service discovery registries to assign to this task set. For more information, see Service Discovery .

(structure)

Details of the service registry.

registryArn -> (string)

The Amazon Resource Name (ARN) of the service registry. The currently supported service registry is AWS Cloud Map. For more information, see CreateService .

port -> (integer)

The port value used if your service discovery service specified an SRV record. This field may be used if both the awsvpc network mode and SRV records are used.

containerName -> (string)

The container name value, already specified in the task definition, to be used for your service discovery service. If the task definition that your service task specifies uses the bridge or host network mode, you must specify a containerName and containerPort combination from the task definition. If the task definition that your service task specifies uses the awsvpc network mode and a type SRV DNS record is used, you must specify either a containerName and containerPort combination or a port value, but not both.

containerPort -> (integer)

The port value, already specified in the task definition, to be used for your service discovery service. If the task definition your service task specifies uses the bridge or host network mode, you must specify a containerName and containerPort combination from the task definition. If the task definition your service task specifies uses the awsvpc network mode and a type SRV DNS record is used, you must specify either a containerName and containerPort combination or a port value, but not both.

scale -> (structure)

A floating-point percentage of the desired number of tasks to place and keep running in the task set.

value -> (double)

The value, specified as a percent total of a service's desiredCount , to scale the task set. Accepted values are numbers between 0 and 100.

unit -> (string)

The unit of measure for the scale value.

stabilityStatus -> (string)

The stability status, which indicates whether the task set has reached a steady state. If the following conditions are met, the task set will be in STEADY_STATE :

  • The task runningCount is equal to the computedDesiredCount .
  • The pendingCount is 0 .
  • There are no tasks running on container instances in the DRAINING status.
  • All tasks are reporting a healthy status from the load balancers, service discovery, and container health checks.

If any of those conditions are not met, the stability status returns STABILIZING .

stabilityStatusAt -> (timestamp)

The Unix timestamp for when the task set stability status was retrieved.

failures -> (list)

Any failures associated with the call.

(structure)

A failed resource.

arn -> (string)

The Amazon Resource Name (ARN) of the failed resource.

reason -> (string)

The reason for the failure.