ipa-stack-queue

name	ipa-stack-queue
description	Deploy a queue tier stack: SQS + DLQ + worker Lambda + ESM + DynamoDB (feature-flagged).
model	opus

ipa-stack-queue

Deploy a queue tier stack: SQS + DLQ + worker Lambda + ESM + DynamoDB (feature-flagged).

Stack Identity

Property	Value
Stack name	{APP_NAMESPACE}-{APP_ENV}-queue
Template	infra/cfn/queue/queue.yml
Capabilities	CAPABILITY_NAMED_IAM
Lifecycle	deploy (solution stack)
Tier	queue

Parameters

Parameter	Required	Default	Description
Namespace	Yes	—	Project namespace prefix
Environment	Yes	—	Deployment environment (dev/staging/prod)
ImageUri	Yes	—	ECR image URI with tag
AuthIssuer	Yes	—	Cognito OIDC issuer URL
AuthAudience	Yes	—	Cognito app client ID
QueueName	No	jobs	Logical queue name
VisibilityTimeout	No	300	Message visibility timeout (seconds)
MessageRetentionPeriod	No	345600	Message retention (seconds, default 4 days)
MaxReceiveCount	No	3	Attempts before DLQ
CreateDLQ	No	true	Create dead-letter queue
FunctionName	No	fn-worker	Worker Lambda name
MemorySize	No	512	Worker Lambda memory (MB)
Timeout	No	300	Worker Lambda timeout (seconds)
ImageCommand	No	python,-m,sqs_handler	Worker container CMD
EnableJobsTable	No	false	Feature flag: create jobs DynamoDB table

Feature Flags

Flag	Default	Condition	Controls
EnableJobsTable	false	HasJobsTable	JobsTable resource, DynamoDB IAM policy, JobsTableArn output
CreateDLQ	true	HasDLQ	DeadLetterQueue resource, DlqUrl/DlqArn outputs, DLQ depth alarm

Wirable Parameters

Parameter	Source Stack	Source Output	Notes
ImageUri	ecr	RepositoryUri	Append :$(IMAGE_TAG)
AuthIssuer	cognito	IssuerUrl	OIDC issuer URL
AuthAudience	cognito	UserPoolClientId	App client ID

Outputs

Output	Export Name	Description
QueueUrl	{StackName}-QueueUrl	Consumed by backend → SqsQueueUrl
QueueArn	{StackName}-QueueArn	Consumed by backend → SqsSendQueueArns
QueueName	{StackName}-QueueName	Physical queue name
WorkerFunctionArn	{StackName}-WorkerFunctionArn	Worker Lambda ARN
WorkerFunctionName	{StackName}-WorkerFunctionName	Worker Lambda name
DlqUrl	{StackName}-DlqUrl	Conditional (HasDLQ)
DlqArn	{StackName}-DlqArn	Conditional (HasDLQ)
JobsTableArn	{StackName}-JobsTableArn	Conditional (HasJobsTable)

Build Requirements

The queue worker Lambda reuses the shared rest-lambda container image built by the backend stack — CMD is overridden via the ImageCommand parameter. No additional build target is required for this stack; do not emit a duplicate build-rest-lambda when backend is also in the composition.

Security

• SQS: Deny non-SSL policy, SQS-managed SSE
• Lambda: Per-function execution role, SQS receive policy always present
• IAM: Conditional DynamoDB policies scoped to !GetAtt Table.Arn
• Log groups: 30-day retention
• No CrossTierTableArns parameter (K2:B — convention-based ARN only)

Deploy Order

Queue deploys before backend (S2:B). Backend receives queue outputs via wirable parameters.

Local Dev Environment

After deployment, the update-env-sqs target in scripts/env.mk writes SQS_QUEUE_URL to .env:

Variable	Source Output	Description
SQS_QUEUE_URL	QueueUrl	SQS queue URL for job submission

This enables the local FastAPI backend (load_dotenv()) to submit jobs to the deployed queue without manual .env configuration. The target runs as part of post-deploy.mk's update-env step, gated by .env existence (skipped in CI/CD).

Compose Config

Parameter overrides applied by /ipa-compose:

Parameter	Value	Reason
FunctionName	fn-worker	Distinct from REST handler
InvokeMode	BUFFERED	Synchronous SQS processing
Timeout	300	Match REST handler timeout
ImageCommand	python,-m,sqs_handler	Worker entrypoint
EnableJobsTable	true	Job tracking feature

Deploy Command

aws cloudformation deploy \
  --template-file infra/cfn/queue/queue.yml \
  --stack-name $(APP_NAMESPACE)-$(APP_ENV)-queue \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides \
    Namespace=$(APP_NAMESPACE) \
    Environment=$(APP_ENV) \
    ImageUri=$(REPO_URI):$(IMAGE_TAG) \
    AuthIssuer=$(AUTH_ISSUER) \
    AuthAudience=$(AUTH_AUDIENCE) \
    EnableJobsTable=true

Terraform Module

Property	Value
Module path	infra/tf/queue/
State key	{namespace}-{env}/queue/terraform.tfstate
Required version	>= 1.5.0
Providers	hashicorp/aws >= 5.0

Variables

Variable	Type	Default	Maps to CFN
namespace	string	—	Namespace
environment	string	—	Environment
region	string	—	(implicit)
state_bucket	string	—	(TF infrastructure)
image_uri	string	—	ImageUri
auth_issuer	string	—	AuthIssuer
auth_audience	string	—	AuthAudience
queue_name	string	jobs	QueueName
visibility_timeout	number	300	VisibilityTimeout
message_retention_period	number	345600	MessageRetentionPeriod
max_receive_count	number	3	MaxReceiveCount
function_name	string	fn-worker	FunctionName
memory_size	number	512	MemorySize
timeout	number	300	Timeout
image_command	string	python,-m,sqs_handler	ImageCommand
enable_jobs_table	bool	false	EnableJobsTable

Outputs

Output	Maps to CFN
queue_url	QueueUrl
queue_arn	QueueArn
queue_name	QueueName
worker_function_arn	WorkerFunctionArn
worker_function_name	WorkerFunctionName
dlq_url	DlqUrl
dlq_arn	DlqArn
jobs_table_arn	JobsTableArn

Remote State References

Source Module	Data Source	Outputs Used
cognito	terraform_remote_state.cognito	issuer_url, user_pool_client_id
ecr	terraform_remote_state.ecr	repository_uri