DEV Community: Muhammad Usama Saleem

Building an Event-Driven Order Processing System with AWS Lambda, SQS, DynamoDB, EventBridge, and Terraform

Muhammad Usama Saleem — Thu, 10 Sep 2026 18:55:03 +0000

In my previous AWS projects, I worked with services such as DynamoDB, Lambda, API Gateway, S3, IAM, and Terraform.

This time, I wanted to build something a little closer to a real production architecture.

Instead of processing an order synchronously inside an API request, we'll build an event-driven order processing system where the API accepts an order, stores it, places a message on Amazon SQS, and lets a separate Lambda function process it asynchronously.

We'll also handle:

Automatic retries
Failed messages
Dead-letter queues
Duplicate messages
Idempotent processing
EventBridge events
CloudWatch logging
IAM permissions
Infrastructure as Code with Terraform

The entire infrastructure is deployed using Terraform.

What We Are Building

The application accepts an order through an HTTP API.

The flow is:

Client
   │
   ▼
API Gateway
   │
   ▼
Order Lambda
   │
   ├──────────────► DynamoDB
   │                 Orders
   │
   └──────────────► SQS
                       │
                       ▼
                Processor Lambda
                       │
                       ├──────► DynamoDB
                       │          Update Order
                       │
                       └──────► EventBridge
                                  OrderCompleted

If the processor repeatedly fails, Amazon SQS moves the message to a Dead-Letter Queue.

SQS
 │
 │ processing fails
 │
 ▼
Retry
 │
 │ fails again
 ▼
Retry
 │
 │ maxReceiveCount reached
 ▼
DLQ

The important part is that the API does not need to wait for the order to finish processing.

It accepts the order and returns a PENDING status.

The actual processing happens asynchronously.

Architecture

The final architecture contains the following AWS services:

API Gateway
AWS Lambda
Amazon DynamoDB
Amazon SQS
Amazon EventBridge
Amazon CloudWatch
AWS IAM
Terraform

We will use two DynamoDB tables:

Orders
  └── OrderId

Products
  └── ProductId

The order lifecycle is:

PENDING
   ↓
PROCESSING
   ↓
COMPLETED

If processing repeatedly fails, the SQS message is moved to the DLQ.

Prerequisites

Before starting, make sure you have:

An AWS account
AWS CLI
Terraform
Node.js
AWS credentials configured
Basic knowledge of Lambda, DynamoDB and SQS

You can verify Terraform with:

terraform version

And verify AWS authentication with:

aws sts get-caller-identity

Project Structure

The Terraform project looks like this:

terraform/
├── main.tf
├── variables.tf
├── terraform.tfvars
├── sqs.tf
├── iam.tf
├── lambda.tf
├── api_gateway.tf
├── eventbridge.tf
├── cloudwatch.tf
├── outputs.tf
└── lambda/
    ├── order/
    │   └── index.mjs
    └── processor/
        └── index.mjs

Each Terraform file is responsible for a specific part of the infrastructure.

Step 1: Configure Terraform

In main.tf:

terraform {
  required_version = ">= 1.6.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }

    archive = {
      source  = "hashicorp/archive"
      version = "~> 2.7"
    }
  }
}

provider "aws" {
  region = var.aws_region
}

The AWS provider allows Terraform to communicate with AWS.

The archive provider is used to package the Lambda source code into ZIP files.

Step 2: Define Variables

Create variables.tf:

variable "aws_region" {
  type        = string
  description = "AWS region"
}

variable "order_table_name" {
  type        = string
  description = "DynamoDB order table name"
}

variable "product_table_name" {
  type        = string
  description = "DynamoDB product table name"
}

Then configure the values in terraform.tfvars:

aws_region         = "ap-southeast-1"
order_table_name   = "Orders"
product_table_name = "Products"

Using variables makes the Terraform configuration easier to reuse.

Step 3: Create DynamoDB Tables

The first table stores orders.

The second table stores products.

module "dynamodb_order_table" {
  source = "terraform-aws-modules/dynamodb-table/aws"

  name         = var.order_table_name
  hash_key     = "OrderId"
  billing_mode = "PAY_PER_REQUEST"

  attributes = [
    {
      name = "OrderId"
      type = "S"
    }
  ]
}

module "dynamodb_product_table" {
  source = "terraform-aws-modules/dynamodb-table/aws"

  name         = var.product_table_name
  hash_key     = "ProductId"
  billing_mode = "PAY_PER_REQUEST"

  attributes = [
    {
      name = "ProductId"
      type = "S"
    }
  ]
}

The Orders table uses:

OrderId

as its partition key.

The Products table uses:

ProductId

as its partition key.

We use:

billing_mode = "PAY_PER_REQUEST"

because this project does not require us to manage provisioned read and write capacity.

Step 4: Create the SQS Queue

Now we need a queue between the API and the processing Lambda.

First, create the Dead-Letter Queue:

resource "aws_sqs_queue" "order_processing_dlq" {
  name = "order-processing-dlq"

  message_retention_seconds = 1209600

  sqs_managed_sse_enabled = true
}

The DLQ retains messages for 14 days.

Now create the main queue:

resource "aws_sqs_queue" "order_processing" {
  name = "order-processing"

  visibility_timeout_seconds = 60
  message_retention_seconds  = 345600
  receive_wait_time_seconds  = 10

  sqs_managed_sse_enabled = true

  redrive_policy = jsonencode({
    deadLetterTargetArn = aws_sqs_queue.order_processing_dlq.arn
    maxReceiveCount     = 4
  })
}

There are a few important settings here.

Visibility timeout

visibility_timeout_seconds = 60

When Lambda receives a message, SQS temporarily hides that message from other consumers.

Message retention

message_retention_seconds = 345600

The main queue keeps messages for up to four days.

Dead-Letter Queue

maxReceiveCount = 4

If the message is received four times without being successfully processed, SQS moves it to the DLQ.

This prevents a permanently broken message from being retried forever.

Step 5: Create the Order Lambda

The Order Lambda is responsible for accepting the API request.

It performs the following operations:

Validate the request
Check that the product exists
Generate an order ID
Store the order in DynamoDB
Send the order ID to SQS
Return the order ID to the client

The environment variables are:

environment {
  variables = {
    ORDER_TABLE   = module.dynamodb_order_table.dynamodb_table_id
    PRODUCT_TABLE = module.dynamodb_product_table.dynamodb_table_id
    QUEUE_URL     = aws_sqs_queue.order_processing.url
  }
}

The Lambda function uses Node.js 22:

