CloudOps GitOps Platform

CloudOps GitOps Platform is an EKS GitOps delivery platform. It uses Argo CD, Helm, GitHub Actions, Terraform, ECR, and EKS to move a small app through dev, staging, and prod while Git stays the source of truth.

The app stays small on purpose. The useful part is the delivery path around it: how a version reaches each environment, how Argo CD handles manual drift, and how a bad release gets recovered through Git.

Project Versions

• v1.0: GitOps delivery platform with Argo CD, Helm, EKS, ECR, GitHub Actions, drift correction, and rollback validation.
• v1.1: GitOps-managed Prometheus/Grafana observability and Terraform-managed AWS Budgets for cost-controlled validation environments.

Platform Capabilities

• GitOps delivery with Argo CD as the reconciliation controller
• Namespace-isolated dev, staging, and prod environments
• GitOps-managed observability namespace for Prometheus and Grafana
• Resource quotas and scoped RBAC boundaries per environment
• Ingress NetworkPolicies for app namespaces, allowing same-namespace traffic and Prometheus scraping from observability
• Helm-based application packaging with environment-specific values
• Argo CD multi-source Applications so environment values stay outside the chart without path traversal
• PR-style promotion of immutable 12-character commit-SHA image tags
• Drift detection and self-healing after manual cluster changes
• Failed deployment recovery through Git rollback
• Terraform-provisioned AWS foundation for EKS, ECR, IAM, and VPC networking
• Terraform-managed AWS Budget for validation cost guardrails

Current State

The repository includes:

• Demo app with version and health endpoints
• Demo app Prometheus metrics endpoint
• Helm chart with probes, resource requests, resource limits, and security context
• Optional Helm-managed ServiceMonitor for app metrics
• Argo CD AppProject and multi-source Applications
• Namespace-scoped dev, staging, and prod environments
• Argo CD-managed kube-prometheus-stack Application for Prometheus and Grafana
• Grafana dashboard ConfigMap for GitOps workload health
• ResourceQuotas, NetworkPolicies, Roles, RoleBindings, and ServiceAccounts per environment
• GitHub Actions workflow for app tests, Helm rendering, Argo CD manifest rendering, image build, and optional ECR push
• GitHub Actions workflow that verifies immutable commit-SHA tags in ECR before opening promotion pull requests
• Terraform modules and environment roots for VPC, EKS, ECR, IAM, and AWS Budgets
• Local validation path using kind or minikube image loading
• AWS validation path using EKS, ECR, Argo CD, Helm, and GitHub as the source of truth

Validated scenarios:

• Argo CD sync of all three environments
• Drift detection and self-healing after a manual replica change
• Failed deployment recovery through Git revert
• EKS/ECR deployment validation with screenshots and terminal output
• Argo CD-managed Prometheus/Grafana observability on EKS
• Terraform-managed AWS Budget validation

Architecture

flowchart LR
    dev["Developer"] --> repo["GitHub Repository"]
    repo --> gha["GitHub Actions"]
    gha --> image["Container Image Tag"]
    gha --> pr["Promotion Pull Request"]
    pr --> envs["GitOps Environment Values"]
    envs --> argocd["Argo CD"]
    argocd --> nsdev["dev namespace"]
    argocd --> nsstg["staging namespace"]
    argocd --> nsprod["prod namespace"]
    argocd --> nsobs["observability namespace"]
    nsdev --> appdev["Demo App"]
    nsstg --> appstg["Demo App"]
    nsprod --> appprod["Demo App"]
    nsobs --> prom["Prometheus"]
    nsobs --> graf["Grafana"]
    prom --> appdev
    prom --> appstg
    prom --> appprod

Loading

More detail: docs/architecture.md

Deployment Model

The repo supports two deployment targets:

• EKS deployment using the default environments/{dev,staging,prod} values, which point at ECR images.
• Local validation using VALUES_ROOT=environments/local, which points at kind/minikube-loaded images.

For local runs, kind or minikube can validate the GitOps loop before anything runs in AWS:

1. Install Argo CD.
2. Apply namespaces, ResourceQuotas, RBAC, and NetworkPolicies.
3. Sync three Argo CD Applications.
4. Promote app versions through Git changes.
5. Run the drift correction and rollback scenarios.

Terraform provisions the AWS foundation for the EKS run. The applied model uses one EKS cluster and separates dev, staging, and prod with Kubernetes namespaces.

AWS deployment path and permission preflight: docs/aws-deployment.md

Cost control and cleanup notes: docs/cost-control.md

Observability design and runbook: docs/observability.md

Repository Structure

