This project automates the deployment of a containerized web application to Amazon ECS (Fargate) using Terraform and a GitLab CI/CD pipeline. The application is a simple Nginx web service containerized with Docker, and the pipeline automatically builds, pushes, and deploys it on ECS.
ECS-TERRAFORM-GITLAB/
β
βββ app/ # Application Layer (Dockerized Web App)
β βββ Dockerfile # Builds Nginx-based container
β βββ index.html # Static webpage for ECS deployment test
β
βββ terraform/ # Infrastructure Layer (Terraform IaC)
β βββ backend.tf # Remote backend (S3 + DynamoDB) configuration
β βββ provider.tf # AWS provider + region definition
β βββ variables.tf # All input variables
β βββ vpc.tf # Creates VPC + subnets
β βββ igw.tf # Internet Gateway + route table
β βββ security_groups.tf # Security Group for ECS tasks
β βββ ecr.tf # ECR repository configuration
β βββ ecs.tf # ECS cluster, roles, task definition, service
β βββ outputs.tf # Terraform outputs (ECS, VPC, ECR, etc.)
β βββ .terraform.lock.hcl # Terraform dependency lock file (auto-generated)
β
βββ .gitlab-ci.yml # GitLab CI/CD pipeline for build/deploy/destroy
βββ .gitignore # Ignores Terraform state and sensitive files
βββ README.md # Project documentation (overview, steps, etc.)
| File | Purpose |
|---|---|
| backend.tf | Configures Terraform remote state in an S3 bucket with DynamoDB lock. |
| provider.tf | Declares AWS provider and region. |
| variables.tf | Holds reusable project parameters (VPC CIDR, AZs, ECS sizes, etc.). |
| vpc.tf | Creates custom VPC and public subnets. |
| igw.tf | Sets up Internet Gateway and public route table. |
| security_groups.tf | Allows HTTP (port 80) inbound and all outbound traffic. |
| ecr.tf | Creates AWS ECR repo for storing container images. |
| ecs.tf | Defines ECS cluster, task definition, service, and IAM roles. |
| outputs.tf | Exposes IDs, names, and URLs after apply. |
| app/Dockerfile | Builds Nginx image serving your index.html. |
| .gitlab-ci.yml | Automates build β push β deploy β destroy pipeline stages. |
The goal of this project is to automate ECS deployment with infrastructure and pipeline as code, demonstrating:
-
Containerization with Docker
-
Infrastructure as Code (IaC) with Terraform
-
Continuous Integration & Deployment (CI/CD) using GitLab
-
Automatic vertical scaling by changing ECS service size variables
-
Centralized logging using AWS CloudWatch
| Category | Tools Used |
|---|---|
| Cloud Provider | AWS |
| IaC | Terraform |
| CI/CD | GitLab CI/CD |
| Containerization | Docker |
| Compute | ECS Fargate |
| Repository | GitHub / GitLab |
| Logging | AWS CloudWatch |
The Terraform configuration creates the following components:
| Resource | Description |
|---|---|
| VPC | Custom VPC (10.0.0.0/16) with two public subnets |
| Subnets | Two public subnets across different AZs (us-east-1a & us-east-1b) |
| Internet Gateway & Route Table | Provides public internet access for ECS tasks |
| Security Group | Allows inbound HTTP (port 80) |
| ECR Repository | Stores Docker images built by the CI/CD pipeline |
| CloudWatch Log Group | Captures container logs from ECS |
| ECS Cluster | Manages Fargate-based services |
| ECS Task Definition | Defines container CPU/memory and image |
| ECS Service | Deploys and maintains the running task in ECS |
A minimal Nginx web app used for testing container deployment.
FROM nginx:alpine
COPY index.html /usr/share/nginx/html/index.html
EXPOSE 80
<html>
<body style="font-family: sans-serif; text-align: center;">
<h2>ECS CI/CD Deployment Success!</h2>
</body>
</html>
The Terraform scripts:
-
Create all AWS resources (VPC, ECS, ECR, CloudWatch)
-
Automatically read parameters (like ECR image URL and tag) from pipeline variables
Docker builds the Nginx container.
Pushes image to AWS ECR.
Terraform provisions VPC, ECS Cluster, and deploys Fargate service.
The container image from ECR runs on ECS.
Cleans up all resources (terraform destroy).
-
Uses aws-cli for authentication and ECR creation
-
Uses Terraform Docker image for IaC apply/destroy
-
Pipeline variables dynamically set the image tag and scaling level
-
Destroy job is manual to avoid accidental deletions
| Key | Description | Example |
|---|---|---|
AWS_ACCESS_KEY_ID |
AWS access key | AKIA******** |
AWS_SECRET_ACCESS_KEY |
AWS secret | ******** |
AWS_ACCOUNT_ID |
AWS account ID | 123456789012 |
AWS_REGION |
AWS region | us-east-1 |
SERVICE_SIZE |
ECS scaling size | small / medium / large |
The Terraform backend stores remote state:
terraform {
backend "s3" {
bucket = "<BUCKET_NAME>"
key = "global/s3/terraform.tfstate"
region = "us-east-1"
dynamodb_table = "terraform-locks"
encrypt = true
}
}Ensure the S3 bucket and DynamoDB table exist before first run:
aws s3 mb s3://<BUCKET_NAME> --region us-east-1
aws dynamodb create-table \
--table-name terraform-locks \
--attribute-definitions AttributeName=LockID,AttributeType=S \
--key-schema AttributeName=LockID,KeyType=HASH \
--billing-mode PAY_PER_REQUEST- Push code to main branch (pipeline triggers automatically).
- Or manually run pipeline β Build β Pipelines β Run Pipeline.
Stages:
-
build: Builds Docker image and pushes to ECR
-
deploy: Applies Terraform to deploy ECS
-
Check ECS Cluster β Tasks β copy Public IP and test in browser:
http://<PUBLIC_IP>
You should see:
Trigger the destroy job from the GitLab pipeline UI:
terraform destroy -auto-approveThis removes all ECS resources (VPC, subnets, ECS, ECR, CloudWatch).
After terraform apply, useful details are shown:
Outputs:
ecs_cluster_name = "ecs_project-cluster"
ecs_service_name = "ecs_project-service"
ecr_repository_url = "123456789012.dkr.ecr.us-east-1.amazonaws.com/ecs_project"
public_subnet_ids = ["subnet-xxxx", "subnet-yyyy"]
log_group_name = "/ecs/ecs_project"Get the public IP of the running ECS task:
CLUSTER="ecs_project-cluster"
SERVICE="ecs_project-service"
REGION="us-east-1"
TASK_ARN=$(aws ecs list-tasks --region $REGION --cluster $CLUSTER --service-name $SERVICE --desired-status RUNNING --query 'taskArns[0]' --output text)
ENI_ID=$(aws ecs describe-tasks --region $REGION --cluster $CLUSTER --tasks $TASK_ARN --query 'tasks[0].attachments[0].details[?name==`networkInterfaceId`].value' --output text)
aws ec2 describe-network-interfaces --region $REGION --network-interface-ids $ENI_ID --query 'NetworkInterfaces[0].Association.PublicIp' --output text| Feature | Implemented |
|---|---|
| Containerized app with Docker | β |
| Terraform-based AWS infrastructure | β |
| ECS Fargate deployment | β |
| GitLab CI/CD automation | β |
| CloudWatch logging | β |
| Vertical scaling (small/medium/large) | β |
| Automated ECR image builds | β |
Andrew Ferdinandus
π» Senior Linux / Systems Engineer
π New Zealand
π GitHub Profile | LinkedIn
