Land It on AWS GovCloud
Updated
IntermediateWhat you'll learn
~60 min- Point lesson 03's sign-in code at your agency's identity provider of record (the system that already authenticates your staff), and decide whether an Application Load Balancer (ALB, AWS's HTTP load balancer) should do the sign-in instead
- Land the database credential as a secret in Secrets Manager (AWS's secret store) with managed rotation (AWS replaces the password on a schedule), because Amazon RDS for SQL Server (AWS's managed SQL Server) has no passwordless login, and choose delivery 'runtime' over 'startup' on purpose
- Send traces through an OpenTelemetry collector sidecar (a second container in the same task that forwards telemetry) to AWS X-Ray (AWS's trace service), and validate the collector config before any deploy
- Separate what runs on your laptop (type check, unit tests, a LocalStack secret test, collector validation) from what needs your AWS account, and write the runbook for the second group
Lessons 34, 35 and 36 land the same seam on three clouds; read the one your agency uses, then lesson 37 for your code host. On a different cloud? Azure Government (34) · Google Cloud Assured Workloads (36).
One file lands the whole seam, and the database is the honest difference
Lessons 03, 05, 08 and 16 built the reference app against the platform seam and ran it on a laptop with the local implementation. Lesson 34 landed the same seam on Azure Government with a database that has no password. This lesson writes the AWS implementation, src/platform/aws/index.ts, and the passwordless part does not carry over: the managed SQL Server on AWS has no token login, so the database credential is a secret, and the work moves to storing it, rotating it and getting the new value to the running app.
Before the detail — Artifact: one file, src/platform/aws/index.ts, selected by PLATFORM=aws, a collector config, a deploy script, and a verification runbook. Acceptance test: the reference type-checks, its unit tests pass, a LocalStack test proves the adapter reads a rotated secret, both collector configs validate, and six checks that need your AWS account each have a command and an expected result you have run or have marked NOT RUN. Status of what follows: reusable guidance. The AWS choices are one landing of the seam, and none of it is a federal requirement.
What the file lands, and where each piece plugs in:
| Seam member | What the AWS file supplies | Core code that uses it |
|---|---|---|
identity | Issuer, client id and secret id of your identity provider, read from environment settings | src/lib/auth/oidc.ts (lesson 03) |
db.auth | A secret credential, kind secret, delivery runtime | src/lib/db/connection.ts and withPool (lesson 08) |
secrets.get | Secrets Manager reads | The sign-in client secret (lesson 03) |
telemetry.start | OTLP (OpenTelemetry’s wire protocol) to a collector sidecar on localhost | startTelemetry (lesson 16), reached through registerTelemetry |
| Host | ECS Fargate (AWS’s serverless container host), an image in ECR (AWS’s private image registry), PLATFORM=aws | The deploy steps (lesson 18) |
The model adapter is not in this file. It sits behind its own interface in lesson 26, the model call behind your API.
Availability, authorization, agency approval, region support, and price are five separate facts. This box holds the dated service facts for this lesson; the prose does not state any of them. Everything here is read from AWS documentation, not run against a live GovCloud account.
Regions and partition. GovCloud (US) has two regions, us-gov-west-1 and us-gov-east-1. Resource ARNs (Amazon Resource Names, the unique ids policies refer to) use the partition arn:aws-us-gov:. AWS says “If you require FIPS 140-3 compliance you should use the FIPS Endpoints”. Source: https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-cog.html and the Identity Center page in the same guide.
Secrets Manager. The GovCloud guide lists it in both regions: “AWS Secrets Manager is available in the following AWS GovCloud (US) Regions: AWS GovCloud (US-East) AWS GovCloud (US-West)”. One difference: “Managed External Secrets are not available.” Built-in rotation covers RDS. Source: https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-asm.html.
Database. “IAM database authentication isn’t available with the following engines: RDS for Db2, RDS for Oracle, RDS for SQL Server”. The only alternative is Windows Authentication through AWS Managed Microsoft AD, and the master user stays on SQL authentication. Source: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RDS_Fea_Regions_DB-eng.Feature.IamDatabaseAuthentication.html and https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_SQLServerWinAuth.html. GovCloud RDS uses the region-specific CA rds-ca-rsa4096-g1 and says “Intermediate SSL certificates must be used”: https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-rds.html. UNVERIFIED: which SQL Server engine versions GovCloud offers (“Instance types and engine versions might vary”).
Sign-in. An ALB can authenticate users itself (authenticate-oidc) and forwards claims in the x-amzn-oidc-data header; the legacy x-amzn-oidc-accesstoken and x-amzn-oidc-identity headers are unsigned. The identity provider’s endpoints “must be publicly resolvable”. The GovCloud ELB page says “Cognito authentication is not available”, so the ALB Cognito route is out. The ALB guide publishes GovCloud key endpoints for verifying the signed header: https://s3-us-gov-west-1.amazonaws.com/aws-elb-public-keys-prod-us-gov-west-1/key-id and the us-gov-east-1 equivalent. Source: https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-elb.html and https://docs.aws.amazon.com/elasticloadbalancing/latest/application/listener-authenticate-users.html. Cognito itself exists in both regions with FIPS endpoints only and no custom domains (govcloud-cog page above).
Host. ECS and Fargate are listed for both regions; “Amazon EKS on Fargate is not available”. App Runner does not appear in its endpoints table for us-gov-* (https://docs.aws.amazon.com/general/latest/gr/apprunner.html); treat it as not available, though the GovCloud page for it was not readable. ECR is listed for both regions with “Amazon ECR public registries are not available”. Sources: https://docs.aws.amazon.com/govcloud-us/latest/UserGuide/govcloud-ecs.html, govcloud-fargate.html, govcloud-ecr.html. Task roles give containers temporary credentials; the execution role (image pull, secret injection) is separate: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html. Secrets injected through the task definition’s secrets field arrive “when the container is initially started”, and a rotation reaches a task only by launching a new one or forcing a new deployment: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/secrets-envvar-secrets-manager.html.
Export control. The GovCloud guides say not to enter export-controlled data in names and similar fields; for ECR: “Do not enter export-controlled data in the following fields: Repository name Image tag Image manifest Lifecycle policy Repository policy”. RDS says the same for names and tags.
Telemetry. CloudWatch’s OTLP trace endpoint states “If using the OTLP endpoint for tracing, make sure that Transaction Search is enabled” (https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPSimplesetup.html), and the GovCloud CloudWatch page lists “Transaction Search is not available.” (govcloud-cw.html). X-Ray is listed for both regions with the note “Versions 3.1.0 or above of AWS X-Ray Daemon should be used.” (govcloud-xray.html). CloudWatch Logs is listed for both regions and “Use SSL (HTTPS)” (govcloud-cwl.html). UNVERIFIED: whether CloudWatch’s OTLP logs and metrics endpoints exist in GovCloud.
Recheck the cited source and your agency’s authorization boundary before you rely on any of it.
Sign-in: your identity provider, run by the app
AWS GovCloud does not hand you a workforce sign-in for your own application. IAM Identity Center (AWS’s single sign-on for AWS accounts) signs people in to the console, not to your app. So the reference does what lesson 03 already does: oidc.ts runs authorization code with PKCE (a one-time proof that the party finishing sign-in started it) against the identity provider your agency already uses, and the AWS file only reads where that provider is.
Plan the change with your agent
In gov-dev-reference-app, src/platform/aws/index.ts already ships so npm run typecheck runs out of the box (either audit the existing implementation against the checklist below, or run git rm src/platform/aws/index.ts on a practice branch to watch the agent build it from scratch). Open your agent in the project root and switch to Plan mode (Shift+Tab, /plan, or the mode picker). Ask it to read the platform seam types and plan the AWS implementation:
Read src/platform/types.ts and src/platform/local/index.ts without editing, and plan src/platform/aws/index.ts for OIDC identity, RDS SQL Server secret auth via Secrets Manager, and OTLP telemetry. Ask me anything unclear first.What to check in the plan before you approve
identityreadsOIDC_ISSUER,OIDC_CLIENT_ID, andOIDC_CLIENT_SECRET_IDfrom environment variables without hardcoding a vendor, tenant, or region, and extracts string roles fromclaims.roles.db.authuseskind: 'secret'withdelivery: 'runtime', fetchingRDS_SECRET_IDfrom Secrets Manager on demand, parsingusernameandpassword, takingrotatedAtfrom the secret version’sCreatedDate, and requiringROTATION_OWNER.SecretsManagerClientrequiresAWS_REGIONwith no default and enables FIPS endpoints whenAWS_USE_FIPS_ENDPOINT === 'true'.telemetry.startdefaultsOTEL_EXPORTER_OTLP_ENDPOINTtohttp://localhost:4318so traces flow to the local OpenTelemetry collector sidecar and on to X-Ray.
If the first plan injects the RDS database password as an ECS task definition environment variable and still labels delivery: 'runtime', correct it before approving:
Keep the database credential out of ECS task definition environment variables and fetch RDS_SECRET_ID at runtime with GetSecretValue so delivery: 'runtime' is accurate.The reference identity block in src/platform/aws/index.ts from gov-dev-reference-app (compare with what your agent writes; you do not type it by hand):
// src/platform/aws/index.ts (excerpt)export const awsPlatform: Platform = { name: 'aws', identity: { // The agency's identity provider of record; the app runs the OIDC flow itself (lesson 03). issuer: need('OIDC_ISSUER'), clientId: need('OIDC_CLIENT_ID'), clientSecretName: need('OIDC_CLIENT_SECRET_ID'), scopes: ['openid', 'profile'], // Which claim carries roles depends on the provider; this reference expects `roles`. rolesFrom: (claims) => (Array.isArray(claims.roles) ? claims.roles.filter((r): r is string => typeof r === 'string') : []), },Nothing in it names a vendor. OIDC_CLIENT_SECRET_ID is the secret’s name or ARN, never its value: oidc.ts receives the value from platform.secrets.get. The comment on rolesFrom is the one place to adapt: if your provider puts roles in another claim, change that one line, and lesson 05 still maps the raw names to the closed role set.
The alternative: let the load balancer sign people in. An ALB can run the OpenID Connect flow itself and forward the result in a signed header. Commercial starting practice: many teams do this to keep sign-in code out of the app. The GovCloud delta (see the status box): the Cognito option is not offered on the ALB, so the only route is authenticate-oidc against your provider, whose endpoints must be publicly resolvable. The handoff artifact is the header, and it changes what the app must do:
- Verify the
x-amzn-oidc-dataJWT’s signature against the GovCloud public-key endpoint for your region, and check that thesignerfield in its header names your ALB’s ARN. - Strip the unsigned legacy headers (
x-amzn-oidc-accesstoken,x-amzn-oidc-identity) before any code can read them. - Refuse any request that reaches the container without the signed header, so a direct hit on the task cannot claim an identity.
What is not equivalent: with the ALB route the session is the load balancer’s, not the app’s, so lesson 03’s __Host-app_sid cookie, state and nonce checks are not exercised, and the roles claim comes from whatever the provider puts in the forwarded token. The reference implements the first route (the app runs the flow), so the standards library’s issuer and audience checks stay in your code. You decide which your agency has approved; if you choose the ALB, write the header verification as a new file and test it with a forged header.
A database with a secret, and rotation that reaches the app
Lesson 08 split the credential into two kinds. On AWS the secret kind applies: RDS for SQL Server has no token login, so the app holds a user and password, and the password lives in Secrets Manager. “No stored credential” is a property of the Azure landing, not of the seam. The honest AWS property is smaller and still worth having: one SQL login, held in the secret store, never in the image or the repository, with a named rotation owner.
REFERENCE CODE src/platform/aws/index.ts (excerpt): runtime secret credential from Secrets Manager open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
// src/platform/aws/index.ts (excerpt) db: { target: { server: need('RDS_ENDPOINT'), database: need('RDS_DATABASE') }, auth: { kind: 'secret', // The RDS rotation function writes { username, password, ... }; the version's // CreatedDate is when that rotation happened, so no extra permission is needed. get: async (): Promise<SecretCredential> => { const out = await secretValue(need('RDS_SECRET_ID')); const v = JSON.parse(out.SecretString!) as { username: string; password: string }; return { user: v.username, password: v.password, rotatedAt: (out.CreatedDate ?? new Date(0)).toISOString() }; }, rotationOwner: need('ROTATION_OWNER'), maxAgeDays: Number(process.env.ROTATION_MAX_AGE_DAYS ?? 30), delivery: 'runtime', // fetched by the app with GetSecretValue, not injected into the task definition }, },Four things to read in it.
- The secret has the shape RDS rotation writes. Managed rotation updates the secret’s
usernameandpasswordfields, so the code reads those two and nothing else. rotatedAtcosts no extra permission. The version’sCreatedDateis the moment rotation wrote the new value, andGetSecretValuealready returns it. Lesson 08’scheckRotation()uses it withmaxAgeDaysto tell you when a credential is overdue.rotationOwneris a name, required when the file loads. A rotation with no one answering for it is the failure this field exists to prevent.delivery: 'runtime'is a claim about how the value reaches the app, and it must be true. The app callsGetSecretValueitself each time lesson 08’s provider needs a credential, so a rotation is picked up on the next login or on the single refresh after a failed one. ECS can also inject a secret into the container as an environment variable, but then the value is fixed when the task starts. That is delivery'startup': a rotation reaches the app only through a new deployment, and the runbook must say who forces it and how soon. Choose one per secret; do not label an injected secret'runtime'.
Transport. Connect to RDS over TLS and trust the RDS certificate chain for your region rather than turning verification off. The status box names the GovCloud-specific CA; download the bundle from AWS, bake it into the image, and point the driver at it. Never set trustServerCertificate outside a laptop.
What the RDS service does not run. The managed engine removes features a legacy database may rely on: CLR on SQL Server 2017 and later, xp_cmdshell, and full linked-server support are among them, and the time zone is fixed when the instance is created. Those are lesson 24’s parity questions, answered by its schema contract; check them before you choose the target, not after the first failed restore.
Local proof of the adapter’s reading. The reference tests the AWS file against LocalStack (a local stand-in for Secrets Manager), so the reading of the secret is not an act of faith:
REFERENCE TEST tests/env/aws-secrets.env.test.ts (excerpt): LocalStack verification of rotated RDS secret reading open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
// tests/env/aws-secrets.env.test.ts (excerpt) it('reads the RDS-shaped secret and takes rotatedAt from the version, then sees a rotation', async () => { const sm = new SecretsManagerClient({}); await sm.send(new CreateSecretCommand({ Name: env.RDS_SECRET_ID, SecretString: JSON.stringify({ engine: 'sqlserver', username: 'app_user', password: 'first-Aa1!' }) })); const { awsPlatform } = await import('../../src/platform/aws/index.ts'); if (awsPlatform.db.auth.kind !== 'secret') throw new Error('expected secret'); const a = await awsPlatform.db.auth.get(); expect(a).toMatchObject({ user: 'app_user', password: 'first-Aa1!' }); await new Promise((r) => setTimeout(r, 1100)); await sm.send(new PutSecretValueCommand({ SecretId: env.RDS_SECRET_ID, SecretString: JSON.stringify({ engine: 'sqlserver', username: 'app_user', password: 'second-Aa1!' }) })); const b = await awsPlatform.db.auth.get(); expect(b.password).toBe('second-Aa1!'); expect(Date.parse(b.rotatedAt)).toBeGreaterThan(Date.parse(a.rotatedAt)); // the new version's CreatedDate expect(awsPlatform.db.auth.delivery).toBe('runtime'); });Run against LocalStack, that test passed: 1 test passed. It proves the adapter’s reading (user and password parsed, rotatedAt from the version, a second version seen as a rotation). It does not prove GovCloud, the RDS rotation function, or a login to a real instance; those are NOT RUN below.
Secrets: Secrets Manager behind platform.secrets.get
Here is the reference SecretsManagerClient and secrets.get implementation in src/platform/aws/index.ts from gov-dev-reference-app:
// src/platform/aws/index.ts (excerpt)const sm = new SecretsManagerClient({ region: need('AWS_REGION'), useFipsEndpoint: process.env.AWS_USE_FIPS_ENDPOINT === 'true' });
async function secretValue(id: string) { const out = await sm.send(new GetSecretValueCommand({ SecretId: id })); if (out.SecretString === undefined) throw new Error(`secret ${id} has no string value`); return out;}// ... secrets: { get: async (name) => (await secretValue(name)).SecretString! },The task role (the identity AWS hands the running container) supplies credentials, so no access key appears anywhere. AWS_REGION is read from the environment and has no default, so a missing region stops the process instead of silently calling the wrong endpoint. AWS_USE_FIPS_ENDPOINT=true switches the client to the FIPS endpoints; set it where your agency’s cryptography requirements say to.
Give the task role read access to exactly the two secrets the code reads, in the GovCloud partition (reference IAM policy pattern for your infrastructure config):
{ "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": [ "arn:aws-us-gov:secretsmanager:us-gov-west-1:<account-id>:secret:<db-secret-name>-*", "arn:aws-us-gov:secretsmanager:us-gov-west-1:<account-id>:secret:<oidc-client-secret-name>-*" ] }]}An ARN written with the commercial partition (arn:aws:) matches nothing here and fails as access denied, so copy ARNs from the GovCloud console or CLI, never from a commercial example. A wildcard resource is how a task ends up able to read every secret in the account.
The export-control naming rule, as a lint you add. The status box records that AWS tells GovCloud users not to put export-controlled data in secret names, ECR repository names and tags, log group names, or resource names and tags. Nothing in the platform enforces it, because the platform cannot know what your agency treats as controlled. Add a reference check like scripts/lint-names.sh from gov-dev-reference-app to your pipeline that fails on a term your export-control officer supplies:
#!/usr/bin/env bash# scripts/lint-names.sh <terms-file> <file>... (deny list comes from your export-control officer)set -euo pipefailTERMS="${1:?usage: lint-names.sh <terms-file> <file>...}"; shiftif grep -n -i -F -f "$TERMS" "$@"; then echo "lint-names: a name or tag contains a listed term" >&2 exit 1fiRun it over the infrastructure definitions and the task definition, and keep the terms file out of the repository’s public history. It cannot see names created by hand in the console, so the runbook below asks a person to look.
Telemetry: a collector sidecar to X-Ray
Lesson 16’s startup hook calls platform.telemetry.start. In the reference implementation from gov-dev-reference-app, that function does almost nothing, on purpose: the app keeps sending standard OTLP, and the destination is the collector’s business:
// src/platform/aws/index.ts (excerpt) telemetry: { // OTLP to the collector sidecar in the same task; its config exports traces to X-Ray. start: async (serviceName) => { process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??= 'http://localhost:4318'; const { startTelemetry } = await import('../../lib/telemetry/start.ts'); startTelemetry(serviceName); }, },The sidecar is a second container in the same ECS task, listening on port 4318, so localhost from the app reaches it. Its configuration, from the reference:
REFERENCE CONFIG deploy/aws/otel-collector.yaml (excerpt): OpenTelemetry collector sidecar exporting to X-Ray open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
# deploy/aws/otel-collector.yaml (excerpt)receivers: otlp: protocols: http: endpoint: 0.0.0.0:4318processors: batch: {}exporters: awsxray: region: ${env:AWS_REGION}service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [awsxray]Why X-Ray and not the CloudWatch OTLP trace endpoint: the status box records that the CloudWatch trace endpoint requires Transaction Search and the GovCloud CloudWatch page says it is not there. The awsxray exporter sends traces to X-Ray directly, and the task role needs permission to write trace segments. If you run the X-Ray daemon rather than this exporter, the status box names the minimum version.
Logs. The container’s standard output goes to CloudWatch Logs over HTTPS through the ECS log driver. Whether OTLP logs or metrics endpoints exist in GovCloud was not verified, so this lesson does not use them. Remember the naming rule from the last section: log group names are names.
Validate the collector config before you deploy it. A typo in an exporter name only shows up when the collector starts in your cluster, and a collector that fails to start leaves the app running with no traces. The reference ships a validation script that runs the real collector’s validate command against each cloud’s config:
cd gov-dev-reference-appnpm run validate:collectorsFor this lesson’s config that command passes (the Google config is validated in the same run). The negative case was run too: a planted bad exporter name makes validation fail, which is the behavior you want from a gate. Neither proves a trace reaches X-Ray; that is a runbook check.
The host: ECS Fargate and ECR
The app runs as one container image, plus the collector sidecar, as an ECS service on Fargate. ECR holds the image. App Runner, the simpler host, is not a choice here (status box), and ECR public registries are unavailable, so the image lives in a private registry in your account. Lesson 18 has the image and deploy steps; the AWS-specific settings are these:
| Task definition setting | Value |
|---|---|
PLATFORM | aws (any other value fails at startup; mainframe fails with PLATFORM must be one of: local, azure, aws, google) |
AWS_REGION | us-gov-west-1 or us-gov-east-1; no default |
AWS_USE_FIPS_ENDPOINT | true where your cryptography requirements say so |
OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET_ID | Your identity provider; the last is a secret’s name or ARN |
RDS_ENDPOINT, RDS_DATABASE, RDS_SECRET_ID | Copy the endpoint from your console, never from an AI answer |
ROTATION_OWNER, ROTATION_MAX_AGE_DAYS | A named owner (required) and the age at which lesson 08’s check calls the credential overdue (default 30) |
OTEL_EXPORTER_OTLP_ENDPOINT | Unset is fine; the file defaults to http://localhost:4318 |
Which missing setting fails when. AWS_REGION, OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET_ID, RDS_ENDPOINT, RDS_DATABASE and ROTATION_OWNER are read with need(...) while the file loads, so the process stops at startup and the error names the setting. RDS_SECRET_ID is read inside the credential’s get() callback, so a missing value fails on the first database use, not at startup. Put it in the same startup check as the others.
Two IAM roles, and the difference matters. The execution role lets ECS pull the image from ECR and write logs. The task role is what your code runs as; it holds only the secret-read policy above plus permission to write traces. Do not put secrets into the task definition’s secrets field for anything the code reads through platform.secrets.get; that would deliver the value once at startup and make the ‘runtime’ label untrue.
Lesson 19’s deploy stage calls scripts/deploy/<PLATFORM>.sh with one argument: the digest-qualified image reference, registry/repo@sha256:.... For this platform the script copies the service’s current task definition, replaces the app container’s image with the digest, registers that as a new revision, updates the service, waits for ECS to report the service stable, and refuses to report success until the health URL from lesson 18 answers:
REFERENCE CODE scripts/deploy/aws.sh: register ECS task definition by image digest and verify health open reference hide reference Reference implementation from gov-dev-reference-app; open to inspect or compare with what your agent builds.
#!/usr/bin/env bash# scripts/deploy/aws.sh <registry/repo@sha256:...>set -euo pipefail
IMAGE="${1:?usage: aws.sh <registry/repo@sha256:digest>}": "${ECS_CLUSTER:?}" "${ECS_SERVICE:?}" "${HEALTH_URL:?}"CONTAINER="${APP_CONTAINER:-app}"TIMEOUT="${HEALTH_TIMEOUT_SECONDS:-300}"tmp="$(mktemp)"; trap 'rm -f "$tmp"' EXIT
CURRENT=$(aws ecs describe-services --cluster "$ECS_CLUSTER" --services "$ECS_SERVICE" \ --query 'services[0].taskDefinition' --output text)aws ecs describe-task-definition --task-definition "$CURRENT" --query taskDefinition --output json \ | jq --arg c "$CONTAINER" --arg i "$IMAGE" \ 'del(.taskDefinitionArn, .revision, .status, .requiresAttributes, .compatibilities, .registeredAt, .registeredBy) | .containerDefinitions |= map(if .name == $c then .image = $i else . end)' > "$tmp"NEW=$(aws ecs register-task-definition --cli-input-json "file://$tmp" \ --query taskDefinition.taskDefinitionArn --output text)aws ecs update-service --cluster "$ECS_CLUSTER" --service "$ECS_SERVICE" --task-definition "$NEW" > /dev/nullaws ecs wait services-stable --cluster "$ECS_CLUSTER" --services "$ECS_SERVICE"
deadline=$((SECONDS + TIMEOUT))until curl -fsS -o /dev/null "$HEALTH_URL"; do if (( SECONDS >= deadline )); then echo "deploy: $HEALTH_URL did not return 200 within ${TIMEOUT}s" >&2 exit 1 fi sleep 5doneecho "deploy: $IMAGE is serving at $HEALTH_URL"The digest, not a tag, goes into the task definition, so what runs is exactly what lesson 19’s build produced. aws ecs wait ends non-zero if the service does not stabilize, and the health route does not touch the database (lesson 18), so a slow database cannot fail the deploy. Set AWS_USE_FIPS_ENDPOINT=true in the pipeline’s environment so the CLI uses the same endpoints as the app. This script has not been run against an account; see the check in “Prove it”.
Kubernetes (EKS) is the exception, not the starting point: this module is PaaS first, and an orchestrator earns its place only when no managed container host can run the workload.
Plan, implement, check
The file already exists in the reference. In your own repository you would have your AI CLI write it, and the order matters: read-only planning first, then implementation, then the type check and tests. Planning spellings per tool are in lesson 02’s four-tool table.
- Typed in the terminal:
claude - Mode:Plan mode
- You type in the session: Read src/platform/types.ts and src/platform/local/index.ts. Plan src/platform/aws/index.ts: identity, db auth, secrets, telemetry. RDS for SQL Server has no IAM login. Do not edit.
- The tool replies: Plan (read-only, nothing edited): 1. identity: issuer, client id and client-secret id from OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET_ID. No provider named in code. rolesFrom reads the roles claim and keeps strings only. 2. db: target from RDS_ENDPOINT and RDS_DATABASE. Auth kind 'secret': read the secret named by RDS_SECRET_ID, parse username and password, rotatedAt from the version's CreatedDate. rotationOwner required. 3. delivery: 'runtime', because the app calls GetSecretValue itself. If an ECS secrets injection were used it would have to be 'startup'. 4. secrets: one Secrets Manager client, region from AWS_REGION with no default, FIPS endpoints behind AWS_USE_FIPS_ENDPOINT. 5. telemetry: default OTEL_EXPORTER_OTLP_ENDPOINT to http://localhost:4318 and call startTelemetry. The collector config is a separate file. Open question I cannot answer from the repository: whether your provider puts roles in a claim named roles. I will say so in a comment.
- Mode:Plan approved: plan mode off
- You type in the session: Approved. Implement it. Fail at startup if a required setting is missing, and name the setting. Add deploy/aws/otel-collector.yaml exporting traces to X-Ray.
- The tool replies: Created src/platform/aws/index.ts and deploy/aws/otel-collector.yaml. - A need(name) helper throws '<NAME> is not set'. A missing OIDC_ISSUER stops the process at startup; a missing RDS_SECRET_ID is read inside the credential's get() callback and fails on first database use, so check it at startup too. - The platform is registered in src/platform/index.ts under 'aws' and loaded lazily, so PLATFORM=local never reads these settings. - The collector config receives OTLP over HTTP on 4318 and exports through awsxray. I did not use the CloudWatch trace endpoint.
- You type in the session: Run the type check and the unit tests, then the validation for the collector configs.
- The tool replies: $ cd gov-dev-reference-app && npx tsc --noEmit $ echo $? 0 $ npx vitest run tests/unit/connection.test.ts 12 tests passed $ npm run validate:collectors (both collector configs validated) The AWS file satisfies the Platform interface: db.auth is the 'secret' kind with delivery 'runtime', secrets.get returns Promise<string>, telemetry.start returns Promise<void>. This proves names, types and config syntax. It does not prove a login, a task-role read, a rotation reaching a running task, or a trace in X-Ray; those need your account.
- You type in the session: In staging, the app starts, then database requests fail after the password rotated. Diagnose without changing code.
- The tool replies: A rotation alone should not cause a lasting failure with this adapter. The pool holds a config built from the old password, so the first new connection after rotation gets ELOGIN, and lesson 08's provider then fetches the secret once through GetSecretValue and retries. Check, in order: 1. What error do callers see? One ELOGIN followed by success is the design working. CredentialRefreshFailed ('runtime') means the freshly read credential also failed to log in: ask the rotation owner whether the rotation finished and whether the account is locked. 2. AccessDeniedException from GetSecretValue naming the secret means the refresh could not read it. Compare the task role's policy resource with the secret's full ARN, which ends in a random suffix; a secret recreated under the same name has a different ARN. 3. RDS_SECRET_ID unset or wrong fails when get() runs, not at startup. No code change in any case. An unused copy of the secret in the task definition cannot cause this: the adapter reads only through GetSecretValue.
Illustrative session in Claude Code; the exact wording varies.
Prove it
Two groups of checks. Run the first on your laptop now; the second needs your AWS account, so each line carries a status you fill in.
Runs locally. From the repository root of the reference:
cd gov-dev-reference-appnpx tsc --noEmitnpx vitest run tests/unit/connection.test.tsnpm run validate:collectorsnpx tsc --noEmit type-checks the AWS file against the seam’s interface. npx vitest run tests/unit/connection.test.ts runs the connection provider’s unit tests (12 passed on the reference), which cover both kinds of credential. npm run validate:collectors passes for both collector configs, and a planted bad exporter name fails it. The LocalStack test above (1 test passed) covers the secret reading. None of these starts a real AWS client against GovCloud.
Needs your AWS account (NOT RUN here). None of these has been run against a live GovCloud account for this lesson. The runbook, with the expected result:
| Check | Command or action | Expected | Status |
|---|---|---|---|
| Sign-in | Set PLATFORM=aws and the settings above, open /auth/login, sign in as a user your provider has given a role | The session holds sub, your provider’s issuer, a name, and the role names you assigned | NOT RUN |
| Task role secret read | From the running task (aws ecs execute-command) or a test task with the same role, run aws secretsmanager get-secret-value --secret-id <db-secret> --query VersionId; then repeat with a secret outside the two ARNs | The two named secrets return a version id; the other returns AccessDenied | NOT RUN |
| RDS login | In the app, run one read through withPool; check the instance’s connection log or run SELECT SUSER_NAME() once | The read returns rows under the secret’s username, over TLS | NOT RUN |
| Rotation reaching the task | Trigger rotation (aws secretsmanager rotate-secret --secret-id <db-secret>), wait for it to finish, then make a request that opens a new connection | The request succeeds without a redeploy, and rotatedAt read by lesson 08’s check moves forward | NOT RUN |
| X-Ray traces | Make three requests, then open the X-Ray trace list in the GovCloud console | Traces for your service appear within a few minutes, under the service name you set | NOT RUN |
| Deploy script | Export ECS_CLUSTER, ECS_SERVICE and HEALTH_URL, run scripts/deploy/aws.sh "$REGISTRY/platform-app@sha256:<digest>" with a digest already in ECR; then rerun it with HEALTH_URL pointing at a stopped service and HEALTH_TIMEOUT_SECONDS=30 | The first run prints the serving line and exits 0; the second exits non-zero after the timeout | NOT RUN |
The negative cases belong in the runbook too. Remove the task role’s grant and expect a failed read with the secret’s id in the error. Point the task role’s policy at a different secret ARN and expect the AccessDeniedException from the session above on the first connection that needs a refresh. Set PLATFORM=mainframe and expect the startup error from the table; the reference’s environment tests already prove that last one against the local stack. Finally, have a person read the console for any resource name, tag or log group that the lint cannot see.
Your team wants the same 'no database password' result on RDS for SQL Server that the Azure landing has. What is the accurate position?
After a rotation, the first request that needs a new connection gets ELOGIN, and the retry then raises AccessDeniedException from GetSecretValue naming the database secret. What is the most likely cause?
Practice status
| Practice | Status | Also called |
|---|---|---|
| Database credential in a secret store with managed rotation and a named owner | common baseline | secret rotation, credential lifecycle |
| Declare how a rotated secret reaches the running app (‘runtime’ fetch or ‘startup’ injection) and write the redeploy runbook for the second | strong optional | secret delivery mode, rotation propagation |
| Task role scoped to the exact secret ARNs the code reads | common baseline | least-privilege workload role |
| Sign-in run by the app against the identity provider of record | common baseline | app-level OIDC |
| Sign-in run by the load balancer, with signed-header verification in the app | strong optional | edge authentication, forwarded identity |
| Telemetry as OTLP to a collector sidecar, destination set in the collector | common baseline | OpenTelemetry collector, agent sidecar |
| Validate collector config in CI before deploy | strong optional | config validation gate |
| Deny-list lint on resource, secret, repository and log names for export-controlled terms | reference-shop | naming-rule lint |
| Managed container host first, Kubernetes by exception | strong optional | PaaS first |
Scale: required | common baseline | strong optional | reference-shop (seen only at organizations that publish their own practice) | emerging
Key takeaway
- AWS GovCloud is one implementation of the seam. Core code did not change; one file supplies identity settings, a secret credential, a Secrets Manager client and an OTLP start, and a collector config sends the traces to X-Ray.
- The database is the honest difference: RDS for SQL Server has no passwordless login, so the work is a rotated secret, a named owner, and a delivery label that is true in the task definition as well as in the file.
- The type check, unit tests, LocalStack test and collector validation prove the file’s shape and its reading of a rotated secret. Sign-in, the task-role read, the RDS login, rotation reaching the task, X-Ray traces and the deploy script need your account and stay NOT RUN until you run them.
- LEADERSHIP DECISION
- Who owns database credential rotation on this cloud, and whether your agency accepts an app-run or a load-balancer-run sign-in against its identity provider.
- PRACTITIONER ACTION
- Scope the task role to the two secret ARNs, keep the database secret out of the task definition's secrets field, add the name lint, then run the six runbook checks and record each result.
- SUCCESS MEASURE
- Audit finding avoided: a rotation completes with no redeploy and no login failure, and no database password appears in the image, the repository or the task definition.
Legend: LEADERSHIP DECISION = what a leader decides · PRACTITIONER ACTION = what the engineer does next · SUCCESS MEASURE = how you know, in calendar time, assessor-hours or cost, contract or revenue risk, or audit finding avoided