Forem: SWAPNIL UPPIN

Building a Two-Tier AWS Infrastructure with Terraform, Flask & Ansible — Every File Explained

SWAPNIL UPPIN — Mon, 27 Apr 2026 18:42:47 +0000

Introduction

A two-tier architecture on AWS — the bread and butter of real-world cloud deployments. Here's the idea:

Tier 1 (Public): An EC2 instance sitting in a public subnet, running a Flask web application. This is what users hit.
Tier 2 (Private): An RDS MySQL database sitting in private subnets. No direct internet access. Only the EC2 instance can talk to it.

The infrastructure is provisioned with Terraform (modularized), the app is deployed with Ansible, and the application itself is a simple Flask + HTML frontend that talks to MySQL.

By the end of this post, you'll understand why every single file exists and how they all connect together.

Architecture

Project Structure

two-tier-aws-infra/
├── app/
│   ├── app.py                    
│   ├── requirements.txt          
│   └── frontend/
│       └── index.html            
├── terraform/
│   ├── main.tf                   
│   ├── provider.tf               
│   ├── backend.tf                
│   ├── variables.tf              
│   ├── outputs.tf                
│   ├── terraform.tfvars          
│   └── modules/
│       ├── vpc/                  
│       ├── ec2/                  
│       ├── security_group/       
│       ├── rds/                  
│       └── nat_gateway/          
└── ansible/
    ├── playbook.yml              
    ├── inventory.ini             
    └── roles/
        └── app/
            └── tasks/
                └── main.yml

Part 1: Terraform — Infrastructure as Code

Why Modules?
You could dump everything into one massive main.tf. But that's a nightmare to maintain. Terraform modules let you:

Isolate concerns: VPC logic doesn't bleed into EC2 logic.
Reuse: Need another EC2 instance? Call the module again.
Test independently: Each module has its own inputs and outputs.

Each module follows a three-file pattern:

main.tf — the actual resources
variables.tf — inputs the module needs
outputs.tf — values the module exposes to other modules

terraform/provider.tf:
Terraform doesn't know anything about AWS by default. This file says: "Download the AWS provider plugin (version 6.x), and operate in the region I specify." We use var.region instead of hardcoding "us-east-1" so you can deploy to any region just by changing a variable.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}
provider "aws" {
    region = var.region
}

terraform/backend.tf:

Every time you run terraform apply, Terraform writes a "state file" that maps your .tf files to real AWS resources. By default, it's stored locally. That's fine for solo work, but in a team:

S3 backend = everyone shares the same state
use_lockfile = true = prevents two people from running apply at the same time (avoids corruption)
encrypt = true = your state file (which contains secrets like DB passwords) is encrypted at rest

terraform {
    backend "s3" {
        bucket       = "your-bucket-name"
        key          = "terraform/state.tfstate"
        region       = "us-east-1"
        use_lockfile = true
        encrypt      = true
    }
}

terraform/variables.tf:

It's the single control panel for the entire infrastructure. Notice some variables have default values (like vpc_cidr) — you can override them but don't have to. Others like ami_id, key_name, and db_password have no default — Terraform forces you to provide them. db_password is marked sensitive = true so it never appears in logs or plan output.

It's the single control panel for the entire infrastructure. Notice some variables have default values (like vpc_cidr) — you can override them but don't have to. Others like ami_id, key_name, and db_password have no default — Terraform forces you to provide them. db_password is marked sensitive = true so it never appears in logs or plan output.

Why two private subnets? AWS RDS requires a DB Subnet Group that spans at least two Availability Zones. One private subnet isn't enough — the RDS creation will literally fail.

variable "region"              { default = "us-east-1" }
variable "vpc_cidr"            { default = "10.0.0.0/16" }
variable "public_subnet_cidr"  { default = "10.0.1.0/24" }
variable "private_subnet_cidr" { default = "10.0.2.0/24" }

variable "private_subnet_cidr_2" {
    description = "CIDR block for the second private subnet (different AZ for RDS)"
    default     = "10.0.3.0/24"
}

variable "instance_type" { default = "t2.micro" }

variable "ami_id" {
    description = "AMI ID for the EC2 instance"
    type        = string
}

variable "key_name" {
    description = "Name of the SSH key pair for EC2"
    type        = string
}

variable "db_password" {
    description = "Password for the RDS database"
    type        = string
    sensitive   = true
}

}

terraform/terraform.tfvars:

Separates what you can configure (variables.tf) from what you actually configured (terraform.tfvars). Terraform automatically loads this file. This file should be in your .gitignore — it contains secrets.

ami_id      = "ami-098e39bafa7e7303d"
key_name    = ""  #Enter you key name 
db_password = ""  # Enter your password

terraform/outputs.tf:

After terraform apply, you need two pieces of information: the EC2's public IP (to SSH into and to point your browser at) and the RDS endpoint (to configure the app). Without outputs, you'd have to dig through the AWS Console.

output "ec2_public_ip" {
  value = module.ec2.public_ip
}
output "db_endpoint" {
  value = module.rds.endpoint
}

terraform/main.tf:

This is where the magic happens. It wires all modules together by passing outputs from one module as inputs to another. Look at the data flow:

module.vpc creates the VPC and subnets → exposes vpc_id, public_subnet_id, private_subnet_id
module.sg takes the vpc_id → creates security groups → exposes sg_id and db_sg_id
module.ec2 takes the public subnet + security group → launches the instance
module.rds takes two private subnets + DB security group → creates the database
module.nat_gateway takes the public subnet + VPC → enables private subnet internet access

No module directly references another module's resources. They only communicate through variables and outputs. This is the key principle of modular Terraform.

