Now let’s look at actual Terraform code for configuring each service. These examples show you how to write infrastructure as code.

📦 1. S3 Bucket Configuration

Here’s how to create a private S3 bucket with security best practices. Note: These are code examples showing Terraform syntax. This project uses modules (see section 6).

Basic S3 Bucket

Enable Encryption

Enable Versioning

Configure CORS (for WebGL/Web Apps)

S3 Bucket Policy (Allow CloudFront Access)

🌐 2. CloudFront Distribution Configuration

Here’s how to create a CloudFront distribution with Origin Access Control. Note: These are code examples. This project uses modules (see section 6).

Create Origin Access Control (OAC)

CloudFront Distribution

🔐 3. IAM Roles and Policies

Here’s how to create IAM roles for CI/CD deployments:

IAM Role for GitHub Actions (OIDC)

IAM Policy for Deployment

📝 4. Variables Configuration

Define variables to make your code reusable:

Variable Definitions

Environment-Specific Values

📤 5. Outputs Configuration

Define outputs to get important values after deployment. Note: This project uses modules, so outputs reference module outputs:

🧩 6. Using Modules

Organize code into reusable modules:

Module Structure

Using a Module

🔧 7. Provider Configuration

Configure the AWS provider:

🎯 8. Complete Example: Main Configuration

Before you can deploy infrastructure with Terraform, you need to configure AWS authentication on your local machine. This section covers everything you need to set up AWS CLI and authenticate with your AWS account.

📋 Prerequisites

1. AWS Account – You need an active AWS account
2. AWS CLI – Command-line tool for interacting with AWS
3. IAM User with Access Keys – For programmatic access

🔧 Step 1: Install AWS CLI

First, install the AWS Command Line Interface (CLI) on your machine.

macOS Installation

Linux Installation

Windows Installation

Download the AWS CLI MSI installer from aws.amazon.com/cli and run it.

Verify Installation

👤 Step 2: Create IAM User and Access Keys

You need an IAM user with programmatic access (access keys) to use with Terraform.

Create IAM User in AWS Console

1. Log in to AWS Console
2. Navigate to IAM → Users
3. Click Create user
4. Enter username (e.g., terraform-deploy)
5. Select Provide user access to the AWS Management Console (optional) or Access key – Programmatic access
6. Click Next

Attach Permissions

Attach policies that grant necessary permissions. For this project, you need:

• S3 – Full access (for bucket creation and file uploads)
• CloudFront – Full access (for distribution creation and invalidation)
• IAM – Limited access (for role creation, if using CI/CD)

Create Access Keys

1. After creating the user, go to the Security credentials tab
2. Scroll to Access keys section
3. Click Create access key
4. Select Command Line Interface (CLI) as the use case
5. Click Next and then Create access key
6. IMPORTANT: Download or copy both:
   • Access Key ID
   • Secret Access Key

⚙️ Step 3: Configure AWS CLI Profile

This project uses an AWS profile named deploy-config for authentication. You can configure it interactively or non-interactively.

Method 1: Interactive Setup (Recommended)

This is the easiest method – AWS CLI will prompt you for each value:

You will be prompted to enter:

• AWS Access Key ID: Your access key ID (e.g., AKIAIOSFODNN7EXAMPLE)
• AWS Secret Access Key: Your secret access key
• Default region name: e.g., us-east-1 (recommended for CloudFront)
• Default output format: json (recommended)

Method 2: Non-Interactive Setup

Use this method if you want to configure via command line or scripts:

Method 3: Manual Configuration Files

You can also edit the configuration files directly:

Edit Credentials File

Edit Config File

✅ Step 4: Verify AWS Configuration

Verify that your AWS profile is configured correctly:

List All Profiles

Output should include deploy-config:

Check Profile Configuration

Test Authentication

Expected output:

🔍 Step 5: Test AWS Access

Test that you have the necessary permissions:

Test S3 Access

Test IAM Access

🌍 Using Different AWS Regions

You can configure different regions for different profiles or override the region per command:

🔄 Using a Different Profile Name

If you want to use a different profile name instead of deploy-config:

📁 Configuration File Locations

AWS CLI stores configuration in these files:

🔒 Security Best Practices

