DEV Community: Viktor Vasylkovskyi

OpenClaw and Claude Code - Multi Agents talking via Handoff File

Viktor Vasylkovskyi — Wed, 20 May 2026 08:30:28 +0000

A few months ago I finished setting up my Raspberry Pi with metrics, alerting, domain access, and secrets, and ended up with a pretty neat device that did nothing. Around the same time OpenClaw started showing up in my feed — a bot with access to an LLM that could sit on a small device and do work for you. The pitch was good enough that I gave it a weekend.

A weekend turned into months of configurations hell and confusion. The thing I underestimated was how big the gap is between "an LLM bot responds on Discord" and "an LLM bot does real engineering work for me." A bot that can chat is easy. A bot that can take a Discord message, decide it needs to write code, write that code, run tests, open a PR, and tell me about it that is a different category of system.

An LLM bot does real engineering work for me..

That shift surfaces three problems that the cosy "ask the LLM a question" framing hides. Given my experience in building agents, I wanted to avoid the context rots and instruction overload problems from the start. Additionally, I had been pretty comfortable using Claude Code for coding tasks. So OpenClaw had to come-in for something else.

If you have are agents builder, you will recognise that building a multi agent system is the answer to the problems above. The killer feature of OpenClaw for me is the chat integrations which comes at a low cost so it felt really compelling.

The separation becomes clear:

OpenClaw handles user interaction
Claude Code handles writing code.

Unsurpisingly this is a setup that has been proven in the past by this tweet https://x.com/elvissun/status/2025920521871716562, which has been an inspiration and drove me to reproduce the setup.

Building Coding Assistant

Here is the shape of it, before getting into the why:

Two agents, one file hand-off between them. OpenClaw is the long-lived assistant on Discord. Claude Code is spawned per task, does the work, opens a PR, exits. The filesystem is just a folder — OpenClaw drops a task in, Claude Code picks it up, drops the result back. OpenClaw also listens for PR events from GitHub as a heartbeat, so it can confirm the work actually landed and not just that Claude Code said it did.

The rest of the post is the why and the how.

Three protocols, one survivor

The job is straightforward to describe. OpenClaw understands the user request from Discord, decides this needs real code written, and hands the work off to Claude Code, which produces a PR. OpenClaw watches for completion and reports back.

The whole problem is the box in the middle.

The hard part is the hand-off. I tried three using a shared tmux session and a filesystem via handoff file, and with an ACP (Agent Communication Protocol):

ACP (Agent Communication Protocol). The "right" way. Sessions, capabilities, structured messages, the whole thing. I had this working in Part 4 with Codex. It worked. It also fell over under load, hit timeouts, and depended on a pairing dance that broke every time the Pi rebooted.
A shared tmux session. Skip the protocol entirely, drive a real terminal that the worker lives inside. Capture the pane to read output. It works. It is also extremely fragile — anything that touches the terminal state (a stray newline, an ANSI escape, a pager that opens) corrupts the channel.
A filesystem mailbox. OpenClaw writes a JSON file. inotifywait sees the file. A systemd service launches Claude Code with -p against that file. Claude Code writes the result to another JSON file. Done.

I have spent weeks trying to fine-tune the ACP and Tmux, until I found inotifywait. The rest of this post is how that is wired up and why the others didn't work for me.

OpenClaw under systemd

Although all of the documentations of OpenClaw and Claude Code omit that, there is a hidden truth about agents - they are system processes. Which means, they will die eventually, silently - unless you deamonise them.

We will handle it using a systemd file. The relevant guarantees from systemd:

Restart=on-failure — the process comes back if it crashes
systemctl --user enable makes it survive reboot

Think about systemd like a docker container, but it lives on your bare metal. A typical systemd file looks like that:

[Unit]
Description=OpenClaw Bot
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
User={{ bot_user }}
WorkingDirectory={{ bot_home }}
EnvironmentFile={{ env_file }}
Environment=REPO_DIR={{ repo_dir }}
Environment=FEATURE_DOCS_DIR={{ feature_docs_dir }}
ExecStart={{ bot_home }}/scripts/start.sh
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Start it with


systemctl --user daemon-reload
systemctl --user enable --now openclaw-gateway.service
journalctl --user -u openclaw-gateway -f

And see the logs