module "vpc" {
    source = "./modules/vpc"
    vpc_cidr              = var.vpc_cidr
    public_subnet_cidr    = var.public_subnet_cidr
    private_subnet_cidr   = var.private_subnet_cidr
    private_subnet_cidr_2 = var.private_subnet_cidr_2
}
module "ec2" {
    source         = "./modules/ec2"
    ami_id         = var.ami_id
    subnet_id      = module.vpc.public_subnet_id
    security_group = module.sg.sg_id
    instance_type  = var.instance_type
    key_name       = var.key_name
}
module "sg" {
    source = "./modules/security_group"
    vpc_id = module.vpc.vpc_id
}
module "rds" {
    source               = "./modules/rds"
    private_subnets      = [module.vpc.private_subnet_id, module.vpc.private_subnet_id_2]
    db_security_group_id = module.sg.db_sg_id
    db_password          = var.db_password
}
module "nat_gateway" {
    source            = "./modules/nat_gateway"
    public_subnet_id  = module.vpc.public_subnet_id
    vpc_id            = module.vpc.vpc_id
    private_subnet_id = module.vpc.private_subnet_id
}

modules/vpc/main.tf:
This is the biggest module because networking is the foundation of everything.

Instead of hardcoding us-east-1a, we dynamically fetch available AZs. This makes the code portable across regions.

data "aws_availability_zones" "available" {
  state = "available"
}

The VPC is your private network in AWS. 10.0.0.0/16 gives you 65,536 IP addresses. DNS support is enabled because RDS endpoints are DNS names — without it, your app can't resolve the database hostname.

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

Why three subnets?

Public subnet: EC2 lives here. map_public_ip_on_launch = true means instances automatically get a public IP.
Private subnet 1 & 2: RDS lives here. No public IPs. The two subnets MUST be in different AZs because AWS RDS requires it for the DB Subnet Group — even if you're not using Multi-AZ replication.

resource "aws_subnet" "public" {
    vpc_id                  = aws_vpc.main.id
    cidr_block              = var.public_subnet_cidr      # 10.0.1.0/24
    availability_zone       = data.aws_availability_zones.available.names[0]
    map_public_ip_on_launch = true
}

resource "aws_subnet" "private" {
    vpc_id            = aws_vpc.main.id
    cidr_block        = var.private_subnet_cidr           # 10.0.2.0/24
    availability_zone = data.aws_availability_zones.available.names[0]
}

resource "aws_subnet" "private_2" {
    vpc_id            = aws_vpc.main.id
    cidr_block        = var.private_subnet_cidr_2         # 10.0.3.0/24
    availability_zone = data.aws_availability_zones.available.names[1]  # Different AZ!
}

modules/ec2/main.tf:

This creates the actual VM where your Flask app runs. Every value is parameterized — nothing is hardcoded. The key_name lets you SSH into the instance for debugging. The security group controls what traffic can reach it (ports 22 and 80).

resource "aws_instance" "main" {
    ami           = var.ami_id
    instance_type = var.instance_type

    subnet_id              = var.subnet_id
    vpc_security_group_ids = [var.security_group]

    key_name = var.key_name

    tags = {
        Name = "two-tier-app"
    }
}

modules/security_group/main.tf:

main (for EC2): Allows SSH (22) and HTTP (80) from anywhere, plus all outbound traffic. The egress rule is critical — without it, your EC2 can't download packages, reach the internet, or talk to RDS.
db_sg (for RDS): Only allows MySQL traffic (3306) from the EC2's security group. Not from 0.0.0.0/0. Not from any IP. Only from instances that have the main security group attached. This is how you lock down the database.

resource "aws_security_group" "main" {
    vpc_id = var.vpc_id

    ingress { from_port = 22;  to_port = 22;  protocol = "tcp"; cidr_blocks = ["0.0.0.0/0"] }
    ingress { from_port = 80;  to_port = 80;  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"] }
}

resource "aws_security_group" "db_sg" {
    vpc_id = var.vpc_id

    ingress {
        from_port       = 3306
        to_port         = 3306
        protocol        = "tcp"
        security_groups = [aws_security_group.main.id]
    }
}

modules/rds/main.tf:

The DB Subnet Group tells RDS "launch the database in these private subnets." The db.t3.micro is the smallest RDS instance (free-tier eligible). skip_final_snapshot = true is for dev environments — in production, you'd want a final snapshot before deletion. The password comes from a variable marked sensitive = true — it never appears in Terraform output.

resource "aws_db_subnet_group" "db_subnet" {
    name       = "db-subnet-group"
    subnet_ids = var.private_subnets
}

resource "aws_db_instance" "db" {
    allocated_storage      = 20
    engine                 = "mysql"
    engine_version         = "8.0"
    instance_class         = "db.t3.micro"
    db_name                = "appdb"
    username               = "admin"
    password               = var.db_password
    db_subnet_group_name   = aws_db_subnet_group.db_subnet.name
    skip_final_snapshot    = true
    vpc_security_group_ids = [var.db_security_group_id]
}

modules/nat_gateway/main.tf:

RDS is in a private subnet — no internet access. But what if the database needs to download patches, or a Lambda in the private subnet needs to call an external API? The NAT Gateway sits in the public subnet and acts as a proxy. Private subnet traffic goes through the NAT → through the IGW → to the internet. The response comes back the same way. Crucially, nothing from the internet can initiate a connection to the private subnet. One-way door.

Why the route table association? Without it, the private subnet uses the VPC's default route table (which has no internet route). The association says "this private subnet should use the route table that points to the NAT Gateway."

resource "aws_eip" "nat" { ... }

resource "aws_nat_gateway" "nat" {
    allocation_id = aws_eip.nat.id
    subnet_id     = var.public_subnet_id    # NAT lives in PUBLIC subnet
}

resource "aws_route_table" "private_rt" { ... }

resource "aws_route" "private_internet" {
    route_table_id         = aws_route_table.private_rt.id
    destination_cidr_block = "0.0.0.0/0"
    nat_gateway_id         = aws_nat_gateway.nat.id
}

resource "aws_route_table_association" "private_rt_association" {
    subnet_id      = var.private_subnet_id
    route_table_id = aws_route_table.private_rt.id
}

Part 2: The Flask Application

Three routes, three purposes:

/ — Serves the frontend HTML. Flask acts as both the API server and the static file server.
/api — Connects to RDS MySQL, runs SELECT NOW() to prove the connection works, and returns the result. The finally block ensures the connection is always closed, even if an error occurs. Without it, you'd leak database connections until MySQL refuses new ones.
/health — A simple health check endpoint. Useful for load balancers and monitoring.
Database credentials come from environment variables (DB_HOST, DB_USER, DB_PASS) — never hardcoded in the app. The systemd service loads them from an .env file.

app/app.py: — The Backend

from flask import Flask, send_from_directory
import os
import pymysql

app = Flask(__name__, static_folder="frontend")

def get_db_connection():
    return pymysql.connect(
        host=os.getenv("DB_HOST"),
        user=os.getenv("DB_USER"),
        password=os.getenv("DB_PASS"),
        database="appdb"
    )

@app.route("/")
def frontend():
    return send_from_directory("frontend", "index.html")

@app.route("/api")
def backend():
    conn = None
    try:
        conn = get_db_connection()
        with conn.cursor() as cursor:
            cursor.execute("SELECT NOW()")
            result = cursor.fetchone()
        return f"DB Connected! Time: {result}"
    except Exception as e:
        return f"DB Error: {str(e)}"
    finally:
        if conn:
            conn.close()

@app.route("/health")
def health():
    return "OK"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=80)