resource "aws_lambda_function" "order" {
  function_name = "order-service"

  filename         = data.archive_file.order_lambda.output_path
  source_code_hash = data.archive_file.order_lambda.output_base64sha256

  runtime = "nodejs22.x"
  handler = "index.handler"

  role = aws_iam_role.order_lambda.arn

  timeout     = 10
  memory_size = 256

  environment {
    variables = {
      ORDER_TABLE   = module.dynamodb_order_table.dynamodb_table_id
      PRODUCT_TABLE = module.dynamodb_product_table.dynamodb_table_id
      QUEUE_URL     = aws_sqs_queue.order_processing.url
    }
  }
}

The Lambda source code uses the AWS SDK for DynamoDB and SQS.

A simplified version of the request flow looks like this:

const orderId = crypto.randomUUID();

await dynamodb.send(
  new PutItemCommand({
    TableName: ORDER_TABLE,
    Item: {
      OrderId: { S: orderId },
      CustomerId: { S: customerId },
      ProductId: { S: productId },
      Quantity: { N: String(quantity) },
      Status: { S: "PENDING" },
      CreatedAt: { S: new Date().toISOString() }
    }
  })
);

await sqs.send(
  new SendMessageCommand({
    QueueUrl: QUEUE_URL,
    MessageBody: JSON.stringify({ orderId })
  })
);

The important thing is that the API does not process the order itself.

It only creates the order and places a message on SQS.

Step 6: Create API Gateway

Now we expose the Lambda through an HTTP API.

The API contains two routes:

POST /orders
GET  /orders/{orderId}

The POST endpoint creates an order.

The GET endpoint retrieves its current status.

The architecture becomes:

Client
   ↓
API Gateway
   ↓
Order Lambda

API Gateway uses an AWS_PROXY integration, allowing the Lambda function to receive the HTTP request directly.

Step 7: Connect SQS to the Processor Lambda

Now we create the second Lambda.

Its job is to consume messages from SQS.

resource "aws_lambda_function" "processor" {
  function_name = "order-processor"

  filename         = data.archive_file.processor_lambda.output_path
  source_code_hash = data.archive_file.processor_lambda.output_base64sha256

  runtime = "nodejs22.x"
  handler = "index.handler"

  role = aws_iam_role.processor_lambda.arn

  timeout     = 30
  memory_size = 256

  environment {
    variables = {
      ORDER_TABLE    = module.dynamodb_order_table.dynamodb_table_id
      EVENT_BUS_NAME = aws_cloudwatch_event_bus.orders.name
    }
  }
}

Then connect SQS to Lambda:

resource "aws_lambda_event_source_mapping" "order_processing" {
  event_source_arn = aws_sqs_queue.order_processing.arn
  function_name    = aws_lambda_function.processor.arn

  batch_size = 1
}

This means Lambda automatically polls the SQS queue and invokes the processor when messages are available.

Step 8: Process the Order

The processor first reads the order from DynamoDB.

const existingOrder = await dynamodb.send(
  new GetItemCommand({
    TableName: ORDER_TABLE,
    Key: {
      OrderId: {
        S: orderId
      }
    }
  })
);

If the order doesn't exist, we throw an error:

if (!existingOrder.Item) {
  console.error(`Order ${orderId} does not exist`);

  throw new Error(`Order ${orderId} does not exist`);
}

This is important.

We want Lambda to fail in this situation.

Why?

Because SQS uses the Lambda invocation result to determine whether the message was successfully processed.

If Lambda throws an error:

Lambda failure
      ↓
SQS message becomes available again
      ↓
Lambda retries
      ↓
Repeated failures
      ↓
DLQ

Step 9: Prevent Duplicate Processing

Amazon SQS provides at-least-once delivery.

That means the same message can potentially be delivered more than once.

So we cannot assume:

1 message = 1 Lambda invocation

Instead, our processor needs to be idempotent.

We store the order status in DynamoDB.

Before processing:

PENDING

The processor conditionally changes it to:

PROCESSING

using:

await dynamodb.send(
  new UpdateItemCommand({
    TableName: ORDER_TABLE,
    Key: {
      OrderId: {
        S: orderId
      }
    },
    UpdateExpression: "SET #status = :processing",
    ConditionExpression: "#status = :pending",

    ExpressionAttributeNames: {
      "#status": "Status"
    },

    ExpressionAttributeValues: {
      ":pending": {
        S: "PENDING"
      },
      ":processing": {
        S: "PROCESSING"
      }
    }
  })
);

The condition is important:

Status must currently be PENDING

Only then can the processor claim the order.

Step 10: Handle Duplicate Messages

After the order is already completed, another copy of the message might arrive.

We check the current status:

if (
  currentStatus === "PROCESSING" ||
  currentStatus === "COMPLETED"
) {
  console.log(
    `Order ${orderId} has already been processed or is being processed`
  );

  return;
}

This makes the processor idempotent.

For example:

Message 1
   ↓
PENDING
   ↓
PROCESSING
   ↓
COMPLETED

Message 2
   ↓
COMPLETED
   ↓
Ignore

The second message is successfully consumed without processing the order again.

Step 11: Complete the Order

After processing, we update the order:

await dynamodb.send(
  new UpdateItemCommand({
    TableName: ORDER_TABLE,
    Key: {
      OrderId: {
        S: orderId
      }
    },

    UpdateExpression: "SET #status = :completed",

    ConditionExpression: "#status = :processing",

    ExpressionAttributeNames: {
      "#status": "Status"
    },

    ExpressionAttributeValues: {
      ":processing": {
        S: "PROCESSING"
      },
      ":completed": {
        S: "COMPLETED"
      }
    }
  })
);

The state transition is:

PENDING
   ↓
PROCESSING
   ↓
COMPLETED

The conditional update prevents the order from being completed from an unexpected state.

Step 12: Publish an Event with EventBridge

Once the order is completed, we publish an event.

First, create the custom event bus:

resource "aws_cloudwatch_event_bus" "orders" {
  name = "order-events"
}

Then the processor publishes:

await eventbridge.send(
  new PutEventsCommand({
    Entries: [
      {
        EventBusName: EVENT_BUS_NAME,
        Source: "order-service",
        DetailType: "OrderCompleted",

        Detail: JSON.stringify({
          orderId
        })
      }
    ]
  })
);

The resulting event contains information such as:

{
  "source": "order-service",
  "detail-type": "OrderCompleted",
  "detail": {
    "orderId": "b91eb8b4-0c80-4305-9651-518f6347b8dc"
  }
}

This gives us another useful architectural property.

The processor does not need to know what happens after an order is completed.

Other systems can subscribe to the event later.

For example:

                 ┌── Email Service
                 │
OrderCompleted ──┼── Analytics
                 │
                 ├── Notification Service
                 │
                 └── Inventory Service

This is one of the main benefits of event-driven architecture.

