> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/aws-ecs

Manage and deploy apps via Amazon's AWS Elastic Container Service (ECS) on CircleCI. Supports the EC2 and Fargate launch types and Blue/Green deployment via CodeDeploy.


## Commands

### deploy_ecs_scheduled_task

Deploy an ECS Scheduled Task Rule after updating a task definition. The update_task_definition command must be run first.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `region` | string | $AWS_DEFAULT_REGION | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `rule_name` | string |  | The name of the scheduled task's rule to update. |

### install_ecs_cli

Installs the AWS ECS CLI

| Parameter | Type | Default | Description |
|---|---|---|---|
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `install_dir` | string | /usr/local/bin/ecs-cli | Specify the installation directory for the AWS ECS CLI. By default, the installation directory will be /usr/local/bin/ecs-cli. |
| `override_installed` | boolean | false | By default, if the AWS ECS CLI is detected on the system, the install will be skipped.
Enable this to override the installed version and install your specified version.
 |
| `version` | string | latest | Specify the  version of the AWS ECS CLI to install. By default, the latest version will be installed. |

### run_task

Starts a new ECS task using the specified task definition and other parameters.

For more information on ECS Run-Task options, see: https://awscli.amazonaws.com/v2/documentation/api/latest/reference/ecs/run_task.html


| Parameter | Type | Default | Description |
|---|---|---|---|
| `assign_public_ip` | enum | DISABLED | Assign a public IP or not
 |
| `awsvpc` | boolean | true | Does your task defintion use awsvpc mode or not.
If so, this should be true and you should also include subnet_ids and optionally security_group_ids / assign_public_ips.
 |
| `capacity_provider_strategy` | string |  | The capacity provider strategy to use for the task.
If a `capacity_provider_strategy` is specified, the `launch_type` parameter must be set to an empty string.
 |
| `cluster` | string |  | The name or ARN of the cluster on which to run the task. |
| `count` | integer | 1 | "The number of instantiations of the specified task to place on your
cluster. You can specify up to 10 tasks per call."
 |
| `enable_ecs_managed_tags` | boolean | false | "Specifies whether to enable Amazon ECS managed tags for the task."
 |
| `enable_execute_command` | boolean | false | 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.
 |
| `exit_code_from` | string |  | Name of the container which exit code will be returned if wait_task_stopped is true. Defaults to the first container. |
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `group` | 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).
 |
| `launch_type` | enum | FARGATE | The launch type on which to run your task.
Possible values EC2, FARGATE, or an empty string.

For more information, see Amazon ECS Launch Types in the Amazon Elastic Container Service Developer Guide.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as "20m", "1.25h", "5s". The default is 10 minutes.
 |
| `overrides` | string |  | 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.
 |
| `placement_constraints` | string |  | An array of placement constraint objects to use for the task. You can specify up to 10 constraints per task (including constraints in the task definition and those specified at runtime).
Expected format: type=string,field=string.
 |
| `placement_strategy` | string |  | The placement strategy objects to use for the task. You can specify a maximum of five strategy rules per task.
Expected format: type=string,field=string.
 |
| `platform_version` | string |  | Use this to specify the platform version that the task should run on.
A platform version should only be specified for tasks using the Fargate launch type.
 |
| `profile_name` | string | default | AWS profile name to be configured. |
| `propagate_tags` | boolean | false | Specifies whether to propagate the tags from the task definition to
the task.
If no value is specified, the tags are not 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.
 |
| `region` | string | $AWS_DEFAULT_REGION | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `run_task_output` | string |  | Specifies a local json file to save the output logs from the aws ecs run_task command. Use tools like JQ to read and parse this information such as "task-arns" and "task-ids"
 |
| `security_group_ids` | string |  | List of security group ids separated by commas.
Expected Format: sg-010a460f7f442fa75,sg-010a420f7faa5fa75
 |
| `started_by` | string |  | An optional tag specified when a task is started.
For example, if you automatically trigger a task to run a batch process job, you could apply a unique identifier for that job to your task with the startedBy parameter. You can then identify which tasks belong to that job by filtering the results of a ListTasks call with the startedBy value. Up to 36 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed.
 |
| `subnet_ids` | string |  | List of subnet ids separated by commas.
Expected Format: subnet-70faa93b,subnet-bcc54b93
 |