app/frontend/index.html:

A minimal frontend that proves the two-tier flow works end-to-end. Click the button → JavaScript calls /api → Flask queries MySQL → result displays on screen. The .catch() block handles network errors gracefully

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Two Tier App</title>
</head>
<body>
    <h1>Frontend</h1>
    <button onclick="callAPI()">Call Backend</button>
    <p id="result"></p>

    <script>
        function callAPI() {
            fetch('/api')
                .then(res => res.text())
                .then(data => {
                    document.getElementById("result").innerText = data;
                })
                .catch(err => {
                    document.getElementById("result").innerText = "Error: " + err.message;
                });
        }
    </script>
</body>
</html>

Part 3: Ansible — Automated Deployment

ansible/inventory.ini:

Tells Ansible which server to connect to, which SSH user to use (ec2-user is the default on Amazon Linux), and which private key to authenticate with. After terraform apply, replace with the actual IP from the Terraform output.

[web]
<EC2_PUBLIC_IP> ansible_user=ec2-user ansible_ssh_private_key_file=~/.ssh/key.pem

ansible/playbook.yml:

The playbook ties everything together. become: true means "run as root" (needed to install packages and create systemd services). vars_prompt asks you for the database endpoint and password at runtime — no secrets stored in files. These variables cascade down into the app role's tasks.

- name: Deploy Two-Tier Flask Application
  hosts: web
  become: true
  vars_prompt:
    - name: db_endpoint
      prompt: "Enter the RDS database endpoint"
      private: false
    - name: db_password
      prompt: "Enter the database password"
      private: true
  roles:
    - app

ansible/roles/app/tasks/main.yml:

Six tasks, executed in order:

Install dependencies — mariadb is the MySQL client on Amazon Linux (not mysql). python3-pip is explicitly installed because pip may not exist by default.
Copy app — Uploads the entire app/ directory to the EC2 instance.
Install Python deps — Uses pip3 explicitly (not pip which might point to Python 2).
Create .env file — Writes database credentials. The {{ db_endpoint }} and {{ db_password }} are populated from the playbook's vars_prompt.
Create systemd service — This is the key. Instead of nohup python3 app.py & (which dies on reboot and is impossible to manage), we create a proper systemd service. EnvironmentFile loads the .env file so os.getenv() in Python works. Restart=always means if the app crashes, systemd restarts it automatically.
Start the service — daemon_reload tells systemd to re-read service files. enabled: true means it starts automatically on boot.

- name: Install dependencies
  yum:
    name: [python3, python3-pip, git, mariadb]
    state: present

- name: Copy app
  copy:
    src: ../../../../app/
    dest: /home/ec2-user/app

- name: Install Python deps
  pip:
    requirements: /home/ec2-user/app/requirements.txt
    executable: pip3

- name: Create env file
  copy:
    dest: /home/ec2-user/app/.env
    content: |
      DB_HOST={{ db_endpoint }}
      DB_USER=admin
      DB_PASS={{ db_password }}

- name: Create systemd service for the app
  copy:
    dest: /etc/systemd/system/two-tier-app.service
    content: |
      [Unit]
      Description=Two Tier Flask App
      After=network.target

      [Service]
      User=ec2-user
      WorkingDirectory=/home/ec2-user/app
      EnvironmentFile=/home/ec2-user/app/.env
      ExecStart=/usr/bin/python3 /home/ec2-user/app/app.py
      Restart=always

      [Install]
      WantedBy=multi-user.target

- name: Start and enable app service
  systemd:
    name: two-tier-app
    state: started
    enabled: true
    daemon_reload: true

The Complete Flow

You → terraform apply
       │
       ├── VPC, Subnets, IGW created
       ├── Security Groups created
       ├── EC2 launched in public subnet
       ├── RDS launched in private subnets
       ├── NAT Gateway created
       │
       └── Output: EC2 IP + RDS endpoint

You → ansible-playbook -i inventory.ini playbook.yml
       │
       ├── SSH into EC2
       ├── Install Python, pip, mariadb
       ├── Upload Flask app
       ├── Write .env with DB credentials
       ├── Create systemd service
       └── Start the app

User → http://<EC2_IP>/
       │
       ├── Flask serves index.html
       ├── User clicks "Call Backend"
       ├── JavaScript fetches /api
       ├── Flask connects to RDS (via private subnet)
       ├── MySQL returns current time
       └── Result displayed on screen

Complete Deployment Process — Step by Step

Phase 1: Terraform — Infrastructure Provisioning

Step 1 — Format the Code

cd terraform
terraform fmt

Automatically formats all .tf files to canonical HCL style
Fixes indentation, spacing, and alignment
Always run this before committing to Git — keeps code clean and consistent
Returns a list of files it modified (no output = already clean)

Step 2 — Initialize the Working Directory

terraform init

