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.
• Nginx container serving the Quantum application screen through Traefik.

Default resource names for the dev environment:

quantum-dev-artifacts
quantum-dev-events
quantum-dev-events-dlq
quantum-dev-processor
/aws/lambda/quantum-dev-processor
quantum-dev/app

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

Runtime Evidence

Use the commands below to prove that LocalStack, the Quantum application screen, and the provisioned resources are running.

The AWS resource evidence commands assume the selected environment has already been applied with tofu apply or docker compose run --rm tofu apply.

LocalStack Health

curl -s https://localstack.paulononato.com.br/_localstack/health

Expected evidence:

"edition": "community"
"s3": "available" or "s3": "running"
"sqs": "available"
"lambda": "available"
"iam": "available"
"logs": "available"
"secretsmanager": "available"

OpenTofu State

From an environment directory, for example environments/dev:

tofu output

When using Docker from the repository root:

docker compose run --rm tofu output

Expected outputs:

localstack_endpoint
quantum_bucket_name
quantum_queue_url
quantum_dlq_url
quantum_lambda_name
quantum_log_group_name
quantum_secret_name

S3 Evidence

aws --endpoint-url https://localstack.paulononato.com.br s3 ls
aws --endpoint-url https://localstack.paulononato.com.br s3 ls s3://$(tofu output -raw quantum_bucket_name)

Expected evidence:

quantum-dev-artifacts
config/quantum-dev.json

SQS Evidence

aws --endpoint-url https://localstack.paulononato.com.br sqs list-queues

Send a message:

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

Expected evidence:

quantum-dev-events
quantum-dev-events-dlq
MessageId

Lambda Evidence

aws --endpoint-url https://localstack.paulononato.com.br lambda list-functions
aws --endpoint-url https://localstack.paulononato.com.br lambda invoke \
  --function-name quantum-dev-processor \
  --invocation-type DryRun \
  /tmp/quantum-lambda-dry-run.json

Expected evidence:

quantum-dev-processor
StatusCode: 204

IAM Evidence

aws --endpoint-url https://localstack.paulononato.com.br iam get-role \
  --role-name quantum-dev-lambda-role

aws --endpoint-url https://localstack.paulononato.com.br iam list-policies \
  --scope Local

Expected evidence:

quantum-dev-lambda-role
quantum-dev-lambda-policy

CloudWatch Logs Evidence

aws --endpoint-url https://localstack.paulononato.com.br logs describe-log-groups \
  --log-group-name-prefix /aws/lambda/quantum-dev-processor

Expected evidence:

/aws/lambda/quantum-dev-processor

Secrets Manager Evidence

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

Expected evidence:

quantum-dev/app
SecretString

Application Screen Evidence

curl -s https://quantum.paulononato.com.br

Expected evidence:

Hello Quantum

On the Docker Swarm host:

docker stack ls
docker service ls --filter name=quanto
docker service ps quanto_app

Expected evidence:

quanto
quanto_app
1/1

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.