Step 13: Configure IAM

Each Lambda gets its own execution role.

The Order Lambda only needs permissions required for its job.

For example:

DynamoDB
  ├── GetItem
  └── PutItem

SQS
  └── SendMessage

The Processor Lambda has different permissions:

DynamoDB
  ├── GetItem
  └── UpdateItem

SQS
  ├── ReceiveMessage
  ├── DeleteMessage
  └── GetQueueAttributes

EventBridge
  └── PutEvents

This follows the principle of least privilege.

The processor does not need permission to create DynamoDB tables.

The Order Lambda does not need permission to publish EventBridge events.

Each role gets only the permissions required by that Lambda.

Step 14: Add CloudWatch Logs

Each Lambda gets a dedicated CloudWatch log group.

resource "aws_cloudwatch_log_group" "order_lambda" {
  name = "/aws/lambda/${aws_lambda_function.order.function_name}"

  retention_in_days = 7
}

resource "aws_cloudwatch_log_group" "processor_lambda" {
  name = "/aws/lambda/${aws_lambda_function.processor.function_name}"

  retention_in_days = 7
}

This gives us visibility into the application.

For example, the processor logs:

Order b91eb8b4-0c80-4305-9651-518f6347b8dc currently has status: PENDING

Started processing order b91eb8b4-0c80-4305-9651-518f6347b8dc

Order b91eb8b4-0c80-4305-9651-518f6347b8dc completed

OrderCompleted event published for order b91eb8b4-0c80-4305-9651-518f6347b8dc

Step 15: Initialize Terraform

Now initialize the project:

terraform init

Then validate the configuration:

terraform validate

You should see:

Success! The configuration is valid.

Step 16: Review the Deployment

Before creating anything:

terraform plan

Terraform will show the resources it intends to create.

Always review the plan before applying infrastructure.

Step 17: Deploy

Run:

terraform apply

Terraform will create:

API Gateway
Lambda
Lambda IAM Roles
DynamoDB
SQS
SQS DLQ
EventBridge
CloudWatch Log Groups

Once the deployment finishes, Terraform should report the resources it created.

Step 18: Seed a Product

Before creating an order, we need a product.

For example:

aws dynamodb put-item \
  --table-name Products \
  --item '{
    "ProductId": {"S":"product-456"},
    "Name": {"S":"Test Laptop"},
    "Price": {"N":"999.99"}
  }' \
  --region ap-southeast-1

Now the order API can reference:

product-456

Step 19: Create an Order

Our API accepts:

{
  "customerId": "customer-123",
  "productId": "product-456",
  "quantity": 2
}

Send the request:

curl -X POST \
  "https://YOUR_API_ID.execute-api.ap-southeast-1.amazonaws.com/orders" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId":"customer-123",
    "productId":"product-456",
    "quantity":2
  }'

The API immediately returns:

{
  "orderId": "b91eb8b4-0c80-4305-9651-518f6347b8dc",
  "status": "PENDING"
}

Notice that the API doesn't wait for the processor.

The order is now waiting for asynchronous processing.

Step 20: Check the Order

Now request:

curl \
  "https://YOUR_API_ID.execute-api.ap-southeast-1.amazonaws.com/orders/b91eb8b4-0c80-4305-9651-518f6347b8dc"

After processing, the result is:

{
  "orderId": "b91eb8b4-0c80-4305-9651-518f6347b8dc",
  "customerId": "customer-123",
  "productId": "product-456",
  "quantity": 2,
  "status": "COMPLETED",
  "createdAt": "2026-09-10T18:28:39.336Z"
}

The complete flow is now working:

API Gateway
     ↓
Order Lambda
     ↓
DynamoDB
     ↓
SQS
     ↓
Processor Lambda
     ↓
DynamoDB
     ↓
COMPLETED
     ↓
EventBridge

Step 21: Test Failure Handling

A good distributed system should not only handle successful requests.

We also need to test failures.

I sent a message to SQS containing an order ID that doesn't exist:

aws sqs send-message \
  --queue-url "YOUR_QUEUE_URL" \
  --message-body '{"orderId":"does-not-exist"}' \
  --region ap-southeast-1

The processor detects that the order doesn't exist and throws an error:

ERROR Order does-not-exist does not exist

Because Lambda failed, SQS retries the message.

After the configured number of failures, the message is moved to the DLQ.

The result:

SQS
 ↓
Lambda
 ↓
Failure
 ↓
Retry
 ↓
Failure
 ↓
Retry
 ↓
Failure
 ↓
Retry
 ↓
Failure
 ↓
DLQ

We can verify the DLQ:

aws sqs get-queue-attributes \
  --queue-url "YOUR_DLQ_URL" \
  --attribute-names ApproximateNumberOfMessages \
  --region ap-southeast-1

The queue reported:

ApproximateNumberOfMessages: 1

This confirmed that the failure path was working.

Step 22: Test Duplicate Processing

This is one of the most important tests.

SQS provides at-least-once delivery, so we need to make sure a duplicate message does not process the order again.

I manually sent the already completed order back to SQS:

aws sqs send-message \
  --queue-url "YOUR_QUEUE_URL" \
  --message-body '{"orderId":"b91eb8b4-0c80-4305-9651-518f6347b8dc"}' \
  --region ap-southeast-1

The processor found:

Order b91eb8b4-0c80-4305-9651-518f6347b8dc currently has status: COMPLETED

Then:

Order b91eb8b4-0c80-4305-9651-518f6347b8dc has already been processed or is being processed

The Lambda invocation succeeded without processing the order again.

This proves our duplicate protection works.

What We Have Tested

At this point, the system has three important paths.

1. Successful order

PENDING
   ↓
PROCESSING
   ↓
COMPLETED

2. Failed order

Lambda failure
   ↓
SQS retry
   ↓
SQS retry
   ↓
SQS retry
   ↓
SQS retry
   ↓
DLQ

3. Duplicate order

COMPLETED
   ↓
Duplicate message
   ↓
Detected
   ↓
Ignored

These tests are more useful than simply checking whether Terraform created the AWS resources.

They verify that the actual distributed workflow behaves as expected.

Why Use SQS Here?

Without SQS, the API could directly invoke the processing logic:

API
 ↓
Lambda
 ↓
Process Order

But now the API is coupled to the processing operation.

With SQS:

API
 ↓
SQS
 ↓
Processor

The producer and consumer are separated.

This gives us:

Asynchronous processing
Automatic retries
Buffering
Failure isolation
DLQ support
Independent scaling

If the processor temporarily fails, the API can still accept orders.

Why Use EventBridge?

SQS is useful for work that needs to be processed.

EventBridge is useful for events that other systems may want to react to.

For example:

Order Processor
      │
      ▼