| `tags` | string |  | 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. Expected format: key=string,value=string.
 |
| `task_definition` | string |  | The family and revision (family:revision) or full ARN of the task definition to run. If a revision is not specified, the latest ACTIVE revision is used.
 |
| `wait_task_stopped` | boolean | false | Wait until the task execution ends. Doesn't work with `run_task_output`. |

### update_service

Registers a task definition for the given ECS service and updates the service to use it. Optionally polls the status of the deployment until the created task definition revision has reached its desired running task count and is the only revision deployed for the service.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster` | string |  | The short name or full ARN of the cluster that hosts the service. |
| `codedeploy_application_name` | string |  | The name of the AWS CodeDeploy application used for the deployment. Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `codedeploy_capacity_provider_base` | string |  | The base of AWS Capacity Provider to be added to CodeDeploy deployment. Must be used with codedeploy_capacity_provider_name and codedeploy_capacity_provider_weight.
 |
| `codedeploy_capacity_provider_name` | string |  | The name of AWS Capacity Provider to be added to CodeDeploy deployment. Must be used with capacity-provider-base and capacity-provider-weight.
 |
| `codedeploy_capacity_provider_weight` | string |  | The weight of AWS Capacity Provider to be added to CodeDeploy deployment. Weight must be greater than 0. Must be used with codedeploy_capacity_provider_name and codedeploy_capacity_provider_base.
 |
| `codedeploy_deployment_group_name` | string |  | The name of the AWS CodeDeploy deployment group used for the deployment. Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `codedeploy_load_balanced_container_name` | string |  | The name of the container to be load-balanced via AWS CodeDeploy. Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `codedeploy_load_balanced_container_port` | string | 80 | The port of the container to be load-balanced via AWS CodeDeploy. Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `container_docker_label_updates` | string |  | Use this to update or set the values of docker label variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,<key>=<env-var-name>,<key>=<env-var-value>,container=...,<key>=...,<key>=...,
Values should not contain commas.
 |
| `container_env_var_updates` | string |  | Use this to update or set the values of environment variables that will be defined for the containers. (Existing environment variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,value=<env-var-value>,container=...,name=...,value=...,
Values should not contain commas.
 |
| `container_image_name_updates` | string |  | Use this to update the Docker image names and/or tag names of existing containers that had been defined in the previous task definition.
Expected format: container=<container-name>,image-and-tag=<image-name>:<tag-name>|image=<image-name>|tag=<tag-name>,container=...,image-and-tag|image|tag=...,
For each container, specify only either "image-and-tag" or "image" or "tag".
If "image-and-tag" is specified, the container image will be updated to the value of the name-value pair. If "image" is specified, the image tag defined in the previous task definition will be retained, if exists. If "tag" is specified, the image name defined in the previous task definition will be used.
 |
| `container_name` | string |  | The name of the container to associate with the load balancer when the service needs to be created.
Only works with ECS deployment controller.
Default to empty.
 |
| `container_port` | string |  | The port on the container to associate with the load balancer when the service needs to be created.
This port must correspond to a containerPort in the task definition the tasks in the service are using.
Only works with ECS deployment controller.
Default to empty.
 |
| `container_secret_updates` | string |  | Use this to update or set the values of secret variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,valueFrom=<env-var-value>,container=...,name=...,valueFrom=...,
Values should not contain commas.
 |
| `create_service` | boolean | false | Create the service if it does not exist already.
Only works with ECS deployment controller.
Default false.
 |
| `deployment_config_name` | string |  | The name of a CODE DEPLOY deployment configuration associated with the IAM user or AWS account. If not specified, the value configured in the deployment group is used as the default.
 |
| `deployment_controller` | enum | ECS | The deployment controller to use for the service. Defaulted to ECS |
| `desired_count` | string |  | The desired number of tasks to run. If empty it would keep the existing count.
Only works with ECS deployment controller.
Default to empty.
 |
| `enable_circuit_breaker` | boolean | false | Determines whether a service deployment will fail if the service can't reach a steady state.
To use the deployment circuit breaker for CodeDeploy services, the verify_revision_is_deployed parameter must be set to true.
 |
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `fail_on_verification_timeout` | boolean | true | Whether to exit with an error if the verification of the deployment status does not complete within the number of polling attempts.
Only in use when verify_revision_is_deployed is set to true.
 |
| `family` | string |  | Name of the task definition's family. |
| `force_new_deployment` | boolean | false | Whether to force a new deployment of the service.
Not applicable to ECS services that are of the Blue/Green Deployment type.
 |
| `max_poll_attempts` | integer | 50 | The maximum number of attempts to poll the deployment status before giving up. Only in use when verify_revision_is_deployed is set to true.
 |
| `poll_interval` | integer | 20 | The polling interval, in seconds.
Only in use when verify_revision_is_deployed is set to true.
 |
| `previous_revision_number` | string |  | Optional previous task's revision number |
| `profile_name` | string | default | AWS profile name to be configured. |
| `public_ip` | enum | DISABLED | Whether the task's elastic network interface receives a public IP address when the service needs to be created.
Only works with ECS deployment controller.
The default value is DISABLED.
 |
| `region` | string | $AWS_DEFAULT_REGION | AWS region to use for looking up task definitions. |
| `security_groups` | string |  | Comma separated list of security group ids for the service when it needs to be created, e.g. "sg-00000000,sg-1111111"
Only works with ECS deployment controller.
Default to empty.
 |
| `service_name` | string |  | The name of the service to update. If undefined, we assume `family` is the name of both the service and task definition. |
| `skip_task_definition_registration` | boolean | false | Whether to skip registration of a new task definition.
 |
| `subnets` | string |  | Comma separated list of subnet ids for the service when it needs to be created, e.g. "subnet-00000000,subnet-1111111"
Only works with ECS deployment controller.
Default to empty.
 |
| `target_group` | string |  | The full ARN of the Elastic Load Balancing target group or groups associated with a service when it needs to be created.
Only works with ECS deployment controller.
Default to empty.
 |
| `task_definition_tags` | string |  | The metadata that you apply to the task definition to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
(Existing tags not included in this parameter will not be removed)
Expected formats:
  - Shorthand Syntax
    key=string,value=string ...
  - JSON Syntax
   [{"key": "string","value": "string"} ... ]

Values should not contain commas.
 |
| `verification_timeout` | string | 10m | The maximum amount of time to wait for a blue/green deployment to complete before timing out.
Only in use when the deployment controller is the blue/green deployment type.
 |
| `verify_revision_is_deployed` | boolean | false | Runs the verify_revision_is_deployed Orb command to verify that the revision has been deployed and is the only deployed revision for the service.

Note: enabling this may result in the build being marked as failed if tasks for older revisions fail to be stopped before the max number of polling attempts is reached.
 |

### update_task_definition

Registers a task definition based on the last task definition, except with the Docker image/tag names and environment variables of the containers updated according to this command's parameters.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `container_docker_label_updates` | string |  | Use this to update or set the values of docker label variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,<key>=<env-var-name>,<key>=<env-var-value>,container=...,<key>=...,<key>=...,
Values should not contain commas.
 |
| `container_env_var_updates` | string |  | Use this to update or set the values of environment variables that will be defined for the containers.
(Existing environment variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,value=<env-var-value>,container=...,name=...,value=...,
Values should not contain commas.
 |
| `container_image_name_updates` | string |  | Use this to update the Docker image names and/or tag names of existing containers that had been defined in the previous task definition.
Expected format: container=<container-name>,image-and-tag=<image-name>:<tag-name>|image=<image-name>|tag=<tag-name>,container=...,image-and-tag|image|tag=...,
For each container, specify only either "image-and-tag" or "image" or "tag".
If "image-and-tag" is specified, the container image will be updated to the value of the name-value pair. If "image" is specified, the image tag defined in the previous task definition will be retained, if exists. If "tag" is specified, the image name defined in the previous task definition will be used.
 |
| `container_secret_updates` | string |  | Use this to update or set the values of secrets variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,valueFrom=<env-var-value>,container=...,name=...,valueFrom=...,
Values should not contain commas.
 |
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `family` | string |  | Name of the task definition's family. |
| `previous_revision_number` | string |  | Optional previous task's revision number |
| `profile_name` | string | default | AWS profile name to be configured. |
| `region` | string | $AWS_DEFAULT_REGION | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `task_definition_tags` | string |  | The metadata that you apply to the task definition to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
(Existing tags not included in this parameter will not be removed)
Expected formats:
  - Shorthand Syntax
    key=string,value=string ...
  - JSON Syntax
   [{"key": "string","value": "string"} ... ]

Values should not contain commas.
 |

### update_task_definition_from_json

Registers a task definition based on a json file.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `profile_name` | string | default | AWS profile name to be configured. |
| `region` | string | $AWS_DEFAULT_REGION | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `task_definition_json` | string |  | Location of your .json task definition file (relative or absolute).
 |

### verify_revision_is_deployed

Polls the service's deployment status at intervals until the given task definition revision is the only one deployed for the service, and for the task definition revision's running task count to match the desired count.
Does not support ECS services that are of the Blue/Green Deployment type.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster` | string |  | The short name or full ARN of the cluster that hosts the service. |
| `extra_command_label` | string |  | Extra label that attaches to the end of every step name |
| `fail_on_verification_timeout` | boolean | true | Whether to exit with an error if the verification of the deployment status does not complete within the number of polling attempts.
 |
