Skip to content

Platform Architecture & Deployment Overview

This document provides a high-level overview of the platform architecture and deployment flow, from source code changes to application runtime within AWS. It is intended to help engineers, operators, and stakeholders understand how code moves through CI/CD, how infrastructure is structured, and how workloads run securely in production.

overview

High-Level Architecture Summary

The platform follows a GitOps-driven, cloud-native architecture built on AWS and Kubernetes (EKS). It uses GitHub for source control and CI/CD, GitHub Container Registry (GHCR) for image storage, and Argo CD for continuous deployment into Amazon EKS.

At a glance:

  • Source Control & CI/CD: GitHub + GitHub Actions
  • Container Registry: GitHub Container Registry (GHCR)
  • Deployment Model: GitOps with Argo CD
  • Compute Platform: Amazon EKS
  • Networking: VPC with public and private subnets across multiple AZs
  • Security & Access: IAM Roles, OIDC, least-privilege access
  • Storage: EBS via CSI Driver

Development & CI/CD Flow

  1. Developers push code changes to a development branch in GitHub.
  2. A GitHub Actions CI/CD pipeline is triggered automatically.
  3. The pipeline:
  4. Builds Docker images
  5. Runs automated tests
  6. Pushes versioned images to GitHub Container Registry (GHCR)
  7. Kubernetes manifests reference the published container images and are stored in Git repositories.

GitOps Deployment with Argo CD

  • Argo CD continuously monitors Git repositories containing Kubernetes manifests.
  • When changes are detected:
  • The desired state is compared with the live cluster state.
  • Argo CD synchronizes the cluster to match the declared configuration.
  • This approach provides:
  • Declarative infrastructure management
  • Full auditability via Git history
  • Safe rollbacks by reverting commits

AWS Infrastructure Overview

Virtual Private Cloud (VPC)

  • The platform operates within a dedicated VPC (10.0.0.0/16).
  • The VPC spans multiple Availability Zones to ensure high availability and fault tolerance.

Subnet Design

Public Subnets - Host the Internet Gateway and NAT Gateway - Enable outbound internet access for private workloads

Private Subnets - Host Amazon EKS worker nodes and Kubernetes pods - No direct inbound internet access

Network Traffic Flow

  • Inbound traffic is controlled through managed AWS and Kubernetes entry points.
  • Outbound traffic from private subnets routes through a NAT Gateway.
  • Internal service-to-service communication occurs within the VPC.

Amazon EKS Cluster

Control Plane

  • Fully managed by AWS
  • Kubernetes version: 1.29
  • Integrated with IAM, OIDC, autoscaling, and storage drivers

Worker Nodes

  • Deployed as EKS Managed Node Groups
  • Instance type: t3.small
  • Distributed across multiple Availability Zones
  • Responsible for running Kubernetes workloads

Security & Identity Management

IAM Roles

The cluster uses distinct IAM roles to enforce least-privilege access:

  • Cluster Role: Used by the EKS control plane
  • Node Group Role: Used by worker nodes to interact with AWS services
  • EBS CSI Driver Role: Grants permissions for EBS volume management
  • Cluster Autoscaler Role: Enables dynamic scaling of node groups

OIDC Integration

  • An OIDC provider is configured for the EKS cluster.
  • Enables IAM Roles for Service Accounts (IRSA).
  • Allows Kubernetes workloads to assume AWS IAM roles without static credentials.

Storage & Add-ons

  • EBS CSI Driver
  • Version: v1.28.0-eksbuild.1
  • Provides dynamic provisioning of persistent volumes backed by Amazon EBS
  • Supports stateful workloads while remaining Kubernetes-native

Observability & Operations

  • Cluster components report status and metrics to Kubernetes and AWS control planes.
  • GitOps continuously detects and corrects configuration drift.
  • The platform supports:
  • Controlled rollouts
  • Rollbacks
  • Horizontal scaling

Key Benefits of This Architecture

  • Security-first design with private networking and IAM-based access
  • High availability through multi-AZ deployment
  • Scalable, managed Kubernetes infrastructure
  • Fully auditable and version-controlled deployments
  • Reduced operational overhead through automation
  • Client Deployment Guide
  • Internal Runbooks
  • CI/CD Pipeline Documentation
  • Kubernetes Standards & Conventions