AWS on Eric Ngigi's Blog

CI/CD for Hugo: AWS, GitHub Actions & Cloudflare via Terraform

Mon, 13 Oct 2025 00:00:00 +0000

Introduction

In modern web development, automation has become a cornerstone of efficiency and reliability. Static site generators like Hugo make it easy to build fast, lightweight websites, but deploying and managing them securely and consistently can be challenging without proper automation. That’s where Terraform, AWS, Cloudflare, and GitHub Actions come together to create a fully automated and secure deployment pipeline.

This article walks through the automation of a Hugo CI/CD pipeline using Terraform to provision cloud resources and GitHub Actions to handle continuous integration and delivery. The pipeline builds Hugo’s static files, uploads them to Amazon S3, and serves them globally through CloudFront with SSL certificates managed by AWS Certificate Manager (ACM). Finally, Cloudflare is used to map a custom subdomain to the CloudFront distribution, ensuring global accessibility and security via DNS and SSL integration.

By the end of this guide, you’ll understand how each Terraform module - storage, network, security, and cloudflare - fits together to form a complete infrastructure-as-code solution. You’ll see how to securely connect GitHub Actions to AWS using OpenID Connect (OIDC), and how the modular Terraform approach keeps the setup scalable, maintainable, and reusable across projects.

Project Structure and Module Overview

Before diving into the implementation, it’s important to understand how the Terraform configuration is organized. The project follows a modular design, where each core component of the infrastructure - storage, networking, security, and DNS - is defined as an independent Terraform module. This structure improves readability, reusability, and scalability, allowing you to make updates to one part of the infrastructure without affecting the others.

At the heart of the setup is the main.tf file, which serves as the orchestrator for all the modules. It defines how these modules interact, passing outputs from one module as inputs to another. For instance, the storage module creates the S3 bucket that hosts the Hugo-generated static files, and the network module consumes its details to configure a CloudFront distribution for global delivery. Similarly, the security module defines the IAM roles and OIDC permissions needed for GitHub Actions to deploy securely to AWS, while the cloudflare module manages DNS and SSL integration for the public-facing domain.

Each module encapsulates a specific function:

Storage Module: Handles S3 bucket creation and access configuration for static site hosting.
Network Module: Sets up CloudFront for content delivery and configures SSL certificates via AWS ACM.
Security Module: Manages IAM roles, policies, and OIDC trust relationships for secure GitHub Actions deployments.
Cloudflare Module: Connects Cloudflare DNS records to the CloudFront distribution and manages domain SSL validation.

This modular approach keeps the Terraform configuration clean, easier to maintain, and ideal for CI/CD workflows where each component can evolve independently. In the next sections, we’ll explore each module in detail and examine how they integrate to form a fully automated deployment pipeline for a Hugo website.

Configuring AWS for Secure GitHub Actions Access (Terraform Setup)

Before automating deployments with GitHub Actions, we first need to create the AWS resources that will enable secure authentication and object storage for our Hugo site. This foundation ensures that GitHub can deploy to AWS without static access keys, using OpenID Connect (OIDC) instead.

The Terraform configuration below lives in the security and storage modules, forming the security and storage backbone of the CI/CD pipeline.

Establishing OIDC Trust Between GitHub and AWS

We start by defining an OpenID Connect (OIDC) provider in AWS that recognizes GitHub as a trusted identity source. This allows GitHub Actions workflows to assume roles in AWS using temporary tokens rather than permanent credentials.

variables.tf (security module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


variable "github_org" {
 description = "GitHub organization or username"
 type = string
}

variable "github_repo" {
 description = "Github repository name"
 type = string
}

# Security details
variable "git_oidc_url" {
 description = "GitHub actions OIDC url"
 type = string
}

variable "oidc_thumbprint" {
 description = "SHA1 thumbprint for GitHub OIDC provider SSL certificate"
 type = string
}

variable "git_oidc_thumbprint_list" {
 description = "List of thumbprints for the GitHub OIDC provider"
 type = list(string)
}

main.tf (security module):

1
2
3
4
5
6
7


# OIDC Provider for GitHub Actions
resource "aws_iam_openid_connect_provider" "github" {
 url = var.git_oidc_url

 client_id_list = ["sts.amazonaws.com"]
 thumbprint_list = var.git_oidc_thumbprint_list
}

This resource registers GitHub’s identity provider (token.actions.githubusercontent.com) with AWS. The thumbprint_list ensures the TLS certificate used by GitHub is valid and trusted.

Creating the IAM Role for GitHub Actions

Next, we define an IAM role that GitHub Actions will assume during deployment. The trust policy allows GitHub’s OIDC provider to assume the role, but only for a specific organization and repository.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


resource "aws_iam_role" "github_actions" {
 name = "github-actions-hugo-deploy"
 assume_role_policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Effect = "Allow"
 Principal = {
 Federated = aws_iam_openid_connect_provider.github.arn
 }
 Action = "sts:AssumeRoleWithWebIdentity"
 Condition = {
 StringEquals = {
 "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
 }
 StringLike = {
 "token.actions.githubusercontent.com:sub" = "repo:${var.github_org}/${var.github_repo}:*"
 }
 }
 }
 ]
 })
 tags = {
 Name = "GitHub Actions Hugo Deploy Role"
 }
}

This configuration limits access to a specific repository, enforcing the principle of least privilege. Only workflows running in that repository can assume this role via OIDC.

outputs.tf:

