2025/04/23 - Amazon EC2 Container Service - 1 new2 updated api methods
Changes Add support to roll back an In_Progress ECS Service Deployment
Stops an ongoing service deployment.
The following stop types are avaiable:
ROLLBACK - This option rolls back the service deployment to the previous service revision. You can use this option even if you didn't configure the service deployment for the rollback option.
For more information, see Stopping Amazon ECS service deployments in the Amazon Elastic Container Service Developer Guide.
See also: AWS API Documentation
Request Syntax
client.stop_service_deployment(
serviceDeploymentArn='string',
stopType='ABORT'|'ROLLBACK'
)
string
[REQUIRED]
The ARN of the service deployment that you want to stop.
string
How you want Amazon ECS to stop the task.
The valid values are ROLLBACK.
dict
Response Syntax
{
'serviceDeploymentArn': 'string'
}
Response Structure
(dict) --
serviceDeploymentArn (string) --
The ARN of the stopped service deployment.
{'serviceDeployments': {'status': {'ROLLBACK_REQUESTED'}}}
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 View service history using Amazon ECS service deployments.
See also: AWS API Documentation
Request Syntax
client.describe_service_deployments(
serviceDeploymentArns=[
'string',
]
)
list
[REQUIRED]
The ARN of the service deployment.
You can specify a maximum of 20 ARNs.
(string) --
dict
Response Syntax
{
'serviceDeployments': [
{
'serviceDeploymentArn': 'string',
'serviceArn': 'string',
'clusterArn': 'string',
'createdAt': datetime(2015, 1, 1),
'startedAt': datetime(2015, 1, 1),
'finishedAt': datetime(2015, 1, 1),
'stoppedAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1),
'sourceServiceRevisions': [
{
'arn': 'string',
'requestedTaskCount': 123,
'runningTaskCount': 123,
'pendingTaskCount': 123
},
],
'targetServiceRevision': {
'arn': 'string',
'requestedTaskCount': 123,
'runningTaskCount': 123,
'pendingTaskCount': 123
},
'status': 'PENDING'|'SUCCESSFUL'|'STOPPED'|'STOP_REQUESTED'|'IN_PROGRESS'|'ROLLBACK_REQUESTED'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_SUCCESSFUL'|'ROLLBACK_FAILED',
'statusReason': 'string',
'deploymentConfiguration': {
'deploymentCircuitBreaker': {
'enable': True|False,
'rollback': True|False
},
'maximumPercent': 123,
'minimumHealthyPercent': 123,
'alarms': {
'alarmNames': [
'string',
],
'rollback': True|False,
'enable': True|False
}
},
'rollback': {
'reason': 'string',
'startedAt': datetime(2015, 1, 1),
'serviceRevisionArn': 'string'
},
'deploymentCircuitBreaker': {
'status': 'TRIGGERED'|'MONITORING'|'MONITORING_COMPLETE'|'DISABLED',
'failureCount': 123,
'threshold': 123
},
'alarms': {
'status': 'TRIGGERED'|'MONITORING'|'MONITORING_COMPLETE'|'DISABLED',
'alarmNames': [
'string',
],
'triggeredAlarmNames': [
'string',
]
}
},
],
'failures': [
{
'arn': 'string',
'reason': 'string',
'detail': 'string'
},
]
}
Response Structure
(dict) --
serviceDeployments (list) --
The list of service deployments described.
(dict) --
Information about the service deployment.
Service deployments provide a comprehensive view of your deployments. For information about service deployments, see View service history using Amazon ECS service deployments in the Amazon Elastic Container Service Developer Guide .
serviceDeploymentArn (string) --
The ARN of the service deployment.
serviceArn (string) --
The ARN of the service for this service deployment.
clusterArn (string) --
The ARN of the cluster that hosts the service.
createdAt (datetime) --
The time the service deployment was created. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
startedAt (datetime) --
The time the service deployment statred. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
finishedAt (datetime) --
The time the service deployment finished. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
stoppedAt (datetime) --
The time the service deployment stopped. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
The service deployment stops when any of the following actions happen:
A user manually stops the deployment
The rollback option is not in use for the failure detection mechanism (the circuit breaker or alarm-based) and the service fails.
updatedAt (datetime) --
The time that the service deployment was last updated. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
sourceServiceRevisions (list) --
The currently deployed workload configuration.
(dict) --
The information about the number of requested, pending, and running tasks for a service revision.
arn (string) --
The ARN of the service revision.
requestedTaskCount (integer) --
The number of requested tasks for the service revision.
runningTaskCount (integer) --
The number of running tasks for the service revision.
pendingTaskCount (integer) --
The number of pending tasks for the service revision.
targetServiceRevision (dict) --
The workload configuration being deployed.
arn (string) --
The ARN of the service revision.
requestedTaskCount (integer) --
The number of requested tasks for the service revision.
runningTaskCount (integer) --
The number of running tasks for the service revision.
pendingTaskCount (integer) --
The number of pending tasks for the service revision.
status (string) --
The service deployment state.
statusReason (string) --
Information about why the service deployment is in the current status. For example, the circuit breaker detected a failure.
deploymentConfiguration (dict) --
Optional deployment parameters that control how many tasks run during a deployment and the ordering of stopping and starting tasks.
deploymentCircuitBreaker (dict) --
The deployment circuit breaker determines whether a service deployment will fail if the service can't reach a steady state. If you use the deployment circuit breaker, a service deployment will transition to a failed state and stop launching new tasks. If you use the rollback option, when a service deployment fails, the service is rolled back to the last deployment that completed successfully. For more information, see Rolling update in the Amazon Elastic Container Service Developer Guide
enable (boolean) --
Determines whether to use the deployment circuit breaker logic for the service.
rollback (boolean) --
Determines whether to configure Amazon ECS to roll back the service if a service deployment fails. If rollback is on, when a service deployment fails, the service is rolled back to the last deployment that completed successfully.
maximumPercent (integer) --
If a service is using the rolling update ( ECS) deployment type, the maximumPercent parameter represents an upper limit on the number of your service's tasks that are allowed in the RUNNING or PENDING state during a deployment, as a percentage of the desiredCount (rounded down to the nearest integer). This parameter enables you to define the deployment batch size. For example, if your service is using the REPLICA service scheduler and has a desiredCount of four tasks and a maximumPercent value of 200%, the scheduler may start four new tasks before stopping the four older tasks (provided that the cluster resources required to do this are available). The default maximumPercent value for a service using the REPLICA service scheduler is 200%.
The Amazon ECS scheduler uses this parameter to replace unhealthy tasks by starting replacement tasks first and then stopping the unhealthy tasks, as long as cluster resources for starting replacement tasks are available. For more information about how the scheduler replaces unhealthy tasks, see Amazon ECS services.
If a service is using either the blue/green ( CODE_DEPLOY) or EXTERNAL deployment types, and tasks in the service use the EC2 launch type, the maximum percent value is set to the default value. The maximum percent value is used to define the upper limit on the number of the tasks in the service that remain in the RUNNING state while the container instances are in the DRAINING state.
If the service uses either the blue/green ( CODE_DEPLOY) or EXTERNAL deployment types, and the tasks in the service use the Fargate launch type, the maximum percent value is not used. The value is still returned when describing your service.
minimumHealthyPercent (integer) --
If a service is using the rolling update ( ECS) deployment type, the minimumHealthyPercent represents a lower limit on the number of your service's tasks that must remain in the RUNNING state during a deployment, as a percentage of the desiredCount (rounded up to the nearest integer). This parameter enables you to deploy without using additional cluster capacity. For example, if your service has a desiredCount of four tasks and a minimumHealthyPercent of 50%, the service scheduler may stop two existing tasks to free up cluster capacity before starting two new tasks.
If any tasks are unhealthy and if maximumPercent doesn't allow the Amazon ECS scheduler to start replacement tasks, the scheduler stops the unhealthy tasks one-by-one — using the minimumHealthyPercent as a constraint — to clear up capacity to launch replacement tasks. For more information about how the scheduler replaces unhealthy tasks, see Amazon ECS services .
For services that do not use a load balancer, the following should be noted:
A service is considered healthy if all essential containers within the tasks in the service pass their health checks.
If a task has no essential containers with a health check defined, the service scheduler will wait for 40 seconds after a task reaches a RUNNING state before the task is counted towards the minimum healthy percent total.
If a task has one or more essential containers with a health check defined, the service scheduler will wait for the task to reach a healthy status before counting it towards the minimum healthy percent total. A task is considered healthy when all essential containers within the task have passed their health checks. The amount of time the service scheduler can wait for is determined by the container health check settings.
For services that do use a load balancer, the following should be noted:
If a task has no essential containers with a health check defined, the service scheduler will wait for the load balancer target group health check to return a healthy status before counting the task towards the minimum healthy percent total.
If a task has an essential container with a health check defined, the service scheduler will wait for both the task to reach a healthy status and the load balancer target group health check to return a healthy status before counting the task towards the minimum healthy percent total.
The default value for a replica service for minimumHealthyPercent is 100%. The default minimumHealthyPercent value for a service using the DAEMON service schedule is 0% for the CLI, the Amazon Web Services SDKs, and the APIs and 50% for the Amazon Web Services Management Console.
The minimum number of healthy tasks during a deployment is the desiredCount multiplied by the minimumHealthyPercent/100, rounded up to the nearest integer value.
If a service is using either the blue/green ( CODE_DEPLOY) or EXTERNAL deployment types and is running tasks that use the EC2 launch type, the minimum healthy percent value is set to the default value. The minimum healthy percent value is used to define the lower limit on the number of the tasks in the service that remain in the RUNNING state while the container instances are in the DRAINING state.
If a service is using either the blue/green ( CODE_DEPLOY) or EXTERNAL deployment types and is running tasks that use the Fargate launch type, the minimum healthy percent value is not used, although it is returned when describing your service.
alarms (dict) --
Information about the CloudWatch alarms.
alarmNames (list) --
One or more CloudWatch alarm names. Use a "," to separate the alarms.
(string) --
rollback (boolean) --
Determines whether to configure Amazon ECS to roll back the service if a service deployment fails. If rollback is used, when a service deployment fails, the service is rolled back to the last deployment that completed successfully.
enable (boolean) --
Determines whether to use the CloudWatch alarm option in the service deployment process.
rollback (dict) --
The rollback options the service deployment uses when the deployment fails.
reason (string) --
The reason the rollback happened. For example, the circuit breaker initiated the rollback operation.
startedAt (datetime) --
Time time that the rollback started. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
serviceRevisionArn (string) --
The ARN of the service revision deployed as part of the rollback.
deploymentCircuitBreaker (dict) --
The circuit breaker configuration that determines a service deployment failed.
status (string) --
The circuit breaker status. Amazon ECS is not using the circuit breaker for service deployment failures when the status is DISABLED.
failureCount (integer) --
The number of times the circuit breaker detected a service deploymeny failure.
threshold (integer) --
The threshhold which determines that the service deployment failed.
The deployment circuit breaker calculates the threshold value, and then uses the value to determine when to move the deployment to a FAILED state. The deployment circuit breaker has a minimum threshold of 3 and a maximum threshold of 200. and uses the values in the following formula to determine the deployment failure.
0.5 * desired task count
alarms (dict) --
The CloudWatch alarms that determine when a service deployment fails.
status (string) --
The status of the alarms check. Amazon ECS is not using alarms for service deployment failures when the status is DISABLED.
alarmNames (list) --
The name of the CloudWatch alarms that determine when a service deployment failed. A "," separates the alarms.
(string) --
triggeredAlarmNames (list) --
One or more CloudWatch alarm names that have been triggered during the service deployment. A "," separates the alarm names.
(string) --
failures (list) --
Any failures associated with the call.
If you decsribe a deployment with a service revision created before October 25, 2024, the call fails. The failure includes the service revision ARN and the reason set to MISSING.
(dict) --
A failed resource. For a list of common causes, see API failure reasons in the Amazon Elastic Container Service Developer Guide.
arn (string) --
The Amazon Resource Name (ARN) of the failed resource.
reason (string) --
The reason for the failure.
detail (string) --
The details of the failure.
{'status': {'ROLLBACK_REQUESTED'}}
Response {'serviceDeployments': {'status': {'ROLLBACK_REQUESTED'}}}
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.
See also: AWS API Documentation
Request Syntax
client.list_service_deployments(
service='string',
cluster='string',
status=[
'PENDING'|'SUCCESSFUL'|'STOPPED'|'STOP_REQUESTED'|'IN_PROGRESS'|'ROLLBACK_REQUESTED'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_SUCCESSFUL'|'ROLLBACK_FAILED',
],
createdAt={
'before': datetime(2015, 1, 1),
'after': datetime(2015, 1, 1)
},
nextToken='string',
maxResults=123
)
string
[REQUIRED]
The ARN or name of the service
string
The cluster that hosts the service. This can either be the cluster name or ARN. Starting April 15, 2023, Amazon Web Services will not onboard new customers to Amazon Elastic Inference (EI), and will help current customers migrate their workloads to options that offer better price and performance. If you don't specify a cluster, default is used.
list
An optional filter you can use to narrow the results. If you do not specify a status, then all status values are included in the result.
(string) --
dict
An optional filter you can use to narrow the results by the service creation date. If you do not specify a value, the result includes all services created before the current time. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
before (datetime) --
Include service deployments in the result that were created before this time. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
after (datetime) --
Include service deployments in the result that were created after this time. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
string
The nextToken value returned from a ListServiceDeployments request indicating that more results are available to fulfill the request and further calls are needed. If you provided maxResults, it's possible the number of results is fewer than maxResults.
integer
The maximum number of service deployment results that ListServiceDeployments returned in paginated output. When this parameter is used, ListServiceDeployments only returns maxResults results in a single page along with a nextToken response element. The remaining results of the initial request can be seen by sending another ListServiceDeployments request with the returned nextToken value. This value can be between 1 and 100. If this parameter isn't used, then ListServiceDeployments returns up to 20 results and a nextToken value if applicable.
dict
Response Syntax
{
'serviceDeployments': [
{
'serviceDeploymentArn': 'string',
'serviceArn': 'string',
'clusterArn': 'string',
'startedAt': datetime(2015, 1, 1),
'createdAt': datetime(2015, 1, 1),
'finishedAt': datetime(2015, 1, 1),
'targetServiceRevisionArn': 'string',
'status': 'PENDING'|'SUCCESSFUL'|'STOPPED'|'STOP_REQUESTED'|'IN_PROGRESS'|'ROLLBACK_REQUESTED'|'ROLLBACK_IN_PROGRESS'|'ROLLBACK_SUCCESSFUL'|'ROLLBACK_FAILED',
'statusReason': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
serviceDeployments (list) --
An overview of the service deployment, including the following properties:
The ARN of the service deployment.
The ARN of the service being deployed.
The ARN of the cluster that hosts the service in the service deployment.
The time that the service deployment started.
The time that the service deployment completed.
The service deployment status.
Information about why the service deployment is in the current state.
The ARN of the service revision that is being deployed.
(dict) --
The service deployment properties that are retured when you call ListServiceDeployments.
This provides a high-level overview of the service deployment.
serviceDeploymentArn (string) --
The ARN of the service deployment.
serviceArn (string) --
The ARN of the service for this service deployment.
clusterArn (string) --
The ARN of the cluster that hosts the service.
startedAt (datetime) --
The time that the service deployment statred. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
createdAt (datetime) --
The time that the service deployment was created. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
finishedAt (datetime) --
The time that the service deployment completed. The format is yyyy-MM-dd HH:mm:ss.SSSSSS.
targetServiceRevisionArn (string) --
The ARN of the service revision being deplyed.
status (string) --
The status of the service deployment
statusReason (string) --
Information about why the service deployment is in the current status. For example, the circuit breaker detected a deployment failure.
nextToken (string) --
The nextToken value to include in a future ListServiceDeployments request. When the results of a ListServiceDeployments request exceed maxResults, this value can be used to retrieve the next page of results. This value is null when there are no more results to return.