update_service¶
Operation¶
async
¶
update_service(input: UpdateServiceInput, plugins: list[Plugin] | None = None) -> UpdateServiceOutput
Modifies the parameters of a service.
Note
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 (ECS) you can update the desired
count, deployment configuration, network configuration, load balancers,
service registries, enable ECS managed tags option, propagate tags
option, task placement constraints and strategies, and task definition.
When you update any of these parameters, Amazon ECS starts new tasks
with the new configuration.
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 information, see Amazon EBS
volumes
in the Amazon Elastic Container Service Developer Guide. You can
update your volume configurations and trigger a new deployment.
volumeConfigurations is only supported for REPLICA service and not
DAEMON service. If you leave volumeConfigurations null, it doesn't
trigger a new deployment. For more information on volumes, see Amazon
EBS
volumes
in the Amazon Elastic Container Service Developer Guide.
For services using the blue/green (CODE_DEPLOY) deployment controller,
only the desired count, deployment configuration, health check grace
period, task placement constraints and strategies, enable ECS managed
tags option, and propagate tags can be updated using this API. If the
network configuration, platform version, task definition, or load
balancer need to be updated, create a new CodeDeploy deployment. For
more information, see
CreateDeployment
in the CodeDeploy API Reference.
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 desiredCount parameter.
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 information, 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.
Note
If your updated Docker image uses the same tag as what is in the
existing task definition for your service (for example,
my_image:latest), you don't need to create a new revision of your
task definition. You can update the service using the
forceNewDeployment option. The new tasks launched by the deployment
pull the current image/tag combination from your repository when they
start.
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,
minimumHealthyPercent and maximumPercent, to determine the
deployment strategy.
-
If
minimumHealthyPercentis below 100%, the scheduler can ignoredesiredCounttemporarily during a deployment. For example, ifdesiredCountis four tasks, a minimum of 50% allows the scheduler to stop two existing tasks before starting two new tasks. Tasks for services that don't use a load balancer are considered healthy if they're in theRUNNINGstate. Tasks for services that use a load balancer are considered healthy if they're in theRUNNINGstate and are reported as healthy by the load balancer. -
The
maximumPercentparameter represents an upper limit on the number of running tasks during a deployment. You can use it to define the deployment batch size. For example, ifdesiredCountis four tasks, a maximum of 200% starts four new tasks before stopping the four older tasks (provided that the cluster resources required to do this are available).
When
UpdateService
stops a task during a deployment, the equivalent of docker stop is
issued to the containers running in the task. This results in a
SIGTERM and a 30-second timeout. After this, SIGKILL is sent and the
containers are forcibly stopped. If the container handles the SIGTERM
gracefully and exits within 30 seconds from receiving it, no SIGKILL
is sent.
When the service scheduler launches new tasks, it determines task placement in your cluster with the following logic.
-
Determine which of the container instances in your cluster can support your service's task definition. For example, they have the required CPU, memory, ports, and container instance attributes.
-
By default, the service scheduler attempts to balance tasks across Availability Zones in this manner even though you can choose a different placement strategy.
-
Sort the valid container instances by the fewest number of running tasks for this service in the same Availability Zone as the instance. For example, if zone A has one running service task and zones B and C each have zero, valid container instances in either zone B or C are considered optimal for placement.
-
Place the new service task on a valid container instance in an optimal Availability Zone (based on the previous steps), favoring container instances with the fewest number of running tasks for this service.
When the service scheduler stops running tasks, it attempts to maintain balance across the Availability Zones in your cluster using the following logic:
-
Sort the container instances by the largest number of running tasks for this service in the same Availability Zone as the instance. For example, if zone A has one running service task and zones B and C each have two, container instances in either zone B or C are considered optimal for termination.
-
Stop the task on a container instance in an optimal Availability Zone (based on the previous steps), favoring container instances with the largest number of running tasks for this service.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input
|
UpdateServiceInput
|
An instance of |
required |
plugins
|
list[Plugin] | None
|
A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations. |
None
|
Returns:
| Type | Description |
|---|---|
UpdateServiceOutput
|
An instance of |
Input¶
dataclass
¶
Bases: _SerdeShape
Attributes¶
class-attribute
instance-attribute
¶
availability_zone_rebalancing: str | None = ...
Indicates whether to use Availability Zone rebalancing for the service.
For more information, see Balancing an Amazon ECS service across Availability Zones in the Amazon Elastic Container Service Developer Guide .
The default behavior of AvailabilityZoneRebalancing differs between
create and update requests:
-
For create service requests, when no value is specified for
AvailabilityZoneRebalancing, Amazon ECS defaults the value toENABLED. -
For update service requests, when no value is specified for
AvailabilityZoneRebalancing, Amazon ECS defaults to the existing service'sAvailabilityZoneRebalancingvalue. If the service never had anAvailabilityZoneRebalancingvalue set, Amazon ECS treats this asDISABLED.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
capacity_provider_strategy: list[CapacityProviderStrategyItem] | None = ...
The details of a capacity provider strategy. You can set a capacity provider when you create a cluster, run a task, or update a service.
Note
If you want to use Amazon ECS Managed Instances, you must use the
capacityProviderStrategy request parameter.
When you use Fargate, the capacity providers are FARGATE or
FARGATE_SPOT.
When you use Amazon EC2, the capacity providers are Auto Scaling groups.
You can change capacity providers for rolling deployments and blue/green deployments.
The following list provides the valid transitions:
-
Update the Fargate launch type to an Auto Scaling group capacity provider.
-
Update the Amazon EC2 launch type to a Fargate capacity provider.
-
Update the Fargate capacity provider to an Auto Scaling group capacity provider.
-
Update the Amazon EC2 capacity provider to a Fargate capacity provider.
-
Update the Auto Scaling group or Fargate capacity provider back to the launch type.
Pass an empty list in the capacityProviderStrategy parameter.
For information about Amazon Web Services CDK considerations, see Amazon Web Services CDK considerations.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
cluster: str | None = ...
The short name or full Amazon Resource Name (ARN) of the cluster that your service runs on. If you do not specify a cluster, the default cluster is assumed.
You can't change the cluster name.
class-attribute
instance-attribute
¶
Optional deployment parameters that control how many tasks run during the deployment and the ordering of stopping and starting tasks.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
The deployment controller to use for the service.
class-attribute
instance-attribute
¶
desired_count: int | None = ...
The number of instantiations of the task to place and keep running in your service.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
enable_ecs_managed_tags: bool | None = ...
Determines whether to turn on Amazon ECS managed tags for the tasks in the service. For more information, see Tagging Your Amazon ECS Resources in the Amazon Elastic Container Service Developer Guide.
Only tasks launched after the update will reflect the update. To update
the tags on all tasks, set forceNewDeployment to true, so that
Amazon ECS starts new tasks with the updated tags.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
enable_execute_command: bool | None = ...
If true, this enables execute command functionality on all task
containers.
If you do not want to override the value that was set when the service
was created, you can set this to null when performing this action.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
force_new_deployment: bool = ...
Determines whether to force a new deployment of the service. By default,
deployments aren't forced. You can use this option to start a new
deployment with no service definition changes. For example, you can
update a service's tasks to use a newer Docker image with the same
image/tag combination (my_image:latest) or to roll Fargate tasks onto
a newer platform version.
class-attribute
instance-attribute
¶
gateway_connectors: list[GatewayConnector] | None = ...
The updated set of gateway connectors that connect the service to a gateway ingress path. A service supports no more than one gateway connector.
class-attribute
instance-attribute
¶
health_check_grace_period_seconds: int | None = ...
The period of time, in seconds, that the Amazon ECS service scheduler
ignores unhealthy Elastic Load Balancing, VPC Lattice, and container
health checks after a task has first started. If you don't specify a
health check grace period value, the default value of 0 is used. If
you don't use any of the health checks, then
healthCheckGracePeriodSeconds is unused.
If your service's tasks take a while to start and respond to health checks, you can specify a health check grace period of up to 2,147,483,647 seconds (about 69 years). During that time, the Amazon ECS service scheduler ignores health check status. This grace period can prevent the service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.
If your service has more running tasks than desired, unhealthy tasks in the grace period might be stopped to reach the desired count.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
load_balancers: list[LoadBalancer] | None = ...
Note
You must have a service-linked role when you update this property
A list of Elastic Load Balancing load balancer objects. It contains the load balancer name, the container name, and the container port to access from the load balancer. The container name is as it appears in a container definition.
When you add, update, or remove a load balancer configuration, Amazon ECS starts new tasks with the updated Elastic Load Balancing configuration, and then stops the old tasks when the new tasks are running.
For services that use rolling updates, you can add, update, or remove Elastic Load Balancing target groups. You can update from a single target group to multiple target groups and from multiple target groups to a single target group.
For services that use blue/green deployments, you can update Elastic
Load Balancing target groups by using
CreateDeployment
through CodeDeploy. Note that multiple target groups are not supported
for blue/green deployments. For more information see Register multiple
target groups with a
service
in the Amazon Elastic Container Service Developer Guide.
For services that use the external deployment controller, you can add, update, or remove load balancers by using CreateTaskSet. Note that multiple target groups are not supported for external deployments. For more information see Register multiple target groups with a service in the Amazon Elastic Container Service Developer Guide.
You can remove existing loadBalancers by passing an empty list.
This parameter triggers a new service deployment.
class-attribute
instance-attribute
¶
The optional monitoring configuration for the service, which defines the
resolution for the service-level CPUUtilization and
MemoryUtilization Amazon CloudWatch metrics. When not specified,
Amazon ECS uses the default resolution of 60 seconds.
class-attribute
instance-attribute
¶
An object representing the network configuration for the service.
This parameter triggers a new service deployment.
class-attribute
instance-attribute
¶
placement_constraints: list[PlacementConstraint] | None = ...
An array of task placement constraint objects to update the service to use. If no value is specified, the existing placement constraints for the service will remain unchanged. If this value is specified, it will override any existing placement constraints defined for the service. To remove all existing placement constraints, specify an empty array.
You can specify a maximum of 10 constraints for each task. This limit includes constraints in the task definition and those specified at runtime.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
placement_strategy: list[PlacementStrategy] | None = ...
The task placement strategy objects to update the service to use. If no value is specified, the existing placement strategy for the service will remain unchanged. If this value is specified, it will override the existing placement strategy defined for the service. To remove an existing placement strategy, specify an empty object.
You can specify a maximum of five strategy rules for each service.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
platform_version: str | None = ...
The platform version that your tasks in the service run on. A platform
version is only specified for tasks using the Fargate launch type. If a
platform version is not specified, the LATEST platform version is
used. For more information, see Fargate Platform
Versions
in the Amazon Elastic Container Service Developer Guide.
This parameter triggers a new service deployment.
class-attribute
instance-attribute
¶
propagate_tags: str | None = ...
Determines whether to propagate the tags from the task definition or the service to the task. If no value is specified, the tags aren't propagated.
Only tasks launched after the update will reflect the update. To update
the tags on all tasks, set forceNewDeployment to true, so that
Amazon ECS starts new tasks with the updated tags.
This parameter doesn't trigger a new service deployment.
class-attribute
instance-attribute
¶
service: str | None = ...
The name of the service to update.
class-attribute
instance-attribute
¶
The configuration for this service to discover and connect to services, and be discovered by, and connected from, other services within a namespace.
Tasks that run in a namespace can use short names to connect to services in the namespace. Tasks can connect to services across all of the clusters in the namespace. Tasks connect through a managed proxy container that collects logs and metrics for increased visibility. Only the tasks that Amazon ECS services create are supported with Service Connect. For more information, see Service Connect in the Amazon Elastic Container Service Developer Guide.
This parameter triggers a new service deployment.
class-attribute
instance-attribute
¶
service_registries: list[ServiceRegistry] | None = ...
Note
You must have a service-linked role when you update this property.
For more information about the role see the CreateService request
parameter
role
.
The details for the service discovery registries to assign to this service. For more information, see Service Discovery.
When you add, update, or remove the service registries configuration, Amazon ECS starts new tasks with the updated service registries configuration, and then stops the old tasks when the new tasks are running.
You can remove existing serviceRegistries by passing an empty list.
This parameter triggers a new service deployment.
class-attribute
instance-attribute
¶
task_definition: str | None = ...
The family and revision (family:revision) or full ARN of the task
definition to run in your service. If a revision is not specified, the
latest ACTIVE revision is used. If you modify the task definition with
UpdateService, Amazon ECS spawns a task with the new version of the
task definition and then stops an old task after the new version is
running.
This parameter triggers a new service deployment.
class-attribute
instance-attribute
¶
volume_configurations: list[ServiceVolumeConfiguration] | None = ...
The details of the volume that was configuredAtLaunch. You can
configure the size, volumeType, IOPS, throughput, snapshot and
encryption in
ServiceManagedEBSVolumeConfiguration.
The name of the volume must match the name from the task definition.
If set to null, no new deployment is triggered. Otherwise, if this
configuration differs from the existing one, it triggers a new
deployment.
This parameter triggers a new service deployment.
Output¶
dataclass
¶
Bases: _SerdeShape
Attributes¶
class-attribute
instance-attribute
¶
Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.
class-attribute
instance-attribute
¶
The full description of your service following the update call.
The response includes a lifecycleHookDetails field, which is an empty
array when the service is created or updated. The values are populated
when a lifecycle hook executes and are available as part of the service
deployment details
(DescribeServiceDeployments).