Downloads and installs required provider plugins (e.g., AWS provider)
Sets up the backend for storing terraform.tfstate (local or remote like S3)
Initializes modules if any are referenced
Must be run once when starting fresh or after adding new providers/modules

Step 3 — Validate the Configuration

terraform validate

Checks all .tf files for syntax errors and logical issues
Validates resource arguments, types, and required fields
Does not connect to AWS — purely a static config check
Returns Success! The configuration is valid. if everything is correct
Run this before plan to catch mistakes early

Step 4 — Preview the Changes

terraform plan

Connects to AWS and compares desired state vs current state
Shows exactly what will be created, modified, or destroyed
Look out for:
- + → resource will be created
- ~ → resource will be modified
- - → resource will be destroyed
No changes are made at this stage — it's a dry run
Review this output carefully before proceeding

Step 5 — Apply the Infrastructure

terraform apply

Provisions the actual resources on AWS
Prompts for confirmation — type yes to proceed
Creates resources like:
- ✅ EC2 instance (app server)
- ✅ RDS MySQL database
- ✅ Security groups, VPC, subnets, etc.
On completion, prints output values defined in outputs.tf

Step 6 — Note the Terraform Outputs

ec2_public_ip = "54.xxx.xxx.xxx"
db_endpoint   = "terraform-xxx.us-east-1.rds.amazonaws.com:3306"

These are critical values needed for the next phase
ec2_public_ip → where your app will be hosted
db_endpoint → RDS connection string for the application
Copy and save these before moving to Ansible

Phase 2: Ansible — Application Deployment:

Step 7 — Update the Inventory File

# ansible/inventory.ini
[web]
54.xxx.xxx.xxx ansible_user=ec2-user ansible_ssh_private_key_file=~/.ssh/your-key.pem

Replace with the actual IP from Terraform output
This tells Ansible which server to connect to and how to SSH into it
ansible_user is typically ec2-user (Amazon Linux) or ubuntu (Ubuntu AMI)

Step 8 — Run the Playbook

cd ../ansible
ansible-playbook -i inventory.ini playbook.yml

-i inventory.ini → specifies the target server(s)
playbook.yml → contains all automation tasks to set up the app
When prompted:
- Enter the RDS endpoint (from Step 6)
- Enter the DB password (set during Terraform or manually)
Ansible typically handles tasks like:
- Installing dependencies (Python, Nginx, etc.)
- Copying application code to EC2
- Configuring environment variables
- Starting and enabling the app service

Phase 3: Verify

Step 9 — Access the Application

http://<EC2_PUBLIC_IP>/

Open in browser to confirm the app is live and running
If it doesn't load, check:
- Security group inbound rules (port 80/443 open?)
- App service status on EC2 (systemctl status )
- RDS connectivity from EC2

Phase 4: Cleanup — Destroy Infrastructure

Step 10 — Destroy All Provisioned Resources

cd terraform
terraform destroy

Permanently removes all resources that were created by terraform apply
Connects to AWS and shows a destruction plan first — lists everything that will be deleted
Prompts for confirmation — type yes to proceed
Destroys resources like:
- ❌ EC2 instance
- ❌ RDS database
- ❌ Security groups, VPC, subnets, etc.
⚠️ This action is irreversible — all data on RDS will be lost unless you have a snapshot

Real Errors I Hit (And How I Fixed Them)

No deployment goes smoothly on the first try. Here are the actual errors I ran into while deploying this project, and the exact fixes I applied. If you're following along, you'll likely hit the same ones.

Error: Ansible Doesn't Run on Windows:

PS> ansible-playbook -i inventory.ini playbook.yml
ansible-playbook : The term 'ansible-playbook' is not recognized as the name
of a cmdlet, function, script file, or operable program.

Why it happens: Ansible is a Linux-only tool. There is no native Windows version. If you're developing on Windows (like I was), running ansible-playbook from PowerShell will always fail — it simply doesn't exist in the Windows ecosystem.

The fix: You have two options:

Use WSL (Windows Subsystem for Linux) — Install Ubuntu via wsl --install -d Ubuntu, then install Ansible inside it with sudo apt install ansible.
Skip Ansible entirely — SSH into the EC2 instance directly and run the deployment commands manually. This is what I ended up doing since my WSL only had Docker Desktop's minimal distro.

ssh -i ~/.ssh/my-key.pem ec2-user@<EC2_PUBLIC_IP>

Then execute the equivalent of each Ansible task as shell commands on the EC2 instance. The Ansible role is essentially a recipe — you can follow it step by step manually.

Lesson learned: If you're on Windows, either set up WSL beforehand or plan for manual deployment. Alternatively, you could run Ansible from the EC2 instance itself, or use a CI/CD pipeline (GitHub Actions, Jenkins) running on Linux.

Conclusion

Building a two-tier architecture from scratch isn't just about getting an app to run — it's about understanding why every piece exists and how they all connect.
Here's what this project actually teaches you:

Terraform modules aren't just organization — they enforce separation of concerns so your VPC logic never bleeds into your EC2 logic, and your infrastructure stays maintainable as it grows.
Remote state with S3 isn't overhead — it's what makes infrastructure collaborative and safe in team environments.
Ansible roles aren't just scripts — they give you repeatable, idempotent deployments where running the playbook twice produces the same result as running it once.
Private subnets for RDS aren't optional — keeping your database unreachable from the internet is the bare minimum of production security.
NAT Gateway isn't magic — it's a one-way door that lets private resources reach the internet without exposing them to it.

The real-world errors section matters too. No deployment works perfectly on the first try — and knowing that Ansible doesn't run natively on Windows, or that RDS requires two AZs for a subnet group, are exactly the kinds of lessons that don't appear in documentation but absolutely appear in interviews and on the job.

This project covers the full DevOps lifecycle — from writing infrastructure code, validating and applying it, deploying the application, verifying it's live, and tearing it all down cleanly. That end-to-end thinking is what separates someone who can follow a tutorial from someone who can own a deployment.

source code:two-tier-aws-infra

Every production system you admire was once someone's first Terraform apply.

