feat(cli): add --mode options to diff command. deprecates --change-set/--no-changeset

[msessa]

Issue # (if applicable)

Closes #28753

Reason for this change

The current behaviour of implicitly reverting to template-only diff can hide important error messages from the user that can help catching mistakes early before deployment.

This is especially true when a template uses transforms or when using changeset-level cloudformation hooks to enforce compliance rules.

See an example code snippet at the bottom

Description of changes

Added a --mode option to the diff command that replaces (deprecates) --change-set/--no-changeset.

The following modes are supported:

• auto : Attempts changeset creation and fallback to local mode should any error be encountered. (replaces -change-set)
• change-set: Attempts changeset creation but doesn't handle errors returned by cloudformation when creating a changeset for an existing stack. Instead those errors are surfaced to the user
• template-only: Uses template-only diff (replaces --no-change-set)

Description of how you validated changes

• Added unit test
• Added integration test
• Tested against the example code at the bottom

Checklist

• My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

Example Code

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';

const app = new cdk.App();

export class TestStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Deploy first without this resource, then add and diff
    new cdk.CfnOutput(this, 'TestOutput', {
      value: cdk.Fn.transform('MyTransform', { Param: "Value"}).toString()
    })
  }
}

new TestStack(app, 'MyTestStack');

app.synth()

Current behaviour on diff:

$ npx cdk diff MyTestStack
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff)
Could not create a change set, will base the diff on template differences (run again with -v to see the reason)
Stack MyTestStack
Outputs
[+] Output TestOutput TestOutput: {"Value":{"Fn::Transform":{"Name":"MyTransform","Parameters":{"Param":"Value"}}}}

New behaviour on diff:

$ npx cdk diff --no-fallback MyTestStack
Hold on while we create a read-only change set to get a diff with accurate replacement information (use --no-change-set to use a less accurate but faster template-only diff)
Failed to create ChangeSet cdk-diff-change-set on MyTestStack: FAILED, No transform named 000000000000::MyTransform found.

---

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

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Features must contain a change to an integration test file and the resulting snapshot.
❌ CLI code has changed. A maintainer must run the code through the testing pipeline (git fetch origin pull/32830/head && git push -f origin FETCH_HEAD:test-main-pipeline), then add the 'pr-linter/cli-integ-tested' label when the pipeline succeeds.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

[msessa]

Clarification Request: Integration test has been added but the linter still doesn't seems too happy. Anything I can do about that?

[mrgrain]

Thanks for getting started on this!

In stead of introducing a new boolean option that only sometimes has an effect, we should create a new 3-way switch option to replace the current --change-set and --no-change-set options.

Something like

--mode=auto
--mode=change-set
--mode=template-only

[msessa]

@mrgrain I have addressed your feedback. Let me know what you reckon

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: ea60fe6
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[aws-cdk-automation]

This PR cannot be merged because it has conflicts. Please resolve them. The PR will be considered stale and closed if it remains in an unmergeable state.

[aws-cdk-automation]

This PR has been in the CHANGES REQUESTED state for 3 weeks, and looks abandoned. To keep this PR from being closed, please continue work on it. If not, it will automatically be closed in a week.

[mrgrain]

@msessa FYI, we've parked this to prioritize some other work in the CLI area. I'll be getting back it end of February. Apologies for the delay.