• ✅ Never Commit Credentials – Add ~/.aws/ to .gitignore
• ✅ Use Least Privilege – Grant only necessary permissions
• ✅ Rotate Access Keys – Change keys regularly (every 90 days recommended)
• ✅ Use IAM Roles – For production, prefer IAM roles over access keys
• ✅ Enable MFA – Use Multi-Factor Authentication for your AWS account
• ✅ Monitor Usage – Check CloudTrail logs for unusual activity
• ✅ Separate Accounts – Use different AWS accounts for dev/staging/prod

🔧 Troubleshooting

Issue: “Unable to locate credentials”

Solution: Make sure you’ve configured the profile:

Issue: “Access Denied”

Solution: Check that your IAM user has the necessary permissions. Verify with:

Issue: “Invalid credentials”

Solution: Your access keys may have been rotated or deleted. Create new access keys in the IAM console and reconfigure:

Issue: “Profile not found”

Solution: Verify the profile exists:

📋 Quick Reference

Now that AWS is configured, let’s set up the rest of your local environment:

Prerequisites

1. AWS CLI – ✅ Should be installed and configured (see previous section)
2. Terraform – Install from terraform.io/downloads
3. Git – For cloning the repository

Install Terraform

macOS Installation

Linux Installation

Windows Installation

Download Terraform from terraform.io/downloads and add it to your PATH.

Clone Repository

Clone the project repository from GitHub:

🔗 View Repository on GitHub →

Verify Setup

Set up automated deployments using GitHub Actions. This allows your infrastructure and site to deploy automatically when you push code to GitHub, without storing AWS credentials in GitHub.

🎯 What is CI/CD?

CI/CD (Continuous Integration/Continuous Deployment) automates your deployment process:

• ✅ Automatic Deployment – Deploys when you push code
• ✅ No Manual Steps – No need to run scripts locally
• ✅ Secure – Uses OIDC (OpenID Connect) instead of storing AWS keys
• ✅ Consistent – Same process every time
• ✅ Traceable – All deployments logged in GitHub Actions

📋 Prerequisites

Before setting up CI/CD, ensure you have:

• ✅ AWS account configured locally (see Section 7)
• ✅ GitHub repository with your code
• ✅ Admin access to the GitHub repository
• ✅ Terraform infrastructure already deployed (or ready to deploy)

🔧 Step 1: Set Up Remote State Backend

CI/CD requires remote state (S3 + DynamoDB) so multiple deployments can share the same state file.

Create Remote State Resources

Use the helper script to create S3 bucket and DynamoDB table for Terraform state:

This script:

• Creates S3 bucket for state storage
• Creates DynamoDB table for state locking
• Updates backend/staging.hcl or backend/prod.hcl automatically

Verify Backend Configuration

Check that the backend files are updated:

🔐 Step 2: Create IAM Roles with OIDC

Create IAM roles that GitHub Actions can assume using OIDC (no AWS keys needed!).

Get Your AWS Account ID

Get Your GitHub Repository

Your repository should be in the format: owner/repository-name

Example: m-saad-siddique/static-site-IAC-deploy

Create IAM Roles

Run the setup script for each environment:

Replace:

• $AWS_ACCOUNT_ID – Your AWS account ID from the previous step
• m-saad-siddique/static-site-IAC-deploy – Your GitHub repository (owner/repo)

What the Script Creates

The script automatically creates:

• ✅ OIDC Provider – Connects AWS to GitHub (created once per AWS account)
• ✅ IAM Policy – Permissions for S3, CloudFront, and Terraform operations
• ✅ IAM Role – Can be assumed by GitHub Actions
• ✅ Trust Policy – Allows GitHub Actions to assume the role

Capture Role ARNs

The script will output the role ARN. Copy this value – you’ll need it for GitHub Secrets:

🔑 Step 3: Configure GitHub Secrets

Add secrets to your GitHub repository so workflows can authenticate with AWS.

Navigate to GitHub Secrets

1. Go to your GitHub repository
2. Click Settings (top menu)
3. Click Secrets and variables → Actions (left sidebar)
4. Click New repository secret

Add Required Secrets

Add these three secrets:

Secret 1: AWS_ACCOUNT_ID

• Name: AWS_ACCOUNT_ID
• Value: Your AWS account ID (e.g., 123456789012)

Secret 2: AWS_ROLE_ARN_STAGING

• Name: AWS_ROLE_ARN_STAGING
• Value: The staging role ARN from Step 2 (e.g., arn:aws:iam::123456789012:role/webgl-staging-deployment-role)

