create-task-set¶

Description¶

Create a task set 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 .

Synopsis¶

  create-task-set
--service <value>
--cluster <value>
[--external-id <value>]
--task-definition <value>
[--network-configuration <value>]
[--load-balancers <value>]
[--service-registries <value>]
[--launch-type <value>]
[--capacity-provider-strategy <value>]
[--platform-version <value>]
[--scale <value>]
[--client-token <value>]
[--tags <value>]
[--cli-input-json | --cli-input-yaml]
[--generate-cli-skeleton <value>]
[--cli-auto-prompt <value>]

Options¶

--service (string)

The short name or full Amazon Resource Name (ARN) of the service to create the task set in.

--cluster (string)

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

--external-id (string)

An optional non-unique tag that identifies this task set in external systems. If the task set is associated with a service discovery registry, the tasks in this task set will have the ECS_TASK_SET_EXTERNAL_ID AWS Cloud Map attribute set to the provided value.

--task-definition (string)

The task definition for the tasks in the task set to use.

--network-configuration (structure)

An object representing the network configuration for a task or service.

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 .

Shorthand Syntax:

awsvpcConfiguration={subnets=[string,string],securityGroups=[string,string],assignPublicIp=string}

JSON Syntax:

{
  "awsvpcConfiguration": {
    "subnets": ["string", ...],
    "securityGroups": ["string", ...],
    "assignPublicIp": "ENABLED"|"DISABLED"
  }
}

--load-balancers (list)

A load balancer object representing the load balancer to use with the task set. The supported load balancer types are either an Application Load Balancer or a Network Load Balancer.

(structure)

The load balancer configuration to use with a service or task set.

For specific notes and restrictions regarding the use of load balancers with services and task sets, see the CreateService and CreateTaskSet actions.

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 the target group ARN 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 the load balancer name parameter 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.

Shorthand Syntax:

targetGroupArn=string,loadBalancerName=string,containerName=string,containerPort=integer ...

JSON Syntax:

[
  {
    "targetGroupArn": "string",
    "loadBalancerName": "string",
    "containerName": "string",
    "containerPort": integer
  }
  ...
]

--service-registries (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.

Shorthand Syntax:

registryArn=string,port=integer,containerName=string,containerPort=integer ...

JSON Syntax:

[
  {
    "registryArn": "string",
    "port": integer,
    "containerName": "string",
    "containerPort": integer
  }
  ...
]

--launch-type (string)

The launch type that new tasks in the task set will use. For more information, see Amazon ECS Launch Types in the Amazon Elastic Container Service Developer Guide .

If a launchType is specified, the capacityProviderStrategy parameter must be omitted.

Possible values:

EC2

FARGATE

--capacity-provider-strategy (list)

The capacity provider strategy to use for the task set.

A capacity provider strategy consists of one or more capacity providers along with the base and weight to assign to them. A capacity provider must be associated with the cluster to be used in a capacity provider strategy. The PutClusterCapacityProviders API is used to associate a capacity provider with a cluster. Only capacity providers with an ACTIVE or UPDATING status can be used.

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.

If specifying a capacity provider that uses an Auto Scaling group, the capacity provider must already be created. New capacity providers can be created with the CreateCapacityProvider API operation.

To use a AWS Fargate capacity provider, specify either the FARGATE or FARGATE_SPOT capacity providers. The AWS Fargate capacity providers are available to all accounts and only need to be associated with a cluster to be used.

The PutClusterCapacityProviders API operation is used to update the list of available capacity providers for a cluster after the cluster is created.

(structure)

The details of a capacity provider strategy.

capacityProvider -> (string)

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.

For example, if you have a strategy that contains two capacity providers and both have a weight of 1 , then when the base is satisfied, the tasks will be split evenly across the two capacity providers. Using that same logic, if you specify a weight of 1 for capacityProviderA and a weight of 4 for capacityProviderB , then for every one task that is run using capacityProviderA , four tasks would use capacityProviderB .

base -> (integer)

The base value designates how many tasks, at a minimum, to run on the specified capacity provider. Only one capacity provider in a capacity provider strategy can have a base defined.

Shorthand Syntax:

capacityProvider=string,weight=integer,base=integer ...

JSON Syntax:

[
  {
    "capacityProvider": "string",
    "weight": integer,
    "base": integer
  }
  ...
]

--platform-version (string)

The platform version that the tasks in the task set should use. A platform version is specified only for tasks using the Fargate launch type. If one isn’t specified, the LATEST platform version is used by default.

--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.

Shorthand Syntax:

value=double,unit=string

JSON Syntax:

{
  "value": double,
  "unit": "PERCENT"
}

--client-token (string)

Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Up to 32 ASCII characters are allowed.

--tags (list)

The metadata that you apply to the task set to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. When a service is deleted, the tags are deleted as well.

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 AWS 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.

(structure)

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, 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 AWS 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).

