KubeShop

KubeShop is a cloud-native, polyglot microservices e-commerce platform built to demonstrate an end-to-end DevSecOps workflow on AWS.

It combines:

• Infrastructure-as-Code (Terraform) provisioning of EKS and networking
• Containerized microservices (Docker) deployed to Kubernetes
• GitOps-style delivery (Argo CD) and CI automation (Jenkins)
• Observability (Prometheus + Grafana) and security scanning (Trivy)

If you want a runbook-style guide with copy/paste commands, use COMMANDS.md.

---

Table of Contents

• Architecture
• Project workflow
• Project goals
• Features
• Docs & references
• Screenshots
• Microservices
• Ingress routes (public endpoints)
• Repository layout
• Configuration and secrets
• Local development (Docker Compose)
• Deploy to AWS (EKS)
• CI/CD and GitOps
• Observability (Prometheus + Grafana)
• Load testing (Locust)
• Security
• Troubleshooting
• Contributing
• License

---

Architecture

KubeShop is exposed through a single public entrypoint: an NGINX Ingress Controller behind an AWS Load Balancer. The frontend is served at /, while APIs are exposed under /api/*.

flowchart LR
  user[User / Browser] -->|HTTPS| alb[AWS Load Balancer]
  alb --> ing[NGINX Ingress]

  subgraph eks[EKS Cluster]
    ing --> fe[frontend :3000]
    ing --> cat[catalog :8001]
    ing --> id[identity :8002]
    ing --> cart[cart :8003]
    ing --> ord[order :8004]
    ing --> ai[ai-recs :8005]
    ing --> graf[grafana :3000]

    cat --> mongo[(MongoDB)]
    id --> pg[(PostgreSQL)]
    cart --> redis[(Redis)]
    ord --> pg
    ai --> ord
  end

  subgraph delivery[Delivery]
    dev[Developer] -->|git push| repo[Git Repository]
    repo --> jenkins[Jenkins CI]
    jenkins -->|push images| ecr[AWS ECR]
    repo --> argo[Argo CD]
    argo -->|sync manifests| eks
  end

  subgraph obs[Observability]
    prom[Prometheus] --> graf
    fe -->|/metrics| prom
    cat -->|/metrics| prom
    id -->|/metrics| prom
    cart -->|/metrics| prom
    ord -->|/actuator/prometheus| prom
    ai -->|/metrics| prom
  end

Loading

Internal request flow (example)

This is the typical “place order” flow from the UI through the cluster:

sequenceDiagram
  participant U as User (browser)
  participant I as NGINX Ingress
  participant F as Frontend (Next.js)
  participant ID as Identity API
  participant C as Cart API
  participant O as Order API
  participant CA as Catalog API
  participant DB as PostgreSQL

  U->>I: GET /
  I->>F: route /
  F-->>U: HTML/JS

  U->>I: POST /api/auth/login
  I->>ID: route /api/auth
  ID-->>U: JWT

  U->>I: POST /api/cart/items
  I->>C: route /api/cart
  C-->>U: cart updated

  U->>I: POST /api/orders
  I->>O: route /api/orders
  O->>CA: GET catalog item details
  O->>DB: write order
  O-->>U: order confirmation

Loading

---

Project workflow

This repo is organized around a practical DevSecOps loop:

1. Code changes land in Git (app code, infra, and manifests)
2. CI runs tests and produces container images
3. Images are published to a registry (ECR)
4. GitOps applies manifest changes to EKS (Argo CD sync)
5. Metrics are scraped and visualized (Prometheus → Grafana)

---

Project goals

• Deploy a realistic polyglot microservices application on AWS EKS using Terraform + Kubernetes manifests.
• Practice core Kubernetes operational behaviors (restarts, rescheduling, replica management, readiness/liveness).
• Demonstrate DevSecOps fundamentals end-to-end: CI (Jenkins), GitOps (Argo CD), scanning (Trivy), observability (Prometheus/Grafana), and load testing (Locust).
• Keep credentials out of git and document safe defaults (see SECURITY.md).

---

Features

• Kubernetes-first deployment: services are deployable via manifests under k8s/.
• Single public entrypoint (Ingress): UI at /, APIs under /api/*, Grafana under /grafana.
• Observability: Prometheus scraping + Grafana dashboards via monitoring/.
• Load testing: Locust manifests under tests/locust/.
• Security scanning: Trivy config provided (see tests/security/trivy-config.yaml) and Makefile targets.
• Autoscaling demo: ai-recs includes an HPA example.

---

Docs & references

These are the official docs you’ll commonly use while working with this repo.

AWS / EKS

• Amazon EKS (main docs): https://docs.aws.amazon.com/eks/
• EKS getting started: https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html
• Load balancing on EKS (Service/Ingress concepts): https://docs.aws.amazon.com/eks/latest/userguide/load-balancing.html
• IAM Roles for Service Accounts (IRSA): https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html
• EBS CSI Driver (PVC provisioning): https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html

Kubernetes & tooling

• Kubernetes docs: https://kubernetes.io/docs/
• Ingress-NGINX docs: https://kubernetes.github.io/ingress-nginx/
• Terraform docs: https://developer.hashicorp.com/terraform/docs

CI/CD, GitOps, Observability, Security

• Jenkins docs: https://www.jenkins.io/doc/
• Argo CD docs: https://argo-cd.readthedocs.io/
• Prometheus docs: https://prometheus.io/docs/
• Grafana docs: https://grafana.com/docs/grafana/latest/
• Trivy docs: https://aquasecurity.github.io/trivy/
• Locust docs: https://docs.locust.io/

---

Screenshots

Jenkins (Pipeline / Stage View)	Argo CD (Application Dashboard)

---

Microservices

Service-to-service communication uses Kubernetes DNS (service names), and most user-facing APIs are routed through Ingress.

Service	Language	Purpose	Port	Dependencies
frontend	Next.js/TypeScript	UI and API client	3000	calls APIs via Ingress paths
catalog	Go	product listing/search	8001	MongoDB (MONGO_URI)
identity	Python	auth + JWT issuance	8002	PostgreSQL (DATABASE_URL)
cart	Node.js	cart operations	8003	Redis + Identity (service DNS)
order	Java (Spring Boot)	order creation/retrieval	8004	PostgreSQL + Catalog + Identity
ai-recs	Python	recommendations + HPA demo	8005	Order service

Notes:

• Many workloads include Prometheus scrape annotations.
• ai-recs ships with an HPA for autoscaling demonstrations.

---

Ingress routes (public endpoints)

Ingress rules are defined in k8s/ingress/ingress-rules.yaml.

Route	Destination service
/	frontend:3000
/api/products	catalog:8001
/api/search	catalog:8001
/api/auth	identity:8002
/api/cart	cart:8003
/api/orders	order:8004
/api/recommend	ai-recs:8005
/grafana	grafana:3000

---

Repository layout

app/                 Microservices source (polyglot)
k8s/                 Kubernetes manifests (services, databases, ingress)
infra/terraform/      Terraform for AWS EKS + networking
cicd/                 Jenkins + Argo CD manifests
monitoring/           Prometheus, Grafana, Loki (optional) manifests
tests/locust/         Load testing manifests + locustfile
scripts/              Helper scripts (deploy images, DB init)

---

Configuration and secrets

Kubernetes Deployments read connection strings and credentials from the kubeshop-secrets Secret referenced by multiple services.

Common keys referenced in manifests:

• mongo-uri (used by catalog)
• postgres-url (used by identity)
• postgres-jdbc-url, postgres-user, postgres-password (used by order)
• redis-url (used by cart)
• jwt-secret (used by identity)

Important:

• The repo includes demo defaults under k8s/secrets.yaml. Treat them as placeholders and rotate them for any real deployment.
• For production patterns (external secrets managers, sealed secrets), see SECURITY.md.

---

Local development (Docker Compose)

Prerequisites:

• Docker Desktop
• Make

Start the stack:

make up

Stop the stack:

make down

Open the UI:

• http://localhost:3000

For more local commands (logs, rebuilds, health checks), see COMMANDS.md.

---

Deploy to AWS (EKS)

High-level flow:

1. Provision AWS infrastructure with Terraform
2. Push service images to ECR
3. Deploy Kubernetes manifests (directly or via Argo CD)
4. Access the app via the Ingress Load Balancer

Prerequisites:

• AWS CLI configured (aws configure)
• Terraform
• kubectl
• (recommended) Helm

Provision infra:

cd infra/terraform
terraform init
terraform apply

Configure kubectl:

aws eks update-kubeconfig --name kubeshop-cluster --region us-east-1

Deploy app (GitOps entrypoint):

kubectl apply -f cicd/argocd/application.yaml

Find the public URL:

kubectl get svc -n ingress-nginx
kubectl get ingress -n default

Common AWS/EKS notes:

• Stateful workloads (MongoDB/PostgreSQL/Redis) require a working StorageClass and EBS CSI driver for PVC provisioning.
• This repo uses default namespace in many manifests; keep your resources consistent unless you refactor namespaces.

---

CI/CD and GitOps

GitOps (Argo CD)

Argo CD watches the repo and applies Kubernetes manifests to the cluster. In practice:

• You update manifests in k8s/ (image tags, replicas, resources, etc.)
• Argo CD syncs those changes into EKS

CI (Jenkins)

The Jenkins pipeline is defined in cicd/jenkins/Jenkinsfile and is intended to:

• Run tests for multiple services in parallel
• Run a security scan stage (placeholder in the current pipeline)
• Build and push images (implementation depends on your registry credentials)

Important: the pipeline contains placeholders (example registry, example credentials). You should update DOCKER_REGISTRY and credentials to match your AWS ECR setup.

flowchart LR
  A["Commit / PR"] --> B["Jenkins - tests"]
  B --> C["Security scan"]
  C --> D["Build images"]
  D --> E["Push to registry (ECR)"]
  E --> F["Update manifests (GitOps)"]
  F --> G["Argo CD sync"]
  G --> H["EKS rollout"]

Loading

---

Observability (Prometheus + Grafana)

Prometheus and Grafana manifests live under monitoring/.

• Prometheus service: prometheus:9090 (ClusterIP)
• Grafana service: grafana:3000 (ClusterIP)
• Grafana is also routed by Ingress at /grafana

Grafana defaults in this repo:

• Username: admin
• Password: admin

Recommended access methods:

• Via Ingress: http(s)://<ingress-host>/grafana
• Or port-forward:

kubectl port-forward svc/prometheus 9090:9090
kubectl port-forward svc/grafana 3000:3000

If 9090 is already used locally, change the local port (example: 9091:9090).

---

Load testing (Locust)

Locust manifests live under tests/locust/. The intent is to run load inside the cluster (no extra AWS Load Balancers required).

Typical usage:

kubectl apply -f tests/locust/locust-deploy.yaml
kubectl port-forward svc/locust 8089:8089

Then open:

• http://localhost:8089

---

Security

Security guidance, reporting, and scanning details are in SECURITY.md.

Highlights:

• Image scanning via Trivy (see tests/security/trivy-config.yaml)
• Kubernetes manifests include demo secrets; do not reuse them for real deployments
• CI pipeline includes a scan stage placeholder that you can wire to your Trivy configuration

---

Troubleshooting

These are the most common “first checks” when deploying to EKS:

• kubectl get pods -A and kubectl describe pod <pod> for ImagePullBackOff / CrashLoopBackOff
• kubectl get pvc -A for Pending volumes (usually StorageClass / CSI driver issues)
• kubectl get ingress -n default and kubectl describe ingress kubeshop-ingress -n default for routing issues
• kubectl logs deploy/<service> -n default --tail=200 for app errors

For a deeper runbook (including access patterns on Windows/PowerShell), use COMMANDS.md.

---

Contributing

Contributions are welcome.

• Guidelines and PR checklist: CONTRIBUTING.md
• Security expectations: SECURITY.md

---

License

This project is licensed under the GNU GPL v3.0. See LICENSE for details.