Building a Docker + Kubernetes Project from Scratch with Helm

SWAPNIL UPPIN — Wed, 15 Apr 2026 09:44:13 +0000

Introduction

In modern DevOps workflows, deploying applications is no longer just about writing code—it’s about automating, scaling, and managing services efficiently.

In this project, I built a 2-tier microservices application and deployed it using:

Docker for containerization
Kubernetes for orchestration
Minikube for local cluster
Helm for production-style deployment

The goal was to simulate a real-world DevOps workflow from scratch.

Architecture Overview

This project follows a simple microservices pattern:

User → Frontend (Nginx) → Backend Service → Backend Pods

Frontend acts as a reverse proxy
Backend serves API responses
Kubernetes handles scaling and communication

Tech Stack

Docker
Kubernetes
Minikube
Helm
Python (Flask)
Nginx

Project Structure

project/
├── backend/
├── frontend/
└── helm/

Steps to Execute the project:

Step 1: Build the Backend (Python API)

We start with a simple Flask API:

app.py:

from flask import Flask
import socket

app = Flask(__name__)

@app.route("/")
def home():
    return f"Hello from Backend! Host: {socket.gethostname()}"

@app.route("/health")
def health():
    return "OK"

requirements.txt:

flask
gunicorn

Step 2: Dockerize the Application

Backend Dockerfile

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

EXPOSE 5000

CMD ["gunicorn", "-b", "0.0.0.0:5000", "app:app"]

Build:

docker build -t backend-app ./backend

Step 3: Frontend with Nginx

Nginx forwards requests to the backend:

events {}

http {
  server {
    listen 80;

    location / {
      proxy_pass http://backend-service:5000;
    }
  }
}

Frontend Dockerfile:

FROM nginx:alpine

COPY nginx.conf /etc/nginx/nginx.conf

Build frontend:

docker build -t frontend-app ./frontend

Step 4: Run Kubernetes Cluster

Start Minikube:

minikube start

Use Minikube Docker:

Since we're using Minikube, we must build images inside Minikube’s Docker environment.

& minikube -p minikube docker-env --shell powershell | Invoke-Expression

Rebuild images inside the cluster.

Step 5: Create Helm Chart Structure

Instead of applying raw Kubernetes YAML files, I used Helm to manage deployments in a modular and reusable way.

Chart.yaml:
Defines metadata about the Helm chart:

apiVersion: v2
name: myapp
description: Helm chart for frontend + backend microservices
type: application
version: 0.1.0
appVersion: "1.0"

values.yaml:
Central place to configure application values:

backend:
  image: backend-app
  replicas: 2
  port: 5000

frontend:
  image: frontend-app
  replicas: 1
  port: 80
  nodePort: 30007

templates:
Helm uses templates to dynamically generate Kubernetes manifests.

🔹 Backend Deployment (templates/backend-deployment.yaml)

 apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: {{ .Values.backend.replicas }}
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
        - name: backend
          image: {{ .Values.backend.image }}
          imagePullPolicy: Never
          ports:
            - containerPort: {{ .Values.backend.port }}

🔹 Backend Service (templates/backend-service.yaml)

apiVersion: v1
kind: Service
metadata:
  name: backend-service
spec:
  selector:
    app: backend
  ports:
    - port: {{ .Values.backend.port }}
      targetPort: {{ .Values.backend.port }}

🔹 Frontend Deployment (templates/frontend-deployment.yaml)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
spec:
  replicas: {{ .Values.frontend.replicas }}
  selector:
    matchLabels:
      app: frontend
  template:
    metadata:
      labels:
        app: frontend
    spec:
      containers:
        - name: frontend
          image: {{ .Values.frontend.image }}
          imagePullPolicy: Never
          ports:
            - containerPort: {{ .Values.frontend.port }}

🔹 Frontend Service (templates/frontend-service.yaml)

apiVersion: v1
kind: Service
metadata:
  name: frontend-service
spec:
  type: NodePort
  selector:
    app: frontend
  ports:
    - port: {{ .Values.frontend.port }}
      targetPort: {{ .Values.frontend.port }}
      nodePort: {{ .Values.frontend.nodePort }}

Step 6: Deploy Application Using Helm

Once the application components were ready, I used Helm to package and deploy everything.

1️⃣ Create Helm Chart

helm create myapp

Helm generates a default chart structure with sample templates.

2️⃣ Clean Default Templates

Since my application has a custom structure, I removed unnecessary default files and kept only:

backend-deployment.yaml
backend-service.yaml
frontend-deployment.yaml
frontend-service.yaml

This helped keep the chart minimal and aligned with my architecture.

3️⃣ Deploy Application

helm install myapp ./myapp

This command:

Packages the chart
Generates Kubernetes manifests
Deploys all resources in one step

4️⃣ Upgrade on Changes

Whenever I updated configurations or images:

helm upgrade myapp ./myapp

5️⃣ Verify Deployment

To verify the deployment, use kubectl get pods to check that all pods are created and running, then use kubectl get svc to confirm that the services are up and available.

kubectl get pods
kubectl get svc

6️⃣ Access Application

Run minikube service frontend-service to open the frontend service in your default browser and access the application locally as shown below.

minikube service frontend-service

The browser displays 'Hello from Backend! Host: hostname', confirming that the frontend service is successfully communicating with the backend pod.

Conclusion

This project walked through the full lifecycle of deploying a 2-tier microservices application — from writing a simple Flask API to packaging and managing everything with Helm on a local Kubernetes cluster.

Here's a quick recap of what was covered:

Containerization — Dockerized both the backend (Python/Flask) and frontend (Nginx) services independently, keeping them loosely coupled.
Orchestration — Used Kubernetes to manage pod scheduling, scaling, and inter-service communication.
Local cluster — Ran everything locally using Minikube, simulating a real cluster environment without needing cloud infrastructure.
Helm deployment — Replaced raw YAML manifests with a structured Helm chart, making the deployment configurable, repeatable, and upgrade-friendly.

