Amazon Simple Queue Service is a fully managed message queuing service. This guide shows how to set up SQS using Terraform with a focus on repeatable infrastructure as code, import workflows, and queue type selection for production workloads.
Prerequisites and Project Layout
A working Terraform SQS setup assumes the following baseline.
- AWS CLI configured
- Terraform installed
- Basic understanding of message queues
- Producer and consumer applications ready
A common project structure isolates configuration into reusable files.
aws-sqs-terraform/
├── main.tf
├── variables.tf
├── outputs.tf
└── terraform.tfvars
This layout separates provider configuration, resource definitions, variable declarations, and output exports. Keeping queue definitions in main.tf allows version control and peer review of queue properties just like application code.
Provider configuration establishes authentication details and default settings for interacting with AWS.
hcl
provider "aws" {
region = var.aws_region
}
An alternative explicit region example uses a fixed value.
hcl
provider "aws" {
region = "us-east-1"
}
Standard Queue Configuration
A standard queue is the default high throughput option. The minimal Terraform SQS queue example defines name, timeout, retention, size, delay, and long polling.
hcl
resource "aws_sqs_queue" "basic" {
name = "example-basic-queue"
visibility_timeout_seconds = 30
message_retention_seconds = 345600 # 4 days
max_message_size = 262144 # 256 KB
delay_seconds = 0
receive_wait_time_seconds = 10 # simple long polling
tags = {
Environment = "dev"
Team = "backend"
}
}
In this basic Terraform SQS queue:
name is the human-readable queue name
The project example uses variable interpolation for the name and tags.
hcl
resource "aws_sqs_queue" "standard" {
name = "${var.project_name}-queue"
visibility_timeout_seconds = 30
message_retention_seconds = 345600 # 4 days
max_message_size = 262144 # 256 KB
delay_seconds = 0
receive_wait_time_seconds = 0
tags = {
Environment = var.environment
}
}
Parameters control producer and consumer behavior.
- visibilitytimeoutseconds defines how long a message is invisible after being received
- messageretentionseconds defines how long SQS retains a message before discarding it
- maxmessagesize caps payload size
- delay_seconds adds an initial delay before delivery
- receivewaittime_seconds enables long polling to reduce empty responses
FIFO Queue and Dead Letter Queue
FIFO queues guarantee message order and exactly-once processing. They require a name ending in .fifo and explicit enablement.
hcl
resource "aws_sqs_queue" "fifo" {
name = "${var.project_name}-queue.fifo"
fifo_queue = true
content_based_deduplication = true
visibility_timeout_seconds = 30
message_retention_seconds = 345600
max_message_size = 262144
delay_seconds = 0
receive_wait_time_seconds = 0
tags = {
Environment = var.environment
}
}
contentbaseddeduplication enables automatic deduplication based on message content hash.
Dead letter queues capture messages that fail processing after repeated attempts.
hcl
resource "aws_sqs_queue" "dlq" {
name = "${var.project_name}-dlq"
tags = {
Environment = var.environment
}
}
A main queue with redrive policy can be configured to forward failed messages to the DLQ, isolating producers from consumers and improving system resilience and scalability.
Queue Policy and Access Control
Queue policies control who can access a queue. The example policy allows actions from a specific source ARN.
hcl
resource "aws_sqs_queue_policy" "standard" {
queue_url = aws_sqs_queue.standard.id
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Effect = "Allow"
Principal = {
AWS = "*"
}
Action = "SQS:*"
Resource = aws_sqs_queue.standard.arn
Condition = {
ArnEquals = {
"aws:SourceArn": var.source_arn
}
}
}
]
})
}
The policy references the queue ARN and restricts access via ArnEquals condition on aws:SourceArn.
Importing Existing Queues
A Terraform SQS queue is an AWS SQS queue defined and managed through Terraform, so you can version, review, and reproduce your queue configuration just like you do with application code. Instead of manually creating the queue in the AWS Management Console, you describe it in .tf files and let Terraform create and update it.
When you declare an awssqsqueue resource, Terraform translates the configuration into AWS API calls to create or update the queue. Every property you specify affects how producers send messages and how consumers receive and process them.
Importing an existing queue avoids recreation.
Define the Terraform resource with a minimal block that matches the real SQS queue name.
hcl
resource "aws_sqs_queue" "orders_queue" {
name = "orders-queue"
# Optional: fill in settings to match the existing queue
# visibility_timeout_seconds = 60
# message_retention_seconds = 345600
# ...
}
The resource name is internal to Terraform. The name argument must match the real SQS queue name.
After importing, you can run terraform state show awssqsqueue.orders_queue to see the full set of arguments and align your configuration. Only add arguments in your HCL that you actually want Terraform to manage and leave computed attributes out of the configuration.
Run the import.
bash
terraform init
terraform import aws_sqs_queue.orders_queue https://sqs.eu-central-1.amazonaws.com/123456789012/orders-queue
This tells Terraform:
- Use the resource awssqsqueue.orders_queue in the config
- Link it to the existing SQS queue with that URL
If you use a newer Terraform version you can also define an import block in your configuration instead of running terraform import, but the command shown here is still supported and simple to use.
After the import completes run terraform plan to see any differences between your configuration and the actual queue.
Terraform Workflow for SQS Provisioning
Create SQS topic resource in your Terraform configuration file, specifying the name for the topic.
hcl
resource "aws_sqs_queue" "my_queue" {
name = "my-sqs-topic"
}
Initialize and validate.
bash
terraform init
terraform fmt
terraform validate
terraform plan
Apply changes.
bash
terraform apply --auto-approve
The following screenshot shows that we successfully created a sqs in aws using terraform.
Queue Type Comparison
| Attribute | Standard Queue | FIFO Queue |
|---|---|---|
| Delivery guarantee | At least once | Exactly once processing |
| Ordering | Best effort | Strictly ordered |
| Throughput | High | Lower, limited by deduplication |
| Name requirement | Any valid name | Must end with .fifo |
| Deduplication | Not applicable | Optional content based |
| Use case | High volume decoupling | Ordered workflows |
Standard Queues, which offer high throughput and at least once delivery.
FIFO Queues, which guarantee message order and exactly-once processing.
Terminology and Concepts
Understanding primary terminologies helps correct configuration.
- Amazon Simple Queue Service (SQS): SQS is a completely overseen message queuing provided given by AWS, enabling dependable and versatile message conveyance between dispersed parts of an application.
- Terraform: Terraform is an open-source infrastructure as-code apparatus that permits clients to characterize and arrangement cloud infrastructure resources utilizing declarative configuration files.
- SQS Topic: A SQS topic is a legitimate substance used to coordinate and manage related SQS queues. It works with pub/sub messaging patterns, where messages published to the point are circulated to subscribing in ques or endpoints.
- Queue: A queue in SQS is a named place where messages are put away. It acts as a buffer between message producers and customers, allowing asynchronous correspondence between disseminated parts of an application.
- Pub/Sub Messaging: Pub/Sub informing is a communication design where managing send messages to a central point, and supporters get messages from that topic. SQS topics empower pub/sub messaging, permitting decoupled correspondence between components.
- Infrastructure as-Code (IaC): Infrastructure as- Code is a way to deal with overseeing and provisioning foundation assets utilizing code as opposed to manual cycles
Conclusion
Terraform management of AWS SQS provides a single declarative source for queue names, timeouts, retention, size limits, delay, polling behavior, tags, policies, and FIFO settings. Standard queues deliver high throughput with at least once delivery for decoupled producer consumer systems. FIFO queues provide strict ordering and exactly once processing for workflows that require deterministic handling. Import workflows allow adoption of existing queues without disruption, aligning state before incremental drift management. Dead letter queues and queue policies add resilience and access control. By using variables for project name, environment, and source ARN, configurations remain reusable across dev and production. The Terraform workflow of init, fmt, validate, plan, and apply ensures safe changes, while state inspection after import keeps the configuration aligned with reality. The resulting infrastructure is versioned, reviewed, and reproducible, matching the operational expectations of distributed applications that rely on asynchronous message delivery.