.
├── app/                         # Small app used to validate delivery behavior
├── charts/cloudops-demo-app/    # Helm chart for the app
├── environments/                # Environment-specific Helm values
├── platform/                    # Namespaces, ResourceQuotas, NetworkPolicies, and RBAC
├── argocd/                      # AppProject and Application manifests
├── terraform/                   # AWS VPC, EKS, ECR, and IAM infrastructure
├── docs/                        # Architecture, validation records, runbooks, tradeoffs
├── scripts/                     # Local bootstrap and validation helpers
└── .github/workflows/           # CI and PR-style promotion workflows

Run Results

Screenshots and terminal captures live under docs/screenshots.

• Argo CD showing cloudops-demo-dev, cloudops-demo-staging, and cloudops-demo-prod as Synced and Healthy
• Manual replica drift detected as OutOfSync and reconciled back to Git state
• Broken readiness probe producing a Degraded application
• Git rollback restoring the last healthy version
• Environment quotas and RBAC visible in Kubernetes
• Argo CD Applications resolving $values/environments/.../values.yaml
• Prometheus scraping app ServiceMonitor targets across dev/staging/prod
• Grafana dashboard showing workload health and app metrics
• AWS Budget output for the validation environment
• Terraform destroy output, empty state, AWS resource checks, and project tag sweep after teardown

The screenshot index is in docs/screenshots/README.md.

Detailed validation results: docs/local-validation-results.md

AWS validation results: docs/aws-validation-results.md

Engineering notes: docs/engineering-notes.md

Screenshot Gallery

Promotion Model

Promotion is PR-style: a workflow verifies that a 12-character commit-SHA tag exists in ECR, then opens a pull request that updates the target environment's Helm values. ECR rejects tag overwrites, so the same image tag can move through dev, staging, and prod without being rebuilt.

Details: docs/promotion-workflow.md

Environment Model

The applied environment model uses one EKS cluster with namespace-scoped dev, staging, and prod environments.

Each environment has its own Argo CD Application, Helm values file, ResourceQuota, NetworkPolicies, ServiceAccount, Role, and RoleBinding. Argo CD owns reconciliation for the deployed workloads, while the scoped RBAC manifests define the namespace access model used for manual/operator or CI-style actions.

This keeps the project focused on GitOps delivery mechanics: promotion through Git, drift correction, rollback through Git, workload observability, and Terraform-managed infrastructure lifecycle.

The project uses one EKS cluster with namespace boundaries. NetworkPolicies reduce cross-namespace traffic exposure, but they do not provide the same isolation as separate AWS accounts, separate clusters, or separate production node groups.

Secrets management and progressive delivery are intentionally scoped as future hardening work. The next production step would be External Secrets Operator with AWS Secrets Manager and IRSA, followed by Argo Rollouts for canary or blue-green release controls.

Commands

Render all Helm manifests locally:

./scripts/render-helm.sh

Validate local files:

make validate

Build and load local kind images:

./scripts/build-load-local-images.sh

Bootstrap a local cluster after creating one with kind or minikube:

./scripts/install-argocd.sh
VALUES_ROOT=environments/local ./scripts/local-bootstrap.sh

First live Argo CD test:

git init
git add .
git commit -m "Initial CloudOps GitOps Platform"
./scripts/local-git-server.sh
GIT_REPO_URL=git://host.docker.internal:9418/cloudops-gitops-platform PROJECT_ONLY=true ./scripts/local-bootstrap.sh
GIT_REPO_URL=git://host.docker.internal:9418/cloudops-gitops-platform VALUES_ROOT=environments/local APP_ENV=dev ./scripts/local-bootstrap.sh
argocd app get cloudops-demo-dev

Detailed checklist: docs/first-argocd-sync-test.md

Run validation scenarios:

./scripts/demo-drift.sh dev
./scripts/demo-rollback.sh staging

AWS Run

The AWS run used one EKS cluster and the public GitHub repository:

• Terraform applied the dev AWS root for VPC, EKS, ECR, IAM, and AWS Budgets
• App images were pushed to Amazon ECR with 0.1.0-dev, 0.1.0-staging, and 0.1.0-prod tags
• Argo CD on EKS synced from the public GitHub repository
• Drift and rollback scenarios were re-run on EKS
• Argo CD, Kubernetes, ECR, AWS Budget, Prometheus, Grafana, and teardown evidence were captured after the run

The AWS path uses cost-bearing resources. Keep the environment running only while it is needed for validation, and destroy it through Terraform when finished:

terraform -chdir=terraform/envs/dev destroy

Documentation

• Architecture
• AWS Deployment
• AWS Validation Results
• Cost Control
• Drift Detection Demo
• Engineering Notes
• First Argo CD Sync Test
• Local Validation Results
• Observability
• Promotion Workflow
• RBAC And Resource Boundaries
• Rollback Demo
• Validation Output