BeyondSquare

A cost-conscious, cloud-native DevOps platform demonstrating the end-to-end delivery and operation of a containerized API across local Kubernetes and AWS EKS.

The platform uses PostgreSQL, Redis, Docker, Kubernetes, Kustomize, GitHub Actions, Terraform, AWS EKS/ECR/ALB, and CloudWatch.

The same application, container image, Kubernetes base manifests, and CI/CD workflow are used across both environments. Environment-specific Kustomize overlays adapt only what needs to change between local Kubernetes and AWS EKS.

That equivalence is the point: demonstrating what environment-agnostic infrastructure actually looks like in practice, rather than simply describing it on a slide.

Cost model: The local environment is designed to run at ₹0. AWS is operated as an on-demand lab: provision → deploy → verify → destroy.

---

Project phases

Phase	Description	Status
Mode 1 — Local	Application + Postgres + Redis via docker-compose.yaml / kind-config.yaml	✅ Complete
Mode 2 — AWS	Same stack on EKS + ALB + ECR + CloudWatch, provisioned via Terraform, deployed via GitHub Actions	✅ Complete

AWS evidence is available in docs/images/.

---

See docs/TROUBLESHOOTING.md for real incidents encountered during implementation, including investigation, root cause, fixes, and lessons learned.

---

Architecture

BeyondSquare uses the same application, container image, Kubernetes base manifests, and CI/CD approach across both environments. Environment-specific Kustomize overlays adapt deployment details for Local KIND and AWS EKS.

What this project demonstrates

• Infrastructure as Code with Terraform
• Kubernetes deployment with Kustomize
• Environment-agnostic kubernetes application delivery
• CI/CD with GitHub Actions
• AWS networking with VPC, subnets and NAT
• EKS, ECR and Application Load Balancer
• IAM least-privilege separation and IRSA
• Persistent storage with EBS CSI
• Observability with Prometheus/Grafana/Loki and CloudWatch
• Failure investigation and troubleshooting
• Cost-aware ephemeral AWS infrastructure

Full diagrams and the reasoning behind each major decision (Kustomize over per-env Helm charts, self-hosted runner, single NAT gateway, etc.) live in docs/architecture.md.

---

Tech stack

Layer	Tools
Application	FastAPI, PostgreSQL, Redis
Containers	Docker, Docker Compose, multi-stage builds
Local orchestration	Kind (Kubernetes-in-Docker), Kustomize
Observability	Prometheus, Grafana, Loki, Promtail locally; CloudWatch on AWS
CI/CD	GitHub Actions, self-hosted runner (local), workflow_dispatch (AWS)
Cloud (On demand)	AWS EKS, ECR, VPC, ALB, CloudWatch — via Terraform
Dev environment	WSL2 + Ubuntu 24.04, VS Code (Remote-WSL)

Local Kubernetes observability uses Prometheus, Grafana, Loki and Promtail. AWS currently uses CloudWatch for EKS control-plane logging.

---

Key engineering decisions

Decision	Why
Kustomize overlays	Minimize environment drift
Terraform modules	Reproducible AWS infrastructure
IRSA	Scope controller permissions to service accounts
Dedicated CI/CD IAM identity	Separate deployment permissions from Terraform administration
Manual AWS deployment	Manual AWS deployment
Single NAT Gateway	Cost/availability trade-off for a lab
EBS WaitForFirstConsumer	Avoid cross-AZ volume scheduling failures
Ephemeral AWS environment	Control learning-project costs

See docs/ARCHITECTURE.md for the complete architecture and ADRs.

Engineering lessons

This project intentionally documents failures encountered during implementation rather than presenting only the final "happy path".

See docs/TROUBLESHOOTING.md for the investigation, root cause, fix, and lesson from each incident.

Repository Structure

app/                  Application source and tests
k8s/                  Kubernetes base and environment overlays
terraform/            AWS infrastructure modules
.github/workflows/    CI/CD workflows
docs/                 Architecture, implementation and troubleshooting

---

Running locally - (Mode 1)

git clone https://github.com/KomalSingh21/beyondsquare.git
cd beyondsquare
docker compose up --build
curl http://localhost:3000/health   # {"status":"alive"}
curl http://localhost:3000/ready    # {"status":"ready","checks":{"postgres":true,"redis":true}}

For the full Kubernetes + CI/CD + monitoring path, see docs/IMPLEMENTATION.md.

---

Deploying to AWS - (Mode 2)

The AWS environment is provisioned with Terraform and deployed through GitHub Actions.

The complete account setup, infrastructure provisioning, EKS configuration, ALB controller, deployment, verification and teardown procedure is documented in AWS_IMPLEMENTATION_GUIDE.md.

Cost model: AWS is operated as an ephemeral lab:

terraform apply → deploy → verify → terraform destroy

---

Documentation

Doc	What's in it
docs/PREREQUISITES.md	Every tool this project needs, why, and how to install it (WSL2, Docker, kubectl, Kind, Helm, Terraform, AWS CLI)
docs/CONFIGURATION.md	Environment variables, Docker Compose config, Kubernetes ConfigMaps/Secrets, Terraform variables, GitHub Actions secrets
docs/IMPLEMENTATION.md	Full build log, phase by phase: local dev → Kind/K8s → CI/CD → monitoring → AWS/Terraform
docs/ARCHITECTURE.md	Full topology diagram and Architecture Decision Records (ADRs) — the why behind each choice
docs/TROUBLESHOOTING.md	Real incidents hit while building this, in Symptom → Investigation → Root Cause → Fix → Lesson format
docs/AWS_IMPLEMENTATION_GUIDE.md	Full click-by-click Phase 2 walkthrough — account setup through teardown
app/README.md	API endpoints, environment variables, schema, local run instructions