Shorthand Syntax:

key=string,value=string ...

JSON Syntax:

[
  {
    "key": "string",
    "value": "string"
  }
  ...
]

--cli-input-json | --cli-input-yaml (string) Reads arguments from the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, those 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. This may not be specified along with --cli-input-yaml.

--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. Similarly, if provided yaml-input it will print a sample input YAML that can be used with --cli-input-yaml. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

--cli-auto-prompt (boolean) Automatically prompt for CLI input parameters.

See ‘aws help’ for descriptions of global parameters.

Examples¶

To create a task set

The following create-task-set example creates a task set in a service that uses an external deployment controller.

aws ecs create-task-set \
    --cluster MyCluster \
    --service MyService \
    --task-definition MyTaskDefinition:2 \
    --network-configuration "awsvpcConfiguration={subnets=[subnet-12344321],securityGroups=[sg-12344321]}"

Output:

{
    "taskSet": {
        "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/MyTaskDefinition:2",
        "computedDesiredCount": 0,
        "pendingCount": 0,
        "runningCount": 0,
        "createdAt": 1557128360.711,
        "updatedAt": 1557128360.711,
        "launchType": "EC2",
        "networkConfiguration": {
            "awsvpcConfiguration": {
                "subnets": [
                    "subnet-12344321"
                ],
                "securityGroups": [
                    "sg-12344321"
                ],
                "assignPublicIp": "DISABLED"
            }
        },
        "loadBalancers": [],
        "serviceRegistries": [],
        "scale": {
            "value": 0.0,
            "unit": "PERCENT"
        },
        "stabilityStatus": "STABILIZING",
        "stabilityStatusAt": 1557128360.711
    }
}

Output¶

taskSet -> (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 .

capacityProviderStrategy -> (list)

The capacity provider strategy associated with the task set.

(structure)

The details of a capacity provider strategy.

capacityProvider -> (string)

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.

For example, if you have a strategy that contains two capacity providers and both have a weight of 1 , then when the base is satisfied, the tasks will be split evenly across the two capacity providers. Using that same logic, if you specify a weight of 1 for capacityProviderA and a weight of 4 for capacityProviderB , then for every one task that is run using capacityProviderA , four tasks would use capacityProviderB .

base -> (integer)

The base value designates how many tasks, at a minimum, to run on the specified capacity provider. Only one capacity provider in a capacity provider strategy can have a base defined.

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)

The load balancer configuration to use with a service or task set.

For specific notes and restrictions regarding the use of load balancers with services and task sets, see the CreateService and CreateTaskSet actions.

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 the target group ARN 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 the load balancer name parameter 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.

tags -> (list)

The metadata that you apply to the task set 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 AWS 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.

(structure)

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, 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 AWS 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).

Table of Contents

Feedback

User Guide

create-task-set¶

Description¶

Synopsis¶

Options¶

Examples¶

Output¶