1
2
3
4


output "github_action_role_arn" {
 description = "ARN of the IAM role for GitHub Actions"
 value = aws_iam_role.github_actions.arn
}

This ARN will be used later in the GitHub Actions workflow when configuring AWS credentials.

Creating the S3 Bucket for Hugo Site Hosting

With the security layer in place, we define an S3 bucket to host the static site generated by Hugo.

variables.tf (storage module):

1
2
3
4
5
6
7
8
9


variable "project_name" {
 description = "Project name used for resource tagging"
 type = string
}

variable "cloudfront_distribution_arn" {
 description = "Cloudfront Distribution ARN from the network module"
 type = string
}

main.tf (storage module):

1
2
3
4
5
6
7


resource "aws_s3_bucket" "hugo_site" {
 bucket = "${var.project_name}-stack-theme-s3"

 tags = {
 Name = "Hugo Theme Stack Site"
 }
}

Additional configurations are added to enhance security and compliance:

Block public access
Enable server-side encryption
Restrict CloudFront access

main.tf (storage module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


resource "aws_s3_bucket_public_access_block" "hugo_site" {
 bucket = aws_s3_bucket.hugo_site.id

 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

resource "aws_s3_bucket_server_side_encryption_configuration" "hugo_site" {
 bucket = aws_s3_bucket.hugo_site.id

 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

We also create a bucket policy allowing CloudFront to retrieve objects for content delivery:

main.tf (storage module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


resource "aws_s3_bucket_policy" "hugo_site" {
 bucket = aws_s3_bucket.hugo_site.id

 policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Sid = "AllowCloudFrontServicePrincipal"
 Effect = "Allow"
 Principal = {
 Service = "cloudfront.amazonaws.com"
 }
 Action = "s3:GetObject"
 Resource = "${aws_s3_bucket.hugo_site.arn}/*"
 Condition = {
 StringEquals = {
 "AWS:SourceArn" = var.cloudfront_distribution_arn
 }
 }
 }
 ]
 })
}

outputs.tf (storage module):

1
2
3
4
5
6
7
8
9


output "s3_bucket_arn" {
 description = "Resource output for the ARN value of the hugo s3 bucket"
 value = aws_s3_bucket.hugo_site.arn
}

output "s3_bucket_name" {
 description = "Name of the s3 bucket"
 value = aws_s3_bucket.hugo_site.id
}

Attaching IAM Policy to the GitHub Actions Role

Finally, we grant GitHub Actions permissions to upload, list, and delete objects in the S3 bucket.

