Update the solution

MDAA follows semantic versioning. Minor releases (for example, 1.3.0 to 1.4.0) are generally backward compatible with existing configurations. However, upgrades may include underlying CDK version changes and new module behaviors, so reviewing changes before deploying is recommended.

Before you upgrade

Upgrading to the latest version

To upgrade to the latest published version, simply run the CLI without specifying a version or --mdaa-version:

npx @aws-mdaa/cli deploy -c ./mdaa.yaml

Upgrading to a specific version

To upgrade to a specific version, specify the target version when running the CLI:

npx @aws-mdaa/cli@1.4.0 --mdaa-version 1.4.0 deploy -c ./mdaa.yaml

The --mdaa-version flag controls which version of the MDAA module packages are installed during execution. The version after @aws-mdaa/cli@ controls the CLI version itself. These should generally match.

Gradual upgrade via version pinning

For a more controlled rollout, you can pin specific MDAA versions at different levels in your mdaa.yaml configuration. This allows you to upgrade and validate modules individually before upgrading the rest.

# Pin version globally
mdaa_version: '1.3.0'

domains:
  my-domain:
    environments:
      dev:
        # Override version for a specific environment
        mdaa_version: '1.4.0'
        modules:
          audit:
            # Override version for a specific module
            mdaa_version: '1.4.0'

Version resolution follows a hierarchy: module overrides environment, environment overrides domain, and domain overrides the global setting.

You can also use the -d, -e, and -m CLI flags to target specific domains, environments, or modules during an upgrade:

npx @aws-mdaa/cli@1.4.0 --mdaa-version 1.4.0 deploy -c ./mdaa.yaml -m audit

Validating with baseline diff

Starting with MDAA 1.5.0, you can compare synthesized templates against a stored baseline without requiring a deployed stack. This is useful for CI/CD pipelines or for validating upgrades in a non-deployed environment:

# Synthesize and store templates from the current version
npx @aws-mdaa/cli@1.3.0 --mdaa-version 1.3.0 synth -c ./mdaa.yaml --cdk-out ./baseline

# Compare against the new version
npx @aws-mdaa/cli@1.4.0 --mdaa-version 1.4.0 diff -c ./mdaa.yaml --baseline ./baseline --diff-out ./diff-results