OrderCompleted
      │
      ├── Notification
      ├── Analytics
      ├── Inventory
      └── Billing

The order processor doesn't need to directly call every downstream service.

It simply publishes an event.

Why Use DynamoDB for the Order State?

DynamoDB gives us a simple way to store the current state of an order:

OrderId
CustomerId
ProductId
Quantity
Status
CreatedAt

More importantly, DynamoDB conditional writes allow us to make state transitions safely.

For example:

PENDING → PROCESSING

only succeeds when the order is actually PENDING.

That becomes important when multiple Lambda invocations could potentially see the same message.

Infrastructure as Code

Everything in this project is defined using Terraform.

Instead of manually creating:

Lambda
SQS
DynamoDB
API Gateway
IAM
EventBridge
CloudWatch

through the AWS Console, the infrastructure is represented as code.

The workflow becomes:

Terraform
    ↓
terraform plan
    ↓
Review
    ↓
terraform apply
    ↓
AWS Infrastructure

This makes the environment reproducible and easier to maintain.

One Important Production Consideration

The current architecture is intentionally simple, but there are two reliability issues that I would address before calling this production-ready.

DynamoDB → SQS

Currently the order flow is:

Write Order to DynamoDB
        ↓
Send Message to SQS

Imagine DynamoDB succeeds but SQS fails.

The order would exist as:

PENDING

but there would be no message to process it.

A production system could use a transactional outbox pattern or another reliable event publication strategy.

DynamoDB → EventBridge

There is a similar issue here:

Update Order → COMPLETED
        ↓
Publish EventBridge event

If the DynamoDB update succeeds but EventBridge publishing fails, the order could remain COMPLETED while the event is never published.

A more robust architecture would make event publication retry-safe as well.

These are important considerations once the system moves beyond a learning project.

Final Architecture

The complete system looks like this:

                         ┌──────────────────┐
                         │      Client      │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │   API Gateway    │
                         └────────┬─────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  Order Lambda    │
                         └───────┬───┬──────┘
                                 │   │
                    ┌────────────┘   └─────────────┐
                    ▼                              ▼
             ┌─────────────┐                ┌─────────────┐
             │  DynamoDB   │                │     SQS     │
             │   Orders    │                │    Queue    │
             └─────────────┘                └──────┬──────┘
                                                   │
                                                   ▼
                                            ┌──────────────┐
                                            │  Processor   │
                                            │    Lambda    │
                                            └──────┬───────┘
                                                   │
                                      ┌────────────┴────────────┐
                                      ▼                         ▼
                               ┌─────────────┐          ┌──────────────┐
                               │  DynamoDB   │          │  EventBridge │
                               │   Orders    │          │  OrderEvents │
                               └─────────────┘          └──────────────┘

                         SQS failures
                              │
                              ▼
                       ┌─────────────┐
                       │     DLQ     │
                       └─────────────┘

                         Lambda Logs
                              │
                              ▼
                       ┌─────────────┐
                       │ CloudWatch  │
                       └─────────────┘

Key Takeaways

The main concepts demonstrated in this project are:

API Gateway can expose a serverless HTTP API.
Lambda can handle the API request without managing servers.
DynamoDB can store the order state.
SQS can decouple order creation from order processing.
SQS automatically retries messages when processing fails.
A Dead-Letter Queue provides a place to investigate repeatedly failed messages.
SQS provides at-least-once delivery, so consumers should be designed to handle duplicates.
DynamoDB conditional updates can help implement idempotent state transitions.
EventBridge can publish domain events such as OrderCompleted.
IAM roles can restrict each Lambda to only the AWS actions it needs.
CloudWatch provides logs for observing the serverless application.
Terraform allows the entire infrastructure to be deployed as code.

The important lesson for me was that building an event-driven system is not just about connecting AWS services.

The interesting part is handling what happens when things go wrong:

What if processing fails?

What if the same message arrives twice?

What if an order doesn't exist?

What happens after repeated failures?

How do we prevent duplicate processing?

How do we allow other systems to react to completed orders?

Those failure cases are where the architecture becomes much more interesting than simply deploying a Lambda function.

What's Next?

The next step for this project is to build a small frontend that visualizes the complete order pipeline.

Something like:

Create Order

     ↓

API Gateway
     ↓
Order Lambda
     ↓
DynamoDB
     ↓
SQS
     ↓
Processor Lambda
     ↓
COMPLETED
     ↓
EventBridge

The frontend will also be able to demonstrate successful orders, duplicate messages, processing failures, retries, and DLQ behavior.

That should make the architecture much easier to understand visually.

How to Deploy DynamoDB with Terraform on AWS

Muhammad Usama Saleem — Fri, 04 Sep 2026 19:24:02 +0000

How to Deploy DynamoDB Tables on AWS Using Terraform

Infrastructure as Code allows us to define cloud infrastructure using configuration files instead of creating resources manually through the AWS Console.

In this tutorial, we'll use Terraform to create and manage two Amazon DynamoDB tables:

Orders
Products

By the end, you'll have both tables deployed to AWS and managed entirely through Terraform.

🎯 What We Are Building

The final infrastructure will look like this:

Terraform
    │
    ▼
AWS Provider
    │
    ▼
DynamoDB
    ├── Orders
    │   └── OrderId
    │
    └── Products
        └── ProductId

The Orders table will use OrderId as its partition key, while the Products table will use ProductId.

Prerequisites

Before starting, make sure you have:

An AWS account
Terraform installed
AWS credentials configured for Terraform
An AWS identity with permissions to create and manage DynamoDB tables

You can verify Terraform is installed with:

terraform version

You should also make sure Terraform can authenticate with AWS before continuing.

📁 Step 1: Create the Terraform Files

Create a directory for the Terraform configuration.

Inside it, create these four files:

terraform/
├── providers.tf
├── variables.tf
├── terraform.tfvars
└── dynamodb.tf

Each file has a specific purpose:

File	Purpose
`providers.tf`	Terraform and AWS provider configuration
`variables.tf`	Variable definitions
`terraform.tfvars`	Values for those variables
`dynamodb.tf`	DynamoDB table configuration

Terraform automatically loads all .tf files in the same directory, so there is no need to reference each file individually.

⚙️ Step 2: Configure the AWS Provider

Open providers.tf and add:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }

  required_version = ">= 1.6.0"
}

provider "aws" {
  region = var.aws_region
}

There are two important parts here.

Terraform version

required_version = ">= 1.6.0"

This specifies the Terraform versions supported by the configuration.

AWS provider

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "~> 6.0"
  }
}

The AWS provider allows Terraform to communicate with AWS APIs.

The provider is what allows Terraform to create and manage AWS resources such as DynamoDB tables.

