LATEST 🚀 Welcome to Upgradix by Shrash Studio – Your destination for free technology learning and career growth.
🕘 Updated:
Kubernetes

Capstone: Building & Deploying a GitOps Multi-Service Stack

Deploying a single container is easy. Running a real, production-ready system with multiple services, safe database storage, traffic routing, live monitoring, and zero-touch automated deployments is what separates a beginner from a senior engineer.

Capstone: Building & Deploying a GitOps Multi-Service Stack

Deploying a single container is easy. Running a real, production-ready system with multiple services, safe database storage, traffic routing, live monitoring, and zero-touch automated deployments is what separates a beginner from a senior engineer.

In this capstone project, we will build and deploy a complete multi-tier microservice stack on Kubernetes using 100% free and open-source tools. By the end, you will have a portfolio-ready GitOps architecture where every change in Git automatically updates your live cluster.

What you will learn
  • How to design a clean 3-tier Kubernetes application (Frontend, Backend API, and PostgreSQL Database).
  • How to route external user traffic safely using an NGINX Ingress controller.
  • How to protect database data across pod restarts using PersistentVolumeClaims (PVC).
  • How to scrape live application and cluster metrics using Prometheus.
  • How to automate deployments and enable self-healing using Argo CD GitOps.

1. The Multi-Service Stack Overview

Before writing a single line of YAML, let us look at the exact pieces of our stack. Each component has one clear job. Keeping responsibilities separate makes the system easier to debug, scale, and explain in technical interviews.

Layer Tool / Component Role in the Stack
Traffic Entry NGINX Ingress Routes incoming HTTP requests to the Frontend (/) or Backend API (/api).
Frontend Tier React / Web UI Stateless web interface running across 2 replicas for high availability.
Backend Tier REST API Service Handles business logic, talks to the database, and exposes /metrics.
Storage Tier PostgreSQL + PVC Stores application data safely on a Persistent Volume so restarts never wipe data.
Observability Prometheus Continuously scrapes CPU, memory, and HTTP request metrics from our pods.
GitOps Engine Argo CD Watches our Git repository and automatically syncs any changes into Kubernetes.

2. Architecture & GitOps Workflow Visualized

In a traditional setup, a developer runs kubectl apply from their laptop. That is risky and hard to track. In our GitOps setup, Git is the single source of truth. Argo CD pulls changes from Git into the cluster, NGINX routes user traffic, and Prometheus watches the health of every service.

Live GitOps Multi-Service Architecture

KUBERNETES CLUSTER (PRODUCTION NAMESPACE) Git Repository YAML Manifests End Users HTTPS Traffic Argo CD Auto-Sync & Heal NGINX Ingress / & /api Routing Frontend UI 2 Replicas Backend API Exposes /metrics PostgreSQL + PVC Storage Prometheus Scrapes Live Metrics Pulls Deploys & Syncs

Animated data flow: Argo CD continuously syncs YAML from Git, NGINX routes user traffic to the right tier, PostgreSQL persists data to a PVC, and Prometheus scrapes live metrics.

3. Step 1 – Structuring Your GitOps Repository

A clean folder layout is the secret to stress-free GitOps. Keep your Kubernetes manifests organized by service inside a single k8s/ directory so Argo CD can watch the entire folder at once.

Recommended Repository Layout

gitops-capstone/
├── k8s/
│   ├── namespace.yaml
│   ├── postgres-pvc.yaml
│   ├── postgres-deploy.yaml
│   ├── api-deploy.yaml
│   ├── frontend-deploy.yaml
│   ├── ingress.yaml
│   └── servicemonitor.yaml
└── argocd/
    └── capstone-app.yaml

4. Step 2 – Stateful Database with Persistent Storage (PVC)

Containers are temporary. If a database pod crashes and restarts, any data saved inside the container disappears forever. To fix this, we create a PersistentVolumeClaim (PVC). It asks Kubernetes for a dedicated disk that survives pod restarts.

k8s/postgres-pvc.yaml – Requesting 5Gi of persistent disk

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
  namespace: capstone
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi

Now we mount that PVC into our PostgreSQL deployment and expose it internally using a ClusterIP Service so only our Backend API can reach it.

k8s/postgres-deploy.yaml – Database Deployment & Internal Service

apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: capstone
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:16-alpine
          ports:
            - containerPort: 5432
          env:
            - name: POSTGRES_DB
              value: "ordersdb"
            - name: POSTGRES_USER
              value: "appuser"
            - name: POSTGRES_PASSWORD
              value: "ChangeMeInSecret123"
          volumeMounts:
            - mountPath: /var/lib/postgresql/data
              name: pgdata
      volumes:
        - name: pgdata
          persistentVolumeClaim:
            claimName: postgres-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: postgres-svc
  namespace: capstone
spec:
  selector:
    app: postgres
  ports:
    - port: 5432
      targetPort: 5432
Watch out: Never commit real production database passwords in plain text to a public Git repository. In real production environments, use Sealed Secrets or External Secrets Operator to encrypt credentials safely.

5. Step 3 – Backend API, Frontend, and NGINX Ingress

Next, we deploy our stateless Backend API. Notice how we add prometheus.io/scrape annotations and resource limits. Setting CPU and memory limits prevents one runaway pod from starving the rest of your cluster.

k8s/api-deploy.yaml – Backend API with Metrics & Resource Limits

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend-api
  namespace: capstone
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backend-api
  template:
    metadata:
      labels:
        app: backend-api
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/path: "/metrics"
        prometheus.io/port: "8080"
    spec:
      containers:
        - name: api
          image: your-registry/capstone-api:1.0.0
          ports:
            - name: http
              containerPort: 8080
          env:
            - name: DB_HOST
              value: "postgres-svc"
          resources:
            requests:
              cpu: "100m"
              memory: "128Mi"
            limits:
              cpu: "500m"
              memory: "256Mi"
---
apiVersion: v1
kind: Service
metadata:
  name: backend-api-svc
  namespace: capstone
spec:
  selector:
    app: backend-api
  ports:
    - name: http
      port: 80
      targetPort: 8080

Now we create the Ingress resource. Instead of paying for a separate cloud Load Balancer for every single microservice, one NGINX Ingress routes traffic based on the URL path.

k8s/ingress.yaml – Path-based Routing

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: capstone-ingress
  namespace: capstone
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
    - host: capstone.local
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: backend-api-svc
                port:
                  number: 80
          - path: /
            pathType: Prefix
            backend:
              service:
                name: frontend-svc
                port:
                  number: 80

6. Step 4 – Prometheus Monitoring with ServiceMonitor

If you cannot see what your application is doing, you are flying blind. If you installed Prometheus using the popular open-source kube-prometheus-stack Helm chart, you can tell Prometheus to automatically discover and scrape your Backend API using a ServiceMonitor.

k8s/servicemonitor.yaml – Automatic Metric Scraping

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: backend-api-monitor
  namespace: capstone
  labels:
    release: prometheus
spec:
  selector:
    matchLabels:
      app: backend-api
  endpoints:
    - port: http
      path: /metrics
      interval: 15s
Pro Tip: Every 15 seconds, Prometheus will hit /metrics on your API pods to collect request latency, error rates (HTTP 500s), and memory usage. You can plug this directly into Grafana for a live portfolio dashboard.

7. Step 5 – GitOps Automation with Argo CD

This is where the magic happens. Instead of manually applying the files above, we give Argo CD one single Application manifest. It tells Argo CD where our Git repo lives and turns on prune and selfHeal.

argocd/capstone-app.yaml – Connecting Git to Kubernetes

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: capstone-stack
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/your-username/gitops-capstone.git
    targetRevision: main
    path: k8s
  destination:
    server: https://kubernetes.default.svc
    namespace: capstone
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Apply the Argo CD Application once

kubectl apply -f argocd/capstone-app.yaml
kubectl get applications -n argocd

Expected output

NAME             SYNC STATUS   HEALTH STATUS
capstone-stack   Synced        Healthy

8. Step-by-Step GitOps Execution Breakdown

Once Argo CD is running, here is exactly what happens every time you update your application.

Step 1: You update the image tag in k8s/api-deploy.yaml from 1.0.0 to 1.0.1 and push the commit to GitHub.
Step 2: Argo CD detects that the live cluster no longer matches the Git repository and marks the app as OutOfSync.
Step 3: Because automated sync is enabled, Argo CD pulls the updated YAML and triggers a zero-downtime rolling update of the Backend API pods.
Step 4: If someone manually deletes a Service or changes a replica count with kubectl, selfHeal: true immediately reverts the cluster back to the exact state defined in Git.
Step 5: Prometheus automatically discovers the new pods and begins scraping their metrics without any manual reconfiguration.

9. Hands-On Practice

Take this capstone further and test your GitOps skills with these three portfolio challenges.

Beginner Exercise 1: Test Argo CD Self-Healing

Manually delete the backend-api-svc service using kubectl delete svc backend-api-svc -n capstone and watch what happens.

Hint: Run kubectl get svc -n capstone -w to watch Argo CD recreate the deleted service automatically within seconds.

Intermediate Exercise 2: Verify Persistent Storage

Insert a test row into your PostgreSQL database, then delete the PostgreSQL pod using kubectl delete pod.

Expected result: Once Kubernetes starts a fresh PostgreSQL pod, connect to it and confirm your test row is still there because it lives on the PVC.

Advanced Exercise 3: Add Horizontal Pod Autoscaling (HPA)

Create an hpa.yaml file inside your k8s/ folder that scales backend-api from 2 to 6 replicas when CPU usage crosses 70%, then push it to Git.

Hint: Do not run kubectl apply. Let Argo CD detect the new file in Git and deploy the HPA automatically.

10. Interview Questions

Putting a GitOps capstone on your resume will immediately catch an interviewer's eye. Be ready to answer these common questions clearly.

Q1. What is the difference between traditional CI/CD push deployments and GitOps pull deployments?

Answer: In a push model, your CI server (like Jenkins or GitHub Actions) holds admin credentials to your Kubernetes cluster and pushes changes in. In a GitOps pull model (like Argo CD), the agent lives inside the cluster and pulls changes from Git. This is more secure because cluster credentials never leave the cluster, and it allows continuous drift detection.

Q2. What do prune and selfHeal do in Argo CD?

Answer: prune: true deletes resources from Kubernetes when their YAML files are deleted from Git, preventing orphan resources. selfHeal: true automatically reverts any manual changes made directly to the cluster so that Git always remains the single source of truth.

Q3. Why do we use an Ingress instead of a LoadBalancer Service for every microservice?

Answer: Every LoadBalancer Service provisions a separate cloud load balancer with its own public IP, which gets expensive quickly. A single Ingress controller uses one load balancer and routes traffic to dozens of internal services using hostnames and URL paths, while also centralizing SSL/TLS certificates.

Conclusion

You have just designed and wired together a complete, production-grade Kubernetes stack. By combining multi-tier services, Ingress routing, persistent storage, Prometheus observability, and Argo CD GitOps, you now have a repeatable blueprint that mirrors how modern engineering teams ship software.

Push your code to GitHub, document your architecture diagram in your README, and share your setup with the community on Upgradix by Shrash Studio to help fellow developers level up their DevOps skills.

Official Documentation

Upgradix by Shrash Studio – Learn Technology. Build Your Future.

Comments & Ratings (0)

Log in or create a student account to comment and rate this article.

Be the first to comment on this article.