infra: configure remote Terraform state backend with S3 and DynamoDB locking

[snowrugar-beep]

Problem Statement

The Terraform configuration in infrastructure/terraform/ uses only local state storage. This means every team member and CI pipeline operates on their own isolated state — there is no shared source of truth for infrastructure. State conflicts, duplicate resource creation, and unrecoverable state loss are inevitable in a team environment.

Evidence

• infrastructure/terraform/providers.tf — No backend "s3" {} block; Terraform defaults to local state
• infrastructure/terraform/workspaces.tf — Multi-environment workspace config exists but without remote state, workspace isolation is limited to local files
• No terraform { backend "s3" { ... } } configuration anywhere in the codebase
• No DynamoDB table for state locking

Impact

Team members cannot safely run Terraform concurrently. CI/CD pipelines cannot reliably detect drift. State file loss would result in manual reconstruction of all infrastructure resources. No audit trail of who applied which changes.

Proposed Solution

1. Create an S3 bucket for Terraform state storage (via a separate bootstrap script or a minimal Terraform config)
2. Configure DynamoDB table for state locking to prevent concurrent modifications
3. Add backend "s3" configuration to providers.tf with environment-specific key prefixes (e.g., vertexchain/terraform/dev/terraform.tfstate)
4. Configure state encryption with KMS or AES-256
5. Enable bucket versioning for state file history and rollback capability
6. Update CI/CD pipelines to use the same remote state backend
7. Document the bootstrap process for new developers

Technical Requirements

• S3 bucket must have versioning enabled for state history
• DynamoDB table must have a primary key of LockID (String) for Terraform locking
• Must support multi-environment state isolation (dev/staging/prod)
• State encryption must be enabled at rest (AES-256 or KMS)
• Access to the state bucket must be restricted via IAM policies
• CI/CD workflows must authenticate to the state backend via OIDC or GitHub Actions secrets

Acceptance Criteria

1. terraform init configures remote state backend
2. terraform apply locks state via DynamoDB
3. Concurrent terraform plan from two terminals shows locking in action
4. State file version history is accessible in S3 bucket
5. CI pipeline uses remote state and can plan/apply infrastructure changes
6. terraform workspace select dev/staging/prod uses separate state keys
7. New developer can bootstrap with documented one-time setup

File Inventory

• infrastructure/terraform/providers.tf
• infrastructure/terraform/workspaces.tf
• infrastructure/scripts/bootstrap-state.sh (new)

Dependencies

None.

Testing Strategy

• Manual: run terraform init and verify backend switch
• Manual: run concurrent terraform operations and verify locking
• CI: verify pipeline can plan against remote state

Security Considerations

S3 bucket must have public access blocked. IAM policies must restrict state access to authorized principals. DynamoDB table must be encrypted. State files may contain sensitive values (database passwords, API keys) — consider using KMS encryption or a dedicated secrets backend.

Definition of Done

• S3 bucket created with versioning
• DynamoDB table created for locking
• Backend configured in Terraform
• CI/CD updated for remote state
• Documentation written for bootstrap
• Security considerations addressed

[Mkalbani]

Hi maintainers, can I work on this. I've worked on a similar work. Thank you.

[Mkalbani]

Hi maintainers, can I work on this. I've worked on a similar work. Thank you.

[Menjay7]

Hi! I came across this issue and would love to work on it. I have experience with similar tasks and I'm confident I can investigate, implement a clean solution, and thoroughly test it before submitting a PR. If the issue is still open, I would appreciate it if you could assign it to me. Thank you!

[MicD746]

Hello Maintainer, please can I work on this issue and give you a better result

[grantfox-oss]

🦊 GrantFox — @Mkalbani has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #49)
2. Your PR will be reviewed by the VertexChainLabs maintainers

Good luck! Track your progress on GrantFox.