Secret 3: AWS_ROLE_ARN_PROD

• Name: AWS_ROLE_ARN_PROD
• Value: The production role ARN from Step 2 (e.g., arn:aws:iam::123456789012:role/webgl-prod-deployment-role)

📝 Step 4: Deploy Infrastructure with Terraform

Deploy your infrastructure using Terraform. The IAM roles are already created, so Terraform can use them.

Deploy Staging

Deploy Production

⚙️ Step 5: Understand GitHub Actions Workflows

The project includes pre-configured workflows in .github/workflows/:

Workflow Files

What Workflows Do

Each workflow performs these steps:

1. Checkout Code – Gets code from repository
2. Configure AWS Credentials – Uses OIDC to assume IAM role
3. Setup Terraform – Installs Terraform
4. Initialize Terraform – Downloads providers, configures backend
5. Select Workspace – Chooses environment workspace
6. Plan & Apply – Creates/updates infrastructure
7. Upload Files – Syncs build files to S3
8. Invalidate CloudFront – Clears cache

Example Workflow Structure

🚀 Step 6: Test CI/CD

Test your CI/CD setup by pushing code to trigger a deployment.

Test Staging Deployment

Monitor Deployment

1. Go to your GitHub repository
2. Click Actions tab
3. You should see “Deploy to Staging” workflow running
4. Click on the workflow to see detailed logs

Verify Deployment

Once the workflow completes:

• ✅ Check the workflow shows green checkmark (success)
• ✅ Verify your site is updated at the CloudFront URL
• ✅ Check workflow logs for any warnings

🔄 How CI/CD Works (OIDC Flow)

Here’s how the secure authentication works:

🌿 Branch Strategy

This project uses a three-branch workflow:

🔧 Step 7: Customize Workflows (Optional)

You can customize workflows to match your needs:

Change Build Directory

If your build files are in a different directory:

Add Build Step

If you need to build your site before deploying:

Add Notifications

Get notified when deployments complete:

🔍 Troubleshooting CI/CD

Issue: “Not authorized to perform sts:AssumeRoleWithWebIdentity”

Solution:

• Verify OIDC provider exists: aws iam list-open-id-connect-providers
• Check repository name matches in IAM role trust policy
• Ensure id-token: write permission is in workflow

Issue: “Role ARN not found”

Solution:

• Verify GitHub Secret AWS_ROLE_ARN_STAGING or AWS_ROLE_ARN_PROD exists
• Check the ARN is correct (no typos)
• Verify the role exists in AWS: aws iam get-role --role-name webgl-staging-deployment-role

Issue: “State lock error”

Solution:

• Another deployment might be running – wait for it to complete
• If stuck, manually unlock: Check DynamoDB table for lock entry

Issue: “Backend configuration not found”

Solution:

• Verify backend/staging.hcl or backend/prod.hcl exists
• Check the file contains valid bucket and table names
• Ensure remote state resources were created with setup-remote-state.sh

Issue: “Workflow not triggering”

Solution:

• Check workflow file is in .github/workflows/ directory
• Verify branch name matches workflow trigger (e.g., staging or main)
• Check GitHub Actions is enabled in repository settings

📋 Quick Reference

✅ CI/CD Checklist

This project supports multiple environments (dev, staging, production) with separate infrastructure for each.

Branch Strategy

This project uses a three-branch workflow:

Deployment Workflow

Terraform Workspaces

Each environment uses a separate Terraform workspace for state isolation:

• dev workspace – Manages dev environment state
• staging workspace – Manages staging environment state
• prod workspace – Manages production environment state

Managing Multiple Environments

Deploy to Specific Environment

View Environment Outputs

Destroy Specific Environment

Branch Protection Rules

To enforce the workflow, set up branch protection in GitHub:

1. Go to Repository Settings → Branches
2. Add rule for staging:
   • Require pull request before merging
   • Do not allow deleting this branch
   • Restrict direct pushes
3. Add rule for main:
   • Require pull request before merging
   • Require approvals (optional)
   • Do not allow deleting this branch
   • Restrict direct pushes
4. Add rule for dev:
   • Do not allow deleting this branch

Environment Configuration

Each environment has its own configuration file:

• environments/dev/terraform.tfvars – Dev settings
• environments/staging/terraform.tfvars – Staging settings
• environments/prod/terraform.tfvars – Production settings

Key differences:

Common issues and how to resolve them:

Common Issues

