AWS cli documentation change
Summary
Updated deployment controller documentation with explicit security permissions reference
Security assessment
Added link to 'Permissions required for Lambda functions in blue/green deployments' guide. This documents security best practices but doesn't indicate a patched vulnerability.
Diff
diff --git a/cli/latest/reference/ecs/create-service.md b/cli/latest/reference/ecs/create-service.md index 1080a6dce..61c6f543e 100644 --- a//cli/latest/reference/ecs/create-service.md +++ b//cli/latest/reference/ecs/create-service.md @@ -15 +15 @@ - * [AWS CLI 2.27.50 Command Reference](../../index.html) » + * [AWS CLI 2.27.51 Command Reference](../../index.html) » @@ -79 +79 @@ There are two service scheduler strategies available: - * `DAEMON` \- The daemon scheduling strategy deploys exactly one task on each active container instance that meets all of the task placement constraints that you specify in your cluster. The service scheduler also evaluates the task placement constraints for running tasks. It also stops tasks that don’t meet the placement constraints. When using this strategy, you don’t need to specify a desired number of tasks, a task placement strategy, or use Service Auto Scaling policies. For more information, see [Service scheduler concepts](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) in the _Amazon Elastic Container Service Developer Guide_ . + * `DAEMON` \- The daemon scheduling strategy deploys exactly one task on each active container instance that meets all of the task placement constraints that you specify in your cluster. The service scheduler also evaluates the task placement constraints for running tasks. It also stops tasks that don’t meet the placement constraints. When using this strategy, you don’t need to specify a desired number of tasks, a task placement strategy, or use Service Auto Scaling policies. For more information, see [Amazon ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) in the _Amazon Elastic Container Service Developer Guide_ . @@ -83 +83,24 @@ 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](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html) . The default value for a replica service for `minimumHealthyPercent` is 100%. The default value for a daemon service for `minimumHealthyPercent` is 0%. +The deployment controller is the mechanism that determines how tasks are deployed for your service. The valid options are: + + * ECS When you create a service which uses the `ECS` deployment controller, you can choose between the following deployment strategies: + + * `ROLLING` : When you create a service which uses the _rolling update_ (`ROLLING` ) deployment strategy, the Amazon ECS service scheduler replaces the currently running tasks with new tasks. The number of tasks that Amazon ECS adds or removes from the service during a rolling update is controlled by the service deployment configuration. For more information, see [Deploy Amazon ECS services by replacing tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-ecs.html) in the _Amazon Elastic Container Service Developer Guide_ . Rolling update deployments are best suited for the following scenarios: + * Gradual service updates: You need to update your service incrementally without taking the entire service offline at once. + * Limited resource requirements: You want to avoid the additional resource costs of running two complete environments simultaneously (as required by blue/green deployments). + * Acceptable deployment time: Your application can tolerate a longer deployment process, as rolling updates replace tasks one by one. + * No need for instant roll back: Your service can tolerate a rollback process that takes minutes rather than seconds. + * Simple deployment process: You prefer a straightforward deployment approach without the complexity of managing multiple environments, target groups, and listeners. + * No load balancer requirement: Your service doesn’t use or require a load balancer, Application Load Balancer, Network Load Balancer, or Service Connect (which are required for blue/green deployments). + * Stateful applications: Your application maintains state that makes it difficult to run two parallel environments. + * Cost sensitivity: You want to minimize deployment costs by not running duplicate environments during deployment. + +Rolling updates are the default deployment strategy for services and provide a balance between deployment safety and resource efficiency for many common application scenarios. + + * `BLUE_GREEN` : A _blue/green_ deployment strategy (`BLUE_GREEN` ) is a release methodology that reduces downtime and risk by running two identical production environments called blue and green. With Amazon ECS blue/green deployments, you can validate new service revisions before directing production traffic to them. This approach provides a safer way to deploy changes with the ability to quickly roll back if needed. For more information, see [Amazon ECS blue/green deployments](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-blue-green.html) in the _Amazon Elastic Container Service Developer Guide_ . Amazon ECS blue/green deployments are best suited for the following scenarios: + * Service validation: When you need to validate new service revisions before directing production traffic to them + * Zero downtime: When your service requires zero-downtime deployments + * Instant roll back: When you need the ability to quickly roll back if issues are detected + * Load balancer requirement: When your service uses Application Load Balancer, Network Load Balancer, or Service Connect + * External Use a third-party deployment controller. + + * Blue/green deployment (powered by CodeDeploy) CodeDeploy installs an updated version of the application as a new replacement task set and reroutes production traffic from the original application task set to the replacement task set. The original task set is terminated after a successful deployment. Use this deployment controller to verify a new deployment of a service before sending production traffic to it. @@ -85 +107,0 @@ You can optionally specify a deployment configuration for your service. The depl -If a service uses the `ECS` deployment controller, the minimum healthy percent represents a lower limit on the number of tasks in a service that must remain in the `RUNNING` state during a deployment. Specifically, it represents it as a percentage of your desired number of tasks (rounded up to the nearest integer). This happens when any of your container instances are in the `DRAINING` state if the service contains tasks using the EC2 launch type. Using this parameter, you can deploy without using additional cluster capacity. For example, if you set your service to have desired number of four tasks and a minimum healthy percent of 50%, the scheduler might stop two existing tasks to free up cluster capacity before starting two new tasks. If they’re in the `RUNNING` state, tasks for services that don’t use a load balancer are considered healthy . If they’re in the `RUNNING` state and reported as healthy by the load balancer, tasks for services that _do_ use a load balancer are considered healthy . The default value for minimum healthy percent is 100%. @@ -87 +108,0 @@ If a service uses the `ECS` deployment controller, the minimum healthy percent r -If a service uses the `ECS` deployment controller, the **maximum percent** parameter represents an upper limit on the number of tasks in a service that are allowed in the `RUNNING` or `PENDING` state during a deployment. Specifically, it represents it as a percentage of the desired number of tasks (rounded down to the nearest integer). This happens when any of your container instances are in the `DRAINING` state if the service contains tasks using the EC2 launch type. Using this parameter, you can define the deployment batch size. For example, if your service has a desired number of four tasks and a maximum percent 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 value for maximum percent is 200%. @@ -89 +109,0 @@ If a service uses the `ECS` deployment controller, the **maximum percent** param -If a service uses either the `CODE_DEPLOY` or `EXTERNAL` deployment controller types and tasks that use the EC2 launch type, the **minimum healthy percent** and **maximum percent** values are used only to define the lower and upper limit on the number of the tasks in the service that remain in the `RUNNING` state. This is while the container instances are in the `DRAINING` state. If the tasks in the service use the Fargate launch type, the minimum healthy percent and maximum percent values aren’t used. This is the case even if they’re currently visible when describing your service. @@ -96,0 +117,2 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/ecs-20 +`create-service` uses document type values. Document types follow the JSON data model where valid values are: strings, numbers, booleans, null, arrays, and objects. For command input, options and nested parameters that are labeled with the type `document` must be provided as JSON. Shorthand syntax does not support document types. + @@ -234,0 +257,20 @@ See also: [AWS API Documentation](https://docs.aws.amazon.com/goto/WebAPI/ecs-20 +>> +>> advancedConfiguration -> (structure) +>> +>>> The advanced settings for the load balancer used in blue/green deployments. Specify the alternate target group, listener rules, and IAM role required for traffic shifting during blue/green deployments. +>>> +>>> alternateTargetGroupArn -> (string) +>>> +>>>> The Amazon Resource Name (ARN) of the alternate target group for Amazon ECS blue/green deployments. +>>> +>>> productionListenerRule -> (string) +>>> +>>>> The Amazon Resource Name (ARN) that identifies the production listener rule for routing production traffic. +>>> +>>> testListenerRule -> (string) +>>> +>>>> The Amazon Resource Name (ARN) that identifies the test listener rule or listener for routing test traffic. +>>> +>>> roleArn -> (string) +>>> +>>>> The Amazon Resource Name (ARN) of the IAM role that grants Amazon ECS permission to call the Elastic Load Balancing APIs for you. @@ -239 +281 @@ Shorthand Syntax: - targetGroupArn=string,loadBalancerName=string,containerName=string,containerPort=integer ... + targetGroupArn=string,loadBalancerName=string,containerName=string,containerPort=integer,advancedConfiguration={alternateTargetGroupArn=string,productionListenerRule=string,testListenerRule=string,roleArn=string} ... @@ -250 +292,7 @@ JSON Syntax: - "containerPort": integer + "containerPort": integer, + "advancedConfiguration": { + "alternateTargetGroupArn": "string", + "productionListenerRule": "string", + "testListenerRule": "string", + "roleArn": "string" + } @@ -496,0 +545,8 @@ JSON Syntax: +> +> strategy -> (string) +> +>> The deployment strategy for the service. Choose from these valid values: +>> +>> * `ROLLING` \- When you create a service which uses the rolling update (`ROLLING` ) deployment strategy, the Amazon ECS service scheduler replaces the currently running tasks with new tasks. The number of tasks that Amazon ECS adds or removes from the service during a rolling update is controlled by the service deployment configuration. +>> * `BLUE_GREEN` \- A blue/green deployment strategy (`BLUE_GREEN` ) is a release methodology that reduces downtime and risk by running two identical production environments called blue and green. With Amazon ECS blue/green deployments, you can validate new service revisions before directing production traffic to them. This approach provides a safer way to deploy changes with the ability to quickly roll back if needed. +>> @@ -498,4 +554,42 @@ JSON Syntax: -Shorthand Syntax: - - - deploymentCircuitBreaker={enable=boolean,rollback=boolean},maximumPercent=integer,minimumHealthyPercent=integer,alarms={alarmNames=[string,string],rollback=boolean,enable=boolean} +> +> bakeTimeInMinutes -> (integer) +> +>> The duration when both blue and green service revisions are running simultaneously after the production traffic has shifted. +>> +>> You must provide this parameter when you use the `BLUE_GREEN` deployment strategy. +> +> lifecycleHooks -> (list) +> +>> An array of deployment lifecycle hook objects to run custom logic at specific stages of the deployment lifecycle. These hooks allow you to run custom logic at key points during the deployment process. +>> +>> (structure) +>> +>>> A deployment lifecycle hook runs custom logic at specific stages of the deployment process. Currently, you can use Lambda functions as hook targets. +>>> +>>> hookTargetArn -> (string) +>>> +>>>> The Amazon Resource Name (ARN) of the hook target. Currently, only Lambda function ARNs are supported. +>>>> +>>>> You must provide this parameter when configuring a deployment lifecycle hook. +>>> +>>> roleArn -> (string) +>>> +>>>> The Amazon Resource Name (ARN) of the IAM role that grants Amazon ECS permission to call Lambda functions on your behalf. +>>>> +>>>> For more information, see [Permissions required for Lambda functions in Amazon ECS blue/green deployments](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/blue-green-permissions.html) in the*Amazon Elastic Container Service Developer Guide* . +>>> +>>> lifecycleStages -> (list) +>>> +>>>> The lifecycle stages at which to run the hook. Choose from these valid values: +>>>> +>>>> * RECONCILE_SERVICE This stage only happens when you start a new service deployment with more than 1 service revision in an ACTIVE state. You can use a lifecycle hook for this stage. +>>>> * PRE_SCALE_UP The green service revision has not started. The blue service revision is handling 100% of the production traffic. There is no test traffic. You can use a lifecycle hook for this stage. +>>>> * SCALE_UP The time when the green service revision scales up to 100% and launches new tasks. The green service revision is not serving any traffic at this point. You can’t use a lifecycle hook for this stage. +>>>> * POST_SCALE_UP The green service revision has started. The blue service revision is handling 100% of the production traffic. There is no test traffic. You can use a lifecycle hook for this stage. +>>>> * TEST_TRAFFIC_SHIFT The blue and green service revisions are running. The blue service revision handles 100% of the production traffic. The green service revision is migrating from 0% to 100% of test traffic. You can use a lifecycle hook for this stage. +>>>> * POST_TEST_TRAFFIC_SHIFT The test traffic shift is complete. The green service revision handles 100% of the test traffic. You can use a lifecycle hook for this stage. +>>>> * PRODUCTION_TRAFFIC_SHIFT Production traffic is shifting to the green service revision. The green service revision is migrating from 0% to 100% of production traffic. You can use a lifecycle hook for this stage. +>>>> * POST_PRODUCTION_TRAFFIC_SHIFT The production traffic shift is complete. Yes +>>>> * BAKE_TIME The duration when both blue and green service revisions are running simultaneously. You can’t use a lifecycle hook for this stage. +>>>> * CLEAN_UP The blue service revision has completely scaled down to 0 running tasks. The green service revision is now the production service revision after this stage. You can’t use a lifecycle hook for this stage. +>>>> @@ -502,0 +597,8 @@ Shorthand Syntax: +>>>> +>>>> You must provide this parameter when configuring a deployment lifecycle hook. +>>>> +>>>> (string) +>>> +>>> hookDetails -> (document) +>>> +>>>> Optionally provide details about the hook. Use this field to pass custom parameters to your hook target (such as a Lambda function). @@ -517,0 +620,9 @@ JSON Syntax: + }, + "strategy": "ROLLING"|"BLUE_GREEN", + "bakeTimeInMinutes": integer, + "lifecycleHooks": [ + { + "hookTargetArn": "string", + "roleArn": "string", + "lifecycleStages": ["RECONCILE_SERVICE"|"PRE_SCALE_UP"|"POST_SCALE_UP"|"TEST_TRAFFIC_SHIFT"|"POST_TEST_TRAFFIC_SHIFT"|"PRODUCTION_TRAFFIC_SHIFT"|"POST_PRODUCTION_TRAFFIC_SHIFT", ...], + "hookDetails": {...} @@ -518,0 +630,2 @@ JSON Syntax: + ... + ] @@ -691 +804 @@ JSON Syntax: ->> There are three deployment controller types available: +>> The deployment controller is the mechanism that determines how tasks are deployed for your service. The valid options are: @@ -693 +806 @@ JSON Syntax: ->>> ECS +>> * ECS When you create a service which uses the `ECS` deployment controller, you can choose between the following deployment strategies: @@ -695 +808,9 @@ JSON Syntax: ->> The rolling update (`ECS` ) deployment type involves replacing the current running version of the container with the latest version. The number of containers Amazon ECS adds or removes from the service during a rolling update is controlled by adjusting the minimum and maximum number of healthy tasks allowed during a service deployment, as specified in the [DeploymentConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DeploymentConfiguration.html) . +>> * `ROLLING` : When you create a service which uses the _rolling update_ (`ROLLING` ) deployment strategy, the Amazon ECS service scheduler replaces the currently running tasks with new tasks. The number of tasks that Amazon ECS adds or removes from the service during a rolling update is controlled by the service deployment configuration. Rolling update deployments are best suited for the following scenarios: +>> * Gradual service updates: You need to update your service incrementally without taking the entire service offline at once. +>> * Limited resource requirements: You want to avoid the additional resource costs of running two complete environments simultaneously (as required by blue/green deployments). +>> * Acceptable deployment time: Your application can tolerate a longer deployment process, as rolling updates replace tasks one by one. +>> * No need for instant roll back: Your service can tolerate a rollback process that takes minutes rather than seconds. +>> * Simple deployment process: You prefer a straightforward deployment approach without the complexity of managing multiple environments, target groups, and listeners. +>> * No load balancer requirement: Your service doesn’t use or require a load balancer, Application Load Balancer, Network Load Balancer, or Service Connect (which are required for blue/green deployments). +>> * Stateful applications: Your application maintains state that makes it difficult to run two parallel environments. +>> * Cost sensitivity: You want to minimize deployment costs by not running duplicate environments during deployment. @@ -697 +818 @@ JSON Syntax: ->> For more information about rolling deployments, see [Deploy Amazon ECS services by replacing tasks](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-ecs.html) in the _Amazon Elastic Container Service Developer Guide_ . +>> Rolling updates are the default deployment strategy for services and provide a balance between deployment safety and resource efficiency for many common application scenarios. @@ -699 +820,6 @@ JSON Syntax: ->>> CODE_DEPLOY +>> * `BLUE_GREEN` : A _blue/green_ deployment strategy (`BLUE_GREEN` ) is a release methodology that reduces downtime and risk by running two identical production environments called blue and green. With Amazon ECS blue/green deployments, you can validate new service revisions before directing production traffic to them. This approach provides a safer way to deploy changes with the ability to quickly roll back if needed. Amazon ECS blue/green deployments are best suited for the following scenarios: +>> * Service validation: When you need to validate new service revisions before directing production traffic to them +>> * Zero downtime: When your service requires zero-downtime deployments +>> * Instant roll back: When you need the ability to quickly roll back if issues are detected +>> * Load balancer requirement: When your service uses Application Load Balancer, Network Load Balancer, or Service Connect +>> * External Use a third-party deployment controller. @@ -701 +827 @@ JSON Syntax: ->> The blue/green (`CODE_DEPLOY` ) deployment type uses the blue/green deployment model powered by CodeDeploy, which allows you to verify a new deployment of a service before sending production traffic to it. +>> * Blue/green deployment (powered by CodeDeploy) CodeDeploy installs an updated version of the application as a new replacement task set and reroutes production traffic from the original application task set to the replacement task set. The original task set is terminated after a successful deployment. Use this deployment controller to verify a new deployment of a service before sending production traffic to it. @@ -703 +828,0 @@ JSON Syntax: ->> For more information about blue/green deployments, see [Validate the state of an Amazon ECS service before deployment](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-bluegreen.html) in the _Amazon Elastic Container Service Developer Guide_ . @@ -705,5 +830 @@ JSON Syntax: ->>> EXTERNAL ->> ->> The external (`EXTERNAL` ) deployment type enables you to use any third-party deployment controller for full control over the deployment process for an Amazon ECS service. ->> ->> For more information about external deployments, see [Deploy Amazon ECS services using a third-party controller](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-type-external.html) in the _Amazon Elastic Container Service Developer Guide_ . + @@ -787 +908 @@ JSON Syntax: -> When you use Amazon ECS managed tags, you need to set the `propagateTags` request parameter. +> When you use Amazon ECS managed tags, you must set the `propagateTags` request parameter. @@ -875,0 +997,20 @@ JSON Syntax: