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.
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
- Terraform state: separate state per environment.
- Terraform modules: module version pinning.
- Module 9: Environment separation and Rollback strategies: accounts per environment and how deploys are undone.
- Tools: Docker Desktop (the .NET SDK image) to run the tests. No AWS account is needed for the main exercise.
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:
- Environments that differ in ways nobody chose. The differences are accidents, not decisions, so test no longer predicts production.
- 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:
| Layer | Example | Lives in | Changes how |
|---|---|---|---|
| Code defaults | "Encrypt everything, block public access" | The module or construct | Pull 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 input | Image tag, release version, your IP for a lab | Pipeline variable or command line | Each deploy |
| Secrets | Database password, API keys | Secrets Manager or Parameter Store | Rotation, 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 equivalent | What's different |
|---|---|---|
Bicep parameter files per environment (dev.bicepparam) | tfvars files, CDK context or a C# profile record | The CDK lets you type-check the profile in C# |
| Azure DevOps variable groups and library | Pipeline variables, SSM Parameter Store | Keep secrets in Secrets Manager, not in variable groups |
| Release pipeline stages with approvals | GitHub Actions environments with required reviewers, or CodePipeline manual approval | Same idea; the approval belongs in front of production |
| Subscription per environment | AWS account per environment | Strongest isolation; see Module 9 |
| App Configuration for runtime settings | SSM Parameter Store or AWS AppConfig | Infrastructure profiles are for the platform; app feature flags are a separate concern |
| Git tags and GitHub Releases | The same | Tag 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:
- Console → Systems Manager → Parameter Store, search for
/harbourline/dev/iac/release. The value is the release tag the dev environment was last deployed from. - Console → CloudFormation → Stacks → (your stack) → Outputs. The
Releaseoutput shows the same value for CDK and CloudFormation deployments. - 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.tfplanIn 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
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).
<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>{
"sdk": {
"version": "10.0.100",
"rollForward": "latestFeature"
},
"test": {
"runner": "Microsoft.Testing.Platform"
}
}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.");
}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();
}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.
# 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"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 neverCode explained line by line
EnvironmentProfileis a C#record. Records are immutable and supportwithexpressions, 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.Profiles.For(name)throws for an unknown name. A typo like-c environmentName=prdfails loudly on the laptop rather than deploying defaults to the wrong place.ProfileRules.Validatereturns 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.- 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.
Diffuses reflection over the record's properties to list settings that differ. Run it in a pull request to show reviewers the entire environment gap.- In the wiring,
app.Node.TryGetContextreads-cvalues. The account IDs are looked up from the chosen environment, so a developer cannot accidentally target prod with a dev profile. StringParameterandCfnOutputwrite the release marker. Tag-based markers would touch every resource on every release; one parameter touches one resource.- In
release.ps1, the clean-tree and changelog checks stop a tag from describing something that is not in Git. - 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: writeenables 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.
| Change | Version bump | Example |
|---|---|---|
| Additive, no existing resource changes | Patch or minor | New alarm; a new optional output |
| Modifies existing resources in place | Minor, with a note | Longer log retention |
Replaces or deletes a resource, or changes state addresses without a moved block | Major | New database engine version that replaces the instance |
| Changes the environment profile only | Patch or minor | Prod 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
tfvarsfiles 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
prodenvironment 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 difforterraform planoutput 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
| Symptom | Likely cause | Fix |
|---|---|---|
Unknown environment 'prd' | Typo in -c environmentName | Use dev, test or prod; the error is deliberate |
| CDK deploys to the wrong account | Stack has no explicit Env, so it uses the current credentials | Set Env from the profile and check aws sts get-caller-identity first |
cdk deploy --app cdk.out/prod says no assemblies | You synthesised without -o cdk.out/prod | Re-run cdk synth ... -o cdk.out/prod |
| Terraform plan shows the whole environment as new | Wrong backend config, so it reads empty state | Run terraform init -reconfigure -backend-config=environments/<env>.backend.hcl |
ParameterAlreadyExists for the release marker | Another stack or manual change created the same name | Use one owner for /harbourline/<env>/iac/release; import or delete the stray |
| Profile test fails after a cost-saving change | The change weakened prod or made it weaker than test | Read the failure message; revert the weakening, or change the rule deliberately in the same pull request |
| Tag push does not start the pipeline | Tag does not match v*.*.*, or the workflow is not on the tagged commit | Use 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.csand the project file), run the tests, and confirm six pass. Then setDeletionProtection = falsefor prod and read the failure. - 🟡 Challenge: add a fourth environment
uatbetween test and prod with 2 tasks, 512 CPU and 1024 MiB, Multi-AZ true and 30 days of logs. Update the rules so thatuatmust not be weaker thantest, 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
With DeletionProtection: false on the prod line of Profiles.All, ProfileRules.Validate reports prod: DeletionProtection must be true. and the test The_checked_in_profiles_are_valid fails with that message. That failure is the point: the pull request cannot merge until either the change is reverted or the rule is deliberately changed by a reviewer, in the open.
Add the profile to Profiles.All. In ProfileRules.Validate, generalise the "weaker than" loop to compare uat with test (for example if (uat.LogRetentionDays < test.LogRetentionDays) problems.Add(...)). Tests: one where uat has fewer log days than test (expect the new message), and one where all rules pass. Because Validate returns a list, add Assert.Contains on the specific message so a different failure cannot satisfy the test by accident. Note that the rule prod keeps logs for fewer days than uat is already covered by the existing loop, because it iterates all non-prod profiles.
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
Answer: run tests and synthesise every environment in one build, store the resulting assemblies as an artefact, and deploy those exact outputs to dev, then test, then prod. Re-synthesising later risks a different dependency or a different result.
Answer: in AWS Secrets Manager (generated by RDS or set out of band), never in a profile, a tfvars file or a pipeline variable that is committed. Profiles are reviewed, shared configuration.
Answer: changing a tag on every release modifies every resource in the stack, creating noise and risk. One parameter or output changes one resource and answers "what is live?" with a single CLI call.
Answer: workspaces share one backend and set of credentials, so a mistake or compromise can reach all environments. Separate state, accounts and roles per environment limit the blast radius.
Answer: a required human approval on the prod environment, a pipeline role that only the pipeline can assume, and a visible diff or plan to review. Not a long-lived access key and not a developer laptop.
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
A team uses one CloudFormation-based infrastructure pipeline for three environments. They want the artefact that passed testing in the test account to be exactly what is deployed to production, with a manual approval before production. Which design meets this?
A. Three separate Git branches, each with its own pipeline that rebuilds on merge. B. One pipeline that builds and stores a versioned artefact once, deploys it to dev and test automatically, and requires manual approval before deploying the same artefact to production. C. A developer runs the deploy command from their laptop against production after test passes. D. Copy the template into the production account by email.
Answer: B. Building once and promoting the artefact guarantees the same code is tested and released, and an approval gate controls production. A rebuilds and can diverge. C bypasses controls. D has no traceability.
An operations engineer must show an auditor which release of the infrastructure code was running in each AWS account on a given date, without tagging every resource. Which approach is best?
A. Rename each CloudFormation stack for every release. B. Write the release version to an AWS Systems Manager parameter (and a stack output) at every deployment, and keep the deployment history and Git tags. C. Ask engineers to remember. D. Store the release number in the Amazon S3 bucket name.
Answer: B. A single parameter is queryable, cheap and does not modify every resource. A forces replacement of resources. C is not evidence. D would force bucket replacement on each release.
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.
CloudFormation vs CDK vs Terraform
Compare the same secure bucket in CloudFormation, the AWS CDK (C#) and Terraform, score the tools against a bank's real criteria with a small C# decision scorer, and write an architecture decision record you could defend to your team.
Policy-as-code and secure deployment
Scan templates and plans before anything is deployed with cdk-nag, CloudFormation Guard, cfn-nag and Checkov, give pipelines least-privilege deploy roles, and stop a plan from deleting a database with a small C# guard.