| `family` | string |  | Name of the task definition's family. |
| `max_poll_attempts` | integer | 50 | The maximum number of attempts to poll for the deployment status before giving up. |
| `poll_interval` | integer | 20 | The polling interval, in seconds. |
| `profile_name` | string | default | AWS profile name to be configured. |
| `region` | string | $AWS_DEFAULT_REGION | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `service_name` | string |  | The name of the service to update. If undefined, we assume `family` is the name of both the service and task definition. |
| `task_definition_arn` | string |  | ARN of the task definition whose deployment status is to be monitored. |

## Jobs

### deploy_service_update

Install AWS CLI and update the ECS service with the registered task definition.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `cluster` | string |  | The short name or full ARN of the cluster that hosts the service. |
| `codedeploy_application_name` | string |  | The name of the AWS CodeDeploy application used for the deployment.
Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `codedeploy_capacity_provider_base` | string |  | The base of AWS Capacity Provider to be added to CodeDeploy deployment. Must be used with codedeploy_capacity_provider_name and capacity-provider-weight.
 |
| `codedeploy_capacity_provider_name` | string |  | The name of AWS Capacity Provider to be added to CodeDeploy deployment. Must be used with capacity-provider-base and capacity-provider-weight.
 |
| `codedeploy_capacity_provider_weight` | string |  | The base of AWS Capacity Provider to be added to CodeDeploy deployment. Must be used with codedeploy_capacity_provider_name and capacity-provider-base.
 |