🌍 Step 3: Define the Variables

Open variables.tf:

variable "aws_region" {
  type        = string
  description = "The AWS region to deploy resources in"
  default     = "your-aws-region"
}

variable "order_table_name" {
  type        = string
  description = "The name of the DynamoDB order table"
  default     = "Orders"
}

variable "product_table_name" {
  type        = string
  description = "The name of the DynamoDB product table"
  default     = "Products"
}

These variables allow us to keep configuration values separate from our infrastructure definitions.

📝 Step 4: Set the Variable Values

Now open terraform.tfvars:

aws_region         = "your-aws-region"
order_table_name   = "Orders"
product_table_name = "Products"

Replace:

your-aws-region

with the AWS region where you want to deploy the tables.

For example:

aws_region = "us-east-1"

Using variables makes it easier to reuse the same Terraform configuration across different environments or AWS regions.

🗄️ Step 5: Define the DynamoDB Tables

Now we can create the actual DynamoDB infrastructure.

Open dynamodb.tf:

module "dynamodb_order_table" {
  source       = "terraform-aws-modules/dynamodb-table/aws"
  name         = var.order_table_name
  hash_key     = "OrderId"
  billing_mode = "PAY_PER_REQUEST"

  attributes = [
    {
      name = "OrderId"
      type = "S"
    }
  ]
}

module "dynamodb_product_table" {
  source       = "terraform-aws-modules/dynamodb-table/aws"
  name         = var.product_table_name
  hash_key     = "ProductId"
  billing_mode = "PAY_PER_REQUEST"

  attributes = [
    {
      name = "ProductId"
      type = "S"
    }
  ]
}

We are using the community-maintained:

terraform-aws-modules/dynamodb-table/aws

Terraform module to simplify the DynamoDB configuration.

🧠 Understanding the DynamoDB Configuration

Let's break down the important parts.

`source`

source = "terraform-aws-modules/dynamodb-table/aws"

This tells Terraform which module to use for creating the DynamoDB table.

Modules allow us to reuse existing Terraform configuration instead of implementing every resource detail ourselves.

`name`

name = var.order_table_name

This determines the DynamoDB table name.

Because we're using a variable, the name can be changed without modifying the resource configuration.

`hash_key`

hash_key = "OrderId"

This defines the DynamoDB partition key.

For the Orders table:

OrderId

is the partition key.

For the Products table:

ProductId

is the partition key.

`billing_mode`

billing_mode = "PAY_PER_REQUEST"

This configures DynamoDB's on-demand capacity mode.

With PAY_PER_REQUEST, we don't need to manually configure provisioned read and write capacity.

This is convenient for workloads where traffic can vary significantly.

`attributes`

For the Orders table:

attributes = [
  {
    name = "OrderId"
    type = "S"
  }
]

S means the attribute is a string.

The important thing to understand is that DynamoDB does not require us to define every attribute that an item might contain.

For example, an order could look like:

{
  "OrderId": "order-123",
  "CustomerId": "customer-456",
  "ProductId": "product-789",
  "Quantity": 2,
  "OrderStatus": "PENDING"
}

We don't need to declare CustomerId, ProductId, Quantity, or OrderStatus in the Terraform attributes block unless they participate in the table's key schema or indexes.

🔐 Step 6: Make Sure AWS Permissions Are Available

Terraform communicates with AWS through API calls.

Therefore, the AWS identity used by Terraform needs the required DynamoDB permissions.

Depending on the configuration, permissions can include:

dynamodb:CreateTable
dynamodb:DescribeTable
dynamodb:DeleteTable
dynamodb:UpdateTable
dynamodb:TagResource
dynamodb:ListTagsOfResource

The exact permissions required depend on what Terraform needs to create and manage.

The important concept is:

Terraform itself does not bypass AWS permissions. Every AWS operation performed by Terraform is subject to IAM authorization.

🚀 Step 7: Initialize Terraform

Now that the configuration is ready, initialize Terraform.

Run:

terraform init

Terraform will download the required AWS provider and initialize the modules used by the configuration.

You should run terraform init whenever you start working with a new Terraform configuration or when provider/module requirements change.

✅ Step 8: Validate the Configuration

Before deploying anything, validate the Terraform configuration:

terraform validate

If the configuration is valid, Terraform will report:

Success! The configuration is valid.

Validation checks the configuration itself. It does not deploy anything to AWS.

🔎 Step 9: Preview the Deployment

Next, run:

terraform plan

Terraform will calculate the changes required to make the AWS environment match the configuration.

You should see Terraform planning to create the two DynamoDB tables.

Conceptually:

Terraform Configuration
        ↓
    terraform plan
        ↓
Changes Terraform intends to make

This step is extremely important.

Before allowing Terraform to modify infrastructure, review the plan.

🚀 Step 10: Deploy the DynamoDB Tables

Once you're satisfied with the plan, run:

terraform apply

Terraform will display the planned changes and ask for confirmation.

After confirmation, Terraform will create the DynamoDB tables in AWS.

The flow is:

Terraform Configuration
        ↓
terraform plan
        ↓
Review Changes
        ↓
terraform apply
        ↓
AWS DynamoDB

🔍 Step 11: Verify the Terraform Resources

After the deployment completes, you can check the resources Terraform is managing with:

terraform state list

You should see entries corresponding to the two DynamoDB tables, such as:

module.dynamodb_order_table.aws_dynamodb_table.this[0]
module.dynamodb_product_table.aws_dynamodb_table.this[0]

You can also verify the tables directly in the AWS DynamoDB console.

You should now have:

Orders
    Partition Key: OrderId

Products
    Partition Key: ProductId

✅ Step 12: Run Terraform Plan Again

Finally, run:

terraform plan

If everything matches the Terraform configuration, Terraform should report that there are no changes to make.

For example:

No changes. Your infrastructure matches the configuration.

This means Terraform has reached the desired state defined by the configuration.

🏗️ Final Result

We have successfully defined and deployed two DynamoDB tables using Terraform:

                    Terraform
                        │
                        ▼
                 AWS Provider
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
          DynamoDB             DynamoDB
           Orders              Products
              │                   │
        OrderId PK          ProductId PK

The complete workflow is:

Create Terraform files
        ↓
Configure AWS provider
        ↓
Define variables
        ↓
Define DynamoDB tables
        ↓
terraform init
        ↓
terraform validate
        ↓
terraform plan
        ↓
terraform apply
        ↓
Verify resources
        ↓
terraform plan
        ↓
No changes

💡 Key Takeaways

The important concepts from this tutorial are:

