AWS batch documentation change
Summary
Restructured documentation to introduce three compute environment update strategies (scaling, infrastructure, blue/green) with detailed guidance on selection criteria and implementation. Added sections about AMI update considerations and blue/green deployment methodology.
Security assessment
The changes primarily focus on update methodologies and operational best practices rather than addressing security vulnerabilities. While the documentation emphasizes proper management of AWS resources through approved APIs (which has security implications), there's no evidence of addressing a specific security vulnerability or weakness.
Diff
diff --git a/batch/latest/userguide/updating-compute-environments.md b/batch/latest/userguide/updating-compute-environments.md index 14bb7a418..a86da2146 100644 --- a//batch/latest/userguide/updating-compute-environments.md +++ b//batch/latest/userguide/updating-compute-environments.md @@ -5 +5 @@ -Updating AWS Fargate compute environmentsUpdating the AMI ID +Compute environment update strategiesChoosing the right update strategy @@ -7 +7 @@ Updating AWS Fargate compute environmentsUpdating the AMI ID -# Updating compute environments +# Update a compute environment in AWS Batch @@ -9 +9 @@ Updating AWS Fargate compute environmentsUpdating the AMI ID -After you create a compute environment that uses EC2 resources, you can update many of the settings of the compute environment directly. However, changing some of the settings requires that AWS Batch replace the instances in the compute environment. +AWS Batch provides multiple strategies for updating compute environments, each designed for specific update scenarios and requirements. These approaches use the same underlying update API but represent different prescriptive methods for managing updates effectively. You can manage these updates using the AWS Batch console or the AWS CLI. Understanding these strategies helps you choose the most appropriate method for your needs while minimizing disruption to your workloads. @@ -11,5 +11 @@ After you create a compute environment that uses EC2 resources, you can update m -###### Important - -AWS Batch creates and manages multiple AWS resources on your behalf and within your account, including Amazon EC2 Launch Templates, Amazon EC2 Auto Scaling Groups, Amazon EC2 Spot Fleets, and Amazon ECS Clusters. These managed resources are configured specifically to ensure optimal AWS Batch operation. Manually modifying these Batch-managed resources, unless explicitly stated in AWS Batch documentation, may result in unexpected behavior resulting in `INVALID` Compute Environment, suboptimal instance scaling behavior, delayed workload processing, or unexpected costs. These manual modifications can not be deterministically supported by the AWS Batch service. Always use the supported Batch APIs or the Batch console to manage your Compute Environments. - -## Updating AWS Fargate compute environments +This topic provides an overview of the available update strategies and guidance on when to use each approach. For detailed procedures, see the individual sections for each update strategy. @@ -17,5 +13 @@ AWS Batch creates and manages multiple AWS resources on your behalf and within y -For compute environments that use Fargate resources, you can update the following. - - * `securityGroupIds` - - * `subnets` +###### Important @@ -23 +15 @@ For compute environments that use Fargate resources, you can update the followin - * `desiredvCpus` +AWS Batch creates and manages multiple AWS resources on your behalf and within your account, including Amazon EC2 Launch Templates, Amazon EC2 Auto Scaling Groups, Amazon EC2 Spot Fleets, and Amazon ECS Clusters. These managed resources are configured specifically to ensure optimal AWS Batch operation. Manually modifying these AWS Batch-managed resources, unless explicitly stated in AWS Batch documentation, can result in unexpected behavior, including `INVALID` compute environments, suboptimal instance scaling behavior, delayed workload processing, or unexpected costs. These manual modifications can't be deterministically supported by the AWS Batch service. Always use the supported AWS Batch APIs or the AWS Batch console to manage your compute environments. @@ -25 +17 @@ For compute environments that use Fargate resources, you can update the followin - * `maxvCpus` +###### Topics @@ -27 +19 @@ For compute environments that use Fargate resources, you can update the followin - * `minvCpus` + * Compute environment update strategies @@ -28,0 +21 @@ For compute environments that use Fargate resources, you can update the followin + * Choosing the right update strategy @@ -29,0 +23 @@ For compute environments that use Fargate resources, you can update the followin + * [Perform scaling updates](./scaling-updates.html) @@ -30,0 +25 @@ For compute environments that use Fargate resources, you can update the followin + * [Perform infrastructure updates](./infrastructure-updates.html) @@ -32 +27 @@ For compute environments that use Fargate resources, you can update the followin -AWS Batch has two update mechanisms. The first is a scaling update where instances are added or removed from the compute environment. The second is an infrastructure update where the instances in the compute environment are replaced. An infrastructure update takes much longer than a scaling update. + * [Perform blue/green updates for compute environments](./blue-green-updates.html) @@ -34 +28,0 @@ AWS Batch has two update mechanisms. The first is a scaling update where instanc -If you update compute environments with AWS Batch, changing only these settings causes a scaling update: desired vCPUs (`desiredvCpus`), maximum vCPUs (`maxvCpus`), minimum vCPUs (`minvCpus`), service role (`serviceRole`), and state (`state`). @@ -36 +29,0 @@ If you update compute environments with AWS Batch, changing only these settings -###### Note @@ -38 +30,0 @@ If you update compute environments with AWS Batch, changing only these settings -When you update the `desiredvCpus` setting, the value must be between the `minvCpus` and `maxvCpus` values. @@ -40 +32 @@ When you update the `desiredvCpus` setting, the value must be between the `minvC -Additionally, the updated `desiredvCpus` value must be greater than or equal to the current `desiredvCpus` value. For more information, see [Error message when you update the desiredvCpus setting](./error-desired-vcpus-update.html). +## Compute environment update strategies @@ -42 +34 @@ Additionally, the updated `desiredvCpus` value must be greater than or equal to -If any of the following settings are changed in an [UpdateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) API action, AWS Batch initiates an infrastructure update. An infrastructure update requires that the service role is set to **AWSServiceRoleForBatch** (the default) and that the allocation strategy is `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`. `BEST_FIT` isn't supported. Except for service role, all of the settings that can be changed for a scaling update can also be changed for an infrastructure update. +When you use scaling or infrastructure updates your compute environment is updated in place. For the blue/green update strategy you are creating a new compute environment (green) and then migrating your workload from the old compute environment (blue) to the new compute environment (green). @@ -44 +36 @@ If any of the following settings are changed in an [UpdateComputeEnvironment](ht -###### Note +AWS Batch provides three different strategies for compute environment updates: @@ -46 +38 @@ If any of the following settings are changed in an [UpdateComputeEnvironment](ht -We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPACITY_OPTIMIZED` in most instances. +Scaling updates @@ -48 +39,0 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA -During an infrastructure update, the status of the compute environment changes to `UPDATING`. New instances are launched using the updated settings. New jobs are scheduled on the new instances. Jobs that are currently running are dispatched according to the infrastructure update policy. For more information, see [UpdateComputeEnvironment](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdateComputeEnvironment.html) and [UpdatePolicy](https://docs.aws.amazon.com/batch/latest/APIReference/API_UpdatePolicy.html) in the _AWS Batch API Reference_. @@ -50 +41 @@ During an infrastructure update, the status of the compute environment changes t -In the `UpdatePolicy` data type, consider the following scenarios: +Scaling updates adjust the capacity of your compute environment by adding or removing instances without replacing existing instances. This is the fastest update scenario and requires no downtime. Use scaling updates when you need to change capacity settings (vCPUs). These updates typically complete within minutes. @@ -52 +43 @@ In the `UpdatePolicy` data type, consider the following scenarios: -###### Note +Fargate updates are performed using the same procedures as scaling updates. For more information, see [Perform scaling updates](./scaling-updates.html). @@ -54 +45 @@ In the `UpdatePolicy` data type, consider the following scenarios: -In these scenarios, the following is true. When an instance is terminated, running jobs are stopped. By default, these jobs aren't retried. To retry one of these jobs after an instance is terminated, configure a job retry strategy. For more information, see [Automated job retries](./job_retries.html) in the _AWS Batch User Guide_. +Infrastructure updates @@ -56 +46,0 @@ In these scenarios, the following is true. When an instance is terminated, runni - * If the `terminateJobsOnUpdate` setting is set to `true`, running jobs are terminated during an infrastructure update. The `jobExecutionTimeoutMinutes` setting is ignored. @@ -58 +48 @@ In these scenarios, the following is true. When an instance is terminated, runni - * If the `terminateJobsOnUpdate` setting is set to `false`, jobs can run for additional time after the infrastructure update occurs. This additional time is configured in the `jobExecutionTimeoutMinutes` setting. By default, the `jobExecutionTimeoutMinutes` setting is 30 minutes. +Infrastructure updates replace instances in your compute environment with new instances that have updated settings. These updates require specific service role and allocation strategy configurations but provide minimal downtime, with running jobs potentially interrupted. Use infrastructure updates when you need to modify instance types, AMI configuration, networking settings, service role, environment state, or other infrastructure components. These updates typically complete in 10-30 minutes depending on job completion. @@ -59,0 +50 @@ In these scenarios, the following is true. When an instance is terminated, runni +For more information, see [Perform infrastructure updates](./infrastructure-updates.html). @@ -60,0 +52 @@ In these scenarios, the following is true. When an instance is terminated, runni +Blue/green updates @@ -63 +55 @@ In these scenarios, the following is true. When an instance is terminated, runni -As capacity becomes available in the compute environment, new instances are launched with the updated settings and jobs are started on the new instances. As all of the jobs complete on instances with the old settings, the old instances are terminated. What capacity becoming available means is that desired number of vCPUs is below the maximum number of vCPUs by at least as many vCPUs as required by the smallest instance type. +Blue/green updates create a new compute environment alongside your existing environment, allowing gradual workload transition with zero downtime. This approach provides the safest update path but requires running two environments temporarily. Use blue/green updates when you need zero downtime, want to test changes before full deployment, require quick rollback capability, or are using unsupported configurations for infrastructure updates. The time to complete is variable and controlled by you. @@ -65 +57 @@ As capacity becomes available in the compute environment, new instances are laun -###### Infrastructure updates +For more information, see [Perform blue/green updates for compute environments](./blue-green-updates.html). @@ -67 +59 @@ As capacity becomes available in the compute environment, new instances are laun -An infrastructure update is required to change some settings for a compute environment. If any of the following settings are changed, an infrastructure update is started: +## Choosing the right update strategy @@ -69 +61 @@ An infrastructure update is required to change some settings for a compute envir -###### Important +Use this decision guide to select the most appropriate update strategy for your needs: @@ -71 +63 @@ An infrastructure update is required to change some settings for a compute envir -The compute environment must use the **AWSServiceRoleForBatch** service-linked role to make changes that require an infrastructure update. +### Choose scaling updates when @@ -73 +65 @@ The compute environment must use the **AWSServiceRoleForBatch** service-linked r -If the compute environment uses a service-linked role, it can't be changed to use a regular IAM role. Likewise, if the compute environment has a regular IAM role, it can't be changed to use a service-linked role. Therefore, you can only perform infrastructure updates on compute environments that were created by using a service-linked role. +Choose the scaling update strategy when you only need to adjust compute capacity (vCPUs). Scaling updates are ideal when you need quick updates with no downtime and no infrastructure configuration changes are needed. @@ -75 +67 @@ If the compute environment uses a service-linked role, it can't be changed to us - * Allocation strategy (`allocationStrategy`, must be either `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`. If the original allocation strategy is `BEST_FIT`, infrastructure updates aren't supported.) +For detailed procedures, see [Perform scaling updates](./scaling-updates.html). @@ -77 +69 @@ If the compute environment uses a service-linked role, it can't be changed to us -###### Note +### Choose infrastructure updates when @@ -79 +71 @@ If the compute environment uses a service-linked role, it can't be changed to us -We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPACITY_OPTIMIZED` in most instances. +Choose the infrastructure update strategy when you need to modify instance types, AMI settings, service role, environment state, or networking configuration. Your environment must use the _AWSServiceRoleForBatch_ service-linked role and an allocation strategy of `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED`. Infrastructure updates work well when some job interruption is acceptable during the update and you want automatic updates to the latest Amazon ECS-optimized AMI. @@ -81 +73 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Bid percentage (`bidPercentage`) +For detailed procedures, see [Perform infrastructure updates](./infrastructure-updates.html). @@ -83 +75 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * EC2 configuration (`ec2Configuration`) +### Choose blue/green updates when @@ -85 +77 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Key pair (`ec2KeyPair`) +Choose the blue/green update strategy when zero downtime is required for your workloads or you need to test changes before transitioning production workloads. This approach is essential when quick rollback capability is important, your environment uses `BEST_FIT` allocation strategy, or your environment doesn't use the _AWSServiceRoleForBatch_ service-linked role. Blue/green updates are also the best choice when you're using custom AMIs that require manual updates or need to make major configuration changes. @@ -87 +79 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Image ID (`imageId`) +For detailed procedures, see [Perform blue/green updates for compute environments](./blue-green-updates.html). @@ -89 +81 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Instance role (`instanceRole`) +### AMI update considerations @@ -91 +83 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Instance types (`instanceTypes`) +AWS Batch can update to the latest Amazon ECS-optimized AMI during [infrastructure](./infrastructure-updates.html#infrastructure-updates.title) updates when all of these conditions are met: @@ -93 +85 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Launch template (`launchTemplate`) +###### Note @@ -95 +87 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Placement group (`placementGroup`) +After the infrastructure update has completed `updateToLatestImageVersion` is set to `false`. To initiate another update `updateToLatestImageVersion` has to be set to `true`. @@ -97 +89 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Security groups (`securityGroupIds`) + * The compute environment uses the _AWSServiceRoleForBatch_ service-linked role @@ -99 +91 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * VPC subnets (`subnets`) + * The allocation strategy is set to `BEST_FIT_PROGRESSIVE`, `SPOT_CAPACITY_OPTIMIZED`, or `SPOT_PRICE_CAPACITY_OPTIMIZED` @@ -101 +93 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * EC2 tags (`tags`) + * No AMI ID is explicitly specified in `imageId`, `imageIdOverride`, or launch template @@ -103 +95 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Compute environment type (`type`, can be one of `EC2` or `SPOT`) + * The `updateToLatestImageVersion` is set to `true` @@ -105 +96,0 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA - * Whether to update to the latest AMI that's supported by AWS Batch during an infrastructure update `updateToLatestImageVersion` @@ -108,0 +100 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA +### AMI updates using blue/green deployment @@ -110 +102 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA -## Updating the AMI ID +You must use blue/green deployment to update AMIs in these scenarios: @@ -112 +104 @@ We recommend that you use `SPOT_PRICE_CAPACITY_OPTIMIZED` rather than `SPOT_CAPA -During an infrastructure update, the compute environment's AMI ID might change, depending on whether AMIs are specified in any of these three settings. AMIs are specified in the `imageId` (in `computeResources`), `imageIdOverride` (in `ec2Configuration`), or the launch template specified in `launchTemplate`. Suppose that no AMI IDs are specified in any of those settings and the `updateToLatestImageVersion` setting is `true`. Then, the latest Amazon ECS optimized AMI supported by AWS Batch is used for any infrastructure update. + * When using a specific version of the Amazon ECS-optimized AMI @@ -114 +106 @@ During an infrastructure update, the compute environment's AMI ID might change, -If an AMI ID is specified in at least one of these settings, the update depends on which setting provided the AMI ID used before the update. When you create a compute environment, the priority for selecting an AMI ID is first the launch template, then the `imageId` setting, and finally the `imageIdOverride` setting. However, if the AMI ID that's used came from the launch template, updating either the `imageId` or `imageIdOverride` settings doesn't update the AMI ID. The only way to update an AMI ID selected from the launch template is to update the launch template. If the version parameter of the launch template is `$Default` or `$Latest`, the default or latest version of the specified launch template is evaluated. If a different AMI ID is selected by the default or the latest version of the launch template is selected, that AMI ID is used in the update. + * When the AMI ID is specified in any of: @@ -116 +108 @@ If an AMI ID is specified in at least one of these settings, the update depends -If the launch template was not used to select the AMI ID, the AMI ID that's specified in the `imageId` or `imageIdOverride` parameters is used. If both are specified, the AMI ID specified in the `imageIdOverride` parameter is used. + * Launch template (must update the template or remove it) @@ -118 +110 @@ If the launch template was not used to select the AMI ID, the AMI ID that's spec -Suppose that the compute environment uses an AMI ID specified by the `imageId`, `imageIdOverride`, or `launchTemplate` parameters, and you want to use the latest Amazon ECS optimized AMI supported by AWS Batch. Then, the update must remove the settings that provided AMI IDs. For `imageId`, this requires specifying an empty string for that parameter. For `imageIdOverride`, this requires specifying an empty string for the `ec2Configuration` parameter. + * The `imageId` parameter @@ -120 +112 @@ Suppose that the compute environment uses an AMI ID specified by the `imageId`, -If the AMI ID came from the launch template, you can change to the latest Amazon ECS optimized AMI that's supported by AWS Batch by either one of the following ways: + * The `imageIdOverride` parameter in EC2 configuration @@ -122 +114 @@ If the AMI ID came from the launch template, you can change to the latest Amazon - * Remove the launch template by specifying an empty string for the `launchTemplateId` or `launchTemplateName` parameter. This removes the entire launch template, rather than the AMI ID alone. + * When using the `BEST_FIT` allocation strategy (doesn't support infrastructure updates) @@ -124 +116 @@ If the AMI ID came from the launch template, you can change to the latest Amazon - * If the updated version of the launch template doesn't specify an AMI ID, the `updateToLatestImageVersion` parameter must be set to `true`. + * When not using the _AWSServiceRoleForBatch_ [service-linked role](./using-service-linked-roles-batch-general.html) @@ -135 +127 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Memory and vCPU considerations for AWS Batch on Amazon EKS +Instance type compute table @@ -137 +129 @@ Memory and vCPU considerations for AWS Batch on Amazon EKS -Fargate compute environments +Perform scaling updates