| `codedeploy_deployment_group_name` | string |  | The name of the AWS CodeDeploy deployment group used for the deployment.
Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `codedeploy_load_balanced_container_name` | string |  | The name of the container to be load-balanced via AWS CodeDeploy.
Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `codedeploy_load_balanced_container_port` | string | 80 | The port of the container to be load-balanced via AWS CodeDeploy.
Only effective when the deployment_controller parameter value is "CODE_DEPLOY".
 |
| `container_docker_label_updates` | string |  | Use this to update or set the values of docker label variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,<key>=<env-var-name>,<key>=<env-var-value>,container=...,<key>=...,<key>=...,
Values should not contain commas.
 |
| `container_env_var_updates` | string |  | Use this to update or set the values of environment variables that will be defined for the containers.
(Existing environment variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,value=<env-var-value>,container=...,name=...,value=...,
Values should not contain commas.
 |
| `container_image_name_updates` | string |  | Use this to update the Docker image names and/or tag names of existing
containers that had been defined in the previous task definition.
Expected format: container=<container-name>,image-and-tag=<image-name>:<tag-name>|image=<image-name>|tag=<tag-name>,container=...,image-and-tag|image|tag=...,
For each container, specify only either "image-and-tag" or "image" or "tag".
If "image-and-tag" is specified, the container image will be updated to the value of the name-value pair.
If "image" is specified, the image tag defined in the previous task definition will be retained, if exists.
If "tag" is specified, the image name defined in the previous task definition will be used.
 |
| `container_name` | string |  | The name of the container to associate with the load balancer when the service needs to be created.
Only works with ECS deployment controller.
Default to empty.
 |
| `container_port` | string |  | The port on the container to associate with the load balancer when the service needs to be created.
This port must correspond to a containerPort in the task definition the tasks in the service are using.
Only works with ECS deployment controller.
Default to empty.
 |
| `container_secret_updates` | string |  | Use this to update or set the values of secrets variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,valueFrom=<env-var-value>,container=...,name=...,valueFrom=...,
Values should not contain commas.
 |
| `create_service` | boolean | false | Create the service if it does not exist already.
Only works with ECS deployment controller.
Default false.
 |
| `deployment_config_name` | string |  | The name of a CODE DEPLOY deployment configuration associated with the IAM user or AWS account. If not specified, the value configured in the deployment group is used as the default.
 |
| `deployment_controller` | enum | ECS | The deployment controller to use for the service. Defaulted to ECS |
| `desired_count` | string |  | The desired number of tasks to run. If empty it would keep the existing count.
Only works with ECS deployment controller.
Default to empty.
 |
| `enable_circuit_breaker` | boolean | false | Determines whether a service deployment will fail if the service can’t reach a steady state.
The deployment circuit breaker can only be used for services using the rolling update (ECS ) deployment type.
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `fail_on_verification_timeout` | boolean | true | Whether to exit with an error if the verification of the deployment
status does not complete within the number of polling attempts.
Only in use when verify_revision_is_deployed is set to true.
 |
| `family` | string |  | Name of the task definition's family. |
| `force_new_deployment` | boolean | false | Whether to force a new deployment of the service.
Not applicable to ECS services that are of the Blue/Green Deployment type.
 |
| `max_poll_attempts` | integer | 50 | The maximum number of attempts to poll the deployment status before giving up.
Only in use when verify_revision_is_deployed is set to true.
 |
| `poll_interval` | integer | 20 | The polling interval, in seconds.
Only in use when verify_revision_is_deployed is set to true.
 |
| `profile_name` | string | default | AWS profile name to be configured. |
| `public_ip` | enum | DISABLED | Whether the task's elastic network interface receives a public IP address when the service needs to be created.
Only works with ECS deployment controller.
The default value is DISABLED.
 |
| `region` | string | ${AWS_DEFAULT_REGION} | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `security_groups` | string |  | Comma separated list of security group ids for the service when it needs to be created, e.g. "sg-00000000,sg-1111111"
Only works with ECS deployment controller.
Default to empty.
 |
| `service_name` | string |  | The name of the service to update. If undefined, we assume `family` is the name of both the service and task definition. |
| `skip_task_definition_registration` | boolean | false | Whether to skip registration of a new task definition.
 |
| `subnets` | string |  | Comma separated list of subnet ids for the service when it needs to be created, e.g. "subnet-00000000,subnet-1111111"
Only works with ECS deployment controller.
Default to empty.
 |
| `target_group` | string |  | The full ARN of the Elastic Load Balancing target group or groups associated with a service when it needs to be created.
Only works with ECS deployment controller.
Default to empty.
 |
| `task_definition_tags` | string |  | The metadata that you apply to the task definition to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.
(Existing environment variables not included in this parameter will not be removed)
Expected formats:
  - Shorthand Syntax
    key=string,value=string ...
  - JSON Syntax
   [{"key": "string","value": "string"} ... ]

Values should not contain commas.
 |
| `verification_timeout` | string | 10m | The maximum amount of time to wait for a blue/green deployment to complete before timing out.
Only in use when the deployment controller is the blue/green deployment type.
 |
| `verify_revision_is_deployed` | boolean | false | Runs the verify_revision_is_deployed Orb command to verify that
the revision has been deployed and is the only deployed revision
for the service. Note: enabling this may result in the build
being marked as failed if tasks for older revisions fail to be stopped
before the max number of polling attempts is reached.
 |

### run_task

Install AWS CLI and Start a new ECS task using the specified task definition and other parameters.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `assign_public_ip` | enum | DISABLED | "Assign a public IP or not"
 |
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `awsvpc` | boolean | true | "Does your task definition use awsvpc mode or not. If so,
this should be true and you should also include subnet_ids
and optionally security_group_ids / assign_public_ips."
 |
| `capacity_provider_strategy` | string |  | The capacity provider strategy to use for the task.
If a `capacity_provider_strategy` is specified, the `launch_type` parameter must be set to an empty string.
 |
| `cluster` | string |  | The name or ARN of the cluster on which to run the task. |
| `count` | integer | 1 | "The number of instantiations of the specified task to place on your
cluster. You can specify up to 10 tasks per call."
 |
| `enable_ecs_managed_tags` | boolean | false | "Specifies whether to enable Amazon ECS managed tags for the task."
 |
| `enable_execute_command` | boolean | false | 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.
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `exit_code_from` | string |  | Name of the container which exit code will be returned if wait_task_stopped is true. Defaults to the first container. |
| `group` | 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).
 |
| `launch_type` | enum | FARGATE | The launch type on which to run your task.
Possible values EC2, FARGATE, or an empty string.

For more information, see Amazon ECS Launch Types in the Amazon Elastic Container Service Developer Guide.
 |
| `no_output_timeout` | string | 10m | Elapsed time the command can run without output. The string is a decimal with unit suffix, such as "20m", "1.25h", "5s". The default is 10 minutes.
 |
| `overrides` | string |  | 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.
 |
| `placement_constraints` | string |  | "An array of placement constraint objects to use for the task. You
can specify up to 10 constraints per task (including constraints in
the task definition and those specified at runtime).
Expected format: type=string,field=string."
 |
| `placement_strategy` | string |  | "The placement strategy objects to use for the task. You can specify
a maximum of five strategy rules per task.
Expected format: type=string,field=string."
 |
| `platform_version` | string |  | Use this to specify the platform version that the task should run on.
A platform version should only be specified for tasks using the Fargate launch type.
 |
| `profile_name` | string | default | AWS profile name to be configured. |
| `propagate_tags` | boolean | false | "Specifies whether to propagate the tags from the task definition to
the task. If no value is specified, the tags are not 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."
 |
| `region` | string | ${AWS_DEFAULT_REGION} | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `run_task_output` | string |  | Specifies a local json file to save the output logs from the aws ecs run_task command. Use tools like JQ to read and parse this information such as "task-arns" and "task-ids"
 |