The architecture here is intentionally minimal, but it maps directly to patterns used in production systems. Swapping Minikube for a managed cluster (EKS, GKE, AKS) and a local image build for a proper CI/CD pipeline (GitHub Actions, ArgoCD) would take this setup from local dev to production-ready.

The goal of this project was to connect the dots between containers, orchestration, and deployment tooling — and to show that a well-structured local setup is the best foundation for anything you build at scale.

📌 Source Code
👉 GitHub Repo: k8s_helm_deployment

Common Errors & Fixes:

While working on this project, I encountered some real-world issues that are very common when working with Kubernetes and Helm.

Issue: ImagePullBackOff / ErrImagePull

🔍 Error

kubectl get pods
ImagePullBackOff
ErrImagePull

🧠 Root Cause

Kubernetes was trying to pull images like:

backend-app
frontend-app

But these images did not exist in any container registry. By default, Kubernetes attempts to pull images from external sources like Docker Hub.

✅ Fix

Since I was using Minikube, I needed to build images inside Minikube’s Docker environment.

🔧 Steps to Fix
1️⃣ Point Docker to Minikube

& minikube -p minikube docker-env --shell powershell | Invoke-Expression

Build Images Inside Minikube

docker build -t backend-app ./backend
docker build -t frontend-app ./frontend

3️⃣ Prevent External Pulls

Added in deployment:

imagePullPolicy: Never

4️⃣ Redeploy

helm upgrade myapp ./myapp

✅ Final Result

kubectl get pods

All pods:

Running ✅

Building a CI/CD Pipeline with Docker, Jenkins, and AWS EC2

SWAPNIL UPPIN — Mon, 23 Mar 2026 02:57:25 +0000

Introduction:

In modern DevOps workflows, Continuous Integration and Continuous Deployment (CI/CD) pipelines help teams deliver software faster and more reliably.

In this project, I built a complete CI/CD pipeline that automatically deploys a Dockerized Python application to an AWS EC2 instance using Jenkins.

The goal was to simulate a real-world deployment pipeline where code changes trigger automatic builds, tests, and deployments.

Architecture Overview:

The pipeline works as follows:

Developer → GitHub → Jenkins Pipeline → Docker Build → DockerHub → AWS EC2 → Nginx Reverse Proxy → Application Containers

Application Setup:

We will be using a simple Python Flask application that returns the message 'Hello from CI/CD auto-deploy!', along with a requirements.txt file for managing dependencies and a test_app.py file for running test cases.

app.py:

from flask import Flask, jsonify
import socket
import os

app = Flask(__name__)

@app.get("/health")
def health():
    return jsonify(status="ok")

@app.get("/")
def index():
    return jsonify(
        message="Hello from CI/CD auto-deploy!",
        hostname=socket.gethostname(),
        version=os.getenv("APP_VERSION", "dev"),

    )

if __name__ == "__main__":
    app.run(host="0.0.0.0",port=5000)

requirements.txt:

flask==3.0.3
gunicorn==22.0.0
pytest==8.2.2

test_app.py:

import sys
import os

# Add the app directory to Python path
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from app import app

def test_health():
    client = app.test_client()
    r = client.get("/health")
    assert r.status_code == 200
    assert r.json["status"] == "ok"

Dockerizing the Application:

Create a Dockerfile to containerize the application using python:3.12-slim as the base image. The application listens on port 5000, and the CMD instruction starts the Gunicorn server with 2 workers, binding it to port 5000 and serving the app object from the app module.

Dockerfile:

FROM python:3.12-slim
WORKDIR /app
COPY app/requirements.txt /app/requirements.txt
RUN pip install --no-cache-dir -r requirements.txt
COPY app /app
ENV PYTHONUNBUFFERED=1
EXPOSE 5000
CMD ["gunicorn", "-w", "2", "-b", "0.0.0.0:5000", "app:app"]

Reverse Proxy Configuration:

Below is the configuration for Nginx which acts reverse proxy and Routes user traffic to the correct container. it routes the incoming traffic to either the Blue (port 8081) or Green (port 8082) container, enabling zero-downtime deployments by simply switching the proxy_pass target between the two live environments.

nginx.conf:

events{}

http{
    server{
        listen 80;

        location /
        {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

            # default (blue). deploy script will switch to 127.0.0.1:8082 for green
            proxy_pass http://127.0.0.1:8081;
        }
    }
}

scripts:

ec2_bootstrap.sh:

This is a setup script that runs on EC2 instance to install Docker and Docker Compose, and configure the necessary permissions.

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

sudo apt-get update -y
sudo apt-get install -y ca-certificates curl gnupg lsb-release

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update -y
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker "$USER"

deploy_bluegreen.sh:

The deploy_bluegreen.sh script orchestrates the blue/green switch on the EC2 instance. It begins by pulling the latest Docker image and spinning up both the blue and green containers via Docker Compose. It then inspects the active Nginx proxy_pass directive to determine which slot — port 8081 (blue) or 8082 (green) — is currently serving live traffic, and targets the idle slot for the new deployment. A health check loop polls the new slot's /health endpoint up to 10 times, with a 2-second delay between attempts, before proceeding. Once the new slot is confirmed healthy, the script updates the Nginx config with a sed in-place swap and reloads Nginx — making the cutover instant and zero-downtime — then logs the active port to confirm a successful deployment.

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

# Expected env vars:
# IMAGE_FULL  (e.g. docker.io/<user>/cicd-ec2-autodeploy:build-123)
# APP_VERSION (e.g. build-123)

APP_DIR="/opt/cicd-ec2-deploy"
NGINX_CONF="${APP_DIR}/docker/nginx.conf"

mkdir -p "${APP_DIR}"
cd "${APP_DIR}"

# If first time: put repo runtime files here
# You can git clone on EC2 OR Jenkins will scp needed files. We keep it simple:
# We assume docker-compose.ec2.yml and docker/nginx.conf exist in APP_DIR.

if [[ ! -f docker-compose.ec2.yml ]]; then
    echo "ERROR: docker-compose.ec2.yml not found in ${APP_DIR}"
    exit 1
