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 |
aws-samples