| `security_group_ids` | string |  | "List of security group ids separated by commas.
Expected Format: sg-010a460f7f442fa75,sg-010a420f7faa5fa75"
 |
| `started_by` | 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), num-
bers, hyphens, and underscores are allowed.
 |
| `subnet_ids` | string |  | "List of subnet ids separated by commas.
Expected Format: subnet-70faa93b,subnet-bcc54b93"
 |
| `tags` | string |  | "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. Expected format: key=string,value=string."
 |
| `task_definition` | string |  | "The family and revision (family:revision) or full ARN of the task
definition to run. If a revision is not specified, the latest ACTIVE
revision is used."
 |
| `wait_task_stopped` | boolean | false | Wait until the task execution ends. Doesn't work with `run_task_output`. |

### update_task_definition

Install AWS CLI and register a task definition.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `container_docker_label_updates` | string |  | Use this to update or set the values of docker label variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,<key>=<env-var-name>,<key>=<env-var-value>,container=...,<key>=...,<key>=...,
Values should not contain commas.
 |
| `container_env_var_updates` | string |  | Use this to update or set the values of environment variables that will be defined for the containers.
(Existing environment variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,value=<env-var-value>,container=...,name=...,value=...,
Values should not contain commas.
 |
| `container_image_name_updates` | string |  | Use this to update the Docker image names and/or tag names of existing
containers that had been defined in the previous task definition.
Expected format: container=<container-name>,image-and-tag=<image-name>:<tag-name>|image=<image-name>|tag=<tag-name>,container=...,image-and-tag|image|tag=...,
For each container, specify only either "image-and-tag" or "image" or "tag".
If "image-and-tag" is specified, the container image will be updated to the value of the name-value pair.
If "image" is specified, the image tag defined in the previous task definition will be retained, if exists.
If "tag" is specified, the image name defined in the previous task definition will be used.
 |
| `container_secret_updates` | string |  | Use this to update or set the values of secrets variables that will be defined for the containers. (Existing secrets variables not included in this parameter will not be removed)
Expected format: container=<container-name>,name=<env-var-name>,valueFrom=<env-var-value>,container=...,name=...,valueFrom=...,
Values should not contain commas.
 |
| `deploy_scheduled_task` | boolean | false | Set this parameter to true to deploy updated task definition to a scheduled task rule.
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `family` | string |  | Name of the task definition's family. |
| `profile_name` | string | default | AWS profile name to be configured. |
| `region` | string | ${AWS_DEFAULT_REGION} | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `rule_name` | string |  | The name of the scheduled task's rule to update. Must be a valid ECS Rule. |

### update_task_definition_from_json

Install AWS CLI and  a task definition from a json file.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auth` | steps |  | The authentication method used to access your AWS account. Import the aws-cli orb in your config and
provide the aws-cli/setup command to authenticate with your preferred method. View examples for more information.
 |
| `deploy_scheduled_task` | boolean | false | Set this parameter to true to deploy updated task definition to a scheduled task rule.
 |
| `executor` | executor | default | The executor to use for this job. By default, this will use the "default" executor provided by this orb. |
| `profile_name` | string | default | AWS profile name to be configured. |
| `region` | string | ${AWS_DEFAULT_REGION} | AWS region to use. Defaults to AWS_DEFAULT_REGION environment variable. |
| `rule_name` | string |  | The name of the scheduled task's rule to update. Must be a valid ECS Rule. |
| `task_definition_json` | string |  | Location of your .json task definition file (relative or absolute).
 |

## Executors

### default

A Python Docker image built to run on CircleCI that contains python installed with pyenv and packaging tools pip, pipenv, and poetry.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `resource_class` | enum | medium | Configure the executor resource class |
| `tag` | string | 3.13 | Select any of the available tags here: https://circleci.com/developer/images/image/cimg/python.
 |

## Examples

### deploy_ecs_scheduled_task

Use the AWS CLI and this orb to deploy an ECS Scheduled Task Rule after updating a task definition.
The update_task_definition or update_task_definition_from_json command must be run first.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  deploy_scheduled_task:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-PROFILE
          region: us-east-1
          role_arn: arn:aws:iam::123456789012:role/OIDC_ARN
          role_session_name: example-session-name
          session_duration: '3600'
      - aws-ecs/update_task_definition_from_json:
          region: us-east-1
          task_definition_json: my-app-definition.json
      - aws-ecs/deploy_ecs_scheduled_task:
          region: us-east-1
          rule_name: example-rule
workflows:
  deploy:
    jobs:
      - deploy_scheduled_task:
          context:
            - CircleCI_OIDC_Token
```

### deploy_service_update

Update an ECS service using OIDC for authentication.
Import the aws-cli orb and authenticate using the aws-cli/setup command with a valid role_arn for OIDC authentication.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecr: circleci/aws-ecr@9.3.4
  aws-ecs: circleci/aws-ecs@6.0.0
workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image:
          auth:
            - aws-cli/setup:
                profile_name: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECR_ROLE
          profile_name: OIDC-USER
          region: AWS_REGION
          repo: ${MY_APP_PREFIX}
          tag: ${CIRCLE_SHA1}
      - aws-ecs/deploy_service_update:
          auth:
            - aws-cli/setup:
                profile_name: OIDC-USER
                role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE
          cluster: ${MY_APP_PREFIX}-cluster
          container_image_name_updates: container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}
          family: ${MY_APP_PREFIX}-service
          profile_name: OIDC-USER
          region: us-east-1
          requires:
            - aws-ecr/build_and_push_image
