diff --git a/README.md b/README.md index 95c6309..6881893 100644 --- a/README.md +++ b/README.md @@ -538,6 +538,14 @@ The emphasis is on doing a smaller set of backend/platform concerns properly: - AWS deployment fundamentals - CI discipline +### Commercial production boundary + +This repository demonstrates a production-representative AWS backend/platform slice, not a fully operated commercial production environment. + +The implemented slice shows the core responsibilities expected of a small real-world AWS service: private ECS task networking, RDS persistence, runtime secret injection, CloudWatch logging, CI, manual CD, smoke testing, and auditable policy enforcement. + +A real client production deployment would normally add further controls such as remote Terraform state, HTTPS/ACM, environment separation, monitoring and alerting, restore testing, migration version tracking, and a production credential-administration workflow. Those items are tracked as deliberate hardening boundaries rather than treated as forgotten requirements. + ## Engineering roadmap Planned hardening should remain tied to production-relevant gaps. diff --git a/docs/TRACKER.md b/docs/TRACKER.md index cac2191..befe035 100644 --- a/docs/TRACKER.md +++ b/docs/TRACKER.md @@ -285,9 +285,14 @@ Deferred AWS hardening: - HTTPS listener with ACM certificate - optional HTTP-to-HTTPS redirect -- Terraform remote state backend +- Terraform remote state backend with locking +- separate Terraform state/configuration for dev, staging, and production +- fuller CloudWatch alarms, dashboards, and alerting +- documented RDS backup/restore verification - migration version tracking -- production-grade credential registration/rotation workflow +- production-grade registered-agent credential registration and rotation workflow +- formal IAM/security review evidence +- fuller post-deploy MCP smoke checks in the CD/runbook flow --- diff --git a/docs/aws_deployment_target.md b/docs/aws_deployment_target.md index f5fd3ae..a3973f6 100644 --- a/docs/aws_deployment_target.md +++ b/docs/aws_deployment_target.md @@ -48,6 +48,34 @@ The application code should continue reading configuration through the existing The current AWS deployment runs the existing service using RDS-backed configuration, CloudWatch logging, private ECS task networking, and VPC endpoints for required AWS-service access. +## Production completeness boundary + +This AWS deployment is production-representative, not production-complete. + +It demonstrates the core infrastructure pattern required for a small real-world Python backend service: + +- public Application Load Balancer as the controlled ingress point +- ECS/Fargate app tasks running in private app subnets +- RDS PostgreSQL running in private DB subnets +- private AWS-service access through VPC endpoints +- runtime secrets injected from Secrets Manager +- CloudWatch log capture +- Terraform-managed infrastructure +- manual GitHub Actions CD into ECS + +A commercial production deployment would normally add further operational controls, including: + +- HTTPS with ACM certificate and optional HTTP-to-HTTPS redirect +- remote Terraform state with locking +- separate environment/state management for dev, staging, and production +- fuller monitoring, alarms, and operational alerting +- documented backup and restore testing +- migration version tracking +- production-grade credential registration and rotation workflow +- formal IAM/security review evidence + +These items are deliberately documented as production-hardening boundaries rather than implemented immediately. The project focuses on a complete, auditable AWS runtime slice that demonstrates the main backend/platform responsibilities without expanding into full enterprise operations. + ## Deferred scope Credential brokerage, STS-based tool credentials, S3-backed document reads, admin API, and advanced concurrency testing are deferred until the baseline deployment is working. diff --git a/docs/aws_operator_runbook.md b/docs/aws_operator_runbook.md index 9747ec3..f6db7cf 100644 --- a/docs/aws_operator_runbook.md +++ b/docs/aws_operator_runbook.md @@ -447,8 +447,12 @@ The current AWS environment is a development/portfolio deployment. Known non-production limitations: - HTTP only; HTTPS/ACM is not yet configured. -- Terraform state is currently local, not remote S3-backed state. +- Terraform state is currently local, not remote S3-backed state with locking. +- The deployment is single-environment rather than separated into dev, staging, and production. - RDS migration version tracking is not yet implemented. +- RDS backups are configured through the database service, but restore testing is not documented as part of this project. +- CloudWatch logging is implemented, but production alarms, dashboards, and alerting are not yet configured. - Dev credential registration is operational-script based, not a production admin workflow. - No NAT Gateway is currently deployed; this is acceptable for the current AWS-service-only egress model, but would need revisiting if the app calls external APIs. -- Post-deploy smoke testing currently checks `/health`; fuller MCP smoke checks remain manual. \ No newline at end of file +- Post-deploy smoke testing currently checks `/health`; fuller MCP smoke checks remain manual. +- Formal IAM/security review evidence is not packaged in the repo. \ No newline at end of file diff --git a/docs/aws_terraform_deployment_sequence.md b/docs/aws_terraform_deployment_sequence.md index d997bcb..566320d 100644 --- a/docs/aws_terraform_deployment_sequence.md +++ b/docs/aws_terraform_deployment_sequence.md @@ -953,4 +953,16 @@ The infrastructure must explicitly define: The Mermaid diagram shows the bones. -The Terraform resources define the tissue, routes, attachment points, permissions, and runtime wiring that make the architecture actually work. \ No newline at end of file +The Terraform resources define the tissue, routes, attachment points, permissions, and runtime wiring that make the architecture actually work. + +## Production hardening deliberately deferred + +This deployment sequence records the implemented AWS/Terraform build path for the current production-representative portfolio slice. + +The sequence does not claim to implement every control expected in a full commercial production environment. Production hardening items such as HTTPS/ACM, Terraform remote state, multi-environment state separation, restore testing, monitoring/alerting, migration version tracking, and production credential administration are documented as deliberate boundaries in: + +- `docs/aws_deployment_target.md` +- `docs/production_secret_and_state_security.md` +- `docs/aws_operator_runbook.md` + +This keeps the deployment sequence focused on what was actually built, while making the remaining commercial hardening boundary explicit. \ No newline at end of file diff --git a/docs/production_secret_and_state_security.md b/docs/production_secret_and_state_security.md index ae58952..8743c70 100644 --- a/docs/production_secret_and_state_security.md +++ b/docs/production_secret_and_state_security.md @@ -6,7 +6,7 @@ This document defines the production security approach for Terraform state and r The project rule is: -> Terraform manages infrastructure. +> Terraform manages infrastructure. > Secret values are created, owned, rotated, and administered outside Terraform. This keeps the infrastructure-as-code layer separate from the sensitive runtime credential layer. @@ -153,6 +153,14 @@ They may contain: Even without secret values, state should not be public or committed to Git. +### Current project boundary + +Remote Terraform state is documented here as the production recommendation, but it is not currently implemented for this portfolio/dev environment. + +The current project remains a single-operator deployment using local Terraform state, with the strict rule that local state files must not be committed to Git. + +Remote state should be added if the project moves beyond single-developer demonstration into shared infrastructure management, client handover, or a more production-like multi-environment workflow. + --- ## Repository rules