fi

echo "Pulling image: ${IMAGE_FULL}"
sudo docker pull "${IMAGE_FULL}"

# Pass vars explicitly to docker compose
sudo IMAGE_FULL="${IMAGE_FULL}" APP_VERSION="${APP_VERSION}" \
    docker compose -f docker-compose.ec2.yml up -d

# Determine currently active upstream in nginx.conf
ACTIVE_UPSTREAM="$(grep -E 'proxy_pass http://127\.0\.0\.1:808[12];' -o "${NGINX_CONF}" | tail -n 1 || true)"

if [[ "${ACTIVE_UPSTREAM} == *"8081"*" ]]; then
   NEW_PORT="8082"
   NEW_SLOT="green"
else
   NEW_PORT="8081"
   NEW_SLOT="blue"
fi

echo "Switching traffic to ${NEW_SLOT} (port ${NEW_PORT})"

# Basic health check loop in new slot
for i in {1..10}; do
  if curl -fss "http://127.0.0.1:${NEW_PORT}/health" >/dev/null; then
    echo "New slot healthy"
    break
  fi
  echo "waiting for new slot health... ${i}/10"
  sleep 2
  if [[ $i -eq 20 ]]; then
    echo "ERROR: New slot did not become healthy"
    exit 1
  fi
done

# Swap nginx upstream and reload
sudo sed -i "s#proxy_pass http://127.0.0.1:808[12];#proxy_pass http://127.0.0.1:${NEW_PORT};#g" "${NGINX_CONF}"
sudo docker exec nginx nginx -s reload

echo "Deploy complete. Live traffic now on port ${NEW_PORT} via Nginx:80"

Docker Compose Configuration:

The Docker Compose file defines three services: Nginx acts as a reverse proxy, listening on port 80 and routing traffic using a custom nginx.conf mounted as a read-only volume; app_blue runs the application container on host port 8081; and app_green runs an identical instance on host port 8082. Both the blue and green containers use the same versioned image — injected via the IMAGE_FULL environment variable — and receive an APP_VERSION variable at runtime, making it easy to verify which build is actively serving traffic at any given time.

docker-compose.ec2.yml:

services:
  nginx:
    image: nginx:1.27-alpine
    container_name: nginx
    ports:
      - "80:80"
    volumes:
      - ./docker/nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app_blue
      - app_green
    restart: always

  # Blue app (port 8081 on host)
  app_blue:
    image: ${IMAGE_FULL}
    container_name: app_blue
    environment:
      - APP_VERSION=${APP_VERSION}
    ports:
      - "8081:5000"
    restart: always

  # Green app(port 8082 on host)
  app_green:
    image: ${IMAGE_FULL}
    container_name: app_green
    environment:
      - APP_VERSION=${APP_VERSION}
    ports:
      - "8082:5000"
    restart: always

CI/CD Pipeline:

This pipeline automates the full CI/CD lifecycle and is divided into five stages: Checkout SCM pulls the latest code from source control; Test sets up a Python virtual environment and runs pytest against the application; Build Docker Image builds a versioned Docker image tagged with the Jenkins build number; Docker Push authenticates with DockerHub and pushes the built image to the registry; and finally, Deploy to EC2 (Blue/Green) securely connects to the EC2 instance over SSH, transfers the necessary configuration files — including the Docker Compose file, Nginx config, and blue/green deployment script — and executes the deployment. A post block ensures Docker is logged out and any sensitive files are cleaned up after every run, regardless of the build outcome.

Jenkinsfile:

pipeline{
    agent any
    environment{
      APP_NAME = 'cicd-ec2-deploy'
      DOCKERHUB_REPO = "${env.DOCKERHUB_REPO}"   // set in Jenkins job config
      IMAGE_TAG      = "build-${env.BUILD_NUMBER}"
      IMAGE_FULL     = "${DOCKERHUB_REPO}:${IMAGE_TAG}"
      EC2_HOST       = "${env.EC2_HOST}"         // set in Jenkins job config
      EC2_USER       = "${env.EC2_USER}"         // set in Jenkins job config (ubuntu)
    }

    stages{
        stage("checkout scm"){
            steps{
                checkout scm
            }
        }

        stage("Test"){
          steps {
                bat '''
                python -m venv .venv
                call .venv/Scripts/activate.bat
                pip install -r cicd-ec2-autodeploy/app/requirements.txt --quiet
                python -m pytest cicd-ec2-autodeploy/app -q
                '''
          }
        }

        stage("Build Docker image"){
            steps{
                bat '''
                docker build -t %IMAGE_FULL% -f cicd-ec2-autodeploy/docker/Dockerfile .
                '''

            }
        } 

        stage("docker push image"){
            steps{

                withCredentials([usernamePassword(credentialsId: 'dockerhub', usernameVariable: 'DOCKER_USER', passwordVariable: 'DOCKER_PASS')]){
                  sh '''
                    echo "${DOCKER_PASS}" | docker login -u "${DOCKER_USER}" --password-stdin
                    docker push ${IMAGE_FULL}
                  '''                  
                  }

            }
        }

        stage("Deploy to EC2 (Blue/Green)") {
    steps {
        withCredentials([file(credentialsId: 'ec2-ssh-key-file', variable: 'SSH_KEY_FILE')]) {

            // Windows Jenkins runs bat with %VAR% for local ssh/scp commands
            bat """
            icacls %SSH_KEY_FILE% /inheritance:r
            icacls %SSH_KEY_FILE% /grant:r "%USERNAME%:R"
            icacls %SSH_KEY_FILE% /remove "BUILTIN\\Users"
            icacls %SSH_KEY_FILE% /remove "Everyone"
            icacls %SSH_KEY_FILE% /grant:r "SYSTEM:F"
            icacls %SSH_KEY_FILE% /grant:r "BUILTIN\\Administrators:F"

            ssh -o StrictHostKeyChecking=no -i %SSH_KEY_FILE% ^
                %EC2_USER%@%EC2_HOST% ^
                "sudo mkdir -p /opt/%APP_NAME%/docker /opt/%APP_NAME%/scripts"

            scp -o StrictHostKeyChecking=no -i %SSH_KEY_FILE% ^
                cicd-ec2-autodeploy/docker-compose.ec2.yml ^
                %EC2_USER%@%EC2_HOST%:/tmp/docker-compose.ec2.yml

            scp -o StrictHostKeyChecking=no -i %SSH_KEY_FILE% ^
                cicd-ec2-autodeploy/docker/nginx.conf ^
                %EC2_USER%@%EC2_HOST%:/tmp/nginx.conf

            scp -o StrictHostKeyChecking=no -i %SSH_KEY_FILE% ^
                cicd-ec2-autodeploy/scripts/deploy_bluegreen.sh ^
                %EC2_USER%@%EC2_HOST%:/tmp/deploy_bluegreen.sh

            ssh -o StrictHostKeyChecking=no -i %SSH_KEY_FILE% ^
                %EC2_USER%@%EC2_HOST% ^
                "set -e && sudo apt-get install -y dos2unix -qq && sudo mv /tmp/docker-compose.ec2.yml /opt/%APP_NAME%/docker-compose.ec2.yml && sudo mv /tmp/nginx.conf /opt/%APP_NAME%/docker/nginx.conf && sudo mv /tmp/deploy_bluegreen.sh /opt/%APP_NAME%/scripts/deploy_bluegreen.sh && sudo dos2unix /opt/%APP_NAME%/scripts/deploy_bluegreen.sh && sudo chmod +x /opt/%APP_NAME%/scripts/deploy_bluegreen.sh && sudo IMAGE_FULL=%IMAGE_FULL% APP_VERSION=%IMAGE_TAG% /opt/%APP_NAME%/scripts/deploy_bluegreen.sh"
            """               
        }
    }
}               
    }

    post{
        always{
            sh "docker logout || true"
            sh "rm -rf .env || true"
        }
    }
}

