Skip to Content
Cloud Engineering Academy
10. Infrastructure as Code

Environment configuration and versioning

Promote the same infrastructure code through dev, test and prod by changing only reviewed configuration, guard production settings with an xUnit test, and tag releases so you can always answer which version is running where.

intermediate⏱ 1 h 40 min🟢 FreeDOP-C02SOA-C03

Assumes: .NET 10 LTS · xUnit v3 4.0.3 · Amazon.CDK.Lib 2.277.0 · Terraform 1.17.2 · Terraform AWS provider 6.73.0 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this lesson you can:

  • Explain "build once, promote the same code" and say what that means differently for CDK and for Terraform.
  • Separate what belongs in code, in per-environment configuration, in deploy-time input and in a secret store.
  • Model environment differences as one typed C# record, and protect production with an xUnit test that fails when someone weakens it.
  • Pass the chosen environment into a CDK app and into Terraform (variable files, one state per environment).
  • Version infrastructure releases with semantic versions and Git tags, and record the deployed release inside each environment so it is queryable.
  • Sketch a promotion pipeline with an approval gate before production.

Prerequisites

Why this matters in banking

A payments release goes wrong on a Friday. In test the service ran two containers and the database was single-AZ, because that is cheaper. In production the database is Multi-AZ and the service runs four containers behind a load balancer with a different health check path. Somebody "fixed" a security group in test by hand two months ago and forgot to apply the same rule in production, so a feature that worked in test cannot reach its database in production.

Two failure modes sit under that story:

  1. Environments that differ in ways nobody chose. The differences are accidents, not decisions, so test no longer predicts production.
  2. Environments that differ in ways nobody can list. There is no single place that says what is different on purpose.

Infrastructure as code lets you fix both. The same code runs in every environment. The differences are a short, typed, reviewed list. A test fails if production ever becomes weaker than test. And every environment records which release of the code it is running, so an incident responder can answer "what changed?" in one command.

The idea in plain language

Think of an environment as three things together: an account and Region (where it lives), a configuration (how big, how protected, how long to keep data) and a version of the code (which release of the infrastructure).

Analogy: a bank rolls out a new branch layout. The architectural drawings (the code) are identical for the High Street branch and the village branch. What differs is a short order form: the High Street branch has six counters and two vaults; the village branch has two counters and one safe. The form is reviewed by finance. The drawings carry a revision number, and each branch's file records which revision it was built from.

Four layers of settings, from most stable to most volatile:

