AWS solutions documentation change
Summary
Updated upgrade documentation with versioning strategy, diff validation, version pinning controls, and CLI upgrade workflows
Security assessment
The changes focus on general upgrade procedures and version management without mentioning security vulnerabilities or security-specific features. While version control improvements can have indirect security benefits, there's no explicit security context provided in the diff.
Diff
diff --git a/solutions/latest/modern-data-architecture-accelerator/update-the-solution.md b/solutions/latest/modern-data-architecture-accelerator/update-the-solution.md index fe6bdef18..99be3a4d2 100644 --- a//solutions/latest/modern-data-architecture-accelerator/update-the-solution.md +++ b//solutions/latest/modern-data-architecture-accelerator/update-the-solution.md @@ -4,0 +5,2 @@ +Before you upgradeUpgrading to the latest versionUpgrading to a specific versionGradual upgrade via version pinningValidating with baseline diff + @@ -7 +9,69 @@ -If you deployed a previous version of this solution, you must first uninstall your previous deployment and then deploy the new version. +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 + + 1. Review the [CHANGELOG](https://github.com/aws/modern-data-architecture-accelerator/blob/main/CHANGELOG.md) for the target version to understand new features, bug fixes, and dependency updates. + + 2. Run `diff` to preview the CloudFormation changes the upgrade will introduce. To diff against the latest published version: + + npx @aws-mdaa/cli diff -c ./mdaa.yaml + +To diff against a specific version: + + npx @aws-mdaa/[email protected] --mdaa-version 1.4.0 diff -c ./mdaa.yaml + + + + +## 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/[email protected] --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/[email protected] --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/[email protected] --mdaa-version 1.3.0 synth -c ./mdaa.yaml --cdk-out ./baseline + + # Compare against the new version + npx @aws-mdaa/[email protected] --mdaa-version 1.4.0 diff -c ./mdaa.yaml --baseline ./baseline --diff-out ./diff-results