Updating Versions

The landing zone foundation and constructs are delivered as versioned packages through AWS CodeArtifact. When Towards The Cloud releases improvements, you receive them by bumping two pinned version numbers in .projenrc.ts and redeploying, with no forking or patching required.

Pinned versions

The two licensed packages are pinned in the towardsTheCloudPackages array in .projenrc.ts; the CDK, projen, and pnpm versions are set on the cdkVersion, cdkCliVersion, projenVersion, and pnpmVersion fields:

The versions above match the current starter. The changelog provides curated release highlights and may not include every package release. Towards The Cloud sends the release and migration notices with each release, so follow them when upgrading; your own .projenrc.ts records what you are running today.

The two licensed packages are excluded from the pnpm run upgrade task (depsUpgradeOptions.exclude), so you bump them by hand when a release is announced.

Upgrade procedure

1. Check the release notes: the changelog summarizes the highlights of each month's releases so you can see what a bump brings. It is a curated summary, not an exhaustive per-release log — Towards The Cloud communicates breaking changes and migration steps to you directly with each release, so follow those when they apply.

2. Update the version pins in .projenrc.ts:

   const towardsTheCloudPackages = [
     { name: '@towardsthecloud/cdk-landing-zone-constructs', version: '1.27.1' }, // set to the released version
     { name: '@towardsthecloud/cdk-landing-zone-foundation', version: '1.23.0' }, // and here
   ];
   

   For a CDK bump, update cdkVersion and cdkCliVersion in the same file instead.

3. Regenerate project files and install the new packages:

   pnpm exec projen
   

   This rewrites package.json, pnpm-lock.yaml, and generated files to match the new pins.

   A package bump alone does not change the files you own, such as src/config/ and src/stacks/. When a release needs a change there, the notice from Towards The Cloud says which one.

4. Review the diff: git diff will show which generated files changed. Pay particular attention to changes in .github/workflows/ and any generated npm scripts.

5. Deploy: the first command deploys the organization phase to the management account, and the second deploys the landing-zone phase to the landing zone account.

   pnpm run organization:deploy
   pnpm run landingzone:deploy:all
   

   Or push to main and let the GitHub Actions pipeline deploy.

Upgrading other dependencies

The starter does not ship an automated dependency-upgrade workflow, so nothing opens upgrade pull requests for you. You upgrade the other dependencies, such as the AWS CDK library and CLI, projen, and your dev dependencies, when you choose to:

1. Assume a role in your management account, then run pnpm run setup to refresh the CodeArtifact token and install dependencies.
2. Run pnpm run upgrade. It upgrades everything except the two licensed @towardsthecloud packages, which depsUpgradeOptions.exclude keeps out of it.
3. Review the resulting package.json and lockfile changes and open a pull request. The diff workflow shows the effect on your stacks and StackSets before you merge.

Landing zone releases still go through the manual upgrade procedure above.

CodeArtifact token refresh

The pnpm exec projen step runs pnpm install internally, which requires a valid CodeArtifact token. If the install fails with a 401 error:

# Re-assume your management account role, then:
pnpm run setup

pnpm run setup fetches a fresh token and re-runs the install.

Things to know

• Both packages should be bumped together: cdk-landing-zone-foundation and cdk-landing-zone-constructs are released in tandem and tested against each other, but they version independently and can have different version numbers. Move both to their latest released versions in the same change rather than trying to match the numbers.
• CDK version bumps (cdkVersion and cdkCliVersion) follow the same pattern. Check the AWS CDK changelog for breaking changes before bumping.
• Projen re-runs on install: generated files are regenerated automatically when you run pnpm exec projen. Committing the resulting changes to main keeps the repo consistent.