LayerExampleLives inChanges how
Code defaults"Encrypt everything, block public access"The module or constructPull request to the shared code, new release
Environment profile"prod: Multi-AZ true, log retention 90 days"A checked-in file (C# record, tfvars)Pull request, reviewed, same as code
Deploy-time inputImage tag, release version, your IP for a labPipeline variable or command lineEach deploy
SecretsDatabase password, API keysSecrets Manager or Parameter StoreRotation, never in Git or IaC files

If you cannot say which layer a setting belongs to, it is probably in the wrong place.

What problem this solves

  • Test that predicts production. Because the code is identical, the only differences are the profile values. A reviewer can read the profile diff in a minute.
  • Safe promotion. The release that passed in test is the release that goes to production, not a rebuilt cousin of it.
  • Evidence. A Git tag plus a deployed-release marker gives an auditor a precise answer to "which version of the infrastructure was live on this date".
  • Guard-rails that survive staff changes. A test that says "prod must keep 90 days of logs" is a rule that lasts longer than the person who knew it.

Honest limitations:

  • Environments will never be identical. Cost and scale force differences. The goal is to make them deliberate and few.
  • With the CDK, configuration is read at synthesis time, so each environment produces a slightly different template. "Build once" means build, test and synthesise all environments in one pipeline run and deploy those exact outputs, not re-synthesise later.
  • With Terraform, a saved plan is specific to one state and one set of variables, so each environment has its own plan, produced from the same commit.

Microsoft / Azure comparison

You know (Microsoft/Azure)AWS equivalentWhat's different
Bicep parameter files per environment (dev.bicepparam)tfvars files, CDK context or a C# profile recordThe CDK lets you type-check the profile in C#
Azure DevOps variable groups and libraryPipeline variables, SSM Parameter StoreKeep secrets in Secrets Manager, not in variable groups
Release pipeline stages with approvalsGitHub Actions environments with required reviewers, or CodePipeline manual approvalSame idea; the approval belongs in front of production
Subscription per environmentAWS account per environmentStrongest isolation; see Module 9
App Configuration for runtime settingsSSM Parameter Store or AWS AppConfigInfrastructure profiles are for the platform; app feature flags are a separate concern
Git tags and GitHub ReleasesThe sameTag the infrastructure repository, not only the application

Architecture

Security-boundary view. Each environment is a separate AWS account with its own pipeline role. The pipeline assumes the dev role, then the test role, then (after human approval) the prod role. A developer's own credentials never deploy production, and a compromise of the dev role cannot touch prod.

Step-by-step implementation

Write the profile as a typed record

Put every setting that may differ between environments into one C# record (or one tfvars file per environment). If a value is not in the profile, it is the same everywhere. The full code is in the Complete code section.

Add a test that guards production

Write xUnit tests that fail when a production invariant breaks (deletion protection, Multi-AZ, log retention) and when production is weaker than test. Run them in the build job, before any deploy.

Select the environment at synth or plan time

CDK: -c environmentName=prod. Terraform: -var-file=environments/prod.tfvars and the matching backend file. Never infer the environment from the machine you are on.

Record the release inside the environment

Write the release version into an SSM parameter (and a stack output) at every deploy. aws ssm get-parameter then tells you which release is live.

Tag a release

Choose the next semantic version, update the changelog, create an annotated Git tag and let the pipeline build from the tag.

Promote with a gate

The pipeline deploys dev, then test, then waits for a human approval before prod. The approval screen shows the diff or plan for production.

AWS Console instructions

You mostly use the CLI and Git here, but the console confirms what is deployed:

  1. Console → Systems Manager → Parameter Store, search for /harbourline/dev/iac/release. The value is the release tag the dev environment was last deployed from.
  2. Console → CloudFormation → Stacks → (your stack) → Outputs. The Release output shows the same value for CDK and CloudFormation deployments.
  3. Console → CloudFormation → Stacks → Parameters / Tags (CloudFormation and CDK) and Console → Resource Groups & Tag Editor (any tool) show the tags. Tag the environment (Stage=prod), not the release: changing a tag on every release modifies every resource in the stack. Use the parameter for the release instead.

AWS CLI

# Which infrastructure release is live in each environment? (profile names are examples for your own accounts)
aws ssm get-parameter --name /harbourline/dev/iac/release  --query Parameter.Value --output text --profile hl-dev  --region us-east-1
aws ssm get-parameter --name /harbourline/prod/iac/release --query Parameter.Value --output text --profile hl-prod --region us-east-1

# Show the account behind a profile before you deploy anything. Do this every time.
aws sts get-caller-identity --profile hl-prod

# CDK: synthesise one environment into its own folder, then diff against what is deployed
cdk synth -c environmentName=prod -c release=v1.4.0 -o cdk.out/prod
cdk diff  -c environmentName=prod -c release=v1.4.0 --app cdk.out/prod

# Terraform: one plan per environment, from the same commit
terraform init -reconfigure -backend-config=environments/prod.backend.hcl
terraform plan -var-file=environments/prod.tfvars -var release=v1.4.0 -out=prod.tfplan

In the lab you only have one sandbox account, so you will create all three environments in it with different name prefixes, as the module project does. Use the real multi-account layout in a bank.

Infrastructure as Code

Program.cs (wiring)
using Amazon.CDK;
using Amazon.CDK.AWS.SSM;
using Harbourline.Environments;

var app = new App();

// 1. Which environment and which release? Both come from the command line, never from the machine.
var environmentName = app.Node.TryGetContext("environmentName") as string ?? "dev";
var release = app.Node.TryGetContext("release") as string ?? "v0.0.0-local";
var profile = Profiles.For(environmentName);           // throws for an unknown environment

// 2. Account per environment (fictional account IDs). Region is fixed for this bank.
var accounts = new Dictionary<string, string>
{
    ["dev"] = "111122223333",
    ["test"] = "222233334444",
    ["prod"] = "333344445555",
};

var stack = new Stack(app, $"hl-accounts-{profile.Name}", new StackProps
{
    Env = new Amazon.CDK.Environment { Account = accounts[profile.Name], Region = "us-east-1" },
    TerminationProtection = profile.DeletionProtection,
});

// 3. Resources read the profile; they never look at the environment name themselves.
//    (db, service and alarms would be added here, using profile.DatabaseMultiAz, profile.DesiredCount ...)

// 4. Record the release inside the environment, as a parameter and a stack output.
_ = new StringParameter(stack, "ReleaseMarker", new StringParameterProps
{
    ParameterName = $"/harbourline/{profile.Name}/iac/release",
    StringValue = release,
});
_ = new CfnOutput(stack, "Release", new CfnOutputProps { Value = release });

app.Synth();

Complete code

The profile, its guard-rails and its tests. They run with no AWS account and no Node.js. Create a folder with the files below and run dotnet test (or use the Docker command shown afterwards).

EnvironmentGuard.csproj
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
    <OutputType>Exe</OutputType>
    <IsPackable>false</IsPackable>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="xunit.v3" Version="4.0.3" />
  </ItemGroup>

  <ItemGroup>
    <Using Include="Xunit" />
  </ItemGroup>

</Project>
global.json
{
  "sdk": {
    "version": "10.0.100",
    "rollForward": "latestFeature"
  },
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}
Profiles.cs
namespace Harbourline.Environments;

/// <summary>Everything that is allowed to differ between environments. The infrastructure CODE is identical.</summary>
public sealed record EnvironmentProfile(
    string Name,
    int DesiredCount,
    int TaskCpu,
    int TaskMemoryMiB,
    bool DatabaseMultiAz,
    bool DeletionProtection,
    int BackupRetentionDays,
    int LogRetentionDays,
    bool RetainDataOnDelete);

public static class Profiles
{
    public static IReadOnlyList<EnvironmentProfile> All { get; } =
    [
        new("dev",  DesiredCount: 1, TaskCpu: 256, TaskMemoryMiB: 512,  DatabaseMultiAz: false, DeletionProtection: false, BackupRetentionDays: 1,  LogRetentionDays: 7,  RetainDataOnDelete: false),
        new("test", DesiredCount: 1, TaskCpu: 256, TaskMemoryMiB: 512,  DatabaseMultiAz: false, DeletionProtection: false, BackupRetentionDays: 3,  LogRetentionDays: 14, RetainDataOnDelete: false),
        new("prod", DesiredCount: 2, TaskCpu: 512, TaskMemoryMiB: 1024, DatabaseMultiAz: true,  DeletionProtection: true,  BackupRetentionDays: 14, LogRetentionDays: 90, RetainDataOnDelete: true),
    ];

    public static EnvironmentProfile For(string name) =>
        All.FirstOrDefault(p => p.Name == name)
        ?? throw new InvalidOperationException($"Unknown environment '{name}'. Use dev, test or prod.");
}
ProfileRules.cs
using System.Reflection;

namespace Harbourline.Environments;

public static class ProfileRules
{
    // Valid Fargate CPU / memory pairs for the sizes this bank uses (memory in MiB).
    private static readonly Dictionary<int, int[]> FargateSizes = new()
    {
        [256] = [512, 1024, 2048],
        [512] = [1024, 2048, 3072, 4096],
        [1024] = [2048, 3072, 4096, 5120, 6144, 7168, 8192],
    };

    /// <summary>Returns a list of human-readable violations. Empty means the set of profiles is acceptable.</summary>
    public static IReadOnlyList<string> Validate(IReadOnlyList<EnvironmentProfile> profiles)
    {
        var problems = new List<string>();

        if (profiles.Select(p => p.Name).Distinct().Count() != profiles.Count)
        {
            problems.Add("Environment names must be unique.");
        }

        foreach (var p in profiles)
        {
            if (!FargateSizes.TryGetValue(p.TaskCpu, out var memories) || !memories.Contains(p.TaskMemoryMiB))
            {
                problems.Add($"{p.Name}: {p.TaskCpu} CPU units with {p.TaskMemoryMiB} MiB is not a valid Fargate size.");
            }
            if (p.DesiredCount < 1)
            {
                problems.Add($"{p.Name}: DesiredCount must be at least 1.");
            }
        }

        var prod = profiles.FirstOrDefault(p => p.Name == "prod");
        if (prod is null)
        {
            problems.Add("A 'prod' profile is required.");
            return problems;
        }

        // Production invariants: these protect customers' data, so a test checks them, not someone's memory.
        if (!prod.DeletionProtection) problems.Add("prod: DeletionProtection must be true.");
        if (!prod.DatabaseMultiAz) problems.Add("prod: DatabaseMultiAz must be true.");
        if (!prod.RetainDataOnDelete) problems.Add("prod: RetainDataOnDelete must be true.");
        if (prod.DesiredCount < 2) problems.Add("prod: DesiredCount must be at least 2 for availability.");
        if (prod.BackupRetentionDays < 7) problems.Add("prod: BackupRetentionDays must be at least 7.");
        if (prod.LogRetentionDays < 90) problems.Add("prod: LogRetentionDays must be at least 90 (set by the bank's retention policy).");

        // Production must never be weaker than the environments that are supposed to rehearse it.
        foreach (var lower in profiles.Where(p => p.Name != "prod"))
        {
            if (prod.BackupRetentionDays < lower.BackupRetentionDays) problems.Add($"prod keeps backups for fewer days than {lower.Name}.");
            if (prod.LogRetentionDays < lower.LogRetentionDays) problems.Add($"prod keeps logs for fewer days than {lower.Name}.");
            if (prod.TaskCpu < lower.TaskCpu) problems.Add($"prod has less CPU than {lower.Name}.");
        }

        return problems;
    }

    /// <summary>Lists the settings that differ between two environments: the "what is really different" report.</summary>
    public static IReadOnlyList<(string Setting, string A, string B)> Diff(EnvironmentProfile a, EnvironmentProfile b) =>
        typeof(EnvironmentProfile)
            .GetProperties(BindingFlags.Public | BindingFlags.Instance)
            .Where(prop => prop.Name != nameof(EnvironmentProfile.Name))
            .Select(prop => (Setting: prop.Name, A: prop.GetValue(a)?.ToString() ?? "", B: prop.GetValue(b)?.ToString() ?? ""))
            .Where(x => x.A != x.B)
            .ToList();
}
ProfileTests.cs
using Harbourline.Environments;

namespace Harbourline.Environments.Tests;

public class ProfileTests
{
    [Fact]
    public void The_checked_in_profiles_are_valid()
    {
        var problems = ProfileRules.Validate(Profiles.All);
        Assert.True(problems.Count == 0, string.Join(Environment.NewLine, problems));
    }

    [Fact]
    public void Unknown_environment_is_refused()
    {
        Assert.Throws<InvalidOperationException>(() => Profiles.For("staging"));
    }

    [Fact]
    public void Weakening_production_is_caught()
    {
        var weakProd = Profiles.For("prod") with { DeletionProtection = false, LogRetentionDays = 30 };
        var set = Profiles.All.Where(p => p.Name != "prod").Append(weakProd).ToList();

        var problems = ProfileRules.Validate(set);

        Assert.Contains(problems, p => p.Contains("DeletionProtection", StringComparison.Ordinal));
        Assert.Contains(problems, p => p.Contains("LogRetentionDays", StringComparison.Ordinal));
    }

    [Fact]
    public void Prod_with_fewer_backup_days_than_test_is_caught()
    {
        var odd = Profiles.For("test") with { BackupRetentionDays = 30 };
        var set = Profiles.All.Where(p => p.Name != "test").Append(odd).ToList();

        Assert.Contains(ProfileRules.Validate(set), p => p.Contains("fewer days than test", StringComparison.Ordinal));
    }

    [Fact]
    public void Invalid_fargate_size_is_caught()
    {
        var bad = Profiles.For("dev") with { TaskCpu = 256, TaskMemoryMiB = 4096 };
        var set = Profiles.All.Where(p => p.Name != "dev").Append(bad).ToList();

        Assert.Contains(ProfileRules.Validate(set), p => p.Contains("not a valid Fargate size", StringComparison.Ordinal));
    }

    [Fact]
    public void Diff_lists_only_settings_that_differ()
    {
        var diff = ProfileRules.Diff(Profiles.For("dev"), Profiles.For("test"));

        Assert.Contains(diff, d => d.Setting == nameof(EnvironmentProfile.BackupRetentionDays) && d.A == "1" && d.B == "3");
        Assert.DoesNotContain(diff, d => d.Setting == nameof(EnvironmentProfile.TaskCpu));
    }
}

Run the tests in Docker (no .NET install needed). Mount only your own folder, and delete bin/ and obj/ afterwards:

MSYS_NO_PATHCONV=1 docker run --rm --memory 3g \
  -v "$PWD:/src" -v cea-nuget-m10:/root/.nuget/packages -w /src \
  mcr.microsoft.com/dotnet/sdk:10.0 \
  sh -c "dotnet test; find . -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} +"

Expected: six tests pass. The release helper and pipeline follow.

release.ps1
# Create an annotated release tag for the infrastructure repository.
# Usage: ./release.ps1 -Version 1.4.0
param(
    [Parameter(Mandatory)] [string] $Version
)

$ErrorActionPreference = 'Stop'

if ($Version -notmatch '^\d+\.\d+\.\d+$') { throw "Version must look like 1.4.0 (got '$Version')." }

# Refuse to release uncommitted work: the tag must describe exactly what is in Git.
if (git status --porcelain) { throw 'Working tree is not clean. Commit or stash first.' }

# The changelog must already mention the version.
if (-not (Select-String -Path CHANGELOG.md -Pattern "## \[$([regex]::Escape($Version))\]" -Quiet)) {
    throw "CHANGELOG.md has no '## [$Version]' heading."
}

if (git tag --list "v$Version") { throw "Tag v$Version already exists." }

git tag -a "v$Version" -m "Infrastructure release v$Version"
Write-Host "Created tag v$Version. Push it with: git push origin v$Version"
.github/workflows/promote.yml
name: promote-infrastructure

on:
  push:
    tags: ["v*.*.*"]

permissions:
  id-token: write   # lets the job ask AWS for short-lived credentials (OIDC); no stored access keys
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with: { dotnet-version: "10.0.x" }
      - run: dotnet test                       # unit tests including the profile guard
      - run: npm install -g aws-cdk@2          # pin an exact version in a real pipeline  ⚠ VERIFY
      - name: Synthesise every environment once
        run: |
          for env in dev test prod; do
            cdk synth -c environmentName=$env -c release=${{ github.ref_name }} -o cdk.out/$env
          done
      - uses: actions/upload-artifact@v4
        with: { name: cdk-assemblies, path: cdk.out }

  deploy-dev:
    needs: build
    runs-on: ubuntu-latest
    environment: dev
    steps:
      - uses: actions/download-artifact@v4
        with: { name: cdk-assemblies, path: cdk.out }
      - uses: aws-actions/configure-aws-credentials@v4   # ⚠ VERIFY the current major version
        with:
          role-to-assume: arn:aws:iam::111122223333:role/hl-deploy-dev
          aws-region: us-east-1
      - run: npm install -g aws-cdk@2 && cdk deploy --all --app cdk.out/dev --require-approval never

  deploy-test:
    needs: deploy-dev
    runs-on: ubuntu-latest
    environment: test
    steps:
      - uses: actions/download-artifact@v4
        with: { name: cdk-assemblies, path: cdk.out }
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::222233334444:role/hl-deploy-test
          aws-region: us-east-1
      - run: npm install -g aws-cdk@2 && cdk deploy --all --app cdk.out/test --require-approval never

  deploy-prod:
    needs: deploy-test
    runs-on: ubuntu-latest
    environment: prod      # configure required reviewers on this environment in the repository settings
    steps:
      - uses: actions/download-artifact@v4
        with: { name: cdk-assemblies, path: cdk.out }
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::333344445555:role/hl-deploy-prod
          aws-region: us-east-1
      - run: npm install -g aws-cdk@2 && cdk diff --app cdk.out/prod
      - run: cdk deploy --all --app cdk.out/prod --require-approval never

Code explained line by line

  1. EnvironmentProfile is a C# record. Records are immutable and support with expressions, which the tests use to create "what if" variants. Every setting that can differ lives here, so "what is different between environments?" has one answer.
  2. Profiles.For(name) throws for an unknown name. A typo like -c environmentName=prd fails loudly on the laptop rather than deploying defaults to the wrong place.
  3. ProfileRules.Validate returns a list of readable problems, not a boolean, so a failing build says exactly which rule broke. The production invariants (deletion protection, Multi-AZ, retention) are written once and tested forever.
  4. The "never weaker than test" loop catches an easy mistake: someone raises test backups to 30 days for an experiment and forgets that production now has fewer.
  5. Diff uses reflection over the record's properties to list settings that differ. Run it in a pull request to show reviewers the entire environment gap.
  6. In the wiring, app.Node.TryGetContext reads -c values. The account IDs are looked up from the chosen environment, so a developer cannot accidentally target prod with a dev profile.
  7. StringParameter and CfnOutput write the release marker. Tag-based markers would touch every resource on every release; one parameter touches one resource.
  8. In release.ps1, the clean-tree and changelog checks stop a tag from describing something that is not in Git.
  9. In the workflow, the build job synthesises all three environments once into cdk.out/<env> and uploads them. The deploy jobs download and deploy those exact files with --app cdk.out/<env>, so nothing is rebuilt between test and prod. id-token: write enables OIDC federation so no long-lived AWS keys are stored in GitHub.

Versioning infrastructure

Apply the same rules as application code, with one extra rule about what "breaking" means.

ChangeVersion bumpExample
Additive, no existing resource changesPatch or minorNew alarm; a new optional output
Modifies existing resources in placeMinor, with a noteLonger log retention
Replaces or deletes a resource, or changes state addresses without a moved blockMajorNew database engine version that replaces the instance
Changes the environment profile onlyPatch or minorProd from 2 to 3 tasks

Practical habits:

  • Tag the infrastructure repository, not only the application. Use annotated tags (git tag -a) so the tag carries a message and a tagger.
  • Keep a CHANGELOG. One heading per version, with a line for every environment-visible change and a Migration line when action is needed.
  • Pin everything downstream. Terraform modules by tag or SHA, CDK libraries by exact NuGet version, Terraform providers by .terraform.lock.hcl (commit it).
  • Record the release in the environment with the SSM parameter, so the CLI answers "what is live?".
  • Roll back by redeploying the previous tag, not by editing in the console. Remember that infrastructure rollback does not restore data: deleting a database in a bad release cannot be undone by deploying the old code. See Rollback strategies.

Security considerations

⚠ Learning shortcut — not for production

The lab deploys all three environments into one sandbox account with name prefixes, and the sample workflow uses placeholder account IDs. In production, each environment is its own account with its own pipeline role, state bucket and KMS keys. A human approval must stand in front of production, and production deploys must come from the pipeline, never from a laptop.

  • Keep secrets out of profiles. Profiles and tfvars files are committed. Anything secret comes from Secrets Manager at run time. If you ever commit a secret, rotate it; deleting the commit does not make it safe.
  • OIDC, not access keys. The pipeline gets short-lived credentials by assuming a role; restrict the role's trust policy to your repository, the tag pattern and the environment name. ⚠ VERIFY the exact trust-policy condition keys against the current GitHub OIDC documentation.
  • Production needs a second pair of eyes. Require reviewers on the prod environment and on changes to the profile file (CODEOWNERS).
  • Do not let a lower environment weaken the pipeline. The same pipeline definition deploys every environment; only the role and the profile differ.
  • Change evidence. Attach the cdk diff or terraform plan output for prod to the change record. It is the audit trail for the change, not proof of compliance with any specific regulation.

Banking use case

Harbourline ships the Accounts platform every two weeks. Release v2.7.0 adds a CloudWatch alarm and raises production log retention. The pull request shows the profile diff in four lines and the cdk diff in the PR comment. The pipeline deploys dev and test automatically; the change manager approves production after reading the prod diff. Two weeks later an incident review asks, "was the retention change live on the 14th?". One CLI call against the prod account returns v2.7.0, the Git tag shows the commit and author, and the pipeline run shows who approved it.

Common mistakes

  • Configuration smuggled into code. if (envName == "prod") scattered through constructs. Read the profile once and pass values down.
  • Different code per environment (branches called dev, test, prod). Branches diverge; use one branch and profiles.
  • Workspaces for long-lived environments. One backend means one set of credentials and one blast radius. Use separate state and accounts for dev, test and prod. See Terraform state.
  • Re-synthesising per stage. If prod is synthesised later than test, a dependency may have changed in between. Synthesise once, deploy the artefact.
  • Tagging resources with the release. Every release then modifies every resource. Use an SSM parameter or stack output.
  • No guard on the profile. Without a test, the first person to cut cost in test removes protection in prod too.
  • Promoting a branch instead of a tag. A moving branch is not a release. Deploy immutable tags.

Troubleshooting

SymptomLikely causeFix
Unknown environment 'prd'Typo in -c environmentNameUse dev, test or prod; the error is deliberate
CDK deploys to the wrong accountStack has no explicit Env, so it uses the current credentialsSet Env from the profile and check aws sts get-caller-identity first
cdk deploy --app cdk.out/prod says no assembliesYou synthesised without -o cdk.out/prodRe-run cdk synth ... -o cdk.out/prod
Terraform plan shows the whole environment as newWrong backend config, so it reads empty stateRun terraform init -reconfigure -backend-config=environments/<env>.backend.hcl
ParameterAlreadyExists for the release markerAnother stack or manual change created the same nameUse one owner for /harbourline/<env>/iac/release; import or delete the stray
Profile test fails after a cost-saving changeThe change weakened prod or made it weaker than testRead the failure message; revert the weakening, or change the rule deliberately in the same pull request
Tag push does not start the pipelineTag does not match v*.*.*, or the workflow is not on the tagged commitUse the exact pattern; push the workflow file before tagging

Cost and cleanup

The tests, cdk synth and terraform plan cost nothing. If you deploy the release marker alone, a Parameter Store standard parameter and a tiny CloudFormation stack are free ⚠ VERIFY current Parameter Store standard-tier pricing. Deploying full environments is covered by the module project and the cost notes there.

# If you deployed the release marker for a lab environment:
cdk destroy --all -c environmentName=dev
# or, with Terraform:
terraform destroy -var-file=environments/dev.tfvars

# Confirm nothing tagged for this lab remains
aws resourcegroupstaggingapi get-resources \
  --tag-filters Key=Lab,Values=m10-l12 \
  --profile learn-sandbox --region us-east-1 \
  --query "ResourceTagMappingList[].ResourceARN"

Exercises

  • 🟢 Guided: create the four files (Profiles.cs, ProfileRules.cs, ProfileTests.cs and the project file), run the tests, and confirm six pass. Then set DeletionProtection = false for prod and read the failure.
  • 🟡 Challenge: add a fourth environment uat between test and prod with 2 tasks, 512 CPU and 1024 MiB, Multi-AZ true and 30 days of logs. Update the rules so that uat must not be weaker than test, and add tests that prove it.
  • 🔴 Live problem: the finance team asks you to cut costs by turning Multi-AZ off in test and prod "for now". Production has been Multi-AZ since the bank's resilience review. Write the response: what you will and will not change, who must approve production changes, how the test in this lesson helps you hold the line, and what lower-cost options exist that keep the resilience requirement.

Assignment

In your portfolio repository add environments/ with a typed profile file, the guard tests, a CHANGELOG.md with two releases, and the release.ps1 script. Add a README section "How to promote" that lists the exact steps and who approves production. Include a screenshot-free description of the pipeline stages. Do not include real account IDs.

Solutions

For the live problem, a sound reply: keep production Multi-AZ because it is a recorded resilience decision, not a preference; the guard test makes that explicit and any change needs a deliberate rule change reviewed by risk and architecture. Offer savings that do not break the requirement: single-AZ in dev and test (already the case), smaller instance classes in test, scheduled stop of non-production databases outside working hours, Savings Plans or reserved instances for steady production capacity, and removing unused resources. Quantify with Cost Explorer before and after.

Knowledge check

Interview questions

  • How do you keep dev, test and prod consistent without making them identical? One codebase, one typed profile per environment listing the deliberate differences, a test that guards production invariants, and a diff report in pull requests.
  • How do you know what version of the infrastructure is running in production? The release tag is recorded in a Parameter Store parameter and a stack output at deploy time, and the Git tag and pipeline run show the commit and the approver.
  • What is your rollback plan for an infrastructure release? Redeploy the previous tag through the same pipeline; accept that data-destroying changes cannot be reversed this way, so use deletion protection, snapshots and retain policies on stateful resources.
  • Why do you promote tags rather than branches? A tag is immutable, so what passed in test is exactly what goes to production.

Certification practice

Completion checklist

  • I can name the four layers of configuration and where each belongs
  • I ran the six profile tests and saw one fail when I weakened prod
  • I can explain why the CDK synthesises each environment once and deploys the artefact
  • I can write a release tag and say what version bump a change needs
  • I ran the cleanup steps (or skipped the optional deploy) and confirmed nothing is still billing

Key takeaways

  • Same code everywhere; differences live in a short, typed, reviewed profile.
  • Guard production with tests so cost-cutting cannot quietly weaken it.
  • Build once: synthesise or plan in the build job, deploy the stored output through dev, test and an approval to prod.
  • Version infrastructure with semantic versions and annotated tags, and record the release inside each environment.
  • Keep secrets out of profiles; use separate state, accounts and roles per environment.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page