gitops

Argo CD config for the self-service GitOps platform. If you haven't already, read the infra README first for the overall architecture (Terraform provisions the EKS cluster + IAM/Pod Identity, then installs Argo CD and points it at this repo). This README stays inside this repo: what lives where, and exactly how to add or change what's running on the cluster.

Layout

Path	What it's for
argocd/applications/	One Argo CD Application manifest per thing running on the cluster. This is the authoritative list of what's deployed — if it's not a file in here, Argo CD isn't managing it.
platform/	Shared, cluster-scoped platform resources that don't belong to any single app — currently the aws-secrets-manager ClusterSecretStore and the ExternalSecret for Grafana's admin credentials. Deployed by argocd/applications/platform.yaml.
values/	One <app>-values.yaml per Helm-based Application, referenced from argocd/applications/*.yaml via a second ref: values git source (the $values/values/...yaml path in helm.valueFiles).
apps/simple-social/	Leftover/unused scaffolding from an earlier approach (a ServiceMonitor/ExternalSecret template dir). Not referenced by any current Application — kept for history, not a pattern to copy. See Where simple-social's manifests actually live.

Argo CD only ever reads this repo — there's no build step, CI, or state file here. The root Application created by infra's addons/ module watches argocd/applications/, so anything added there gets created and synced automatically (app-of-apps).

Currently deployed applications

Application file	Deploys	Namespace	Source pattern
argocd.yaml	Argo CD itself (self-managed from here on)	argocd	Helm chart + ref: values
alb-controller.yaml	AWS Load Balancer Controller	kube-system	Helm chart + ref: values
external-secrets.yaml	External Secrets Operator	external-secrets	Helm chart + ref: values
platform.yaml	This repo's platform/ dir: ClusterSecretStore + Grafana ExternalSecret	external-secrets	Plain manifests from this repo
prometheus-stack.yaml	kube-prometheus-stack (Prometheus, Alertmanager, Grafana)	monitoring	Helm chart + ref: values
simple-social.yaml	Example workload (a separate FastAPI portfolio app), deployed to prove the platform works end to end	simple-social	Kustomize overlay, from the app's own repo

Adding a new application

1. Add argocd/applications/<name>.yaml. File name and metadata.name should match the app/component name. Every manifest here follows the same shape:

   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: <name>
     namespace: argocd
     finalizers:
       - resources-finalizer.argocd.argoproj.io   # cascades delete on removal
   spec:
     project: default
     destination:
       server: https://kubernetes.default.svc
       namespace: <target-namespace>
     syncPolicy:
       automated:
         prune: true
         selfHeal: true
         enabled: true
       syncOptions:
         - CreateNamespace=true   # if the namespace doesn't already exist

   Two source patterns are used in this repo, pick whichever fits:
   • Single source, pointing at the app's own repo — plain manifests, a Kustomize overlay (kustomize: {}), or a Helm chart. See simple-social.yaml.
   • Two sources, for a public Helm chart — sources[0] is the chart itself (repoURL/chart/targetRevision + helm.valueFiles: ["$values/values/<name>-values.yaml"]), sources[1] is this repo pinned via ref: values so the $values alias in sources[0] resolves. See alb-controller.yaml, external-secrets.yaml, or prometheus-stack.yaml.
2. Add the values file, if it's a Helm chart: values/<name>-values.yaml.
3. Add a ServiceMonitor, if the app exposes metrics. Don't add it here — put it in the app's own repo, alongside its Kubernetes manifests/overlay (see below). The Prometheus stack is configured with serviceMonitorSelectorNilUsesHelmValues: false, so it discovers ServiceMonitor objects across every namespace with no extra wiring needed on this side. Make sure to add level in metadata

 metadata:
   labels:
     release: kube-prometheus-stack 

This labels is used by the Prometheus Operator to discover and select monitoring resources like ServiceMonitor and PodMonitor objects. If this label does not match the Helm release name, Prometheus will ignore those endpoints and fail to scrape metrics.

4. Add a SecretStore + ExternalSecret, if the app needs secrets. Same as ServiceMonitors: define both in the app's own repo, alongside its Kubernetes manifests/overlay. Each app owns its own namespace-scoped SecretStore pointing directly at AWS Secrets Manager/SSM — apps are self-contained and don't reference a shared store. Only touch platform/ in this repo for genuinely cluster-scoped secrets shared across every app (like the Grafana admin credentials).
5. Commit and push. Argo CD's app-of-apps sync (from the root Application created by infra) picks up the new file and creates/syncs it — there's no manual argocd app create step.

Where simple-social's manifests actually live

argocd/applications/simple-social.yaml is a single-source Application that points straight at the app's own repo:

```yaml spec: source: repoURL: https://github.com/Ishihab/simple-social.git targetRevision: main path: k8s/overlays/dev kustomize: {} destination: namespace: simple-social ```

Its Deployment/Service/Ingress, SecretStore (pointing at AWS Secrets Manager/SSM), ExternalSecret (for the DB password), and ServiceMonitor are all listed as resources in that k8s/overlays/dev Kustomize overlay, inside the simple-social repo itself — not in this repo. When Argo CD syncs this Application, it applies everything in that overlay as one unit, secret store included. apps/simple-social/templates/externalsecret.yaml in this repo predates that setup and isn't wired into any Application; treat it as dead scaffolding rather than the current pattern.