Terraform configuration describes the desired infrastructure.
The AWS provider allows Terraform to communicate with AWS.
Terraform modules simplify resource configuration and reuse.
DynamoDB tables can be defined entirely through Terraform.
terraform init prepares the Terraform working environment.
terraform validate checks the configuration.
terraform plan shows what Terraform intends to change.
terraform apply actually creates or modifies AWS infrastructure.
Terraform state tracks the infrastructure Terraform manages.
Running terraform plan after deployment should show no changes when the infrastructure matches the configuration.

The main idea is simple:

Define your AWS infrastructure as code, review the planned changes, and let Terraform create and manage the resources for you.

Building a Serverless CRUD API with AWS Lambda, API Gateway, and DynamoDB

Muhammad Usama Saleem — Thu, 03 Sep 2026 16:28:24 +0000

Building an API on AWS is one thing. Understanding what happens between the client request, API Gateway, Lambda, DynamoDB, IAM, and the deployment pipeline is another.

For this hands-on project, I built a complete serverless CRUD API using Amazon API Gateway, AWS Lambda, and Amazon DynamoDB.

The goal was to understand how these services work together and to build the API from the ground up rather than treating the architecture as a black box.

🏗️ What I Built

The application follows a simple serverless architecture:

Client
  │
  ▼
API Gateway
  │
  ▼
AWS Lambda
  │
  ▼
DynamoDB

For deployment, GitHub Actions was added to the architecture:

GitHub
  │
  ▼
GitHub Actions
  │
  ▼
GitHub OIDC
  │
  ▼
AWS IAM
  │
  ▼
AWS Lambda

The result is a REST-style CRUD API without managing servers.

🛠️ AWS Services Used

Service	Purpose
Amazon API Gateway	Expose HTTP API endpoints
AWS Lambda	Run the application logic
Amazon DynamoDB	Store application data
AWS IAM	Manage permissions and roles
AWS STS	Provide temporary credentials through role assumption
GitHub Actions	Automate Lambda deployments
GitHub OIDC	Authenticate GitHub Actions with AWS

📌 API Operations

The API supports the main CRUD operations:

Operation	HTTP Method	Purpose
Create	POST	Create a new user
Read	GET	Retrieve one or all users
Update	PUT	Update an existing user
Delete	DELETE	Delete an existing user

For example:

POST /users
GET /users
GET /users/{name}
PUT /users/{name}
DELETE /users/{name}

The exact API Gateway routes are configured in AWS.

🗄️ DynamoDB Design

The project uses a DynamoDB table with:

Partition Key: name
Type: String

A user record looks conceptually like:

{
  "name": "Ali",
  "email": "ali@example.com",
  "followers": 10
}

One important DynamoDB concept I worked through was the role of the primary key.

Because name is the partition key, it uniquely identifies the item in this table.

🔎 Get One vs Get All

One of the concepts I wanted to understand properly was the difference between retrieving a specific DynamoDB item and scanning the table.

For a single user, Lambda uses a GetCommand.

For retrieving all users, Lambda uses a ScanCommand.

Conceptually:

GET /users/Ali
      │
      ▼
DynamoDB GetItem
      │
      ▼
Ali

Whereas:

GET /users
      │
      ▼
DynamoDB Scan
      │
      ▼
All users

This distinction became particularly useful while testing the API.

➕ Create-Only POST Requests

I didn't want a POST request to silently overwrite an existing user.

DynamoDB normally allows a PutItem operation to replace an existing item with the same primary key.

To make the endpoint behave like a create operation, I added a condition:

ConditionExpression: "attribute_not_exists(#name)"

Because name is used as the partition key, this condition prevents an existing record from being replaced.

A duplicate request therefore returns:

HTTP 409 Conflict

instead of overwriting the existing record.

✏️ Updating Records

The PUT endpoint uses DynamoDB's UpdateCommand.

It updates the user's fields and returns the updated item.

For example:

PUT /users/Ali

can update values such as:

{
  "email": "new-email@example.com",
  "followers": 25
}

The updated record is then returned by the API.

🗑️ Deleting Records

The DELETE endpoint first checks whether the user exists.

If the user exists, Lambda removes the DynamoDB item.

If the user does not exist, the API returns:

HTTP 404 Not Found

This keeps the API behavior predictable for the client.

⚡ Lambda

The API logic runs inside AWS Lambda.

The function handles:

Reading the API Gateway request
Identifying the HTTP method
Reading path parameters
Parsing request bodies
Validating input
Performing DynamoDB operations
Returning HTTP responses

The Lambda function uses the AWS SDK for JavaScript.

The project uses the modular AWS SDK v3 packages:

@aws-sdk/client-dynamodb
@aws-sdk/lib-dynamodb

🌐 API Gateway

Amazon API Gateway provides the HTTP interface for the Lambda function.

The API exposes the CRUD routes and forwards requests to Lambda.

The overall request flow is:

HTTP Request
     │
     ▼
API Gateway
     │
     ▼
Lambda
     │
     ▼
DynamoDB
     │
     ▼
Lambda Response
     │
     ▼
API Gateway
     │
     ▼
Client

I tested the endpoints externally through API Gateway and Postman.

🔐 IAM Roles

There are two different IAM responsibilities in this project.

Lambda Execution Role

The Lambda execution role allows the function to interact with DynamoDB.

Conceptually:

Lambda
  │
  ▼
Lambda Execution Role
  │
  ▼
DynamoDB Permissions

GitHub Deployment Role

GitHub Actions uses a separate IAM role to deploy the Lambda function.

GitHub Actions
  │
  ▼
GitHub OIDC
  │
  ▼
Deployment IAM Role
  │
  ▼
Lambda Deployment

Keeping these roles separate helped reinforce an important AWS principle:

The identity deploying a function does not need to be the same identity used by the function at runtime.

🔑 GitHub OIDC Deployment

The Lambda deployment was automated using GitHub Actions.

Instead of storing long-lived AWS access keys inside GitHub, the workflow uses GitHub OIDC.

The flow looks like:

GitHub Actions
      │
      ▼
OIDC Token
      │
      ▼
AWS IAM
      │
      ▼
Temporary Credentials
      │
      ▼
Lambda Deployment

This was one of the main reasons I wanted to include CI/CD in the project.

⚙️ Deployment Workflow

The workflow performs the following steps:

Checkout repository
        │
        ▼
Install dependencies
        │
        ▼
Prepare Lambda package
        │
        ▼
Authenticate with AWS
        │
        ▼
Deploy Lambda

The Lambda package contains the application code and the required dependencies.

I also separated the deployment package from the rest of the repository so files such as tests, documentation, and GitHub configuration are not unnecessarily uploaded to Lambda.

🧪 Testing

The API was tested both through API Gateway and locally.

The final CRUD flow was tested as:

GET all users
      ↓