Issue: “AWS profile ‘deploy-config’ is not configured”

Solution:

Issue: “Workspace doesn’t exist”

Solution: Workspace is created automatically on first plan/apply. Just run:

Issue: “Unable to determine S3 bucket name”

Solution: Make sure you’ve run terraform apply first:

Issue: CI/CD workflow fails with “Role not found”

Solution:

1. Verify IAM roles are created: ./scripts/outputs.sh staging
2. Check GitHub Secrets are set correctly
3. Verify OIDC is configured in terraform.tfvars

Issue: CloudFront shows “Distribution not ready”

Solution: Wait 15-20 minutes. CloudFront distributions take time to deploy globally.

Useful Commands

Common questions and answers about Terraform, AWS, and this deployment project.

🤔 General Questions

Q: What is Infrastructure as Code (IaC)?

A: Infrastructure as Code is the practice of managing and provisioning infrastructure through machine-readable definition files, rather than through manual processes. Terraform is an IaC tool that lets you define infrastructure in code and version control it.

Q: Why use Terraform instead of AWS Console?

A: Terraform provides:

• ✅ Version control for infrastructure
• ✅ Reproducible deployments
• ✅ Ability to review changes before applying
• ✅ Documentation of your infrastructure
• ✅ Multi-cloud support
• ✅ Team collaboration

Q: Do I need to know programming to use Terraform?

A: No! Terraform uses HCL (HashiCorp Configuration Language), which is declarative and easy to learn. You describe what you want, and Terraform figures out how to create it.

🔧 Terraform Questions

Q: What’s the difference between terraform plan and terraform apply?

A:

• terraform plan: Shows what changes will be made without actually making them. Safe to run multiple times.
• terraform apply: Actually creates, modifies, or destroys resources. This makes real changes to your infrastructure.

Always run plan before apply to review changes!

Q: What is a Terraform workspace?

A: A workspace is a named state container. Each workspace has its own state file, allowing you to manage multiple environments (dev, staging, prod) with the same Terraform code but separate infrastructure.

Q: Can I use the same Terraform code for multiple environments?

A: Yes! That’s one of Terraform’s strengths. Use:

• Different .tfvars files per environment
• Different workspaces per environment
• Different backend configurations per environment

This keeps your code DRY (Don’t Repeat Yourself).

Q: What happens if I delete a resource manually in AWS Console?

A: Terraform will detect the resource is missing on the next plan or apply and try to recreate it. To sync Terraform state with reality, use terraform apply -refresh-only or terraform import.

Q: How do I update Terraform provider versions?

A: Update the version constraint in versions.tf:

Then run terraform init -upgrade to download the new version.

☁️ AWS Questions

Q: Why is my S3 bucket private? Can’t I make it public?

A: This project uses a private S3 bucket with CloudFront for security and performance:

• ✅ Security: Private buckets are more secure
• ✅ Performance: CloudFront CDN is faster than direct S3 access
• ✅ HTTPS: CloudFront provides free SSL certificates

You can make S3 public, but it’s not recommended for production.

Q: What is Origin Access Control (OAC)?

A: OAC is AWS’s modern way to securely connect CloudFront to private S3 buckets. It replaces the older OAI (Origin Access Identity). OAC ensures only CloudFront can access your S3 bucket, keeping it private while allowing CloudFront to serve content.

Q: How long does CloudFront take to deploy?

A: CloudFront distributions typically take 15-20 minutes to fully deploy globally. The URL is available immediately, but it may show “Distribution not ready” until deployment completes.

Q: Why do I need DynamoDB for Terraform state?

A: DynamoDB provides state locking, which prevents multiple people (or CI/CD runs) from modifying infrastructure simultaneously. This prevents conflicts and corruption of your Terraform state.

Q: Can I use a custom domain with CloudFront?

A: Yes! You need to:

1. Request an SSL certificate in AWS Certificate Manager (ACM)
2. Add the certificate ARN to your CloudFront configuration
3. Add your domain as an alias in CloudFront
4. Create a CNAME record in your DNS pointing to CloudFront

🔐 Security Questions

Q: Is it safe to store Terraform state in S3?

A: Yes, if you:

• ✅ Enable encryption at rest
• ✅ Enable versioning
• ✅ Use bucket policies to restrict access
• ✅ Never commit state files to version control

State files may contain sensitive data, so always encrypt them.

Q: How does OIDC authentication work?