```

### run_task_and_wait

Start the execution of an ECS task and wait until the task is completed.

```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  run_task:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-USER
          role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE
      - aws-ecs/run_task:
          cluster: $CLUSTER_NAME
          exit_code_from: app
          launch_type: ''
          region: us-east-1
          security_group_ids: $SECURITY_GROUP_IDS_FETCHED\
          subnet_ids: $SUBNET_ONE, $SUBNET_TWO
          task_definition: $My_Task_Def
          wait_task_stopped: true
workflows:
  run_task:
    jobs:
      - run_task
```

### run_task_ec2

Start the run of an ECS task on EC2.

```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  run_task:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-USER
          role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE
      - aws-ecs/run_task:
          awsvpc: false
          cluster: cluster1
          launch_type: EC2
          region: us-east-1
          task_definition: myapp
workflows:
  run_task:
    jobs:
      - run_task
```

### run_task_fargate

Start the run of an ECS task on Fargate.

```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  run_task:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-USER
          role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE
      - aws-ecs/run_task:
          cluster: cluster1
          region: us-east-1
          security_group_ids: $SECURITY_GROUP_IDS
          subnet_ids: $SUBNET_ONE, $SUBNET_TWO
          task_definition: myapp
workflows:
  run_task:
    jobs:
      - run_task