systemctl --user status openclaw-gateway.service
● openclaw-gateway.service - OpenClaw Gateway
     Loaded: loaded (/home/vvasylkovskyi/.config/systemd/user/openclaw-gateway.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-05-18 22:14:07 BST; 17h ago

With systemd in place, OpenClaw is a thing that stays up. That is the floor.

Claude Code, watched by inotifywait, supervised by systemd

The worker side is its own systemd service, similar to the one above. Except in this case, ExecStart={{ bot_home }}/scripts/start.sh will:

Start a persistent inotifywait loop watching the filesystem directory
inotifywait triggers a shell script that, on file creation, launches Claude Code in headless mode
A systemd service that owns the watcher and restarts it if it dies

The watcher loop is the entire orchestration logic on the worker side. There is nothing fancy in here:

#!/usr/bin/env bash
set -euo pipefail

# ── Watcher loop ──────────────────────────────────────────────────────────────
echo "[pipeline] Watching $FEATURE_DOCS_DIR for new feature docs..."
cd "$REPO_DIR"

CLAUDE_BIN=$(find /usr/local/bin "$HOME/.local/bin" "$HOME/.npm-global/bin" -name claude 2>/dev/null | head -1)

inotifywait -m "$FEATURE_DOCS_DIR" -e create | while read -r path _event file; do
  echo "[pipeline] Detected: $file — starting pipeline..."
  "$CLAUDE_BIN" --dangerously-skip-permissions -p \
    "/implementation-orchestrator Process this feature doc: @${path}${file}"
  echo "[pipeline] Done: $file"
done

When the new file is created, claude code is spawned and reads the file. The claude --dangerously-skip-permissions -p ensures that the headless mode is activated, and there are no confirmation prompts - human completely out of the loop.

Skill fine-tuned for human-out-of-the-loop

The message is simple: "/implementation-orchestrator Process this feature doc: @${path}${file}". So whatever is in the file is the direction. The policy is the skill where we have to stir agent from asking questions with prompts like:

You are an orchestration agent running in a fully automated headless pipeline.
You must never pause for input, never ask clarifying questions, and never wait for human confirmation mid-session.

That is the entire worker. A watcher, a launcher, and a folder with markdown files. The interesting design choices are not in the code - they are in what I am deliberately not doing.

Protocols that did not work

It is worth being explicit about what I tried and why I abandoned it, because the file handoff looks underwhelming until you have lived with the alternatives.

Why we eventually pivoted from ACP to tmux

ACP has a lot of open issues — sessions timing out, the gateway pairing dance, the arm64 binary problem. After getting it working, I kept hitting reliability problems. There are also open GitHub issues specifically about this:

Under heavy load, the ACP system would overload:

tmux

The pivot from ACP was to a shared tmux session. Alegendly one can spawn tmux sessions and start in them the coding agents:

tmux list-windows -t agents | grep -q claude || \
  tmux new-window -t agents -n claude

Then start the claude session using the below:

tmux send-keys -t agents:claude \
  "claude --agent-file ~/.claude/CLAUDE.md" Enter

Spawn the worker inside tmux, drive it by writing to its stdin via tmux send-keys, capture results with tmux capture-pane -p. This works... until it doesn't, and when it doesn't, the failure is in terminal not in logs.

The problem is executing the send-keys command reliably. Sometimes double enter is required, and often it is not enough. More importantly, when something fails, the error trace is not available unless we manually ssh into device and attach to the tmux session - if the session is alive. If the tmux server dies for any reason (memory pressure, a crashed pane), every running task is lost with no recovery path.

The general lesson, which I have now learned twice, is that any IPC channel that goes through a TTY is a TTY. You do not get to pretend it is a structured stream. The terminal will assert itself eventually.

Why using inotify is better

Stepping back from the wiring, the reason the inotifywait won is not that it is fast or elegant. It is because the communication is battle-proven and dead simple. The watcher is reliable, and as long as the file drops in the folder, the watcher will spawn the agent. The rest of the components might fail independently but each failure has an obvious recovery. The inotifywait can also have failure modes, but they all show up in either the Discord channel or journalctl, both of which I check anyway.

When OpenClaw dropped the file on the system, the logs show like these.

Apr 28 15:59:29 raspberry-4b systemd[1]: Started claude-coding-bot.service - Claude Code PR Bot.
Apr 28 15:59:29 raspberry-4b start.sh[2514944]: [pipeline] Watching /home/vvasylkovskyi/my-claude-code/context/feature-docs for new feature docs...
Apr 28 15:59:29 raspberry-4b start.sh[2514950]: Setting up watches.
Apr 28 15:59:29 raspberry-4b start.sh[2514950]: Watches established.
Apr 28 15:59:54 raspberry-4b start.sh[2514951]: [pipeline] Detected: print-readme-testing-headless-claude-code.md — starting pipeline...
Apr 28 15:59:59 raspberry-4b start.sh[2515185]: Warning: no stdin data received in 3s, proceeding without it. If piping from a slow command, redirect stdin explicitly: < /dev/null to skip, or wait longer.
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: `🎉 Final PR opened: https://github.com/vvasylkovskyi/my-app/pull/2`
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: ---
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: ```
{% endraw %}

Apr 28 16:03:24 raspberry-4b start.sh[2515185]: === Autopilot Session Complete ===
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: Mode: features
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: Repo: /home/vvasylkovskyi/my-claude-code/repo
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: ✅  print-readme-testing-headless-claude-code → PR #1 merged → feature/autopilot-2026-04-28
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: Skipped:   0
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: Completed: 1
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: Failed:    0
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: ==================================
Apr 28 16:03:24 raspberry-4b start.sh[2515185]: Final PR for your review: https://github.com/vvasylkovskyi/my-app/pull/2

{% raw %}

The ACP and tmux versions of had failure modes that were silent or required SSH. Filesystems are used by Claude Code - They can also use tmux to multiplex your open session. However in headless mode, the TTY is unreliable due to its inherent interactive nature.

What I would tell myself before starting

Multi agents architectures have little to do with AI. What matters are the deep skills in linux and building a distributed system. The filesystem communication pattern is a dead-simple, and the only approach that I didn't have to fix.

Regarding tmux, the assumption that you can drive a terminal as if it were a structured channel is wrong. It works in the demo but it breaks the moment a tool decides to be helpful and open a pager, or the keys-send didn't send the space for the tmux session to submit question to llm. The tmux approach is fine for known, bounded outputs and dangerous for anything else.

The filesystem watcher is not a clever design. It is a design that takes the things Linux is already good at - files, services, watchers - and arranges them so that the agent layer only has to do the parts that genuinely need an agent. Why is it so convenient? Well, because we are on the same device. Sometimes the simplest solutions are the ones taking the longest to reveal themselves.

Infrastructure as Code Toolbox - Final Thoughts and Future Work

Viktor Vasylkovskyi — Wed, 06 May 2026 15:58:03 +0000

Previous: Load Testing Infrastructure

We have reached the end of this infrastructure journey. By now, you should have a solid understanding of how to provision and manage cloud infrastructure using Terraform. You've built a complete three-tier web application architecture on AWS, covering everything from networking and compute to security and data storage.

As promised, we have delivered the following outputs:

domain_for_your_apps = http://www.your-domain.com
database_endpoint = "postgres-db.cspuccciib8v.us-east-1.rds.amazonaws.com:5432"
ec2_first_instance_ip_address = "3.222.64.160"
ec2_second_instance_ip_address = "3.223.185.158"

Note, all of them are public, although your are in charge of protecting them. Use them at your own risk!

Next Steps

I hope you enjoyed this hands-on journey through building infrastructure with Terraform on AWS. The goal was to provide you with a solid foundation that you can build upon.

As you have seen from the load test, the infrastructure is far from production ready. It doesn't handle the load well, and lacks proper security in place. The missing production checklists are numerous, below I will list a few ideas for next steps you can take to enhance this infrastructure.

Security Enhancements

There are several security issues with the current setup. Doesn't mean it is insecure by default, but when you pursue production readiness and certification like Service Organization Control 2 (SOC2), you need to address them. Here are some suggestions:

Restrict Network Access

This one is about the public accessibility of our resources. We don't need to expose everything to the internet:

Our RDS database is publicly accessible. In production it probably best to put it in private subnet, and allow access by ec2 instances only.
The Ec2 instances are in public subnet. Since we are using a load balancer, we can put them in private subnet, and allow access only from the load balancer.
We have exposed the SSH port (22) to the world and reuse same keys for both EC2 instances. In production, you should restrict access to known IPs and use different keys for each instance. Or use AWS Systems Manager (SSM) to access instances without SSH.

Encryption

Everything should be encrypted, both at rest and in transit:

The RDS database does not have encryption at rest enabled. In production, you should enable it.
Use encryption in transit - enforce HTTPS (We got this one right - using API Gateway and Load Balancer with HTTPS)

Access Control (IAM)

The current setup access sensitive resources too permissively:

Lock the root account and use IAM roles with least privilege. Currently we are using root account credentials in the Terraform provider which is not a best practice.
Use secrets management - no hardcoded secrets (We got this one right partially - using AWS Secrets Manager, but the secrets are injected via user data script which is not ideal, and is in plain text on the instance)

Disaster Recovery and Incident Response

The above security enhancement will provide you good preventive controls, but you also need to prepare for the worst-case scenarios:

Application Level Backups and Monitoring

Do periodic backups of your RDS database, and test the restore process.
Enable Application Logging, Monitoring and Alerting using services like CloudWatch or Grafana.
Set up an Incident Response Plan using tools like PagerDuty.

Cloud-Level Disaster Recovery

Use Infrastructure as Code (IaC) to quickly recreate your infrastructure in another region if needed (which we have done using Terraform).
Setup logging and monitoring for your infrastructure using AWS CloudTrail.
Enable logging for database, load balancer, and other services.

Performance and Scalability Improvements

Finally, to go from startup with a few users to enterprise with millions of users, you need to ensure your infrastructure can scale and perform well under load:

Implementing auto-scaling for EC2 instances with ECS
Adding Kubernetes for the orchestration of containers and quick scaling from 2 instances to more
Adding caching layers using services like Redis cache,
Using a Content Delivery Network (CDN) like CloudFront to serve static assets faster
Database optimization and read replicas for RDS
Using multiple availability zones (AZs) for high availability

Conclusion

I encourage you to continue exploring and experimenting with Terraform and AWS. The possibilities are endless, and the skills you've gained here will serve you well in your infrastructure journey. Myself, I will continue expanding this guide with more advanced topics and real-world scenarios. Stay tuned for more!

Previous: Load Testing Infrastructure

Load Test

Viktor Vasylkovskyi — Wed, 06 May 2026 15:57:29 +0000

Previous: Provisioning PostgreSQL RDS

It would not be a complete infrastructure setup without some load testing. We have built this beautiful infrastructure that does pretty much nothing. But how much user load can it handle? Let's find out!

Using k6 for Load Testing

We are going to use k6 - a modern load testing tool that makes it easy to script and run load tests. First, install k6 by following the instructions on their installation page.

Writing a Load Test Script

We are going to create a simple load test script that hits our web application's domain. Create a file named load-test.js with the following content:

We are going to simulate 10000 virtual users (VUs) over a period of 20 seconds, sending requests to our web application's domain.

The following is the script content that you should put in load-test.js:

import http from 'k6/http';
import { sleep } from 'k6';
export const options = {
  vus: 10000,
  duration: '20s',
};
export default function () {
  http.get('http://www.your-domain.com');
  sleep(1);
}

Running the Load Test

You can run the load test using the following command:

k6 run load-test.js

The test will start, after it finishes, the json file will be created and you will see real-time statistics about the requests being made, response times, and any errors encountered.

Analyzing the Results

The JSON output file can be analyzed using various tools. One popular option is to use Grafana along with k6 Cloud. You can also use the built-in summary report that k6 provides at the end of the test run.

I have made a simple web app to render the results, and here is a sample screenshot of how the results might look:

You can see that our infrastructure did not handle the 10000 users very well! Outch!

This is expected since we did not setup auto-scaling, or caching, and only had two EC2 instances running. In a production scenario, you would want to implement these features to handle high traffic loads effectively.

Previous: Provisioning PostgreSQL RDS | Next: Final Thoughts and Future Work

Provisioning PostgresSQL RDBMS on AWS with Terraform

Viktor Vasylkovskyi — Wed, 06 May 2026 15:56:44 +0000

Previous: AWS Secrets Manager

In this guide, we will learn how to provision a managed PostgresSQL database using Amazon RDS (Relational Database Service) with Terraform. RDS makes it easy to set up, operate, and scale a relational database in the cloud.

Why would you want a database? Most web applications need to store and retrieve structured data. A relational database like PostgresSQL provides a reliable way to manage this data with support for complex queries, transactions, and relationships. So let's get started!

Overview

We are going to create infra same as before but with the RDS database integrated. Let's begin by looking at the architecture diagram:

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v8-rds-database. Feel free to clone it and follow along!

Adding RDS Module

First, let's create a new Terraform module for RDS. Create a new folder called modules/rds and add the following files:

# modules/rds/main.tf
resource "aws_db_instance" "postgres" {
  identifier         = "postgres-db"
  engine             = "postgres"
  engine_version     = "15"
  instance_class     = "db.t3.micro"
  allocated_storage  = 20
  storage_type       = "gp2"
  skip_final_snapshot    = true # for dev; not recommended in production
  publicly_accessible = true
  username           = # To be filled soon
  password           = # To be filled soon
  db_name            = # To be filled soon
  vpc_security_group_ids = [] # To be filled soon
  db_subnet_group_name = # To be filled soon
}

Above resource creates a PostgresSQL database instance with the specified parameters. We are using db.t3.micro instance class which is quite small and suitable for development and testing purposes. The allocated_storage means 20GB allocated for this database, and we are using PostgresSQL database here. The skip_final_snapshot is a parameter used in AWS RDS (Relational Database Service) operations, such as when deleting a database instance with Terraform or the AWS CLI. If skip_final_snapshot = true, AWS will not create a final backup (snapshot) of your RDS instance before deleting it. We will keep it as is for our testing purpose, but it is recommended to set it to false for production use.

Usually, a database should be placed in private subnets for security reasons. You can create new private subnet in the modules/network and get it here using var.private_subnet_ids. However, for simplicity, we will use public subnets here. One of the side-effects of having database in a public subnet is that it will have a public endpoint, which is not recommended for production use (but fine for testing).

Besides being inserted in a subnet, the database also needs to be part of a security group that allows access to it, It also needs database name, username and password to be created. We will provide these as variables.

# modules/rds/variables.tf
variable "database_name" { type = string }
variable "database_username" { type = string }
variable "database_password" { type = string }
variable "subnet_ids" { type = list(string) }
variable "vpc_id" { type = string }

And finally, we can add an output to get the database endpoint:

# modules/rds/outputs.tf
output "database_endpoint" {
  value       = aws_db_instance.postgres.endpoint
  description = "The connection endpoint for the Postgres database."
}

Defining Security Groups for RDS

We will create a simple resource that allows inbound access to PostgresSQL port 5432.

# modules/rds/main.tf
resource "aws_security_group" "rds_sg" {
    name        = "rds_sg"
    description = "Allow Postgres access"
    vpc_id      = var.vpc_id

    ingress {
        from_port   = 5432
        to_port     = 5432
        protocol    = "tcp"
        cidr_blocks = ["0.0.0.0/0"]
    }

    egress {
        from_port   = 0
        to_port     = 0
        protocol    = "-1"
        cidr_blocks = ["0.0.0.0/0"]
    }
}

And now, we can use this security group in our database instance:

# modules/rds/main.tf
resource "aws_db_instance" "postgres" {
  ...
  vpc_security_group_ids = [aws_security_group.rds_sg.id]
}

Creating the RDS Subnet Group

AWS RDS requires a subnet group with at least 2 subnets in different Availability Zones for high availability and failover capabilities. For example, your database subnet group can include two private subnets from different AZs.

We already have subnets created in modules/network, so we can create a subnet group in the RDS module like this:

resource "aws_db_subnet_group" "default" {
  name       = "rds-subnet-group"
  subnet_ids = [for id in var.subnet_ids : id]

  tags = {
    Name = "RDS Subnet Group"
  }
}

Now, add this subnet group to the database instance:

# modules/rds/main.tf
resource "aws_db_instance" "postgres" {
  ...
  db_subnet_group_name = aws_db_subnet_group.default.name
}

Using the RDS Module

Finally, we can use the RDS module in our main Terraform configuration. Open main.tf and add the following:

module "rds" {
  source             = "./modules/rds"
  database_name      = "my_app_db"
  database_username  = "your_username"
  database_password  = "your_secure_password"
  subnet_ids         = module.network.public_subnet_ids
  vpc_id             = module.network.vpc_id
}

Make sure to replace your_secure_password with a strong password. Preferably, use Terraform variables or AWS Secrets Manager to manage sensitive information like passwords. You can read more about securing secrets in Provisioning AWS Secret Manager and Securing Secrets.

Outputs

In outputs.tf, add the following to get the database endpoint:

output "database_endpoint" {
  value       = module.rds.database_endpoint
  description = "The connection endpoint for the Postgres database."
}

Testing the Setup

Let's provisiong the infrastructure by running:

terraform init
terraform apply --auto-approve

This will create the RDS database along with the rest of the infrastructure. After the apply is complete, you should see the database endpoint in the outputs.

Outputs:

database_endpoint = "postgres-db.cspuccciib8v.us-east-1.rds.amazonaws.com:5432"

You can use this endpoint to connect to your PostgresSQL database using any Postgres client. Let's test the connection using psql command-line tool:

# Note, you need to install psql client first if you don't have it already
psql \
  --host=postgres-db.cspuccciib8v.us-east-1.rds.amazonaws.com \
  --port=5432 \
  --username=your_username \
  --dbname=my_app_db

# Received prompt like this:
> Password for user your_username:
# Enter the password you specified earlier
# You should see the psql prompt if the connection is successful:
psql (17.5, server 15.14)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, compression: off, ALPN: none)
Type "help" for help.

my_app_db=>

And you are connected to your PostgresSQL database running on AWS RDS! Now you can start creating tables, inserting data, and running queries.

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

In this guide, we learned how to provision a managed PostgresSQL database using Amazon RDS with Terraform. We created a dedicated RDS module, defined security groups, and subnet groups, and integrated the database into our existing infrastructure. With the database up and running, you can now build applications that leverage its capabilities for data storage and retrieval.

Usually the connection to the database should be done from application servers running in private subnets for security reasons. In production scenarios, consider additional aspects such as automated backups, monitoring, scaling, and high availability configurations. Explore more about RDS features in the Amazon RDS Documentation.

Previous: AWS Secrets Manager | Next: Load Testing Infrastructure

Provision AWS Secret Manager Retrieval of Secrets

Viktor Vasylkovskyi — Wed, 06 May 2026 15:56:10 +0000

Previous: CloudFront CDN with Terraform

Every modern web app has secrets that need to be shared securely with it. You web application may need to have a environment variable like an API key. That key should be stored in AWS secrets manager, it is a great use case for us to learn about how to give access to instance to the secret.

Overview

We are going to create infra same as before but with the secrets manager integrated

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v7-secrets. Feel free to clone it and follow along!

Creating a Secret in AWS Secret Manager

Now lets add the actual secrets. We need to add secrets only once, and then reference them. This is the process that we will repeat everytime the secret has to be updated. Let's do this from a command line using aws cli:

aws secretsmanager create-secret \
    --name "my_app/v1/credentials" \
    --description "Application credentials" \
    --secret-string '{
        "my_api_key": "your-api-key",
    }'

This command will create the secret values. If everything goes well, you should see an output like below:

{
    "ARN": "arn:aws:secretsmanager:us-east-1:088656249151:secret:<your-service>/<some-path>/credentials-MhS9Um",
    "Name": "<your-service>/<some-path>/credentials",
    "VersionId": "61c33df3-6e38-4f7f-8b9d-fda8bad3c880"
}

That output indicates your newly created secrets container with the secret.

Adding a secret

Now, we can add a dummy secret value. This can be done via UI, or CLI. Here is an example using CLI:

## Update secrets

#!/bin/bash

# Check if .env file exists
if [ ! -f .env ]; then
    echo "Error: .env file not found!"
    exit 1
fi

# Read .env file and create JSON string
JSON_STRING="{"
FIRST=true

while IFS='=' read -r key value; do
    # Skip empty lines and comments
    [[ -z "$key" || "$key" =~ ^# ]] && continue

    # Remove quotes from value
    value=$(echo "$value" | sed 's/^"//;s/"$//')

    # Add comma if not first item
    if [ "$FIRST" = true ]; then
        FIRST=false
    else
        JSON_STRING="$JSON_STRING,"
    fi

    # Add key-value pair to JSON
    JSON_STRING="$JSON_STRING\"$key\": \"$value\""
done < .env

JSON_STRING="$JSON_STRING}"

# Check if secret exists
if aws secretsmanager describe-secret --secret-id "my_app/v1/credentials" >/dev/null 2>&1; then
    # Update existing secret
    aws secretsmanager update-secret \
        --secret-id "my_app/v1/credentials" \
        --secret-string "$JSON_STRING"
    echo "Secret updated successfully!"
else
    # Create new secret
    aws secretsmanager create-secret \
        --name "portfolio/app/credentials" \
        --description "Application credentials" \
        --secret-string "$JSON_STRING"
    echo "Secret created successfully!"
fi

The above script will read the .env file from a local folder, convert it to JSON format, and then either create a new secret or update an existing one in AWS Secrets Manager.

Now let's create an .env file in the same folder as the script:

my_api_key="your-api-key"
# Note, the new line is important at the end of the file

Let's run the script:

bash update-secrets.sh

# Output below
{
    "ARN": "arn:aws:secretsmanager:us-east-1:088656249151:secret:my_app/v1/credentials-5x50LZ",
    "Name": "my_app/v1/credentials",
    "VersionId": "8202b548-5236-45d2-94f4-4d87d146ad00"
}
Secret updated successfully!

Provisioning AWS Secret Manager and using Secrets

Let's start using the secrets in our infrastructure:

Retrieving Secret Container

# modules/secrets/main.tf
data "aws_caller_identity" "current" {}

data "aws_secretsmanager_secret" "app_secrets" {
  name = var.credentials_name
}

The code above defines a new secret in AWS Secrets Manager. It doesn't contain the actual secret value, just metadata about the secret. The name parameter should match the secret name you created using AWS CLI.

data "aws_caller_identity" "current" {} is a special AWS data source that provides information about the AWS account and IAM principal (user or role) currently being used to make API calls. It requires no arguments and returns three key pieces of information:

account_id - Your AWS account number
arn - The ARN (Amazon Resource Name) of the IAM user or role
user_id - The unique identifier of the IAM user or role

Getting Secret Value

Next, we will define a data source to retrieve the secret value:

# modules/secrets/main.tf

data "aws_secretsmanager_secret_version" "current" {
  secret_id = data.aws_secretsmanager_secret.app_secrets.id
}

We are using id from the previous data source to find the correct secret. By default it gets the latest version of the secret.

Since the secret is a JSON string, we use jsondecode to convert this into Terraform map. We have to provide the variables.tf and outputs.tf files as well:

# modules/secrets/variables.tf
variable "credentials_name" { type = string }

# modules/secrets/outputs.tf
output "secrets" {
  value = jsondecode(data.aws_secretsmanager_secret_version.current.secret_string)
}

Now, to use it in main module and in our ec-2 instance, we can do the following:

# main.tf
module "secrets" {
  source = "./modules/secrets"
  credentials_name = "my_app/v1/credentials"
}

module "ec2_first_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  security_group_id = module.security_group.security_group_id
  subnet_id         = module.network.public_subnet_ids[0]
  ssh_public_key    = var.ssh_public_key
  ssh_key_name    = "ec2-key-first-instance"
  user_data = <<-EOF
              #!/bin/bash
              sudo apt-get update -y
              sudo apt-get install -y docker.io
              sudo systemctl start docker
              sudo systemctl enable docker

              # Add user to docker group
              sudo usermod -aG docker $USERNAME

              sudo docker run -d -p 80:80 \
              -e MY_API_KEY=${module.secrets.secrets.my_api_key} \
              nginx
              EOF
}

module "ec2_second_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  security_group_id = module.security_group.security_group_id
  subnet_id         = module.network.public_subnet_ids[1]
  ssh_public_key    = var.ssh_public_key # Note, you can use the same public key for both instances, but not recommended for production
  ssh_key_name    = "ec2-key-second-instance"
  user_data = <<-EOF
              #!/bin/bash
              sudo apt-get update -y
              sudo apt-get install -y docker.io
              sudo systemctl start docker
              sudo systemctl enable docker

              # Add user to docker group
              sudo usermod -aG docker $USERNAME

              sudo docker run -d -p 80:80 \
              -e MY_API_KEY=${module.secrets.secrets.my_api_key} \
              nginx
              EOF
}

Note that we are passing the secret value as an environment variable to the docker container using -e (environment variable) flag. Let's apply the changes here to ensure nothing breaks so far. Run:

terraform init
terraform apply --auto-approve

Testing the setup

To test if our setup is working, we can SSH into our EC-2 instance and check if the environment variable is set correctly.

ssh-add path/to/your/private-key.pem # Adds your private key to the ssh-agent
ssh ubuntu@<EC2_PUBLIC_IP> # Replace with your EC2 public IP

## Inside the EC2 instance, run:
ubuntu@ip-10-0-61-134:~$ sudo docker ps

# Outputs:
CONTAINER ID   IMAGE     COMMAND                  CREATED         STATUS        PORTS                               NAMES
e4dba1c33ac9   nginx     "/docker-entrypoint.…"   3 seconds ago   Up 1 second   0.0.0.0:80->80/tcp, :::80->80/tcp   recursing_haslett

The above command shows that our nginx container is running. Now, let's check if the environment variable is set correctly inside the container:

sudo docker exec -it e4dba1c33ac9 /bin/bash # Replace with your container ID, you can get it from `docker ps` command

## Inside the container

root@e4dba1c33ac9:/# echo $MY_API_KEY
## Outputs
your-api-key

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

So far this might have worked, but the secrets now get stored in plain text on the EC-2 instance. This is not ideal from security perspective. For instance, anyone with SSH access to the EC-2 instance can see the user data as follows:

curl http://169.254.169.254/latest/user-data

# Reveals user data in plain text
#!/bin/bash
sudo apt-get update -y
sudo apt-get install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USERNAME

sudo docker run -d -p 80:80 \
-e MY_API_KEY=your-api-key \
nginx

So while this tutorial shows how to setup the secrets store with AWS (Which you should do), the retrieval of secrets approach is not secure. Although it works. Providing a secure way is our of scope for now, since we are focusing on setting up a running infra rather than secure. Baby steps.

Next, we will explore the next very important resource in AWS - The RDS (Relational Database Service) and see how to provision a managed database in AWS.

Previous: CloudFront CDN with Terraform | Next: Provisioning PostgreSQL RDS

Provision CloudFront CDN with Terraform

Viktor Vasylkovskyi — Wed, 06 May 2026 15:55:36 +0000

Previous: Application Load Balancer SSL

Previously we have seen how to setup an EC-2 instance, run a simple web server and expose it at your domain using Route53. This allows us to access our web server using HTTP at port 80. If you haven't read about it, please refer to the previous notes:

The natural next step in that setup is to use HTTPS (HTTP + SSL) and enforce access at port 443 instead. We will do it here by adding Cloudfront and ACM to our terraform setup. Let's dive in.

Adding Cloudfront distribution

I will confess that it is not super easy to add CloudFront + ACM for HTTPS for a beginner, so I will break down the steps from simplest cloud architecture to most complicated one hopefully clarifying the steps and the reason for taking them.

First step to add an HTTPS using Cloudfront is naturally to create a Cloudfront distribution. Cloudfront distribution is a CDN network that expands copies of your data towards other geographical locations. From the programmer point of view, Cloudfront is a URL - the distribution URL that uses the content from the origin. Hence these are the two fundamental pieces that we need for now to make sure the distribution works. So let's dive in.

Adding Cloudfront - Creating Origin Server

First thing is to define our origin endpoint. We can do it using Route53, where the origin is a URL pointing to our Ec-2 instance. Let's do it

# modules/dns/main.tf

resource "aws_route53_zone" "main" {
  name = "viktorvasylkovskyi.com"
}

resource "aws_route53_record" "origin" {
  zone_id = var.main_zone_id
  name    = var.domain_name
  type    = "A"
  ttl     = 300
  records = [var.origin_ip]
}

Make sure to add the variables in variables.tf:

# modules/dns/variables.tf
variable "main_zone_id" { type = string }
variable "domain_name" { type = string }
variable "origin_ip" { type = string }

And the origin_ip is going to be the public IP of our Ec-2 instance. So in the main tf file we need to update the module call:

# main.tf
module "dns" {
  source        = "./modules/dns"
  domain_name   = "origin.your-domain.com"
  main_zone_id  = aws_route53_zone.main.zone_id
  origin_ip     = module.ec2.public_ip
}

And let's make sure to output the FQDN of our origin:

# modules/dns/outputs.tf
output "origin_dns_record" {
  value       = aws_route53_record.origin.fqdn
  description = "The FQDN of the origin Route53 record"
}

You can test now by running terraform apply. Note, this origin.your-domain.com is going to be available on HTTP now.

Adding Cloudfront - Define Distribution

Now that we have an origin, we can create distribution:

# modules/cloudfront/main.tf

resource "aws_cloudfront_distribution" "cdn" {
  enabled             = true
  default_root_object = "index.html"
  origin {
    domain_name = var.aws_route53_origin_fqdn
    origin_id   = var.aws_route53_origin_fqdn
    custom_origin_config {
      http_port              = 80
      https_port             = 443
      origin_protocol_policy = "http-only"
      origin_ssl_protocols   = ["TLSv1.2"]
    }
  }
  default_cache_behavior {
    allowed_methods  = ["GET", "HEAD"]
    cached_methods   = ["GET", "HEAD"]
    target_origin_id = var.aws_route53_origin_fqdn
    forwarded_values {
      query_string = false
      cookies {
        forward = "none"
      }
    }
    viewer_protocol_policy = "redirect-to-https"
    min_ttl                = 0
    default_ttl            = 3600
    max_ttl                = 86400
  }
  price_class = "PriceClass_100"
  viewer_certificate {
    cloudfront_default_certificate = true
  }
  restrictions {
    geo_restriction {
      restriction_type = "none"
    }
  }
}

Whoa! that is a lot of configs. One of the main pieces there is the target_origin_id. This will be pointing to our origin.your-domain.com. For now we will use cloudfront_default_certificate which is CloudFront certificate.

Let's add a variable and test output:

# modules/cloudfront/variables.tf
variable "aws_route53_origin_fqdn" { type = string }

And output:

# modules/cloudfront/outputs.tf

output "cloudfront_distribution_domain_name" {
  value = aws_cloudfront_distribution.cdn.domain_name
}

Also, if you followed through previous article on setting up the API Gateway, then make sure to remove the API Gateway related code from the main.tf and variables.tf files as we are not using it here. Additionally, ensure that you have the security group allowing HTTP from anywhere:

# modules/security_group/main.tf
resource "aws_security_group" "my_app" {
  name   = "Security Group for API"
  vpc_id = var.vpc_id

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
  }

... rest of the code ...
}

Finally, update the main.tf file to pass the origin FQDN to CloudFront module:

# main.tf

module "cloudfront" {
  source                     = "./modules/cloudfront"
  aws_route53_origin_fqdn    = module.dns.origin_dns_record
}

Also, ensure that we have outputs for CloudFront distribution domain name:

# outputs.tf
output "cloudfront_distribution_domain_name" {
  value = aws_cloudfront_distribution.cdn.domain_name
}

output "cloudfront_distribution_hosted_zone_id" {
  value = aws_cloudfront_distribution.cdn.hosted_zone_id
}

Apply changes

Install the new module with terraform init and then run terraform apply and observe the cloudfront_distribution_domain_name output. It should return something like

d123456789abcdef.cloudfront.net. # example URL

If everything went well then you should be able to open the URL in the browser. (Notice the URL in browser)

Provision SSL Certificate

You can follow the previous guide on Provisioning SSL Certificate to provision the SSL certificate using ACM. Ensure that you have the certificate ARN available for use in the API Gateway module.

Adding CloudFront Distribution

In the next step we are going to create a cloudfront distribution which contains an endpoint with HTTPS termination and is a place where we are going to place our SSL certificate. First we need to set a rule to wait for the certificate to be validated before creating the distribution.

# modules/cloudfront/main.tf

resource "aws_cloudfront_distribution" "cdn" {
  depends_on = [var.acm_certificate]
}

Ensure to add a variable for it:

# modules/cloudfront/variables.tf
variable "acm_certificate" { type = string }

And bring this certificate from the main.tf file, from ssl module:

# main.tf

module "ssl_acm" {
  source              = "./modules/acm"
  aws_route53_zone_id = aws_route53_zone.main.zone_id
}

module "cloudfront_cdn" {
  source                    = "./modules/cloudfront"
  aws_route53_origin_fqdn   = module.aws_route53_record.origin_dns_record
  acm_certificate           = module.ssl_acm.aws_acm_certificate_arn
}

Use SSL Certificate in CloudFront

We can now change the Viewer certificate: on CloudFront to use our validated ACM certificate for https://www.your-domain.com.

# modules/cloudfront/main.tf

resource "aws_cloudfront_distribution" "cdn" {
  depends_on = [var.acm_certificate]
  ... other code ...
  viewer_certificate {
    acm_certificate_arn      = aws_acm_certificate.cert.arn
    ssl_support_method       = "sni-only"
    minimum_protocol_version = "TLSv1.2_2021"
  }
  ... other code ...
}

Route 53 Record Pointing to CloudFront

Now that Cloudfront setup is done, it is going to be available between our ec2 instance and our DNS. So now we have the Cloudfront doing SSL and sending requests to the ec2 instance. The last step is to enable our DNS Route 53 to send.

# modules/dns/main.tf
resource "aws_route53_record" "origin" {
  zone_id = var.main_zone_id
  name    = "origin.viktorvasylkovskyi.com"
  type    = "A"
  ttl     = 300
  records = [var.origin_ip]
}

resource "aws_route53_record" "www" {
  zone_id = var.main_zone_id
  name    = "www.viktorvasylkovskyi.com"
  type    = "A"
  alias {
    name                   = var.target_domain_name
    zone_id                = var.hosted_zone_id
    evaluate_target_health = false
  }
}

And make sure to use the correct variables:

# modules/dns/variables.tf
variable "main_zone_id" { type = string }
variable "target_domain_name" { type = string }
variable "hosted_zone_id" { type = string }
variable "origin_ip" { type = string }

This sets an alias A record in Route 53 so your domain www.your-domain.com points to the CloudFront distribution instead of the EC2 directly.

Finally, let's glue it all together in the main.tf:

# main.tf
resource "aws_route53_zone" "main" {
  name = "your-domain.com"
}

module "ssl_acm" {
  source              = "./modules/acm"
  aws_route53_zone_id = aws_route53_zone.main.zone_id
}

module "cloudfront_cdn" {
  source                    = "./modules/cloudfront"
  aws_route53_origin_fqdn   = module.aws_route53_record.origin_dns_record
  acm_certificate           = module.ssl_acm.aws_acm_certificate_arn
}

module "aws_route53_record" {
  source       = "./modules/dns"
  main_zone_id = aws_route53_zone.main.zone_id
  origin_ip = module.ec2.public_ip
  target_domain_name = module.cloudfront_cdn.cloudfront_distribution_domain_name
  hosted_zone_id = module.cloudfront_cdn.cloudfront_distribution_hosted_zone_id
}

Lastly, let's not forget to expose port 443 in our VPC security group:

# security_group.tf

resource "aws_security_group" "my-app" {
  name   = "SSH Port"
  vpc_id = aws_vpc.main.id

  ...

  ingress {
    cidr_blocks = [
      "0.0.0.0/0"
    ]
    from_port = 443
    to_port   = 443
    protocol  = "tcp"
  }

  ...
}

Output

Finally, let's add some output for debugging:

# output.tf

output "https_url" {
  value       = "https://www.your-domain.com"
  description = "Public HTTPS endpoint for the EC2 app."
}

All should be working now, lets try to provision our new infrastructure. Run: terraform apply --auto-approve.

Final Validations

You should be able to open your app using https://www.your-domain.com. However if it is not working, we can troubleshoot:

Check DNS propagation

Run:

dig www.your-domain.com +short

If it still returns an IP address, it means the A record is pointing directly to EC2 and not CloudFront — which won't support HTTPS directly.

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

We have covered quite a bit of things today:

SSL certificate via ACM
HTTPS access via CloudFront
DNS validation using Route 53
A secure, CDN-backed endpoint for your EC2 app at https://www.your-domain.com

At this point you are well equipped to set you application in production as you now have HTTPS and a Ec-2 instance and can access to it via your domain name. Next, lets explore how to setup Application Load Balancer in front of our EC-2 instance. Continue reading the Provision Application Load Balancer with Terraform.

Previous: Application Load Balancer SSL | Next: AWS Secrets Manager

Provisioning Application Load Balancer and connecting it to Ec-2 instance using Terraform

Viktor Vasylkovskyi — Wed, 06 May 2026 15:55:14 +0000

Previous: API Gateway SSL Termination

In this notes we will continue improving on our infrastructure by adding HTTPS to our web app.

Due to extra complexity in requirements of setting up the ALB, our network topology will suffer some changes. For example, a load balancer requires two availability zones to run in AWS. This means extra configuration overhead which we will have to work with.

As a bonus, since we will have multiple availability zones, we are going to showcase in the end of this guide how to make ALB work with 2 EC-2 instances. And you could scale to as much instances as you want!

Architecture Overview

We will do the following:

Modify Network so that we have two subnets in two availability zones. This is required for load balancer to work.
Provision SSL certificate using ACM, for load balancer
Provision Load Balancer itself, and make it proxy requests to the EC-2 instances
Update Route53 to point our DNS to the Load Balancer
Update Ec-2 to serve slightly different app for demonstration purposes

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v6-ssl-load-balancer. Feel free to clone it and follow along!

Modify Network module to have multiple availability zones

In the modules/network, change the main.tf to include multiple availability zones:

For simplicity, we will define only two public subnets, without private subnets.

List Availability Zones

First, we will define a resource listing availability zones.

# modules/network/main.tf
resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true
  enable_dns_support   = true
}

data "aws_availability_zones" "available" {}

This resource returns a list of all AZ available in the region configured in the AWS credentials.

Add two public subnets

We will be using the terraform count directive. count is used as a loop, so we can define some resource multiple times. Since we only need two public subnets, naturaly the count=2. Let's write two public subnets:

# modules/network/main.tf

resource "aws_subnet" "public" {
  count                   = 2
  cidr_block              = cidrsubnet(aws_vpc.main.cidr_block, 4, 2 + count.index)
  availability_zone       = data.aws_availability_zones.available.names[count.index]
  vpc_id                  = aws_vpc.main.id
  map_public_ip_on_launch = true
}

We are referencing the data.aws_availability_zones.available.names defined about to choose an availability name in our vpc. Besides that, we need the route table to define how network traffic is directed within our VPC (i.e., after internet gateway).

# modules/network/main.tf
resource "aws_internet_gateway" "my_app" {
  vpc_id = aws_vpc.main.id
}

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.main.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.my_app.id
  }
}

The above code will create a route table for our VPC. The route says that all the outbound traffic 0.0.0.0/0 will be directed to the internet via the VPC's Internet Gateway. This piece of code essentially makes our subnet using this route table public. Now this route table is attached to our VPC, but not to subnet. To attach it to our two subnets, we need to create an association between subnets and this route table:

# modules/network/main.tf

resource "aws_route_table_association" "public" {
  count          = 2
  subnet_id      = aws_subnet.public[count.index].id
  route_table_id = aws_route_table.public.id
}

Finally, we will make our route table a main one, just to leave explicit association.

# modules/network/main.tf

resource "aws_main_route_table_association" "public_main" {
  vpc_id         = aws_vpc.main.id
  route_table_id = aws_route_table.public.id
}

Let's expose the public subnet IDs as output:

# modules/network/outputs.tf
output "vpc_id" { value = aws_vpc.main.id }
output "public_subnet_ids" {
  value = aws_subnet.public[*].id
}

Provision SSL Certificate

Let's create an ACM resource. You can follow the previous guide on Provisioning SSL Certificate to provision the SSL certificate using ACM. Ensure that you have the certificate ARN available for use in the API Gateway module.

Provisioning AWS Load Balancer

Now that we have network and SSL certificate, we can start provisioning load balancer itself.

Creating ALB

First, let's create ALB resource:

# modules/alb/main.tf

resource "aws_lb" "my_app" {
  name               = "my-app-alb"
  internal           = false
  load_balancer_type = "application"
  security_groups    = [aws_security_group.my_alb.id]
  subnets            = var.subnets
}

Load balancer will to be inserted in front of our public subnets (hence the internal=false), i.e, the subnets that we have just created. The load_balancer_type=application is the typical for most web applications. Alternatives are network and gateway.

The security group for ALB needs to allow igress for 443 (SSL) and egress for everything is fine for now.

# modules/alb/main.tf

resource "aws_security_group" "my_alb" {
  name   = "Security Group for Application Load Balancer"
  vpc_id = var.vpc_id

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

Note we are passing multiple subnets created in the network module above. Let's define them as variable:

# modules/alb/variables.tf
variable "subnets" { type = list(string) }
variable "vpc_id" { type = string }

Provision ALB Target Group and ALB Listener

The ALB Listener and ALB Target Group are input and output rules of ALB. We will define that ALB accepts requests at port 443 and use certificate_arn our SSL certificate. The only action ALB will do is HTTPS termination and then a simple forward to the ALB Target group - our cluster.

Begin with defining ALB Listener:

# modules/alb/main.tf

resource "aws_lb_listener" "https" {
  load_balancer_arn = aws_lb.my_app.arn
  port              = 443
  protocol          = "HTTPS"
  ssl_policy        = "ELBSecurityPolicy-2016-08"
  certificate_arn   = var.acm_certificate_cert_arn

  default_action {
    type             = "forward"
    target_group_arn = aws_lb_target_group.my_app.arn
  }

  depends_on = [var.acm_certificate_cert]
}

And now, we have to define our target group: target_group_arn.

Defining our Target Group:

# modules/alb/main.tf

resource "aws_lb_target_group" "my_app" {
  name     = "my-app-tg"
  port     = 80
  protocol = "HTTP"
  vpc_id   = var.vpc_id

  health_check {
    path                = "/"
    protocol            = "HTTP"
    matcher             = "200-399"
    interval            = 30
    timeout             = 15
    healthy_threshold   = 2
    unhealthy_threshold = 5
  }

  depends_on = [aws_lb.my_app]
}

From our load balancer we will forward requests into our cluster, which contains Ec-2 instances listening on port 80. Since we are in our subnet, it is safe to use HTTP. The health_check block defines which URL the ALB uses to decide if the target containers are healthy. Here we define the base URL since this is our simples python server application. You can read more information about health checks on AWS docs. healthy_threshold and unhealthy_threshold define how many (failed) healthchecks a target should be evaluated as healthy or unhealthy. These healthchecks are performed in intervals of seconds defined in interval.

Let's not forget to define the additional variables in variables.tf:

# modules/alb/variables.tf
variable "subnets" { type = list(string) }
variable "vpc_id" { type = string }
variable "acm_certificate_cert_arn" { type = string }
variable "acm_certificate_cert" {
  type = object({
    arn = string
    id  = string
  })
}

Attach EC-2 to the Target Group

For Load Balancer to forward requests to the EC-2, we need to attach it to the target group. This is done using aws_lb_target_group_attachment resource:

resource "aws_lb_target_group_attachment" "ec2_attachment" {
  target_group_arn = aws_lb_target_group.my_app.arn
  target_id        = var.ec2_first_instance_id
  port             = 80
}

Note port 80 is the HTTP but it is fine, since we already checked for SSL at the load balancer listener.

Let's add a variable for ec2_first_instance_id:

# modules/alb/variables.tf
variable "ec2_first_instance_id" { type = string }

Note, we have called it ec2_first_instance_id because we will be adding more EC-2 instances later. Let's ensure setup works with one instance first... Oh well! It is not that hard. Let's prepare out load balancer to accept array of ec2 instances already

Variables

# modules/alb/variables.tf
variable "ec2_instance_ids" { type = list(string) }

Attachment Resource

# modules/alb/main.tf
resource "aws_lb_target_group_attachment" "ec2_attachment" {
  count = length(var.ec2_instance_ids)

  target_group_arn = aws_lb_target_group.my_app.arn
  target_id        = var.ec2_instance_ids[count.index]
  port             = 80
}

Note we are using the count directive to loop over all the EC-2 instance IDs passed in the variable ec2_instance_ids.

Outputs

And lets expose the DNS name and zone ID of the load balancer for later use in Route53:

# modules/alb/outputs.tf
output "dns_name" {
    value = aws_lb.my_app.dns_name
}

output "zone_id" {
    value = aws_lb.my_app.zone_id
}

Update Route53 to Point to ALB

We have HTTPS on our ALB, now we have to make DNS point to ALB.

# modules/dns/main.tf

resource "aws_route53_record" "record" {
  zone_id = data.aws_route53_zone.main.zone_id
  name    = var.domain_name
  type    = "A"

  alias {
    name                   = var.aws_dns_name
    zone_id                = var.aws_zone_id
    evaluate_target_health = true
  }
}

and Outputs:

# modules/dns/outputs.tf
output "www_dns_record" {
  value       = aws_route53_record.www.fqdn
  description = "The FQDN of the www Route53 record"
}

Update Ec-2 to use the subnets from the network module

The Ec-2 instance also needs to be updated to use one of the two public subnets created in the network module:

# modules/ec2/main.tf
resource "aws_key_pair" "ssh-key" {
  key_name   = var.ssh_key_name
  public_key = var.ssh_public_key
}

resource "aws_security_group" "my_app" {
  name   = var.security_group_name
  vpc_id = var.vpc_id

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
  }

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_instance" "my_app" {
  ami                         = var.instance_ami
  instance_type               = var.instance_type
  availability_zone           = var.availability_zone
  security_groups             = [aws_security_group.my_app.id]
  associate_public_ip_address = true
  subnet_id                   = var.subnet_id
  key_name                    = aws_key_pair.ssh-key.key_name
  user_data = <<-EOF
              #!/bin/bash
              sudo yum update -y || sudo apt-get update -y
              sudo yum install -y python3 || sudo apt-get install -y python3
              echo "<html><body><h1>Hello from Terraform EC2!</h1></body></html>" > index.html
              nohup python3 -m http.server 80 &
              EOF
}

Now let's glue everything together in the Root Module

# main.tf

provider "aws" {
  region                   = "us-east-1"
  shared_credentials_files = ["./.aws-credentials"]
  profile                  = "terraform"
}

module "network" {
  source            = "./modules/network"
  vpc_cidr          = "10.0.0.0/16"
  subnet_cidr       = "10.0.1.0/24"
  availability_zone = var.availability_zone
}

module "ec2_first_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  availability_zone = var.availability_zone
  subnet_id         = module.network.public_subnet_ids[0]
  ssh_public_key    = var.ssh_public_key
  ssh_key_name      = var.ssh_key_name
}

resource "aws_route53_zone" "main" {
  name = "viktorvasylkovskyi.com"
}

module "ssl_acm" {
  source              = "./modules/acm"
  aws_route53_zone_id = aws_route53_zone.main.zone_id
}

module "alb" {
  source                  = "./modules/alb"
  subnets                 = module.network.public_subnet_ids
  vpc_id                  = module.network.vpc_id
  acm_certificate_arn     = module.ssl_acm.aws_acm_certificate_arn
  aws_acm_certificate_cert = module.ssl_acm.aws_acm_certificate_cert
  ec2_instance_ids        = [module.ec2_first_instance.instance_id]
}

module "aws_route53_record" {
  source       = "./modules/dns"
  main_zone_id = aws_route53_zone.main.zone_id
  target_domain_name = module.alb.dns_name
  hosted_zone_id = module.alb.zone_id
}

Creating second EC-2 instance

We need to alter out ec2 module so that we can create multiple instances.

Single SSH Key Pair per EC-2 instance

One of the things we have to change is the SSH key pair. Each EC-2 instance needs to have its own key pair. So we will add a variable ssh_key_name to the ec2 module. Same to the security_group_name

# modules/ec2/variables.tf
variable "instance_ami" { type = string }
variable "instance_type" { type = string }
variable "availability_zone" { type = string }
variable "subnet_id" { type = string }
variable "ssh_public_key" { type = string }
variable "ssh_key_name" { type = string }
variable "security_group_name" { type = string }

And int he main.tf of the ec2 module we will use this variable:

# modules/ec2/main.tf
resource "aws_key_pair" "ssh-key" {
  key_name   = var.ssh_key_name
  public_key = var.ssh_public_key
}

resource "aws_security_group" "my_app" {
  name   = var.security_group_name
  vpc_id = var.vpc_id

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
  }

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

# ... rest of the code ...

No hardcoding availability zone

We will also remove hardcoding of availability zone in the ec2 module, so that we can create multiple instances in different availability zones. Since we are already passing subnet_id to the ec2 module, we do not need to pass availability zone separately. So we can remove it from the variables and from the ec2 instance resource.

# modules/ec2/variables.tf
variable "instance_ami" { type = string }
variable "instance_type" { type = string }
variable "security_group_id" { type = string }
variable "subnet_id" { type = string }
variable "ssh_public_key" { type = string }
variable "ssh_key_name" { type = string }
variable "security_group_name" { type = string }

# modules/ec2/main.tf
resource "aws_instance" "my_app" {
  ami                         = var.instance_ami
  instance_type               = var.instance_type
  security_groups             = [aws_security_group.my_app.id]
  associate_public_ip_address = true
  subnet_id                   = var.subnet_id
  key_name                    = aws_key_pair.ssh-key.key_name
  user_data = <<-EOF
              #!/bin/bash
              sudo yum update -y || sudo apt-get update -y
              sudo yum install -y python3 || sudo apt-get install -y python3
              echo "<html><body><h1>Hello from Terraform EC2!</h1></body></html>" > index.html
              nohup python3 -m http.server 80 &
              EOF
}

To create a second EC-2 instance, we can simply duplicate the ec2_first_instance module call and change the subnet to the second public subnet created in the network module.

# main.tf

module "ec2_first_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  security_group_name = "first-ec2-instance"
  subnet_id         = module.network.public_subnet_ids[0]
  ssh_public_key    = var.ssh_public_key
  ssh_key_name    = "ec2-key-first-instance"
}

module "ec2_second_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  security_group_name = "second-ec2-instance"
  subnet_id         = module.network.public_subnet_ids[1]
  ssh_public_key    = var.ssh_public_key # Note, you can use the same public key for both instances, but not recommended for production
  ssh_key_name    = "ec2-key-second-instance"
}

# ... other code ...

module "alb" {
  source                  = "./modules/alb"
  subnets                 = module.network.public_subnet_ids
  vpc_id                  = module.network.vpc_id
  acm_certificate_arn     = module.ssl_acm.aws_acm_certificate_arn
  aws_acm_certificate_cert = module.ssl_acm.aws_acm_certificate_cert
  ec2_instance_ids        = [
    module.ec2_first_instance.instance_id,
    module.ec2_second_instance.instance_id
  ]
}

Custom Initializing of ec-2 user data

To make things a little more interesting, let's change the user_data of the ec-2 instances to show which instance is serving the request. We can do that by changing the user_data in the ec2 module to accept a variable user_data:

# modules/ec2/variables.tf
variable "instance_ami" { type = string }
variable "instance_type" { type = string }
variable "security_group_id" { type = string }
variable "subnet_id" { type = string }
variable "ssh_public_key" { type = string }
variable "ssh_key_name" { type = string }
variable "security_group_name" { type = string }
variable "user_data" { type = string }

Setting user data in ec2 module, start docker container

To test our setup and load balancer work, we need to see both ec-2 instances serving different content. We can do that by passing different user_data to each ec-2 instance module call. Of course, in production you will probably want them to be the same to achieve redundancy and make load balancer worth its while. Here we are doing it for the demonstration purposes only.

First, let's update the ec2 module to use the user_data variable:

# modules/ec2/main.tf
resource "aws_instance" "my_app" {
  ami                         = var.instance_ami
  instance_type               = var.instance_type
  security_groups             = [var.security_group_id]
  associate_public_ip_address = true
  subnet_id                   = var.subnet_id
  key_name                    = aws_key_pair.ssh-key.key_name
  user_data                   = var.user_data
}

And now, we can pass different user_data to each ec-2 instance module call in the root module. Let's keep the user_data in the first ec-2 instance as is:

module "ec2_first_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  vpc_id            = module.network.vpc_id
  subnet_id         = module.network.public_subnet_ids[0]
  ssh_public_key    = var.ssh_public_key
  ssh_key_name    = "ec2-key-first-instance"
  security_group_name = "first-ec2-instance"
  user_data = <<-EOF
              #!/bin/bash
              sudo yum update -y || sudo apt-get update -y
              sudo yum install -y python3 || sudo apt-get install -y python3
              echo "<html><body><h1>Hello from Terraform EC2!</h1></body></html>" > index.html
              nohup python3 -m http.server 80 &
              EOF
}

And now, the second ec-2 instance will have different user_data. Let's make it server the docker image with nginx:

module "ec2_second_instance" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  vpc_id = module.network.vpc_id
  subnet_id         = module.network.public_subnet_ids[1]
  ssh_public_key    = var.ssh_public_key # Note, you can use the same public key for both instances, but not recommended for production
  ssh_key_name    = "ec2-key-second-instance"
  security_group_name = "second-ec2-instance"
  user_data = <<-EOF
              #!/bin/bash
              sudo apt-get update -y
              sudo apt-get install -y docker.io
              sudo systemctl start docker
              sudo systemctl enable docker

              # Add user to docker group
              sudo usermod -aG docker $USERNAME

              sudo docker run -d -p 80:80 nginx
              EOF
}

Finally, add outputs:

# outputs.tf
output "ec2_first_instance_ip_address" {
  value       = module.ec2_first_instance.public_ip
  description = "The Elastic IP address allocated to the first EC2 instance."
}

output "ec2_second_instance_ip_address" {
  value       = module.ec2_second_instance.public_ip
  description = "The Elastic IP address allocated to the second EC2 instance."
}

Testing the setup

Now run the following commands:

terraform init
terraform apply --auto-approve

And observe the output:

Outputs:

ec2_first_instance_ip_address = "34.201.164.185"
ec2_second_instance_ip_address = "54.236.186.223"

Navigate to https://www.your-domain.com and see the magic happen!
Double check that you have two EC-2 instances serving the requests by refreshing the page multiple times.

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

Whoa! This was quite a journey. I am super glad you made it to the end. We have successfully provisioned an Application Load Balancer with SSL termination and connected it to multiple EC-2 instances using Terraform. This is a solid foundation for building scalable and secure web applications on AWS. For now this is the end of the road. However, there is lots of things to explore further, such as autoscaling groups, more complex health checks, and advanced routing rules.

Previous: API Gateway SSL Termination | Next: CloudFront CDN with Terraform

Provisioning API Gateway and connecting it to Ec-2 instance using Terraform

Viktor Vasylkovskyi — Wed, 06 May 2026 15:54:40 +0000

Previous: Provision SSL Certificate

The architecture of our infrastructure is going to change a bit now, as we have to accommodate the API Gateway in between our Ec-2 and the DNS resolution. The overall architecture looks like this:

Provision SSL certificate using ACM, for our API Gateway
Provision API Gateway itself, and make it proxy requests to EC-2 instance
Update Route53 to point our DNS to the Load Balancer
Update EC-2 Instance to enable port 80, and update the security group with rule to accept incoming traffic only from API Gateway.

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v5-api-gateway. Feel free to clone it and follow along!

Provision SSL Certificate

You can follow the previous guide on Provisioning SSL Certificate to provision the SSL certificate using ACM. Ensure that you have the certificate ARN available for use in the API Gateway module.

Provisioning AWS API Gateway

Now that we have network and SSL certificate, we can start provisioning the API Gateway itself.

Creating API Gateway

First, let's create API Gateway resource:

# modules/api-gateway/main.tf

resource "aws_apigatewayv2_api" "this" {
  name          = var.api_name
  protocol_type = "HTTP"
}

The above creates an API Container for a new API Gateway HTTP API (v2 is the newer version). We tell the API name an tell it that it is an HTTP API. It could be also web socket one if using protocol_type = WEBSOCKET.

Creating Integration to Ec2

Now, we are going to define the integration between our ec2 and the new api gateway:

# modules/api-gateway/main.tf

resource "aws_apigatewayv2_integration" "ec2" {
  api_id                 = aws_apigatewayv2_api.this.id
  integration_type       = "HTTP_PROXY"
  integration_uri        = var.ec2_public_url
  integration_method     = "ANY"
  payload_format_version = "1.0"
}

We define the both uris above - the API Gateway and the EC-2 instance. integration_type tells that it is an HTTP Proxy meaning that all requests are forwarded into integration_url as is. payload_format_version is simply to ensure the request/response payload use HTTP/1.1 passthrough formatting.

Notice that ec2_public_url has to be a full URL like: "http://<public-ec2-ip>:8080"

Integration Routes

Now that we have integration done, we need to specify when to activate it, i.e., on which request route. In our case it is all the requests should be routed to EC-2, so we need to say "whatever the request route/path, proxy it to ec2". Saying it in terraform language is like following:

# modules/api-gateway/main.tf

resource "aws_apigatewayv2_route" "proxy" {
  api_id    = aws_apigatewayv2_api.this.id
  route_key = "ANY /{proxy+}"
  target    = "integrations/${aws_apigatewayv2_integration.ec2.id}"
}

The ANY - match all HTTP methods: GET, POST, PUT, etc., /{proxy+} is to match any pathname, and the target is naturally the target our ec2 integration.

Adding Stage

API Gateways require definition of deployment and stage. Stages exist because API Gateway is designed for API lifecycle management. They allow us define environments like dev vs prod. Let's start coding it:

# modules/api-gateway/main.tf

resource "aws_apigatewayv2_stage" "default" {
  api_id      = aws_apigatewayv2_api.this.id
  name        = "$default"
  auto_deploy = true
}

We will specify $default stage meaning we do not have production and dev environment, we only have 1 environment, since this is enough for our use case. Note, it bigger projects, we could have wanted multiple stages for better deployment strategies of API like separate environments (dev/staging/prod) but only a single API definition.

https://api.example.com/dev/... → forwards to dev EC2
https://api.example.com/prod/... → forwards to prod EC2

the auto_deploy = true means changes to routes/integrations are automatically deployed (no need for manual deploys).

Custom Domain Mapping

Finally we have all the integration and rules in place, we are going to move a big higher in the picture and changing DNS and SSL to our Gateway API. It is pretty simple to do:

# modules/api-gateway/main.tf

resource "aws_apigatewayv2_domain_name" "custom" {
  domain_name = var.domain_name

  domain_name_configuration {
    certificate_arn = var.acm_certificate_arn
    endpoint_type   = "REGIONAL"
    security_policy = "TLS_1_2"
  }
}

We simply specify the domain_name for DNS and the certificate_arn for SSL. endpoint_type = "REGIONAL" means that the API Gateway is deployed regionally and is not optimized for edge like for example in cloudfront. Finally we glue it all together in the mapping:

resource "aws_apigatewayv2_api_mapping" "mapping" {
  api_id      = aws_apigatewayv2_api.this.id
  domain_name = aws_apigatewayv2_domain_name.custom.id
  stage       = aws_apigatewayv2_stage.default.id
}

Together, these ensure our API is available at https://api.example.com instead of the ugly default abcdef123.execute-api.us-east-1.amazonaws.com.

Adding Route53 alias record

Finally, we want to make our DNS entry point at the custom domain in API Gateway:

# modules/dns/main.tf
resource "aws_route53_record" "www" {
  zone_id = var.main_zone_id
  name    = var.domain_name
  type    = "A"
  alias {
    name                   = var.target_domain_name
    zone_id                = var.hosted_zone_id
    evaluate_target_health = false
  }
}

With new accepted variables:

# modules/dns/variables.tf
variable "target_domain_name" { type = string }
variable "hosted_zone_id" { type = string }

And we will pass them from the outputs of API Gateway module. So first, let's define the outputs in modules/api-gateway/outputs.tf:

# modules/api-gateway/outputs.tf

output "aws_apigatewayv2_domain_name" {
  value       = aws_apigatewayv2_domain_name.custom.domain_name_configuration[0].target_domain_name
  description = "The custom domain name for the API Gateway"
}

output "aws_apigatewayv2_hosted_zone_id" {
  value       = aws_apigatewayv2_domain_name.custom.domain_name_configuration[0].hosted_zone_id
  description = "The hosted zone ID for the API Gateway custom domain"
}

Using it as a module

Now that we have defined all the moving pieces of the API Gateway module, we can use it in our terraform as follows:

# main.tf
module "api_gateway" {
  source              = "./modules/api-gateway"
  api_name            = "my-api"
  domain_name         = "myapp.example.com"
  acm_certificate_arn = module.ssl_acm.aws_acm_certificate_arn
  ec2_public_url      = "http://${module.ec2.public_ip}:80"
}

Updating Ec-2 firewall rules

We have added an API Gateway and told it that our ec2 is ready to listen on port 80. Next we need to update the firewall security groups of our ec-2 instance so that the port 80 is actually opened. Once it is opened, we will harden the rule by saying that it should accept connections only from our API Gateway. Let's update the Ec-2 security group. From Deploying EC2 instance on AWS with Terraform, our security group originally looks like this:

resource "aws_security_group" "my_app" {
  vpc_id = aws_vpc.main.id

  ingress {
    cidr_blocks = [
      "0.0.0.0/0"
    ]
    from_port = 22
    to_port   = 22
    protocol  = "tcp"
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

We will update it with port 80:

resource "aws_security_group" "my_app" {
  name   = "SSH port for API"
  vpc_id = aws_vpc.main.id

  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = data.aws_ip_ranges.apigw.cidr_blocks
  }
}

And the cird_blocks are the IP ranges that are allowed for that security group, in our case inbound traffic for port 80. The data.aws_ip_ranges.apigw.cidr_blocks come from the official AWS public IP ranges JSON. It will not work just like that, we need to make terraform fetch this JSON by writing it down:

data "aws_ip_ranges" "apigw" {
  services = ["API_GATEWAY"]  # Only API Gateway IPs
  regions  = ["us-east-1"]    # Your API Gateway region
}

We can also output them to see what IPs are those:

output "apigw_ips" {
  value = data.aws_ip_ranges.apigw.cidr_blocks
}

Testing

Now that we have all the code in place, I will let you glue the modules together. Once the code is ready, run terraform init and terraform apply --auto-approve and see that your infra is working now with the API Gateway!

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

And that is a wrap! We have provisioned the setup that achieves the following:

Users hit https://www.example.com
DNS (Route 53) resolves to API Gateway
API Gateway terminates SSL (using ACM cert)
Routes any request → EC2 backend (via public IP).

This architecture is great for simple APIs that need SSL offloading without the overhead of load balancers or CDNs. API Gateway handles scaling, SSL, and routing, while EC2 runs your application logic. Continue experimenting and building and follow into the next article.

Previous: Provision SSL Certificate | Next: Application Load Balancer SSL

Provisioning SSL Certificate

Viktor Vasylkovskyi — Wed, 06 May 2026 15:54:02 +0000

Previous: SSL Termination Overview

To enable SSL termination in AWS, you first need to provision an SSL certificate using AWS Certificate Manager (ACM). This certificate will be used by services like API Gateway or Application Load Balancer to encrypt traffic between your users and your application.

In this guide, we will walk through the steps to request and validate an SSL certificate using Terraform. Then the certificate can be provisioned as a terraform module, and we will show how to use it in the next guides:

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v4-acm-ssl. Feel free to clone it and follow along!

Provision SSL Certificate

let's create an ACM resource. We will do that in new module: modules/acm

# modules/acm/main.tf
provider "aws" {
  alias  = "us_east_1"
  region = "us-east-1"
  shared_credentials_files = ["./.aws-credentials"]
  profile                  = "terraform"
}

resource "aws_acm_certificate" "cert" {
  provider                  = aws.us_east_1
  domain_name               = "your-domain.com"
  validation_method         = "DNS"
  subject_alternative_names = ["www.your-domain.com", "your-domain.com"]
  lifecycle {
    create_before_destroy = true
  }
}

Note, that ACM certificates for API Gateway must be created in us-east-1 region, regardless of where your API Gateway is located. Hence, we define a separate AWS provider with alias us_east_1 to handle this.

The code above requests an SSL/TLS certificate from AWS Certificate Manager for your domain. We choose DNS validation (simplest in Terraform if using Route 53).Note that we are adding lifecycle.create_before_destroy. This is because in case you change something on this resource, since Application Load Balancer will be using the certificate, this directive allows to duplicate certificate, and replace old one before destroying it thus allowing application load balancer to switch certificates without issues.

DNS Validation via Route 53

Next, we need to create the required DNS record to prove domain ownership to ACM.

# modules/acm/main.tf
resource "aws_route53_record" "cert_validation" {
  for_each = {
    for dvo in aws_acm_certificate.cert.domain_validation_options : dvo.domain_name => {
      name  = dvo.resource_record_name
      type  = dvo.resource_record_type
      value = dvo.resource_record_value
    }
  }
  name    = each.value.name
  type    = each.value.type
  zone_id = var.aws_route53_zone_id
  records = [each.value.value]
  ttl     = 60
}

In the code above, the for_each turns the set into a map indexed by domain_name (which is unique). We are dynamically generating multiple DNS records (1 per domain to validate) using for_each. aws_acm_certificate.cert.domain_validation_options is a list of instructions from AWS on how to validate your domain. We loop over each dvo (domain validation option), and create a map like:

{
  "www.your-domain.com" = {
    name  = "_xyz.www.your-domain.com."
    type  = "CNAME"
    value = "_abc.acm-validations.aws."
  }
}

This is how AWS verifies domain ownership: you create a DNS record with those values. The

  records = [each.value.value]
  ttl     = 60

records: The actual value to put in the DNS record (like _abc.acm-validations.aws.)
ttl: Time-to-live (how long DNS resolvers cache it), set to 60 seconds for fast propagation.

Next, we are adding a resource that tells AWS to wait for validation to complete before proceeding. It depends on the DNS record being correct.

# modules/acm/main.tf
resource "aws_acm_certificate_validation" "cert" {
  provider        = aws.us_east_1
  certificate_arn = aws_acm_certificate.cert.arn
  validation_record_fqdns = [
    for record in aws_route53_record.cert_validation : record.fqdn
  ]
}

Let's also output the certificate ARN for later use:

# modules/acm/outputs.tf
output "aws_acm_certificate_arn" {
  value = aws_acm_certificate.cert.arn
}

output "aws_acm_certificate_cert" {
  value = aws_acm_certificate.cert
}

Add this module to your main terraform file:

# main.tf
module "ssl_acm" {
  source              = "./modules/acm"
  aws_route53_zone_id = aws_route53_zone.main.zone_id
}

And now we have ACM certificate ready to be used in API Gateway. Let's ensure everything is correct by running:

terraform init
terraform apply --auto-approve

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Next Steps

With the SSL certificate provisioned, you can now integrate it with your AWS services. In the next guides, we will demonstrate how to use this certificate with API Gateway and Application Load Balancer for SSL termination. Feel free to skip to the relevant section based on your architecture needs.

Previous: SSL Termination Overview | Next: API Gateway SSL Termination

Provisioning SSL Termination for Web Application

Viktor Vasylkovskyi — Wed, 06 May 2026 15:53:30 +0000

Previous: Terraform Modules Best Practices

SSL termination is one of those steps that feels small but shapes your entire architecture. It is a common pattern to offload the SSL termination off your application, and instead make other cloud resource act as an SSL proxy. There are several ways to do it in AWS, and each comes with its own trade-offs. The “right” choice depends less on preference and more on the kind of traffic you're serving. In cloud, three resources can act as SSL termination: Load Balancer, a Content Delivery Network Origin, or an API Gateway.

If you're building a pure REST API, AWS API Gateway is usually the simplest path. It handles SSL for you, integrates cleanly with Lambda or EC2, and keeps the moving parts to a minimum. The catch? It isn't great for serving frontend assets - you'll quickly notice limitations around caching and file delivery.

Then there's the Application Load Balancer. It works for both APIs and web apps, gives you full control, and is the most “production-ready” option. But it comes with overhead: more infrastructure, higher cost, and the expectation that you’ll eventually run multiple EC2 instances across multiple availability zones. ALB shines when your system is growing, but it's definitely not the lightest way to get started.

This section walks through all three approaches. We will start with API Gateway for pure APIs and finally ALB for production-grade systems. By the end, you'll have a clear picture of how SSL termination fits into different architectures and which option makes sense for your next project.

Previous: Terraform Modules Best Practices | Next: Provision SSL Certificate

Provisioning EC2 Instances with Terraform Modules - Best Practices Guide

Viktor Vasylkovskyi — Wed, 06 May 2026 15:52:59 +0000

Previous: Provision DNS Records with Terraform

In this notes, we are going to learn how to organise terraform code using best practices like terraform modules. For the sake of simplicity we will reduce the code to the very basic example. An interesting side-effect is by modularizing our code, we can easily create multiple environments like dev and prod, which we will see later.

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v3-terraform-modules. Feel free to clone it and follow along!

Creating Terraform Modules

Modularizing Terraform means splitting our infrastructure code into reusable, logical components called modules. This improves maintainability, reusability, and clarity, especially as our infrastructure grows.

The best practices are separation of concerns, using inputs and outputs for modules. There are Root Module and Child Modules, where root module is the directory where the terraform commands are meant to run, and child modules are the ones that contain reusable code.

We will create 3 modules: network, ec2 and dns.

The overall folder structure should look like follows:

.
├── modules/
│   ├── network
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   ├── ec2
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   └── outputs.tf
│   ├── dns
│   │    ├── main.tf
│   │    ├── variables.tf
│   │    └── outputs.tf
├── main.tf
├── variables.tf
├── outputs.tf
└── terraform.tfvars

Module: network

resource "aws_vpc" "main" {
  cidr_block           = var.vpc_cidr
  enable_dns_hostnames = true
  enable_dns_support   = true
}

resource "aws_subnet" "my_app" {
  cidr_block        = var.subnet_cidr
  vpc_id            = aws_vpc.main.id
  availability_zone = var.availability_zone
}

resource "aws_internet_gateway" "my_app" {
  vpc_id = aws_vpc.main.id
}

resource "aws_route_table" "my_app" {
  vpc_id = aws_vpc.main.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.my_app.id
  }
}

resource "aws_route_table_association" "subnet-association" {
  subnet_id      = aws_subnet.my_app.id
  route_table_id = aws_route_table.my_app.id
}

Variables:

# variables.tf

variable "vpc_cidr" { type = string }
variable "subnet_cidr" { type = string }
variable "availability_zone" { type = string }

Outputs:

output "vpc_id" { value = aws_vpc.main.id }
output "subnet_id" { value = aws_subnet.my_app.id }

Module: ec2

resource "aws_security_group" "my_app" {
  name   = "Security Group for EC2 Instance"
  vpc_id = var.vpc_id

  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
  }


  ingress {
    cidr_blocks = ["0.0.0.0/0"]
    from_port   = 22
    to_port     = 22
    protocol    = "tcp"
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

resource "aws_key_pair" "ssh-key" {
  key_name   = "ssh-key"
  public_key = var.ssh_public_key
}

resource "aws_instance" "my_app" {
  ami                         = var.instance_ami
  instance_type               = var.instance_type
  availability_zone           = var.availability_zone
  security_groups             = [aws_security_group.my_app.id]
  associate_public_ip_address = true
  subnet_id                   = var.subnet_id
  key_name                    = aws_key_pair.ssh-key.key_name
}

resource "aws_eip" "my_app" {
  instance = aws_instance.my_app.id
  domain   = "vpc"
}

We will also add security group next to our EC2 module to allow SSH and HTTP access.

Variables:

# variables.tf

variable "instance_ami" { type = string }
variable "instance_type" { type = string }
variable "availability_zone" { type = string }
variable "subnet_id" { type = string }
variable "ssh_public_key" { type = string }
variable "vpc_id" { type = string }

Outputs:

output "instance_id" { value = aws_instance.my_app.id }
output "public_ip"   { value = aws_eip.my_app.public_ip }

Using modules - route module

The root modules will reference the children modules and assign the variables.

# main.tf

provider "aws" {
  region                   = "us-east-1"
  shared_credentials_files = ["./.aws-credentials"]
  profile                  = "terraform"
}

module "network" {
  source            = "./modules/network"
  vpc_cidr          = "10.0.0.0/16"
  subnet_cidr       = "10.0.1.0/24"
  availability_zone = var.availability_zone
}

module "security_group" {
  source = "./modules/security_group"
  vpc_id = module.network.vpc_id
}

module "ec2" {
  source            = "./modules/ec2"
  instance_ami      = var.instance_ami
  instance_type     = var.instance_type
  availability_zone = var.availability_zone
  subnet_id         = module.network.subnet_id
  ssh_public_key    = var.ssh_public_key
}

And the outputs:

# outputs.tf

output "ec2_ip_address" {
  value       = module.ec2.public_ip
  description = "The Elastic IP address allocated to the EC2 instance."
}

Install modules and apply

The modules have to be installed, so we need to run terraform init first. After that run terraform apply --auto-approve to see that everything works ok. You should see something like this on terminal:


Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:
ec2_ip_address = "your-ip"

Adding DNS module pointing to our instance and a simple HTTP server

Now to make things interesting, we will create a simple web server and two environments - dev and prod. A common requirement for web applications.

To accomplish that, we need to create:

DNS module
Update EC-2 Module to launch HTTP server
Make dev and prod environments

DNS Module

Similarly, we will create the module called dns with 3 files in it - main, variables, outputs.

# main.tf
resource "aws_route53_record" "www" {
  zone_id = var.main_zone_id
  name    = var.domain_name
  type    = "A"
  ttl     = 60
  records = [var.dns_record]
}

Variables:

# variables.tf

variable "main_zone_id" { type = string }
variable "domain_name" { type = string }
variable "dns_record" { type = string }

# outputs.tf
output "dns_record" {
  value       = aws_route53_record.www.fqdn
  description = "The FQDN of the www Route53 record"
}

We will leave outputs.tf black for now.

Now in our route53.tf:

# route53.tf

resource "aws_route53_zone" "main" {
  name = "viktorvasylkovskyi.com"
}

module "aws_route53_record" {
  source       = "./modules/dns"
  domain_name  = var.domain_name
  main_zone_id = aws_route53_zone.main.zone_id
  dns_record   = module.ec2.public_ip
}

Note, the domain_name is your domain name that you should own. Declare this variable in your variables.tf in the root module, and define it in terraform.tfvars.

Updating our EC-2 to start HTTP server

Now, let's update our ec2 module in main.tf. We are going to add a user_data that will instantiate a simple http server on the startup of the machine. Add the following:

# ec2.main.tf

resource "aws_instance" "app" {
  ... your instance previous code ...
  user_data = <<-EOF
              #!/bin/bash
              sudo yum update -y || sudo apt-get update -y
              sudo yum install -y python3 || sudo apt-get install -y python3
              echo "<html><body><h1>Hello from Terraform EC2!</h1></body></html>" > index.html
              nohup python3 -m http.server 80 &
              EOF
}

Adding outputs

Add outputs at the root module:

# outputs.tf

output "ec2_domain_name" {
  value       = module.aws_route53_record.dns_record
  description = "The Elastic IP address allocated to the EC2 instance."
}

Apply changes

Run terraform init and terraform apply --auto-approve and see your server working. You should be able to open browser at var.domain_name.

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

By modularizing our Terraform code, we make our infrastructure more organized, reusable, and easier to maintain. This approach not only saves time as our projects grow, but also helps us avoid duplication and mistakes. With modules, scaling and evolving your infrastructure becomes a much smoother process.
Next we are going to focus on security, and more importantly, the SSL termination for our web applications.

Appendix

(Note, the following is optional. The following guides assume you do not follow this in the code, for simplicity sake.)

Adding dev and production environments

The great thing about modules is that we can reuse them. Let's reuse them in two environments: prod and dev. We need to refactor our code such that we have new folder structure:

environments/
  dev/
    main.tf
    terraform.tfvars
    variables.tf
  prod/
    main.tf
    terraform.tfvars
    variables.tf
modules/

Note, since our environments will be pretty much the same, the terraform.tfvars are going to drive the change of the environments.

Example of the terraform.tfvars in dev

availability_zone = "us-east-1a"
instance_ami      = "ami-xxxx"
instance_type     = "t2.micro"
domain_name       = "dev.example.com"

and in prod

availability_zone = "us-east-1b"
instance_ami      = "ami-yyyy"
instance_type     = "t3.medium"
domain_name       = "prod.example.com"

Now, you can apply.

Applying multiple environments

You can apply both environments using terraform apply. Just jump into the folder and run apply.

Previous: Provision DNS Records with Terraform | Next: SSL Termination Overview

Provision DNS records with Terraform

Viktor Vasylkovskyi — Wed, 06 May 2026 15:52:00 +0000

Previous: Deploying EC2 instance with Terraform

In the previous notes we talked about how to setup the ec2 instance inside of the VPC on the subnet. We managed to access to this instance via SSH by providing ssh key in security groups. If you haven't read about it, fear not, you can still go back and read it: Deploying EC2 instance on AWS with Terraform.

All is fine and dandy until now, but when we want to run a real application, we want to expose it on HTTP (and later HTTPS). In this note, I will walk you through how to do it using terraform. In practice, we will spawn a simple http server on our ec2 instance, and provide Route53 DNS records (diagram below).

When adding DNS, we will be able to access our application not via IP address like

http://52.206.93.210/

but via actual domain that you own like

http://www.your-domain.com

Let's dive in!

Github Repository

This guide full code is available in https://github.com/IaC-Toolbox/iac-toolbox-project/tree/main/v2-ec2-http. Feel free to clone it and follow along!

Spawn HTTP server on ec2 instance

in your ec2.tf add the following:

resource "aws_instance" "app" {
  ... your instance previous code ...
  user_data = <<-EOF
              #!/bin/bash
              sudo yum update -y || sudo apt-get update -y
              sudo yum install -y python3 || sudo apt-get install -y python3
              echo "<html><body><h1>Hello from Terraform EC2!</h1></body></html>" > index.html
              nohup python3 -m http.server 80 &
              EOF
}

In outputs.tf ensure you have the following:

output "ec2_ip_address" {
  value       = aws_eip.my_app.public_ip
  description = "The Elastic IP address allocated to the EC2 instance."
}

The user_data is a cool utility in aws that allows us to bake in ec2 some bootstrap code. In this example we start a server using python that is a simple <html><body><h1>Hello from Terraform EC2!</h1></body></html> static page.

Add HTTP rule to security group

In security-groups.tf ensure that you have the following rule to allow HTTP access:

resource "aws_security_group" "my_app" {
  vpc_id = aws_vpc.main.id
  # ... other rules ...
  ingress {
    cidr_blocks = [
      "0.0.0.0/0"
    ]
    from_port = 80
    to_port   = 80
    protocol  = "tcp"
  }
  # ... other rules ...
}

Testing the setup

Run terraform apply --auto-approve.

See the output:

ec2_ip_address = "3.214.79.152" # example output

Navigate to ec2_ip_address and see website opening

Adding Route53 records

Next step, to create DNS records we actually have to create a hosted zone first.

Prerequisite: Domain name

Before we proceed, ensure that you have a domain name registered. You can use any domain registrar of your choice (e.g., GoDaddy, Namecheap, Cloudflare, etc.). For this example, we'll use your-domain.com. Replace it with your actual domain name in the Terraform code.

Run terraform apply --auto-approve and navigate to Route 53 Hosted Zones and confirm that your hosted zone was created.

Adding Route53 records

Lets begin our route53.tf

# route53.tf
resource "aws_route53_zone" "main" {
  name = "your-domain.com"
}

Updating DNS Registrar

At this point, there is a manual step where we actually have to go to the web and click our way through. We need to ensure that our DNS registrar has namespaces of our hosted zone from route 53. You may be familiar with the process of updating NS records in your registrar.

You may have purchased your domain from a registrar providers, in my case it is happens to be AWS. But there are many (e.g., GoDaddy, Namecheap, Cloudflare, etc.). So I leave you figure out how to find your DNS management in the registrar. Once you get there, next step is update the NS records to the ones that you have just created with the terraform in AWS.

Update DNS NameSpace records in your DNS registrar

The new Route53 zone that we created using terraform above can be found in the Hosted Zones. Open the zone and find the NS records.

Next step is to copy those NS records and add them one by one into DNS registrar of your choice (e.g. Cloudflare). These NS records essentially are addresses that will know how to find that DNS records of Route53.

The general flow is:

The user navigates to www.your-domain.com
The your-domain.com registrar checks its NS records to find out where to look for DNS records.
The registrar finds the NS records that point to Route53.
The registrar queries Route53 for the DNS records of www.your-domain.com.
Route53 responds with the IP address associated with www.your-domain.com.

Therefore, it is a crucial step to update the NS records in your DNS registrar to point to the Route53 (AWS) name servers.

Add new DNS record

Once this is done we can proceed and add new DNS record using terraform:

# route53.tf
resource "aws_route53_zone" "main" {
  name = "your-domain.com"
}

resource "aws_route53_record" "www" {
  zone_id = aws_route53_zone.main.zone_id
  name    = "www.your-domain.com"
  type    = "A"
  ttl     = 60
  records = [aws_eip.my_app.public_ip]
}

Above we are creating a DNS record of type A which is a type that assigns DNS name to Ipv4 IP address. Note that in this example we are using EIP which are fixed IP, to avoid the issues with dynamic IP addresses. This way we make sure that even if the EC2 instance is restarted, and receives new private IP, we still keep same fixed public IP. Lets apply and test terraform apply --auto-approve.

Note, check if the name servers got applied. Sometimes it takes a while for your changes to take effect. You can check by running:

dig +short NS your-domain.com

In the output, you should see the name servers that you have added in your DNS registrar. If they are not correct, wait a bit longer, you should receive the following error in browser DNS_PROBE_FINISHED_NXDOMAIN which indicates that the DNS records are not yet propagated.

Once they are correct, your DNS should be applied. Visit http://www.your-domain.com and see it showing our demo app!

Destroying Infra

Remember, infra has costs. When you are done experimenting, you can destroy the infra like follows:

terraform destroy --auto-approve

Conclusion

And that is a wrap! Now we have the DNS records pointing to our Ec2 instance. Next, let's explore about how to add SSL to this domain and enable HTTPS. But before that, let's organize our code a little. Continue reading!

Previous: Deploying EC2 instance with Terraform | Next: Terraform Modules Best Practices