(aws-opensearchservice): add useLatestServiceSoftwareForBlueGreen to Domain construct

[Swathi-Karanth]

Describe the feature

Amazon OpenSearch Service supports UseLatestServiceSoftwareForBlueGreen in the SoftwareUpdateOptions of AWS::OpenSearchService::Domain. This feature request adds that property to the L2 Domain construct so users can enable it directly, alongside the existing enableAutoSoftwareUpdate property.

Use Case

When enabled, the domain automatically uses the latest available service software during a blue/green deployment, rather than the currently pinned service software version. The property is already available in CloudFormation (AWS::OpenSearchService::Domain → SoftwareUpdateOptions.UseLatestServiceSoftwareForBlueGreen), but is not exposed by the CDK L2 Domain construct. Today users must fall back to an escape hatch (addPropertyOverride) to set it.

Proposed Solution

Add an optional useLatestServiceSoftwareForBlueGreen boolean to DomainProps, wired through to the L1 SoftwareUpdateOptions.useLatestServiceSoftwareForBlueGreen. The softwareUpdateOptions block is rendered when either enableAutoSoftwareUpdate or useLatestServiceSoftwareForBlueGreen is specified. The property is optional and defaults to off, so existing behavior is unchanged.

Other Information

Implementation is in progress in PR #38499 (currently in Draft — build is blocked on the L1 property not yet being available in @aws-cdk/aws-service-spec; the CloudFormation schema is public but has not yet been ingested).

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

AWS CDK Library version (aws-cdk-lib)

2.266.0

AWS CDK CLI version

2.1131.0

Environment details (OS name and version, etc.)

macOS 26.5.2 (arm64), Node.js v20.20.2

[pahud]

Thanks for the clear request and for opening #38499. I reproduced the gap using the reported aws-cdk-lib@2.266.0: useLatestServiceSoftwareForBlueGreen is absent from both DomainProps and the generated L1 SoftwareUpdateOptionsProperty. I also checked the published 2.267.0 L1, current main, the current aws-service-spec, and the generated property mixin; all still omit it, even though CloudFormation documents the property:

https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-opensearchservice-domain-softwareupdateoptions.md

For now, the raw override is the available workaround:

const cfnDomain = domain.node.defaultChild as opensearch.CfnDomain;
cfnDomain.addPropertyOverride(
  'SoftwareUpdateOptions.UseLatestServiceSoftwareForBlueGreen',
  true,
);

I verified that this synthesizes the expected property. Because CDK's validation schema is stale too, it currently emits CloudFormation-Validate::F3002; that warning can be acknowledged specifically until the schema update lands.

I reviewed draft PR #38499 as well. Its L2 wiring, README, and unit tests are directionally correct, and it now includes an integration-test source file. However, it cannot compile until the property is ingested into @aws-cdk/aws-service-spec and the L1 is regenerated. It also still needs the generated integration snapshot, a rebase, full build/test checks, and human review.

In my opinion the next step is the service-spec/L1 sync, followed by finishing #38499 on top of it. Contributions to either part would be very welcome.

[satyakigh]

Hello, this was fixed in aws-cloudformation/cloudformation-validate#324, can you please confirm whether this is still an issue with the latest cdk release?

[pahud]

Until Domain exposes this as an L2 prop, the CDK Mixins mechanism (GA in aws-cdk-lib) gives a clean, reusable way to set SoftwareUpdateOptions.UseLatestServiceSoftwareForBlueGreen today — the property already exists on the L1 CfnDomain.

Verified with aws-cdk-lib@2.270.0 (compiles under strict TS, synthesizes, and the property appears on the AWS::OpenSearchService::Domain resource):

import { Mixin, Mixins } from 'aws-cdk-lib';
import { IConstruct } from 'constructs';
import * as opensearch from 'aws-cdk-lib/aws-opensearchservice';

class DomainSoftwareUpdateOptions extends Mixin {
  constructor(private readonly options: opensearch.CfnDomain.SoftwareUpdateOptionsProperty) {
    super();
  }
  supports(construct: IConstruct): boolean {
    return opensearch.CfnDomain.isCfnDomain(construct);
  }
  applyTo(construct: IConstruct): void {
    if (!this.supports(construct)) return;
    const domain = construct as opensearch.CfnDomain;
    domain.softwareUpdateOptions = {
      ...(domain.softwareUpdateOptions ?? {}),
      ...this.options,
    };
  }
}

const domain = new opensearch.Domain(this, 'Domain', {
  version: opensearch.EngineVersion.OPENSEARCH_2_11,
});

Mixins.of(domain).requireAny().apply(new DomainSoftwareUpdateOptions({
  useLatestServiceSoftwareForBlueGreen: true,
}));

Synthesized output on the domain:

"SoftwareUpdateOptions": { "UseLatestServiceSoftwareForBlueGreen": true }

The mixin merges with any existing softwareUpdateOptions (so it composes with the L2's enableAutoSoftwareUpdate prop, which sets AutoSoftwareUpdateEnabled in the same block), and it can be applied to a whole scope via Mixins.of(stack).apply(...) to cover every domain at once.

[github-actions]

This issue has not received a response in a while. If you want to keep this issue open, please leave a comment below and auto-close will be canceled.