Skip to content

bootstrap-and-operations.md

Latest commit

 

History

History
98 lines (73 loc) · 3.16 KB

bootstrap-and-operations.md

File metadata and controls

98 lines (73 loc) · 3.16 KB
Raw

Bootstrap And Operations

Fresh Account Bootstrap

  1. Enable MFA for root and avoid day-to-day root usage.
  2. Select a single primary region for MVP.
  3. Bootstrap CDK:
   npx cdk bootstrap aws://<account-id>/<region>
  1. Configure GitHub OIDC:
    • Create token.actions.githubusercontent.com IAM OIDC provider.
    • Create deploy roles for dev and prod.
    • Restrict trust to repository and branch/environment claims.
  2. Set GitHub environments:
    • dev and prod
    • AWS_REGION variable
    • AWS_DEPLOY_ROLE_ARN secret

Deploy

# synth
npm run cdk:synth

# deploy dev
npx cdk deploy TrustedLearningContextServiceStack-dev --context stage=dev --require-approval never

# deploy prod
npx cdk deploy TrustedLearningContextServiceStack-prod --context stage=prod --require-approval never

API Authentication (Cognito)

  • The platform stack provisions Cognito resources for API auth:
    • user pool
    • user pool domain
    • app clients for OAuth2 client credentials flow
  • Stack outputs include issuer URL, token endpoint, and app client IDs.
  • Retrieve app client secrets with aws cognito-idp describe-user-pool-client for the created user pool/client IDs.
  • Use token endpoint /oauth2/token to mint bearer tokens and call API routes.

Delete An Environment

Use these steps when you want to tear down an entire stage (for example dev) in AWS.

  1. Destroy the CDK stack:
npx cdk destroy TrustedLearningContextServiceStack-dev --context stage=dev --force
  1. Delete retained data resources created by the stack. By default, some resources are retained to protect data (DynamoDB tables and S3 bucket), so remove them manually:
# Empty and remove the stage bucket (replace with your actual bucket name)
aws s3 rm s3://<raw-payload-bucket-name> --recursive
aws s3 rb s3://<raw-payload-bucket-name>

# Delete stage DynamoDB tables
aws dynamodb delete-table --table-name TrustedLearningContextCredentialTable-dev
aws dynamodb delete-table --table-name TrustedLearningContextEventTable-dev
aws dynamodb delete-table --table-name TrustedLearningContextSubmissionTable-dev
  1. (Optional) remove CI/CD/OIDC infrastructure for that repo if you no longer deploy from GitHub Actions:
# If you deployed the CICD stack via CDK
npx cdk destroy TrustedLearningContextServiceCicdStack-dev --context stage=dev --force

# Optional manual cleanup if needed
aws iam delete-role --role-name GitHubDeployRoleDev
  1. Verify cleanup:
    • CloudFormation stack is deleted.
    • No *-dev DynamoDB tables remain.
    • trusted-learning-context-service-queue-dev and trusted-learning-context-service-dlq-dev are gone.
    • The stage API endpoint no longer responds.

Observability Checklist

  • Monitor DLQ message count alarm.
  • Monitor Persist Lambda errors.
  • Monitor API 5xx alarm.
  • Monitor DynamoDB throttling alarm.
  • Review dashboard trusted-learning-context-service-<stage>.

Replay And Idempotency

  • Transport ID: submissionId (ULID-derived).
  • Persistence IDs: deterministic hash-derived IDs.
  • Duplicate content produces same credentialId / eventId.
  • Persistence writes use conditional expressions to avoid accidental overwrite.