GET specific user
      ↓
POST new user
      ↓
GET new user
      ↓
PUT user
      ↓
GET updated user
      ↓
DELETE user
      ↓
GET deleted user
      ↓
404 response

I also tested the duplicate-create scenario.

Attempting to create an existing user returns:

409 Conflict

which confirms that the DynamoDB condition is working as intended.

🧯 Some Problems I Had to Solve

The most useful part of the project was probably the troubleshooting.

Lambda Deployment Permissions

The GitHub deployment role initially did not have all the Lambda permissions required by the deployment action.

The missing permissions were identified from the deployment error and the IAM policy was updated accordingly.

Lambda Package Contents

The first deployment approach packaged the entire repository.

That meant files such as:

README.md
test.js
.github/

could end up inside the Lambda deployment package.

I changed the workflow to create a dedicated lambda-package directory containing only the Lambda code, package metadata, and required dependencies.

ES Modules

The Lambda code uses ES module syntax.

Running the same code locally initially produced an error because Node.js was treating the project as CommonJS.

Adding the appropriate module configuration to package.json allowed the same code to run locally.

Duplicate Data

During testing, attempting to create the same user again correctly returned a 409.

This was a useful reminder that test data can affect subsequent runs and that negative test cases are just as important as successful ones.

🔒 Security Considerations

The project was designed without putting AWS credentials into the GitHub repository.

The main authentication approach is:

GitHub OIDC
IAM roles
Temporary AWS credentials
Separate Lambda execution and deployment roles
Specific AWS permissions for each role

No access keys, passwords, tokens, or other credentials are included in the repository.

📁 Project Structure

aws-serverless-crud-api/
│
├── .github/
│   └── workflows/
│       └── deploy.yml
│
├── index.js
├── package.json
├── package-lock.json
├── test.js
└── README.md

💡 What I Learned

This project gave me hands-on experience with:

AWS Lambda

Lambda functions
Event handling
Execution roles
Error handling
Lambda deployment

API Gateway

HTTP APIs
Routes
Path parameters
HTTP status codes
Connecting API Gateway to Lambda

DynamoDB

Tables
Partition keys
GetItem
Scan
PutItem
UpdateItem
DeleteItem
Conditional expressions

IAM

Trust policies
Permission policies
Execution roles
Deployment roles
Least-privilege access

GitHub Actions

CI/CD workflows
OIDC authentication
AWS role assumption
Lambda deployment

🎯 Why I Built This

I wanted to go beyond simply learning what Lambda, API Gateway, and DynamoDB are.

The goal was to build something where I had to deal with the actual interactions between these services.

The project also gave me the opportunity to work through IAM permissions, deployment packaging, API error handling, DynamoDB conditions, and CI/CD.

That made the architecture much easier to understand because every part of it was actually configured and tested.

🔮 Possible Improvements

There are several directions this project could be taken next:

Add API authentication and authorization
Add request validation
Introduce Amazon Cognito
Add CloudWatch dashboards and alarms
Add infrastructure as code
Add automated API tests to the CI/CD pipeline
Add a frontend application
Introduce API versioning

These would move the project closer to a production-style serverless application.

📌 Final Architecture

                    ┌──────────────────┐
                    │     Client       │
                    │ Browser / Postman│
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │  API Gateway     │
                    │    HTTP API      │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │  AWS Lambda      │
                    │  CRUD Logic      │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │    DynamoDB      │
                    │   User Records   │
                    └──────────────────┘


Deployment:

GitHub
   │
   ▼
GitHub Actions
   │
   ▼
GitHub OIDC
   │
   ▼
AWS IAM
   │
   ▼
AWS Lambda

👨‍💻 Project

Built as part of my hands-on AWS learning journey, with a focus on understanding serverless architecture, REST APIs, DynamoDB operations, IAM, and automated AWS deployments.

Deploy a Static Website to AWS S3 with GitHub Actions and OIDC

Muhammad Usama Saleem — Wed, 02 Sep 2026 16:28:06 +0000

In this guide, we'll build a simple deployment pipeline where a website stored in GitHub is automatically deployed to an Amazon S3 bucket whenever changes are pushed to the main branch.

No long-lived AWS access keys will be stored in GitHub.

🏗️ What is being built?

The idea is simple:

Create a website.
Store it in GitHub.
Push the code.
GitHub Actions starts automatically.
GitHub authenticates with AWS using OIDC.
AWS allows the workflow to assume an IAM role.
The workflow uploads the website to S3.
S3 serves the website.

The final flow looks like this:

GitHub
   ↓
GitHub Actions
   ↓
GitHub OIDC
   ↓
AWS IAM Role
   ↓
Amazon S3
   ↓
Static Website 🌐

📋 What is required?

Before starting, you'll need the following.

AWS

An AWS account
An S3 bucket
An IAM role
An IAM permissions policy
GitHub OIDC configured for AWS

GitHub

A GitHub repository
A main branch
GitHub Actions enabled

Local machine

Git
A text/code editor
A simple index.html

You don't need a server or an EC2 instance for this project.

🧰 What to prepare

For my project, I used the following setup:

AWS Region: <AWS_REGION>
S3 Bucket: <S3_BUCKET_NAME>
IAM Role: <IAM_ROLE_NAME>
GitHub Repository: <GITHUB_USERNAME>/<GITHUB_REPOSITORY>
Branch: main

For example, throughout this guide, replace:

<AWS_REGION>
<S3_BUCKET_NAME>
<IAM_ROLE_NAME>
<GITHUB_USERNAME>
<GITHUB_REPOSITORY>
<AWS_ACCOUNT_ID>

with your own values.

We'll prepare four main things:

S3 bucket
IAM role + permissions
GitHub OIDC authentication
GitHub Actions workflow

1️⃣ Prepare the S3 Bucket

Go to:

AWS Console → S3 → Create bucket

Create a bucket with a name such as:

my-aws-s3-project

💡 S3 bucket names must be globally unique. If this name is already taken, choose another one.

Choose your AWS region.

For example:

ap-southeast-1

Encryption

For server-side encryption, I used:

SSE-S3

This means S3 manages the encryption keys for the objects stored in the bucket.

Once the bucket is created, open it.

2️⃣ Prepare Static Website Hosting

Open:

S3 → Your bucket → Properties

Find:

Static website hosting

Enable it and set the index document to:

index.html

Save the configuration.

At this point, S3 knows that this bucket is going to be used to serve a website.

But we still need to put a website inside it.

3️⃣ Prepare the IAM Role

Next, we need an IAM role that GitHub Actions can use.

Go to:

AWS Console → IAM → Roles → Create role

Create a role such as:

Git-S3-Project

The important thing here is that we're creating a role, not creating an AWS access key and putting that key into GitHub.