```

### run_task_fargate_spot

Amazon Fargate Spot Instances let you take advantage of spare compute capacity in the AWS Cloud at steep discounts. Fargate Spot is an AWS Fargate capability that can run interruption-tolerant Amazon Elastic Container Service (Amazon ECS) tasks at up to a 70% discount off the Fargate price. Since tasks can still be interrupted, only fault tolerant applications are suitable for Fargate Spot.
CircleCI provides continuous integration and delivery for any platform, as well as your own infrastructure. CircleCI can automatically trigger low-cost, serverless tasks with AWS Fargate Spot in Amazon ECS.


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  run_task:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-USER
          role_arn: arn:aws:iam::123456789012:role/VALID_OIDC_ECS_ROLE
      - aws-ecs/run_task:
          capacity_provider_strategy: >-
            capacityProvider=FARGATE,weight=1
            capacityProvider=FARGATE_SPOT,weight=1
          cluster: $CLUSTER_NAME
          launch_type: ''
          region: us-east-1
          security_group_ids: $SECURITY_GROUP_IDS_FETCHED
          subnet_ids: $SUBNET_ONE, $SUBNET_TWO
          task_definition: $My_Task_Def
workflows:
  run_task:
    jobs:
      - run_task
```

### update_service

Use the AWS CLI and this orb to update an ECS service.
(Supports both EC2 and Fargate launch types)


```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  update-tag:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-PROFILE
          region: AWS_REGION
          role_arn: arn:aws:iam::123456789012:role/OIDC_ARN
          role_session_name: example-session-name
          session_duration: '3600'
      - aws-ecs/update_service:
          cluster: ${MY_APP_PREFIX}-cluster
          container_image_name_updates: container=${MY_APP_PREFIX}-service,tag=stable
          family: ${MY_APP_PREFIX}-service
          region: us-east-1
workflows:
  deploy:
    jobs:
      - update-tag:
          context:
            - CircleCI_OIDC_Token
```

### update_task_definition_from_json

Use the AWS CLI and this orb to create a new ECS task definition based upon a local JSON file.

```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  update-tag:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-PROFILE
          region: AWS_REGION
          role_arn: arn:aws:iam::123456789012:role/OIDC_ARN
          role_session_name: example-session-name
          session_duration: '3600'
      - aws-ecs/update_task_definition_from_json:
          region: us-east-1
          task_definition_json: my-app-definition.json
workflows:
  deploy:
    jobs:
      - update-tag:
          context:
            - CircleCI_OIDC_Token
```

### verify_revision_deployment

Verify the deployment of an ECS revision.

```yaml
version: '2.1'
orbs:
  aws-cli: circleci/aws-cli@5.1.0
  aws-ecs: circleci/aws-ecs@6.0.0
jobs:
  verify-deployment:
    docker:
      - image: cimg/python:3.13
    steps:
      - aws-cli/setup:
          profile_name: OIDC-PROFILE
          region: AWS_REGION
          role_arn: arn:aws:iam::123456789012:role/OIDC_ARN
          role_session_name: example-session-name
          session_duration: '3600'
      - run:
          command: >
            TASK_DEFINITION_ARN=$(aws ecs describe-task-definition \
                --task_definition ${MY_APP_PREFIX}-service \
                --output text \
                --query 'taskDefinition.taskDefinitionArn' \
                --profile default \
                --region ${AWS_DEFAULT_REGION})
            echo "export TASK_DEFINITION_ARN='${TASK_DEFINITION_ARN}'" >>
            $BASH_ENV
          name: Get last task definition
      - aws-ecs/verify_revision_is_deployed:
          cluster: ${MY_APP_PREFIX}-cluster
          family: ${MY_APP_PREFIX}-service
          region: us-east-1
          task_definition_arn: ${TASK_DEFINITION_ARN}
workflows:
  test-workflow:
    jobs:
      - verify-deployment:
          context:
            - CircleCI_OIDC_Token
```