A: OIDC (OpenID Connect) allows GitHub Actions to request temporary AWS credentials without storing AWS keys:

1. GitHub generates a JWT token with repository information
2. AWS validates the token against the OIDC provider
3. AWS issues temporary credentials (valid for 1 hour)
4. GitHub Actions uses these credentials to deploy

This is more secure than storing long-lived AWS access keys.

Q: Should I use the same AWS account for dev, staging, and prod?

A: For production, it’s best practice to use separate AWS accounts:

• ✅ Better security isolation
• ✅ Prevents accidental production changes
• ✅ Easier compliance and auditing

For learning or small projects, separate accounts per environment is fine.

🚀 Deployment Questions

Q: How do I update my static site after deployment?

A: Upload new files:

Or push to GitHub if CI/CD is configured – it will deploy automatically!

Q: Why do I need to invalidate CloudFront cache?

A: CloudFront caches files at edge locations. After uploading new files to S3, you need to invalidate the cache so users get the latest version. Without invalidation, users might see old cached content.

Q: Can I deploy to multiple regions?

A: CloudFront is global, so you don’t need multiple regions. However, if you want S3 buckets in multiple regions, you can:

• Create separate Terraform configurations per region
• Use Terraform workspaces with region-specific backends
• Use CloudFront with multiple origins

Q: How do I rollback a deployment?

A: Several options:

• Upload previous version: Upload the previous build files to S3
• Terraform rollback: Use terraform state commands or restore from state backup
• S3 versioning: If enabled, restore previous object versions

🛠️ Troubleshooting Questions

Q: Terraform says “state is locked” – what do I do?

A: Another operation is running. Options:

• Wait for the other operation to complete
• If stuck, manually unlock: terraform force-unlock LOCK_ID
• For remote state, check DynamoDB table for lock entries

Warning: Only unlock if you’re sure no operation is running!

Q: My CloudFront URL shows “Access Denied” – why?

A: Common causes:

• CloudFront distribution not fully deployed (wait 15-20 minutes)
• OAC not properly configured
• S3 bucket policy missing or incorrect
• No files uploaded to S3 yet

Q: How do I see what Terraform will change before applying?

A: Always use terraform plan:

The plan shows what will be created (+), modified (~), or destroyed (-).

Q: Can I destroy everything and start over?

A: Yes, but be careful:

Warning: This is irreversible! Make sure you have backups if needed.

💡 Tips & Tricks

Q: How can I speed up Terraform operations?

A:

• Use -parallelism flag to run operations in parallel
• Cache Terraform providers between runs
• Use targeted operations: terraform apply -target=resource
• Avoid unnecessary terraform apply -refresh-only calls

Q: How do I share Terraform state with my team?

A: Use remote state (S3 backend):

• Configure backend/*.hcl files
• Use DynamoDB for state locking
• All team members use the same backend
• State is automatically shared and locked

Q: Can I use this for non-WebGL static sites?

A: Absolutely! This works for any static site:

• React, Vue, Angular apps
• Jekyll, Hugo, Gatsby sites
• Plain HTML/CSS/JS
• Documentation sites
• Any static content

Q: How do I add more AWS services?

A: Add resources to your Terraform configuration:

• Create new .tf files or add to existing ones
• Use Terraform modules for reusable components
• Update variables and outputs as needed
• Test in dev environment first

🔧 Terraform Commands

Basic Commands

Workspace Commands

Plan & Apply Commands

Output Commands

State Management

☁️ AWS CLI Commands

Configuration

S3 Commands

CloudFront Commands

IAM Commands

💻 Shell/Bash Commands

Environment Variables

File Operations

Command Chaining & Variables

Script Execution

Useful Utilities

📜 Helper Scripts (Optional Shortcuts)

🔀 Git Commands

Official Documentation

• Terraform Documentation – Complete Terraform guide
• AWS Provider Documentation – All AWS resources

Learning Resources

• HashiCorp Learn – Free Terraform tutorials
• Terraform Intro – Getting started guide
• AWS Getting Started – AWS basics

Project Documentation

• README.md – Main project documentation
• WORKSPACES_GUIDE.md – Workspace management guide
• GITHUB_ACTIONS_SETUP.md – CI/CD setup instructions
• IAM_ROLE_GUIDE.md – IAM roles and policies explained
• AWS_PROFILE_SETUP.md – Local AWS configuration