step by step execution:

Step 1 — Create an EC2 Instance:

Create an EC2 instance in the AWS Console using the following configuration:

Instance Type: t2.micro (Free Tier eligible)
AMI: Ubuntu 22.04 (Free Tier eligible)
Security Group Inbound Ports: 22, 80, 8081, and 8082
Storage: 8 GB gp2 EBS volume

Step 2 — Create a Jenkins Pipeline Job:

In Jenkins, create a new job and select Pipeline as the project type.

In the Pipeline section, select Git as the SCM and enter your repository URL.

Under Branches to Build, set the Branch Specifier to */main and set the Script Path to cicd-ec2-autodeploy/Jenkinsfile.

Navigate to Configure → Build Environment → This project is parameterized and add the following as string parameters, matching the environment variables referenced in the Jenkinsfile:

Parameter         Description
DOCKERHUB_REPO    Your DockerHub repository 
EC2_HOST          Public IP or DNS of your EC2 instance
EC2_USER          SSH login user (e.g. ubuntu)

Step 3 — Generate SSH Keys on EC2 and Add to Jenkins:

SSH into your EC2 instance and generate an RSA key pair:

ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N "" -m PEM

This produces two files — id_rsa (private key) and id_rsa.pub (public key). Register the public key as an authorized key on the instance:

mkdir -p ~/.ssh
cat id_rsa.pub >> ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa
chmod 600 ~/.ssh/authorized_keys

On your Windows machine, open Notepad and paste the private key in the following format:

-----BEGIN RSA PRIVATE KEY-----
<your key content>
-----END RSA PRIVATE KEY-----

Save the file as id_rsa.pem and ensure the following:

No extra blank lines at the top or bottom
No extra spaces anywhere in the file
File encoding is UTF-8 (not UTF-8 BOM)

Now upload the key to Jenkins by navigating to Manage Jenkins → Credentials → System → Global Credentials and adding a new credential with the following settings:

Field       Value 
Kind        Secret file        
ID          ec2-ssh-key-file
File        Upload id_rsa.pem

Step 4 — Bootstrap the EC2 Instance:

Clone the repository onto your EC2 instance, or manually copy and paste the ec2-bootstrap.sh script into it, then run the script to install Docker and Docker Compose and configure the necessary permissions.
Once the installation is complete, verify that Docker is installed and running:

systemctl status docker

Step 5 — Run the Jenkins Job

Trigger the Jenkins job by selecting Build with Parameters and allow the job to run through all the stages defined in the Jenkinsfile. Monitor the Console Output to track the progress of each stage as it executes.
If any stage encounters an error, the job will mark the build as Failed and the console output will indicate exactly where the failure occurred. If all stages complete without issues, the job will mark the build as Success.

Deployment Result:

Once the Jenkins job completes successfully, the application will be deployed on the EC2 instance as two running Docker containers — app_blue on port 8081 and app_green on port 8082. Nginx listens on port 80 and routes all live traffic to one active slot at a time, switching to the idle slot on each new deployment. You can access the application either through Nginx on port 80, or directly on port 8081 or 8082 via the EC2 instance's public IP in your browser, as shown below:

Clean up:

After the completion of the project delete your EC2 instance. The purpose of deleting the EC2 instance is to release the compute resources and avoid unnecessary costs associated with running and maintaining the instance

In conclusion,This project demonstrates how a fully automated CI/CD pipeline can be built from scratch using Jenkins, Docker, and a simple Bash script — without relying on any cloud-native deployment services. Every push to the repository triggers a clean build, test, containerization, and a zero-downtime blue/green deployment to a live EC2 instance, all within a single pipeline run.

About the Repo

The full source code for this project is available on GitHub, including the Jenkinsfile, Dockerfile, Docker Compose configuration, Nginx config, blue/green deployment script, and the EC2 bootstrap script. The repository is structured to be straightforward to clone and adapt to your own use case — swap in your DockerHub credentials, point it at your EC2 instance, and the pipeline handles the rest.

🔗 GitHub: EC2-CICD-DEPLOY

Thank you for reading this article, and we hope it has provided valuable insights into deploying applications on cloud platforms.