aws-localstack/README.md

aws-localstack

OpenTofu project for provisioning AWS resources on LocalStack for the Quantum application.

LocalStack endpoint:

https://localstack.paulononato.com.br

Resources

• S3 bucket for Quantum application artifacts.
• SQS main queue and DLQ.
• Python Lambda function for event processing.
• IAM role and policies for the Lambda function.
• CloudWatch Log Group.
• Secrets Manager secret with application configuration.
• Event source mapping SQS -> Lambda.

Repository Layout

.
+-- environments
|   +-- dev
|   +-- stg
|   +-- prd
+-- examples
+-- modules
    +-- quantum

Each environment is an independent OpenTofu root module. The shared infrastructure code lives in modules/quantum.

Prerequisites

• OpenTofu installed.
• AWS CLI, optional for testing.
• Access to the LocalStack endpoint.

Credentials used by LocalStack:

export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_DEFAULT_REGION=us-east-1

On PowerShell:

$env:AWS_ACCESS_KEY_ID="test"
$env:AWS_SECRET_ACCESS_KEY="test"
$env:AWS_DEFAULT_REGION="us-east-1"

Usage

Choose an environment first:

cd environments/dev

Use environments/stg or environments/prd for the other stages.

Initialize:

tofu init

Plan:

tofu plan

Apply:

tofu apply

Destroy:

tofu destroy

Docker Usage

You can run OpenTofu from a Docker container instead of installing it on the host.

Build the runner image:

docker compose build tofu

Run init for the default dev environment:

docker compose run --rm tofu init

Run plan:

docker compose run --rm tofu plan

Run apply:

docker compose run --rm tofu apply

Select another environment with QUANTUM_ENV:

QUANTUM_ENV=stg docker compose run --rm tofu plan
QUANTUM_ENV=prd docker compose run --rm tofu plan

On PowerShell:

$env:QUANTUM_ENV="stg"
docker compose run --rm tofu plan

Quick Tests

List buckets:

aws --endpoint-url https://localstack.paulononato.com.br s3 ls

Send a message to the Quantum queue:

aws --endpoint-url https://localstack.paulononato.com.br sqs send-message \
  --queue-url "$(tofu output -raw quantum_queue_url)" \
  --message-body file://../../examples/quantum-message.json

Read the secret:

aws --endpoint-url https://localstack.paulononato.com.br secretsmanager get-secret-value \
  --secret-id "$(tofu output -raw quantum_secret_name)"

RDS Note

RDS is not included in the LocalStack Community edition provisioned on the server. This project avoids RDS and uses only the services available in the current stack.