The authentication flow will be:

GitHub
   ↓
OIDC token
   ↓
AWS STS
   ↓
IAM Role
   ↓
Temporary credentials

This means GitHub Actions can use temporary AWS credentials instead of storing long-lived AWS credentials.

4️⃣ Prepare the Trust Policy

The role needs to know:

Who is allowed to assume me?

That's what the trust policy controls.

For the GitHub repository, use a trust policy like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": [
            "repo:<GITHUB_USERNAME>/<GITHUB_REPOSITORY>:ref:refs/heads/main"
          ]
        }
      }
    }
  ]
}

Replace:

<AWS_ACCOUNT_ID>
<GITHUB_USERNAME>
<GITHUB_REPOSITORY>

with your own values.

For example, this part:

repo:<GITHUB_USERNAME>/<GITHUB_REPOSITORY>:ref:refs/heads/main

should point to the repository and branch that are allowed to assume the role.

Trust policy vs permissions policy

Keep this distinction in mind:

Trust Policy
     ↓
Who can assume the role?

Permissions Policy
     ↓
What can the role do?

We'll configure the permissions policy next.

5️⃣ Prepare the S3 Permissions

Now we need to tell AWS what the role is actually allowed to do.

For this project, the role needs permission to upload objects to the S3 bucket.

Use:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowS3",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::<S3_BUCKET_NAME>/*"
      ]
    }
  ]
}

Replace:

<S3_BUCKET_NAME>

with your bucket name.

The permission that matters most for our deployment is:

s3:PutObject

because GitHub Actions needs to upload the website files into S3.

💡 For a production setup, review these permissions carefully and follow the principle of least privilege. The example above is intended to keep this learning project straightforward.

6️⃣ Prepare the Website

Create an index.html in your GitHub repository.

For example:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My AWS Website</title>
</head>

<body>
    <h1>Hello from AWS S3 🚀</h1>
    <p>This website is deployed using GitHub Actions.</p>
</body>
</html>

Your repository can now look like:

aws-s3-project/
│
├── index.html
│
└── .github/
    └── workflows/
        └── deploy.yml

7️⃣ Prepare GitHub Actions

Now we connect GitHub to AWS.

Create:

.github/workflows/deploy.yml

Add:

name: Deploy to S3 Bucket

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    permissions:
      id-token: write
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::<AWS_ACCOUNT_ID>:role/<IAM_ROLE_NAME>
          aws-region: <AWS_REGION>

      - name: Upload files to S3
        run: |
          aws s3 cp ./index.html s3://<S3_BUCKET_NAME>/

Replace:

<AWS_ACCOUNT_ID>
<IAM_ROLE_NAME>
<AWS_REGION>
<S3_BUCKET_NAME>

with your own values.

There are three important parts here.

Trigger

on:
  push:
    branches:
      - main

This means the workflow runs when code is pushed to main.

OIDC permission

permissions:
  id-token: write
  contents: read

id-token: write allows GitHub Actions to request an OIDC token.

It does not give GitHub access to S3.

AWS still decides whether that identity is allowed to assume the IAM role.

Upload

Finally:

aws s3 cp ./index.html s3://<S3_BUCKET_NAME>/

This copies the file into the S3 bucket.

8️⃣ Prepare Public Website Access

At this point, GitHub Actions can upload the file.

But that's a different question from:

Can someone visiting the website read the file?

For a basic S3 static website, the website objects need to be publicly readable.

For this learning project, you can use a bucket policy that allows public read access to index.html:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadForWebsite",
      "Principal": "*",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::<S3_BUCKET_NAME>/index.html"
      ]
    }
  ]
}

Replace:

<S3_BUCKET_NAME>

with your bucket name.

Here:

"Principal": "*"

means anyone can be the requester, while:

"Action": "s3:GetObject"

allows them to read the object.

⚠️ This makes index.html publicly readable. This is appropriate for demonstrating a public static website, but you should not blindly use this access model for sensitive or private data.

⚠️ This example only makes index.html public. If your website contains CSS, JavaScript, images, or other files, you'll need to account for those objects too.

For production applications, a common approach is to keep the S3 bucket private and use Amazon CloudFront to serve the website.

✅ Once Done — How to Check

Now we have everything prepared.

Let's test it from end to end.

Check 1: Push the Code

Commit and push:

git add .
git commit -m "Deploy website to S3"
git push origin main

Check 2: Open GitHub Actions

Go to your GitHub repository:

Actions → Deploy to S3 Bucket

You should see a workflow run.

The steps should complete successfully:

✓ Checkout code
✓ Configure AWS credentials
✓ Upload files to S3

If these are green, GitHub successfully authenticated with AWS and uploaded the file.

Check 3: Check the S3 Bucket

Go to:

AWS Console → S3 → Your Bucket → Objects

You should see:

index.html

This confirms the file reached S3.

Check 4: Open the Website

Go back to:

S3 → Properties → Static website hosting

Copy the website endpoint shown there and open it in your browser.

You should see:

Hello from AWS S3 🚀

🎉 Your GitHub repository is now deploying a website to S3.

🔎 If Something Goes Wrong

Here are the main things to check.

GitHub Actions cannot assume the role

Check the IAM trust policy.

The GitHub repository and branch in the sub condition must match the workflow.

For example:

repo:<GITHUB_USERNAME>/<GITHUB_REPOSITORY>:ref:refs/heads/main

Also make sure the GitHub Actions workflow has:

permissions:
  id-token: write
  contents: read

GitHub assumes the role but S3 returns `AccessDenied`

Check the IAM permissions policy.

Make sure the role has:

s3:PutObject

for the correct bucket:

arn:aws:s3:::<S3_BUCKET_NAME>/*

Deployment succeeds but website shows `AccessDenied`

GitHub's deployment permission and visitor access are separate.

Check:

S3 bucket policy
Static website hosting
Block Public Access settings

Presigned URL works but normal URL doesn't

A presigned URL provides temporary authorization to access an object.

It does not mean the object is publicly accessible.

For example:

Normal S3 URL
      ↓
Requires permission

Presigned URL
      ↓
Contains temporary authorization

🎯 Final Result

What we started with:

GitHub

What we ended with:

GitHub
   ↓
GitHub Actions
   ↓
OIDC
   ↓
IAM Role
   ↓
S3
   ↓
Static Website 🌐

And the deployment process is now automatic:

Change index.html
       ↓
   git push
       ↓
GitHub Actions
       ↓
 Upload to S3
       ↓
Website updated

The main takeaway is that GitHub Actions can authenticate with AWS using OIDC and assume an IAM role without storing long-lived AWS access keys in the repository.

That's the complete setup. 🚀