fix(batch): undeprecate useOptimalInstanceClasses property (#36353)

### Issue # (if applicable)

Closes #36291.

### Reason for this change

The `useOptimalInstanceClasses` property was deprecated in v2.220 in favor of `defaultInstanceClasses`, but there is no way to exclude the `optimal` instance type using `defaultInstanceClasses` alone. Users who want to specify only custom instance types (e.g., R4 only) without `optimal` being automatically added have no non-deprecated path forward.

Setting `defaultInstanceClasses: []` (empty array) does not prevent `optimal` from being added because the current logic treats an empty array the same as `undefined`.

### Description of changes

- Removed `@deprecated` annotation from `useOptimalInstanceClasses` property
- Updated README to remove the deprecation warning and reorganized the "Choosing Your Instance Types" section with:
  - Clear subsections for each use case (Default Instance Classes, Specific Instance Types Only, Optimal Instance Classes)
  - A configuration reference table for quick lookup
  - Example showing how to use `useOptimalInstanceClasses: false` to exclude `optimal`

#### Alternatives considered

Three options were discussed in #36291:

1. **Remove deprecation** (this PR) - Restores `useOptimalInstanceClasses` as a non-deprecated property
2. **Treat empty `defaultInstanceClasses: []` as "exclude all defaults"** - Would introduces implicit behavior
3. **Change default behavior** - Breaking change, not acceptable

Option 1 was chosen because:
- Minimal code change (documentation only)
- No risk of breaking existing users
- `useOptimalInstanceClasses` provides explicit, clear control that `defaultInstanceClasses` cannot fully replace

### Describe any new or updated permissions being added

N/A

### Description of how you validated changes

Existing tests

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: badmintoncryer

packages/aws-cdk-lib/aws-batch/README.md

@@ -65,68 +65,88 @@ For stateful or otherwise non-interruption-tolerant workflows, omit `spot` or se
 
 #### Choosing Your Instance Types
 
-Batch allows you to choose most up-to-date instance classes based on your region.
-This example configures your `ComputeEnvironment` to use only ARM64 instance:
+There are several ways to configure instance types for your compute environment:
+
+##### Using Default Instance Classes (Recommended)
+
+AWS Batch provides default instance classes that automatically select cost-effective, up-to-date instances based on your region.
+This is the recommended approach for new projects:
 
 ```ts
-const vpc = new ec2.Vpc(this, 'VPC');
+const vpc = new ec2.Vpc(this, 'Vpc');
 
-new batch.ManagedEc2EcsComputeEnvironment(this, 'myEc2ComputeEnv', {
+// Use ARM64 instances (e.g., m6g, c6g, r6g, c7g families)
+new batch.ManagedEc2EcsComputeEnvironment(this, 'Arm64Ec2ComputeEnv', {
   vpc,
   defaultInstanceClasses: [batch.DefaultInstanceClass.ARM64],
 });
-```
-
-This example configures your `ComputeEnvironment` to use only the `M5AD.large` instance:
-
-```ts
-const vpc = new ec2.Vpc(this, 'VPC');
 
-new batch.ManagedEc2EcsComputeEnvironment(this, 'myEc2ComputeEnv', {
+// Use x86_64 instances (e.g., m6i, c6i, r6i, c7i families)
+new batch.ManagedEc2EcsComputeEnvironment(this, 'X86_64Ec2ComputeEnv', {
   vpc,
-  instanceTypes: [ec2.InstanceType.of(ec2.InstanceClass.M5AD, ec2.InstanceSize.LARGE)],
+  defaultInstanceClasses: [batch.DefaultInstanceClass.X86_64],
 });
 ```
 
-Batch allows you to specify only the instance class and to let it choose the size, which you can do like this:
+The `default_x86_64` and `default_arm64` categories are dynamically updated by AWS as new instance families become available in your region.
+
+##### Using Specific Instance Types Only
+
+To use only specific instance types without any automatic defaults, set `useOptimalInstanceClasses: false`:
 
 ```ts
-const vpc = new ec2.Vpc(this, 'VPC');
+const vpc = new ec2.Vpc(this, 'Vpc');
 
-declare const computeEnv: batch.IManagedEc2EcsComputeEnvironment
-computeEnv.addInstanceClass(ec2.InstanceClass.M5AD);
-// Or, specify it on the constructor:
-new batch.ManagedEc2EcsComputeEnvironment(this, 'myEc2ComputeEnv', {
+// Use only R4 instance class (Batch chooses the size)
+new batch.ManagedEc2EcsComputeEnvironment(this, 'R4Ec2ComputeEnv', {
   vpc,
+  useOptimalInstanceClasses: false,
   instanceClasses: [ec2.InstanceClass.R4],
 });
+
+// Use only a specific instance type
+new batch.ManagedEc2EcsComputeEnvironment(this, 'M5AdLargeEc2ComputeEnv', {
+  vpc,
+  useOptimalInstanceClasses: false,
+  instanceTypes: [ec2.InstanceType.of(ec2.InstanceClass.M5AD, ec2.InstanceSize.LARGE)],
+});
 ```
 
-> [!WARNING] 
-> `useOptimalInstanceClasses` is deprecated! Use `defaultInstanceClasses` instead.
+##### Using Optimal Instance Classes
+
+By default, `useOptimalInstanceClasses` is `true`, which adds the `optimal` instance type.
+
+**Note**: Since November 2025, `optimal` behaves the same as `default_x86_64` and is dynamically updated as AWS introduces new instance families. Both options automatically select cost-effective x86_64 instance types (from the m6i, c6i, r6i, and c7i families) based on your region.
 
-Unless you explicitly specify `useOptimalInstanceClasses: false`, this compute environment will use `'optimal'` instances,
-which tells Batch to pick an instance from the C4, M4, and R4 instance families.
-*Note*: Batch does not allow specifying instance types or classes with different architectures.
-For example, `InstanceClass.A1` cannot be specified alongside `'optimal'`,
-because `A1` uses ARM and `'optimal'` uses x86_64.
-You can specify both `'optimal'` alongside several different instance types in the same compute environment:
+You can combine this with additional instance types:
 
 ```ts
 declare const vpc: ec2.IVpc;
 
-const computeEnv = new batch.ManagedEc2EcsComputeEnvironment(this, 'myEc2ComputeEnv', {
-  instanceTypes: [ec2.InstanceType.of(ec2.InstanceClass.M5AD, ec2.InstanceSize.LARGE)],
-  useOptimalInstanceClasses: true, // default
+const computeEnv = new batch.ManagedEc2EcsComputeEnvironment(this, 'Ec2ComputeEnv', {
   vpc,
+  instanceTypes: [ec2.InstanceType.of(ec2.InstanceClass.M5AD, ec2.InstanceSize.LARGE)],
+  // useOptimalInstanceClasses: true (default)
 });
-// Note: this is equivalent to specifying
-computeEnv.addInstanceType(ec2.InstanceType.of(ec2.InstanceClass.M5AD, ec2.InstanceSize.LARGE));
-computeEnv.addInstanceClass(ec2.InstanceClass.C4);
-computeEnv.addInstanceClass(ec2.InstanceClass.M4);
-computeEnv.addInstanceClass(ec2.InstanceClass.R4);
+// Result: ['m5ad.large', 'optimal']
 ```
 
+##### Instance Type Configuration Reference
+
+| Goal | Configuration |
+|------|---------------|
+| Use latest x86_64 instances | `defaultInstanceClasses: [DefaultInstanceClass.X86_64]` or no configuration (default) |
+| Use latest ARM64 instances | `defaultInstanceClasses: [DefaultInstanceClass.ARM64]` |
+| Use only specific instance classes | `useOptimalInstanceClasses: false` + `instanceClasses: [...]` |
+| Use only specific instance types | `useOptimalInstanceClasses: false` + `instanceTypes: [...]` |
+| Use optimal + additional instances | `instanceClasses: [...]` or `instanceTypes: [...]` |
+
+**Note**: Batch does not allow specifying instance types or classes with different architectures.
+For example, `InstanceClass.A1` (ARM) cannot be specified alongside `optimal` (x86_64).
+When using ARM-based instances (e.g., Graviton), use `defaultInstanceClasses: [DefaultInstanceClass.ARM64]`, or set `useOptimalInstanceClasses: false` and explicitly specify ARM instance classes/types.
+
+**Note**: `useOptimalInstanceClasses` and `defaultInstanceClasses` cannot be used together.
+
 #### Configure AMIs
 
 You can configure Amazon Machine Images (AMIs). This example configures your `ComputeEnvironment` to use Amazon Linux 2023.

packages/aws-cdk-lib/aws-batch/lib/managed-compute-environment.ts

@@ -518,7 +518,6 @@ export interface ManagedEc2EcsComputeEnvironmentProps extends ManagedComputeEnvi
    * C4, M4, and R4 instance classes. You can specify other instance classes
    * (of the same architecture) in addition to the optimal instance classes.
    *
-   * @deprecated use defaultInstanceClasses instead
    * @default true
    */
   readonly useOptimalInstanceClasses?: boolean;
@@ -942,7 +941,6 @@ export interface ManagedEc2EksComputeEnvironmentProps extends ManagedComputeEnvi
    * C4, M4, and R4 instance classes. You can specify other instance classes
    * (of the same architecture) in addition to the optimal instance classes.
    *
-   * @deprecated use defaultInstanceClasses instead
    * @default true
    */
   readonly useOptimalInstanceClasses?: boolean;
@@ -1073,7 +1071,7 @@ export class ManagedEc2EksComputeEnvironment extends ManagedComputeEnvironmentBa
     addConstructMetadata(this, props);
 
     if (props.defaultInstanceClasses && props.useOptimalInstanceClasses) {
-      throw new ValidationError('cannot use `defaultInstanceClasses` with `useOptimalInstanceClasses`. Please remove deprecated `useOptimalInstanceClasses`', this);
+      throw new ValidationError('cannot use `defaultInstanceClasses` with `useOptimalInstanceClasses`.', this);
     }
 
     this.kubernetesNamespace = props.kubernetesNamespace;