- Navigation GuideYou are on a Client landing page. Commands (operations) are listed on this page. The Client constructor type is linked at the bottom.
ECSClient
Amazon Elastic Container Service (Amazon ECS) is a highly scalable, fast, container management service. It makes it easy to run, stop, and manage Docker containers. You can host your cluster on a serverless infrastructure that's managed by Amazon ECS by launching your services or tasks on Fargate. For more control, you can host your tasks on a cluster of Amazon Elastic Compute Cloud (Amazon EC2) or External (on-premises) instances that you manage.
Amazon ECS makes it easy to launch and stop container-based applications with simple API calls. This makes it easy to get the state of your cluster from a centralized service, and gives you access to many familiar Amazon EC2 features.
You can use Amazon ECS to schedule the placement of containers across your cluster based on your resource needs, isolation policies, and availability requirements. With Amazon ECS, you don't need to operate your own cluster management and configuration management systems. You also don't need to worry about scaling your management infrastructure.
Installation
npm install @aws-sdk/client-ecs
yarn add @aws-sdk/client-ecs
pnpm add @aws-sdk/client-ecs
ECSClient Operations
Command | Summary |
---|
Command | Summary |
---|---|
CreateCapacityProviderCommand | Creates a new capacity provider. Capacity providers are associated with an Amazon ECS cluster and are used in capacity provider strategies to facilitate cluster auto scaling. Only capacity providers that use an Auto Scaling group can be created. Amazon ECS tasks on Fargate use the |
CreateClusterCommand | Creates a new Amazon ECS cluster. By default, your account receives a When you call the CreateCluster API operation, Amazon ECS attempts to create the Amazon ECS service-linked role for your account. This is so that it can manage required resources in other Amazon Web Services services on your behalf. However, if the user that makes the call doesn't have permissions to create the service-linked role, it isn't created. For more information, see Using service-linked roles for Amazon ECS in the Amazon Elastic Container Service Developer Guide. |
CreateServiceCommand | Runs and maintains your desired number of tasks from a specified task definition. If the number of tasks running in a service drops below the On March 21, 2024, a change was made to resolve the task definition revision before authorization. When a task definition revision is not specified, authorization will occur using the latest revision of a task definition. Amazon Elastic Inference (EI) is no longer available to customers. In addition to maintaining the desired count of tasks in your service, you can optionally run your service behind one or more load balancers. The load balancers distribute traffic across the tasks that are associated with the service. For more information, see Service load balancing 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. Tasks for services that don't use a load balancer are considered healthy if they're in the There are two service scheduler strategies available:
You can optionally specify a deployment configuration for your service. The deployment is initiated by changing properties. For example, the deployment might be initiated by the task definition or by your desired count of a service. You can use UpdateService . The default value for a replica service for If a service uses the If a service uses the If a service uses either the When creating a service that uses the When the service scheduler launches new tasks, it determines task placement. For information about task placement and task placement strategies, see Amazon ECS task placement in the Amazon Elastic Container Service Developer Guide |
CreateTaskSetCommand | Create a task set in the specified cluster and service. This is used when a service uses the On March 21, 2024, a change was made to resolve the task definition revision before authorization. When a task definition revision is not specified, authorization will occur using the latest revision of a task definition. For information about the maximum number of task sets and other quotas, see Amazon ECS service quotas in the Amazon Elastic Container Service Developer Guide. |
DeleteAccountSettingCommand | Disables an account setting for a specified user, role, or the root user for an account. |
DeleteAttributesCommand | Deletes one or more custom attributes from an Amazon ECS resource. |
DeleteCapacityProviderCommand | Deletes the specified capacity provider. The Prior to a capacity provider being deleted, the capacity provider must be removed from the capacity provider strategy from all services. The UpdateService API can be used to remove a capacity provider from a service's capacity provider strategy. When updating a service, the |
DeleteClusterCommand | Deletes the specified cluster. The cluster transitions to the You must deregister all container instances from this cluster before you may delete it. You can list the container instances in a cluster with ListContainerInstances and deregister them with DeregisterContainerInstance . |
DeleteServiceCommand | Deletes a specified service within a cluster. You can delete a service if you have no running tasks in it and the desired task count is zero. If the service is actively maintaining tasks, you can't delete it, and you must update the service to a desired task count of zero. For more information, see UpdateService . When you delete a service, if there are still running tasks that require cleanup, the service status moves from If you attempt to create a new service with the same name as an existing service in either |
DeleteTaskDefinitionsCommand | Deletes one or more task definitions. You must deregister a task definition revision before you delete it. For more information, see DeregisterTaskDefinition . When you delete a task definition revision, it is immediately transitions from the You can't use a A task definition revision will stay in When you delete all |
DeleteTaskSetCommand | Deletes a specified task set within a service. This is used when a service uses the |
DeregisterContainerInstanceCommand | 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. If you terminate a running container instance, Amazon ECS automatically deregisters the instance from your cluster (stopped container instances or instances with disconnected agents aren't automatically deregistered when terminated). |
DeregisterTaskDefinitionCommand | Deregisters the specified task definition by family and revision. Upon deregistration, the task definition is marked as You can't use an At this time, You must deregister a task definition revision before you delete it. For more information, see DeleteTaskDefinitions . |
DescribeCapacityProvidersCommand | Describes one or more of your capacity providers. |
DescribeClustersCommand | Describes one or more of your clusters. For CLI examples, see describe-clusters.rst on GitHub. |
DescribeContainerInstancesCommand | Describes one or more container instances. Returns metadata about each container instance requested. |
DescribeServiceDeploymentsCommand | Describes one or more of your service deployments. A service deployment happens when you release a software update for the service. For more information, see Amazon ECS service deployments . |
DescribeServiceRevisionsCommand | Describes one or more service revisions. A service revision is a version of the service that includes the values for the Amazon ECS resources (for example, task definition) and the environment resources (for example, load balancers, subnets, and security groups). For more information, see Amazon ECS service revisions . You can't describe a service revision that was created before October 25, 2024. |
DescribeServicesCommand | Describes the specified services running in your cluster. |
DescribeTaskDefinitionCommand | Describes a task definition. You can specify a You can only describe |
DescribeTaskSetsCommand | Describes the task sets in the specified cluster and service. This is used when a service uses the |
DescribeTasksCommand | 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. |
DiscoverPollEndpointCommand | This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent. Returns an endpoint for the Amazon ECS agent to poll for updates. |
ExecuteCommandCommand | Runs a command remotely on a container within a task. If you use a condition key in your IAM policy to refine the conditions for the policy statement, for example limit the actions to a specific cluster, you receive an For information about required permissions and considerations, see Using Amazon ECS Exec for debugging in the Amazon ECS Developer Guide. |
GetTaskProtectionCommand | Retrieves the protection status of tasks in an Amazon ECS service. |
ListAccountSettingsCommand | Lists the account settings for a specified principal. |
ListAttributesCommand | Lists the attributes for Amazon ECS resources within a specified target type and cluster. When you specify a target type and cluster, |
ListClustersCommand | Returns a list of existing clusters. |
ListContainerInstancesCommand | Returns a list of container instances in a specified cluster. You can filter the results of a |
ListServiceDeploymentsCommand | This operation lists all the service deployments that meet the specified filter criteria. A service deployment happens when you release a software update for the service. You route traffic from the running service revisions to the new service revison and control the number of running tasks. This API returns the values that you use for the request parameters in DescribeServiceRevisions . |
ListServicesByNamespaceCommand | This operation lists all of the services that are associated with a Cloud Map namespace. This list might include services in different clusters. In contrast, |
ListServicesCommand | Returns a list of services. You can filter the results by cluster, launch type, and scheduling strategy. |
ListTagsForResourceCommand | List the tags for an Amazon ECS resource. |
ListTaskDefinitionFamiliesCommand | Returns a list of task definition families that are registered to your account. This list includes task definition families that no longer have any You can filter out task definition families that don't contain any |
ListTaskDefinitionsCommand | Returns a list of task definitions that are registered to your account. You can filter the results by family name with the |
ListTasksCommand | Returns a list of tasks. You can filter the results by cluster, task definition family, container instance, launch type, what IAM principal started the task, or by the desired status of the task. Recently stopped tasks might appear in the returned results. |
PutAccountSettingCommand | Modifies an account setting. Account settings are set on a per-Region basis. If you change the root user account setting, the default settings are reset for users and roles that do not have specified individual account settings. For more information, see Account Settings in the Amazon Elastic Container Service Developer Guide. |
PutAccountSettingDefaultCommand | Modifies an account setting for all users on an account for whom no individual account setting has been specified. Account settings are set on a per-Region basis. |
PutAttributesCommand | Create or update an attribute on an Amazon ECS resource. If the attribute doesn't exist, it's created. If the attribute exists, its value is replaced with the specified value. To delete an attribute, use DeleteAttributes . For more information, see Attributes in the Amazon Elastic Container Service Developer Guide. |
PutClusterCapacityProvidersCommand | Modifies the available capacity providers and the default capacity provider strategy for a cluster. You must specify both the available capacity providers and a default capacity provider strategy for the cluster. If the specified cluster has existing capacity providers associated with it, you must specify all existing capacity providers in addition to any new ones you want to add. Any existing capacity providers that are associated with a cluster that are omitted from a PutClusterCapacityProviders API call will be disassociated with the cluster. You can only disassociate an existing capacity provider from a cluster if it's not being used by any existing tasks. When creating a service or running a task on a cluster, if no capacity provider or launch type is specified, then the cluster's default capacity provider strategy is used. We recommend that you define a default capacity provider strategy for your cluster. However, you must specify an empty array ( |
RegisterContainerInstanceCommand | This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent. Registers an EC2 instance into the specified cluster. This instance becomes available to place containers on. |
RegisterTaskDefinitionCommand | Registers a new task definition from the supplied You can specify a role for your task with the You can specify a Docker networking mode for the containers in your task definition with the |
RunTaskCommand | Starts a new task using the specified task definition. On March 21, 2024, a change was made to resolve the task definition revision before authorization. When a task definition revision is not specified, authorization will occur using the latest revision of a task definition. Amazon Elastic Inference (EI) is no longer available to customers. 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 You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. For more infomation, 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:
|
StartTaskCommand | Starts a new task from the specified task definition on the specified container instance or instances. On March 21, 2024, a change was made to resolve the task definition revision before authorization. When a task definition revision is not specified, authorization will occur using the latest revision of a task definition. Amazon Elastic Inference (EI) is no longer available to customers. Alternatively, you can use You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when creating or updating a service. For more infomation, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide. |
StopTaskCommand | Stops a running task. Any tags associated with the task will be deleted. When you call For Windows containers, POSIX signals do not work and runtime stops the container by sending a The default 30-second timeout can be configured on the Amazon ECS container agent with the |
SubmitAttachmentStateChangesCommand | This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent. Sent to acknowledge that an attachment changed states. |
SubmitContainerStateChangeCommand | This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent. Sent to acknowledge that a container changed states. |
SubmitTaskStateChangeCommand | This action is only used by the Amazon ECS agent, and it is not intended for use outside of the agent. Sent to acknowledge that a task changed states. |
TagResourceCommand | Associates the specified tags to a resource with the specified |
UntagResourceCommand | Deletes specified tags from a resource. |
UpdateCapacityProviderCommand | Modifies the parameters for a capacity provider. |
UpdateClusterCommand | Updates the cluster. |
UpdateClusterSettingsCommand | Modifies the settings to use for a cluster. |
UpdateContainerAgentCommand | 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 Agent updates with the The |
UpdateContainerInstancesStateCommand | Modifies the status of an Amazon ECS container instance. Once a container instance has reached an A container instance can't be changed to When you set a container instance to Service tasks on the container instance that are in the
Any A container instance has completed draining when it has no more When a container instance has been drained, you can set a container instance to |
UpdateServiceCommand | Modifies the parameters of a service. On March 21, 2024, a change was made to resolve the task definition revision before authorization. When a task definition revision is not specified, authorization will occur using the latest revision of a task definition. For services using the rolling update ( You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when starting or running a task, or when creating or updating a service. For more infomation, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide. You can update your volume configurations and trigger a new deployment. For services using the blue/green ( For services using an external deployment controller, you can update only the desired count, task placement constraints and strategies, health check grace period, enable ECS managed tags option, and propagate tags option, using this API. If the launch type, load balancer, network configuration, platform version, or task definition need to be updated, create a new task set For more information, see CreateTaskSet . You can add to or subtract from the number of instantiations of a task definition in a service by specifying the cluster that the service is running in and a new You can attach Amazon EBS volumes to Amazon ECS tasks by configuring the volume when starting or running a task, or when creating or updating a service. For more infomation, see Amazon EBS volumes in the Amazon Elastic Container Service Developer Guide. If you have updated the container image of your application, you can create a new task definition with that image and deploy it to your service. The service scheduler uses the minimum healthy percent and maximum percent parameters (in the service's deployment configuration) to determine the deployment strategy. If your updated Docker image uses the same tag as what is in the existing task definition for your service (for example, You can also update the deployment configuration of a service. When a deployment is triggered by updating the task definition of a service, the service scheduler uses the deployment configuration parameters,
When UpdateService stops a task during a deployment, the equivalent of When the service scheduler launches new tasks, it determines task placement in your cluster with the following logic.
When the service scheduler stops running tasks, it attempts to maintain balance across the Availability Zones in your cluster using the following logic:
You must have a service-linked role when you update any of the following service properties:
For more information about the role see the |
UpdateServicePrimaryTaskSetCommand | Modifies which task set in a service is the primary task set. Any parameters that are updated on the primary task set in a service will transition to the service. This is used when a service uses the |
UpdateTaskProtectionCommand | Updates the protection status of a task. You can set Task-protection, by default, expires after 2 hours at which point Amazon ECS clears the You can specify a custom expiration period for task protection from 1 minute to up to 2,880 minutes (48 hours). To specify the custom expiration period, set the To learn more about Amazon ECS task protection, see Task scale-in protection in the Amazon Elastic Container Service Developer Guide . This operation is only supported for tasks belonging to an Amazon ECS service. Invoking this operation for a standalone task will result in an If you prefer to set task protection from within the container, we recommend using the Task scale-in protection endpoint . |
UpdateTaskSetCommand | Modifies a task set. This is used when a service uses the |
ECSClient Configuration
Parameter | Type | Description |
---|
Parameter | Type | Description |
---|---|---|
defaultsMode Optional | DefaultsMode | Provider<DefaultsMode> | The @smithy/smithy-client#DefaultsMode that will be used to determine how certain default configuration options are resolved in the SDK. |
disableHostPrefix Optional | boolean | Disable dynamically changing the endpoint of the client based on the hostPrefix trait of an operation. |
extensions Optional | RuntimeExtension[] | Optional extensions |
logger Optional | Logger | Optional logger for logging debug/info/warn/error. |
maxAttempts Optional | number | Provider<number> | Value for how many times a request will be made at most in case of retry. |
profile Optional | string | Setting a client profile is similar to setting a value for the AWS_PROFILE environment variable. Setting a profile on a client in code only affects the single client instance, unlike AWS_PROFILE.When set, and only for environments where an AWS configuration file exists, fields configurable by this file will be retrieved from the specified profile within that file. Conflicting code configuration and environment variables will still have higher priority.For client credential resolution that involves checking the AWS configuration file, the client's profile (this value) will be used unless a different profile is set in the credential provider options. |
region Optional | string | Provider<string> | The AWS region to which this client will send requests |
requestHandler Optional | __HttpHandlerUserInput | The HTTP handler to use or its constructor options. Fetch in browser and Https in Nodejs. |
retryMode Optional | string | Provider<string> | Specifies which retry algorithm to use. |
useDualstackEndpoint Optional | boolean | Provider<boolean> | Enables IPv6/IPv4 dualstack endpoint. |
useFipsEndpoint Optional | boolean | Provider<boolean> | Enables FIPS compatible endpoints. |
Additional config fields are described in the full configuration type: ECSClientConfig