main.tf (security module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


resource "aws_iam_role_policy" "github_actions" {
 name = "github-actions-hugo-policy"
 role = aws_iam_role.github_actions.id

 policy = jsonencode({
 Version = "2012-10-17"
 Statement = [
 {
 Effect = "Allow"
 Action = [
 "s3:PutObject",
 "s3:GetObject",
 "s3:DeleteObject",
 "s3:ListBucket"
 ]
 Resource = [
 var.hugo_s3_bucket_arn,
 "${var.hugo_s3_bucket_arn}/*"
 ]
 }
 ]
 })
}

This IAM policy ensures that the GitHub workflow can safely interact with the S3 bucket — uploading the Hugo build output during deployment.

3.5. Connecting the Terraform Outputs to GitHub Actions

With the Terraform configuration applied, AWS now has:

A registered OIDC provider for GitHub
An IAM role that can be assumed by your repository’s workflow
A secure S3 bucket for static file hosting

From the Terraform outputs, we’ll use the following values in GitHub Actions secrets:

IAM_ROLE_ARN → Output from github_action_role_arn
S3_BUCKET → Output from s3_bucket_name
AWS_REGION → Defined in Terraform or AWS provider

These secrets will allow GitHub Actions to assume the IAM role via OIDC and deploy directly to the bucket.

GitHub Actions Workflow: Building and Deploying the Hugo Site

With the AWS side configured, we can now implement the GitHub Actions workflow. This workflow uses the IAM role and S3 bucket created by Terraform to automatically build and deploy the Hugo site.

The workflow file (.github/workflows/build-hugo-site.yml) performs the following tasks:

Trigger on Push: Runs on commits to the dev branch.
Build Hugo: Compiles static files with the specified Hugo version.
Assume IAM Role via OIDC: Authenticates securely with AWS.
Deploy to S3: Uploads the public/ directory to the bucket.
Invalidate CloudFront Cache: Ensures global users see the latest version immediately.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


name: Build Hugo site
on:
 push:
 branches:
 - dev
permissions:
 id-token: write
 contents: read
jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v4
 with:
 submodules: recursive
 fetch-depth: 0
 - name: Setup Hugo
 uses: peaceiris/actions-hugo@v2
 with:
 hugo-version: '0.150.0'
 extended: true
 - name: Build minified pages
 run: hugo --gc --minify
 - name: Debug - List public directory contents
 run: |
 echo "=== Contents of public/ directory ==="
 ls -laR public/
 echo ""
 echo "=== HTML files found ==="
 find public/ -name "*.html" -type f
 echo ""
 echo "=== Total file count ==="
 find public/ -type f | wc -l
 - name: Configure AWS Credentials
 if: github.event_name != 'pull_request'
 uses: aws-actions/configure-aws-credentials@v4
 with:
 aws-region: ${{ secrets.AWS_REGION }}
 role-to-assume: ${{ secrets.IAM_ROLE_ARN }}
 - name: Debug AWS credentials
 if: github.event_name != 'pull_request'
 run: |
 aws sts get-caller-identity
 - name: Sync public directory with S3 bucket
 run: |
 aws s3 sync ./public s3://${{ secrets.S3_BUCKET }} --delete
 - name: Invalidate CloudFront cache
 if: github.event_name != 'pull_request'
 uses: aws-actions/configure-aws-credentials@v4
 with:
 role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
 aws-region: ${{ secrets.AWS_REGION }}
 continue-on-error: true
 - name: Create CloudFront invalidation
 if: github.event_name != 'pull_request'
 run: |
 aws cloudfront create-invalidation \
 --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
 --paths "/*"
 continue-on-error: true
 - name: Build Summary
 if: github.event_name != 'pull_request'
 run: |
 echo "### Deployment Successful! :rocket:" >> $GITHUB_STEP_SUMMARY

Workflow Overview

The workflow resides in .github/workflows/build-hugo-site.yml and performs these primary functions:

Triggering Conditions The workflow runs on a push to the dev branch. This allows developers to test and validate changes in a development environment before they are promoted to production.
Permissions Configuration Permissions are configured to allow GitHub Actions to generate an OIDC token (id-token: write) and access repository contents (contents: read). The OIDC token is crucial because it enables secure, short-lived authentication with AWS — eliminating the need for static credentials.

Job: Build

The build job runs on an Ubuntu-based GitHub Actions runner (ubuntu-latest) and executes the core CI/CD steps.

Checkout Code

1
2
3
4
5


- name: Checkout code
 uses: actions/checkout@v4
 with:
 submodules: recursive
 fetch-depth: 0

This step retrieves the source code from the repository, including any submodules (such as Hugo themes), ensuring the full codebase is available for the build.

Setup Hugo

1
2
3
4
5


- name: Setup Hugo
 uses: peaceiris/actions-hugo@v2
 with:
 hugo-version: '0.150.0'
 extended: true

Here we install the specific Hugo version required for the build. Using a defined version guarantees consistency between local and CI builds.

Build and Optimize Site

1
2


- name: Build minified pages
 run: hugo --gc --minify

This command generates the static site files in the public/ directory, removing unused assets (--gc) and minifying the output (--minify) for optimal performance.

Debugging Build Output

1
2
3
4
5


- name: Debug - List public directory contents
 run: |
 echo "=== Contents of public/ directory ==="
 ls -laR public/
 ...

A diagnostic step to inspect the build output before deployment. This helps identify missing or misconfigured assets early in the pipeline.

Configure AWS Credentials via OIDC

1
2
3
4
5


- name: Configure AWS Credentials
 uses: aws-actions/configure-aws-credentials@v4
 with:
 aws-region: ${{ secrets.AWS_REGION }}
 role-to-assume: ${{ secrets.IAM_ROLE_ARN }}

This step allows GitHub Actions to assume an AWS IAM role securely via OpenID Connect (OIDC). Unlike static AWS keys, OIDC tokens are short-lived and automatically managed, improving security posture.

Verify AWS Connection

1
2


- name: Debug AWS credentials
 run: aws sts get-caller-identity

This command confirms successful authentication with AWS and verifies which IAM role the workflow is using.

Deploy Static Files to S3

1
2


- name: Sync public directory with S3 bucket
 run: aws s3 sync ./public s3://${{ secrets.S3_BUCKET }} --delete

Uploads all generated files from the public/ directory to the specified S3 bucket. The --delete flag ensures the bucket mirrors the latest build exactly by removing outdated files.

CloudFront Cache Invalidation

1
2
3
4
5


- name: Create CloudFront invalidation
 run: |
 aws cloudfront create-invalidation \
 --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
 --paths "/*"

Invalidates the CloudFront cache so users immediately see updated content after each deployment.

Why This Step Comes First

This workflow forms the foundation of the CI/CD pipeline. It ensures that:

Hugo site builds can be automated and verified directly in GitHub.
Secure OIDC-based authentication with AWS is already in place.
The deployment process (S3 upload + CloudFront invalidation) is tested and working before Terraform provisions or manages any infrastructure.

Setting Up the Network Module: CloudFront Distribution and SSL Certificate

With the static Hugo site now securely stored in Amazon S3, the next step is to distribute it globally and serve it over HTTPS. We achieve this using Amazon CloudFront — AWS’s Content Delivery Network (CDN) — and AWS Certificate Manager (ACM) for SSL/TLS certificates.

This section focuses on defining the network module in Terraform, which provisions the CloudFront distribution, origin access control (OAC), a function for clean URLs, and the SSL certificate required for HTTPS.

CloudFront Origin Access Control (OAC)

The first resource in this module is the Origin Access Control (OAC), which replaces the older OAI mechanism. It ensures CloudFront can securely fetch files from the S3 bucket using signed requests, while preventing direct public access.

variables.tf (network module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


variable "s3_bucket_name" {
 description = "Name of the s3 hugo bucket"
 type = string
}

variable "s3_bucket_regional_domain_name" {
 description = "Domain name of the s3 hugo bucket"
 type = string
}

variable "domain_name" {
 description = "Domain name"
 type = string
}

variable "subdomain_name" {
 description = "Subdomain name"
 type = string
}

main.tf (network module):

1
2
3
4
5
6
7


resource "aws_cloudfront_origin_access_control" "hugo_site" {
 name = "${var.s3_bucket_name}-oac"
 description = "OAC for the hugo site"
 origin_access_control_origin_type = "s3"
 signing_behavior = "always"
 signing_protocol = "sigv4"
}

CloudFront Function for Clean URLs

Next, we define a CloudFront Function to handle “clean URLs.” Since Hugo generates content as index.html within folders, this function rewrites incoming requests to point to the correct file.

main.tf (network module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


resource "aws_cloudfront_function" "url_rewrite" {
 name = "hugo-url-rewrite"
 runtime = "cloudfront-js-2.0"
 comment = "Rewrite URLs to add index.html for Hugo"
 publish = true
 code = <<-EOT
function handler(event) {
 var request = event.request;
 var uri = request.uri;

 if (uri.endsWith('/')) {
 request.uri += 'index.html';
 }
 else if (!uri.includes('.')) {
 request.uri += '/index.html';
 }

 return request;
}
EOT
}

This allows users to access /about/ instead of /about/index.html, providing a cleaner and more professional URL structure.

CloudFront Distribution Configuration

The CloudFront distribution connects the CDN to the S3 origin, enforces HTTPS, enables caching, and associates the custom subdomain.

main.tf (network module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68


resource "aws_cloudfront_distribution" "hugo_site" {
 enabled = true
 is_ipv6_enabled = true
 default_root_object = "index.html"
 price_class = "PriceClass_100"
 comment = "Hugo site distribution"
 http_version = "http2and3"

 aliases = ["${var.subdomain_name}.${var.domain_name}"]

 origin {
 domain_name = var.s3_bucket_regional_domain_name
 origin_id = "S3-${var.s3_bucket_name}"
 origin_access_control_id = aws_cloudfront_origin_access_control.hugo_site.id
 }

 default_cache_behavior {
 allowed_methods = ["GET", "HEAD", "OPTIONS"]
 cached_methods = ["GET", "HEAD"]
 target_origin_id = "S3-${var.s3_bucket_name}"

 forwarded_values {
 query_string = false
 cookies {
 forward = "none"
 }
 }

 function_association {
 event_type = "viewer-request"
 function_arn = aws_cloudfront_function.url_rewrite.arn
 }

 viewer_protocol_policy = "redirect-to-https"
 min_ttl = 0
 default_ttl = 3600
 max_ttl = 86400
 compress = true
 }

 custom_error_response {
 error_code = 404
 response_code = 404
 response_page_path = "/404.html"
 }

 custom_error_response {
 error_code = 403
 response_code = 404
 response_page_path = "/404.html"
 }

 restrictions {
 geo_restriction {
 restriction_type = "none"
 }
 }

 viewer_certificate {
 acm_certificate_arn = aws_acm_certificate.hugo_site.arn
 ssl_support_method = "sni-only"
 minimum_protocol_version = "TLSv1.2_2021"
 }

 tags = {
 Name = "Hugo Site Distribution"
 }
}

This configuration enforces HTTPS, compresses content for faster delivery, and integrates directly with ACM for secure SSL termination.

SSL Certificate with AWS Certificate Manager (ACM)

Before CloudFront can serve HTTPS traffic, a valid certificate must be provisioned. We use AWS Certificate Manager (ACM) for this, specifying DNS validation for automatic verification.

main.tf (network module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


resource "aws_acm_certificate" "hugo_site" {
 domain_name = "${var.subdomain_name}.${var.domain_name}"
 validation_method = "DNS"
 key_algorithm = "EC_prime256v1"

 options {
 certificate_transparency_logging_preference = "ENABLED"
 }

 lifecycle {
 create_before_destroy = true
 }

 tags = {
 Name = "Hugo Site Certificate"
 }
}

Note: For CloudFront, the ACM certificate must always be created in the us-east-1 region.

Network Module Outputs

Once the resources are deployed, several key outputs from the network module are required by other Terraform modules — including Cloudflare for DNS and validation setup.

outputs.tf (network module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


output "cloudfront_distribution_arn" {
 description = "Resource output for the cloudfront distribution arn"
 value = aws_cloudfront_distribution.hugo_site.arn
}

output "cloudfront_distribution_id" {
 description = "CloudFront distribution ID"
 value = aws_cloudfront_distribution.hugo_site.id
}

output "cloudfront_domain_name" {
 description = "CloudFront distribution URL (HTTPS)"
 value = aws_cloudfront_distribution.hugo_site.domain_name
}

output "acm_validation_options" {
 description = "ACM certificate validation DNS records"
 value = [
 for dvo in aws_acm_certificate.hugo_site.domain_validation_options : {
 name = dvo.resource_record_name
 type = dvo.resource_record_type
 value = dvo.resource_record_value
 }
 ]
}

These outputs provide critical data that downstream modules—like Cloudflare—will consume to finalize DNS setup and SSL validation. The acm_validation_options in particular are used to automatically create DNS records for certificate validation.

Configuring Cloudflare: DNS, SSL Validation, and Subdomain Binding

With the CloudFront distribution and SSL certificate in place, the final step is to make the site accessible through your custom domain. We’ll use Cloudflare to manage DNS records, handle ACM certificate validation, and securely bind the subdomain to the CloudFront URL.

This configuration allows Cloudflare to act as a DNS and security layer—enabling global caching, DDoS protection, and HTTPS enforcement on top of AWS CloudFront.

Fetching Zone Information

Before adding any DNS records, Terraform must retrieve details about your Cloudflare-managed domain. The following data block fetches the zone ID based on the domain name provided as a variable (var.domain_name):

variables.tf (cloduflare module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


variable "domain_name" {
 description = "Domain name to use in filter options"
 type = string
}

variable "subdomain_name" {
 description = "Subdomain name to apply to cloudfront url"
 type = string
}

variable "cloudfront_url" {
 description = "Generated website url from cloudfront network module"
 type = string
}

variable "acm_validation_options" {
 description = "ACM certificate validation options from network module"
 type = list(object({
 name = string
 type = string
 value = string
 }))
}

provider.tf (cloudflare module):

1
2
3
4
5
6
7


terraform {
 required_providers {
 cloudflare = {
 source = "cloudflare/cloudflare"
 }
 }
}

main.tf (cloudflare module):

1
2
3


data "cloudflare_zones" "zone" {
 name = var.domain_name
}

Once the zone information is available, a secondary data source lists all existing DNS records in that zone. This is useful when validating or filtering existing records to avoid conflicts.

main.tf (cloudflare module):

1
2
3


data "cloudflare_dns_records" "all" {
 zone_id = data.cloudflare_zones.zone.result[0].id
}

Automating ACM Certificate Validation

When AWS Certificate Manager issues an SSL certificate for CloudFront, it requires DNS-based validation. To automate this process, Terraform dynamically creates the necessary DNS records in Cloudflare using the outputs from the network module (acm_validation_options).

main.tf (cloudflare module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


resource "cloudflare_dns_record" "acm_validation" {
 for_each = {
 for idx, record in var.acm_validation_options : idx => record
 }

 zone_id = data.cloudflare_zones.zone.result[0].id
 name = trimsuffix(each.value.name, ".")
 type = each.value.type
 content = trimsuffix(each.value.value, ".")
 ttl = 60
 proxied = false

 comment = "ACM certificate validation for ${var.subdomain_name}.${var.domain_name}"
}

Each record generated by this block corresponds to a validation entry required by ACM. Once these DNS records propagate, ACM automatically verifies domain ownership and issues the SSL certificate used by CloudFront.

Binding the Subdomain to CloudFront

After the SSL certificate is validated, we can now point the subdomain (e.g., blog.example.com) to the CloudFront distribution. The record below creates a CNAME entry in Cloudflare that maps the subdomain to CloudFront’s domain name, enabling public access to the static site.

main.tf (cloudflare module):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


resource "cloudflare_dns_record" "hugo_site" {
 zone_id = data.cloudflare_zones.zone.result[0].id
 name = var.subdomain_name
 ttl = 1
 type = "CNAME"
 content = var.cloudfront_url
 proxied = true

 comment = "Hugo site on CloudFront with Cloudflare SSL"

 depends_on = [cloudflare_dns_record.acm_validation]
}

Here’s what’s happening:

type = "CNAME": Points your subdomain to the CloudFront distribution.
proxied = true: Routes traffic through Cloudflare, enabling SSL, caching, and security features.
depends_on ensures the DNS validation records are created first, allowing ACM verification to complete before exposing the public domain.

Completing the CI/CD Pipeline

At this point, your Hugo static website is:

Built automatically via GitHub Actions and deployed to Amazon S3.
Distributed globally through AWS CloudFront with an ACM-managed SSL certificate.
Connected to a custom subdomain via Cloudflare, ensuring secure and performant access.

This final step completes the end-to-end automation of your CI/CD pipeline—combining Terraform’s Infrastructure as Code, GitHub Actions’ automation, and the scalability of AWS and Cloudflare.

Terraform AWS Three Tier Architecture

Fri, 10 Oct 2025 00:00:00 +0000

1. Overview

This project implements a Three-Tier Architecture on AWS, designed to provide a secure and highly available environment for deploying modern web applications.

The architecture separates components into three logical layers: Presentation (Web/App Tier), Application (Logic Tier), and Data (Database Tier) to ensure clear separation of concerns, better security, and easier scalability.

The deployment is fully automated using Terraform, enabling consistent, repeatable infrastructure provisioning.

1.1 Objectives

The goal of this architecture is to:

Provide a secure and isolated environment for application and database workloads.
Ensure high availability across multiple Availability Zones.
Maintain resilience and fault tolerance by leveraging AWS managed services.
Enable infrastructure as code (IaC) for repeatable and version-controlled deployments.

1.2 Architectural Layers

1.2.1 Presentation Layer (Web / Application Tier)

Consists of EC2 instances running the application or web server.
Deployed in private subnets across multiple Availability Zones.
Traffic is distributed using an Application Load Balancer (ALB) deployed in public subnets.
The ALB routes HTTP and HTTPS traffic to the backend EC2 instances for processing.

1.2.2 Application / Logic Layer

Handles core business logic and communicates with both the presentation and data tiers.
Uses Elastic File System (EFS) for shared storage between instances (e.g., logs, application data, uploads).

1.2.3 Data Layer

Uses Amazon RDS (MySQL) as the managed relational database engine.
Deployed in private subnets with Multi-AZ replication for high availability.
Database access is restricted to only the application layer via security groups.

1.3 Key AWS Components

Component	Purpose
VPC	Provides the isolated network environment.
Subnets	Separate public and private tiers across Availability Zones.
Internet Gateway	Enables public internet access for external users.
NAT Gateways	Allow private resources outbound access without direct internet exposure.
Application Load Balancer	Distributes traffic across EC2 instances in multiple AZs.
EC2 Instances	Host the web/application layer.
EFS	Provides shared storage across app instances.
RDS (MySQL)	Managed relational database for persistent data storage.
Security Groups	Control inbound and outbound network traffic between layers.

1.4 High-Level Features

Multi-AZ Deployment: Ensures redundancy and fault tolerance.
Secure Networking: Implements VPC isolation and least privilege access via security groups.
Automated Provisioning: Infrastructure managed using Terraform for consistency and versioning.
Centralized Storage: Shared EFS mounted across app instances for consistent file access.
Monitoring & Logging: Easily integrated with AWS CloudWatch for performance and health tracking.

1.5 Use Cases

This architecture is suitable for:

Web applications requiring a secure and scalable backend.
Internal enterprise applications with strict access controls.
Multi-tier deployments (frontend, backend, and database separation).
Environments that require high availability and fault tolerance across AWS Availability Zones.

2. Architecture Diagram

The following diagram illustrates the Three-Tier AWS Architecture implemented in this project. It depicts how each layer — presentation, application, and data — is logically and physically separated within the AWS environment to provide scalability, fault tolerance, and security.

2.1 Diagram

2.2 Architectural Components

The architecture is divided into multiple Availability Zones (AZs) to ensure high availability and fault tolerance. Each tier performs a specific role as outlined below:

2.2.1 Networking Layer

VPC (Virtual Private Cloud): Provides an isolated network environment for all deployed AWS resources.
Subnets:
- Public Subnets – Host the Application Load Balancer (ALB) and NAT Gateways.
- Private Subnets – Host EC2 application servers and RDS instances.
- Each subnet is distributed across two Availability Zones (e.g., us-east-1a, us-east-1b) for redundancy.
Internet Gateway: Enables inbound and outbound internet access for resources in public subnets.
NAT Gateways: Allow EC2 instances in private subnets to access the internet for software updates without exposing them publicly.

2.2.2 Presentation Layer (Web Tier)

Application Load Balancer (ALB):
- Acts as the entry point for all HTTP and HTTPS traffic.
- Deployed in public subnets for external accessibility.
- Routes requests to the EC2 instances in the private subnets via target groups.
- Supports both HTTP (port 80) and HTTPS (port 443) for secure communication.
Route 53 (DNS):
- (Optional) Provides a custom domain name that maps to the ALB’s DNS.
- Improves accessibility and branding of the deployed application.

2.2.3 Application Layer (App Tier)

EC2 Instances:
- Host the web or application logic (e.g., Nginx, Node.js, PHP, etc.).
- Deployed across multiple private subnets for high availability.
EFS (Elastic File System):
- Provides shared storage accessible by all EC2 instances in the app tier.
- Commonly used for logs, session data, media uploads, or persistent application files.
EC2 Security Group:
- Allows inbound traffic only from the ALB (port 80/443).
- Restricts outbound access to necessary services (e.g., database or NAT).

2.2.4 Data Layer (Database Tier)

Amazon RDS (MySQL):
- Deployed in private subnets to ensure database isolation from the public internet.
- Configured for Multi-AZ deployment for failover and data durability.
- Includes Primary and Replica instances for read/write separation and redundancy.
RDS Security Group:
- Allows inbound connections only from the Application Layer security group.
- Prevents direct public or administrative access from the internet.

2.2.5 Storage Layer

Amazon EFS (Elastic File System):
- Accessible from all EC2 instances across Availability Zones.
- Scales automatically to store application files without the need for manual provisioning.
- Enforced by the EFS Security Group to allow only authorized NFS access from the app tier.

2.3 Traffic Flow Summary

External users access the application through a DNS record (Route 53) or the ALB DNS name.
Requests reach the Application Load Balancer in the public subnet.
The ALB forwards traffic to EC2 instances in private subnets via Target Groups.
The EC2 application servers process requests, interact with the RDS database and EFS as needed.
Outbound internet access (for software updates or dependency downloads) is routed through the NAT Gateways.
All communication between layers is controlled using Security Groups and restricted by the principle of least privilege.

2.4 High Availability & Fault Tolerance

All tiers are deployed across two Availability Zones to ensure continuity in case of an AZ outage.
NAT Gateways, App Servers, and RDS instances are distributed between zones.
The Application Load Balancer automatically reroutes traffic to healthy targets during failures.

2.5 Security Considerations

No direct SSH or RDP access to EC2 instances from the internet.
Communication between tiers is restricted via dedicated Security Groups.
The database and EFS are deployed in private subnets with no internet exposure.
HTTPS is recommended for all external traffic to ensure encryption in transit.

3. Components

This section describes the core AWS infrastructure components that make up the three-tier architecture. Each component is modular and defined using Terraform for ease of deployment, management, and scalability.

The architecture is divided into five main categories:

Networking
Compute
Storage
Database
Security

3.1 Networking Components

The networking layer provides the foundation for communication and isolation between resources. It defines the virtual network, subnets, routing, and internet access.

3.1.1 VPC (Virtual Private Cloud)

Defines a logically isolated network within AWS.
CIDR block: typically 10.0.0.0/16 (customizable through variables).
Hosts all public and private subnets used by other resources.
Acts as a boundary for all communication and routing.

3.1.2 Subnets

Public Subnets
- Host resources that require internet access such as the Application Load Balancer and NAT Gateways.
- Associated with a route table that routes traffic to the Internet Gateway.
Private Subnets
- Host internal resources such as EC2 application servers, RDS databases, and EFS.
- Access to the internet is provided via NAT Gateways, not directly.
- Ensures that private resources remain isolated from public exposure.

3.1.3 Internet Gateway

Enables inbound and outbound traffic between the VPC and the internet.
Attached to the VPC and routes requests from public subnets.

3.1.4 NAT Gateways

Deployed in each public subnet for redundancy.
Allow instances in private subnets to access the internet for updates and package installations without direct exposure.

3.1.5 Route Tables

Define how traffic is routed within the VPC.
Public subnets route through the Internet Gateway, while private subnets route through NAT Gateways.
Each subnet is explicitly associated with the appropriate route table.

3.2 Compute Components

This layer hosts the application workload and provides compute capacity for the web or app tier.

3.2.1 EC2 Instances (App Servers)

Run the web application or middleware logic.
Deployed in private subnets for security.
Typically configured with Nginx, Apache, Node.js, or PHP-FPM depending on the workload.
Optionally managed by Auto Scaling Groups to maintain elasticity and availability.

3.2.2 Application Load Balancer (ALB)

Distributes incoming traffic across multiple EC2 instances in different Availability Zones.
Operates at Layer 7 (HTTP/HTTPS) for intelligent routing.
Supports:
- HTTP (port 80) for general access.
- HTTPS (port 443) for encrypted communication.
Integrated with Target Groups to register healthy EC2 instances dynamically.
Provides health checks to detect and isolate unhealthy targets.

3.2.3 Target Groups

Define the set of EC2 instances (targets) that receive traffic from the ALB.
Each group listens on the defined application port (e.g., port 80).
Health checks ensure requests are routed only to healthy targets.

3.3 Storage Components

Storage components provide persistent and shared storage solutions for the application layer.

3.3.1 Elastic File System (EFS)

Shared network file system accessible by all EC2 instances.
Used for:
- Application assets
- Logs
- Media uploads
- Shared configuration files
Scales automatically with demand.
Accessible only within the VPC via NFS and secured with an EFS Security Group.

3.4 Database Components

The database layer provides persistent, managed storage for application data.

3.4.1 Amazon RDS (MySQL)

Provides a managed relational database service for the application.
Deployed in private subnets to ensure isolation.
Configured with:
- Primary Database Instance in one Availability Zone.
- Read Replica or Multi-AZ Deployment in another Availability Zone for redundancy and load balancing.
Automatically handles:
- Backups
- Patching
- Failover
- Storage scaling

3.4.2 Database Security

The RDS instance is associated with a dedicated MySQL Security Group.
Inbound connections allowed only from the App Server Security Group.
No direct internet access permitted.

3.5 Security Components

Security is enforced at every layer using AWS-native mechanisms and Terraform-managed configurations.

3.5.1 Security Groups

Security groups control inbound and outbound traffic to AWS resources.

Security Group	Purpose	Inbound Rules	Outbound Rules
EC2 Security Group	Protects application servers	ALB (HTTP/HTTPS) only	RDS, EFS, NAT
ALB Security Group	Allows user-facing traffic	HTTP/HTTPS from the internet	Forward to EC2 SG
RDS Security Group	Protects database instances	App Server SG only	None (default)
EFS Security Group	Secures shared storage	App Server SG (NFS port 2049)	None (default)

3.5.2 Network Access Control Lists (NACLs)

Provide an additional layer of subnet-level security.
Optional but recommended for environments requiring stricter ingress and egress filtering.

3.5.3 IAM Roles and Policies

Used to grant EC2 instances permissions to access AWS services securely (e.g., S3, CloudWatch).
Ensures that no hardcoded credentials are used within instances or configuration files.

3.6 Optional Components

CloudWatch Monitoring – For real-time monitoring, alarms, and performance insights.
Route 53 – For DNS and custom domain routing to the ALB.
Certificate Manager (ACM) – For managing SSL/TLS certificates when using HTTPS.
S3 Buckets – For centralized log storage or backups.

3.7 Summary of Component Interactions

External users send requests via a DNS name (Route 53 or ALB URL).
The ALB receives the request and forwards it to EC2 App Servers in private subnets.
The App Servers process the requests, read/write data from the RDS database, and access shared files via EFS.
Any outbound connections (e.g., software updates) go through NAT Gateways in the public subnets.
Security Groups ensure that only permitted communication flows between layers.

4. Deployment Steps and Future Enhancements

This section outlines how to deploy the three-tier AWS architecture using Terraform, along with planned improvements for better monitoring, backup, and system management.

4.1 Deployment Steps

Follow these steps to provision the infrastructure and deploy your three-tier architecture on AWS.

4.1.1 Prerequisites

Before deployment, ensure the following tools and credentials are set up:

An AWS account with sufficient permissions (AdministratorAccess or equivalent IAM role).
Terraform installed (version 1.6 or higher recommended).
AWS CLI configured with credentials (aws configure).
Access to Terraform modules and variable files defined within this repository.
Recommended tools:
- tflint for linting Terraform code.
- terraform-docs for generating documentation.
- checkov or terrascan for static security scanning.

4.1.2 Folder Structure

The repository is organized as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62


.
├── .terraform
│ ├── modules
│ │ └── modules.json
│ └── providers
│ └── registry.terraform.io
├── .terraform.lock.hcl
├── .terraform.log
├── cloud-init
│ ├── configuration
│ │ ├── zsh
│ │ └── zsh-home
│ └── shell-scripts
│ ├── bootstrap.sh
│ └── efs-utils.sh
├── main.tf
├── modules
│ ├── containers
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── database
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── instances
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── management
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── network
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── notifications
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── scaling
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── security
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ ├── severless
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ └── variables.tf
│ └── storage
│ ├── main.tf
│ ├── outputs.tf
│ └── variables.tf
├── outputs.tf
├── provider.tf
├── terraform-aws-three-tier-architecture.svg
├── terraform.tfvars
└── variables.tf

4.1.3 Deployment Process

Clone the Repository

1
2


git clone https://github.com/erikngigi/terraform-aws-three-tier-architecture
cd terraform-aws-three-tier-architecture

Initialize Terraform
1

terraform init
This step downloads the necessary Terraform providers and initializes the backend configuration.
Validate the Configuration
1

terraform validate
Ensures there are no syntax or configuration errors.
Review the Execution Plan
1

terraform plan -var-file=dev.tfvars
Displays all resources that will be created, modified, or destroyed.
Deploy the Infrastructure
1

terraform apply -var-file=dev.tfvars
Type yes to confirm and deploy the architecture. Terraform will provision VPC, subnets, security groups, EC2 instances, load balancer, EFS, and RDS.
Verify the Deployment
- Navigate to the AWS Management Console → EC2 → confirm instances are running.
- Open the Application Load Balancer DNS name in a browser (Terraform output variable).
- Confirm the application or placeholder page is accessible.
Clean Up (Optional)
1

terraform destroy -var-file=dev.tfvars
Destroys all infrastructure created by Terraform.

Example of terraform.tfvars Below is an example configuration for the terraform.tfvars file that defines environment-specific parameters:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77


# Project details
 project_name = "project-A"

 # Network details
 vpc_cidr = "172.0.0.0/16"
 target_alb_port = "80"

 # Security details
 ec2_ingress = {
 "HTTP traffic" = {
 description = "HTTP"
 port = 80
 protocol = "tcp"
 sg_cidr_block = ["0.0.0.0/0"]
 }

 "HTTPS traffic" = {
 description = "HTTPS"
 port = 443
 protocol = "tcp"
 sg_cidr_block = ["0.0.0.0/0"]
 }
 }

 ec2_egress = {
 "ALL" = {
 description = "All outbound traffic"
 port = 0
 protocol = "-1"
 sg_cidr_block = ["0.0.0.0/0"]
 }
 }

 mysql_rds_ingress = {
 "MySQL" = {
 description = "Allow MySQL from EC2 security group"
 port = 3306
 protocol = "tcp"
 }
 }

 mysql_rds_egress = {
 "MySQL" = {
 description = "Allow connections to MySQL RDS"
 port = 0
 protocol = "-1"
 sg_cidr_block = ["0.0.0.0/0"]
 }
 }

 efs_ingress = {
 "EFS" = {
 description = "Allow connection to EFS from EC2 only"
 port = 2049
 protocol = "tcp"
 }
 }

 efs_egress = {
 "EFS" = {
 description = "Allow connection from EFS to anywhere"
 port = 0
 protocol = "-1"
 sg_cidr_block = ["0.0.0.0/0"]
 }
 }

 # Instance details
 ami_type = "c5.xlarge"

 # Database details
 rds_engine = "mysql"
 rds_engine_version = "8.0"
 rds_instance_class = "db.t3.micro"
 allocated_storage = "20"
 rds_username = "<username>"
 rds_password = "<password>"

4.2 Future Enhancements

Although the core architecture is functional, the following enhancements will improve observability, resilience, and operational management.

4.2.1 Enable CloudWatch Monitoring

Configure Amazon CloudWatch to collect and visualize key metrics from:
- EC2 instances: CPU utilization, network I/O, and disk performance.
- RDS database: connections, read/write latency, storage, and free memory.
- ALB: request counts, target response times, and HTTP error rates.
Set up CloudWatch Alarms for threshold breaches (e.g., high CPU, low storage).
Optionally integrate CloudWatch Logs for application and system logs from EC2.

4.2.2 Enable AWS Backup for RDS and EFS

Implement AWS Backup policies to automate and centralize backups for:
- RDS databases (daily incremental and weekly full backups).
- EFS file systems for application data.
Use lifecycle policies to transition older backups to cold storage (Glacier) for cost efficiency.
Validate recovery by performing periodic restore tests in non-production environments.

4.2.3 Use AWS Systems Manager (SSM)

Leverage AWS Systems Manager for:
- Patching EC2 instances automatically via Patch Manager.
- Secure parameter storage (e.g., DB passwords, API keys) using Parameter Store.
- Session Manager to access private EC2 instances securely without SSH keys.
Integrate Terraform with SSM parameters for dynamic configuration management.

4.2.4 Additional Considerations

Implement HTTPS: Add an ACM-issued certificate and configure HTTPS listener on the ALB.
Add CI/CD Integration: Use GitHub Actions or AWS CodePipeline to automate Terraform deployment and testing.
Introduce Caching: Integrate Amazon ElastiCache (Redis) to enhance performance for read-heavy workloads.
Add Bastion Host or VPN Access: For secure administrative access to private instances if SSM is not used.

4.3 Summary

After following these steps, you will have:

A fully deployed three-tier AWS infrastructure provisioned via Terraform.
An environment capable of supporting high availability, scalability, and security best practices.
A roadmap of enhancements to improve operational efficiency and monitoring.