Infrastructure Overview¶
How co2-calculator is deployed on EPFL OpenShift and which parts live
where. Every statement here is backed by the private GitOps repository
(openshift-app-config/epfl/co2-calculator). When the two disagree, the
GitOps repo wins and this page needs a fix in the same PR. For what to do
when something breaks, go to Operations.
Environments¶
| Env | URL | Namespace | Cluster | Git branch |
|---|---|---|---|---|
| dev | co2-calculator-dev.epfl.ch |
svc1751d-co2-calculator-dev |
ocpitsd0001 |
dev |
| stage | co2-calculator-stage.epfl.ch |
svc1751t-co2-calculator-stage |
ocpitst0001 |
stage |
| prod | co2-calculator.epfl.ch |
svc1751p-co2-calculator-prod |
ocpitsp0001 |
main |
Each cluster has its own OpenShift console, ArgoCD and Grafana. All three
apps sit behind OpenShift Routes with TLS edge termination, labelled
route: private: reachable from the EPFL network or VPN only. The Route
uses the cluster's *.epfl.ch wildcard certificate; no certificate is
managed in our repos. Routing: / → frontend, /api → backend,
/docs → this site. The backend route carries a 10-minute HAProxy timeout
for SSE streams and long exports.
What runs in a namespace¶
- Frontend: nginx serving the Quasar SPA. 2 to 3 pods (HPA on CPU),
PodDisruptionBudget. Health:
/healthz,/ready. - Backend: FastAPI + Uvicorn, 3 pods on dev and stage, 2 to 3 on prod
(HPA), plus worker pods (one on dev, two on stage and prod) running
the same image with
OTEL_SERVICE_NAME=workerfor background jobs. No Redis, no broker: jobs are claimed in PostgreSQL (ADR-010, ADR-015). Health:/api/healthz(liveness, always 200) and/api/health/deps(database and role provider, 503 on failure). - Docs: this Zensical site, 1 pod.
- Migration Job:
alembic upgrade head, a Helmpre-upgradehook, so a failed migration blocks the rollout. - OTel Collector: receives OTLP from backend and worker. Metrics go to
the cluster Prometheus through a
ServiceMonitor; traces go to Tempo throughenac-it-otel. The collector adds theroute_classlabel, see Observability & SLOs. - db-dump CronJob:
pg_dumpdaily at 02:00 into thedb-dumpsPVC, the only PVC in the namespace. - Monitoring CRs:
PrometheusRule,AlertmanagerConfig(email to the sysadmins group), Grafana dashboards.
Outside the namespace: PostgreSQL (EPFL DBaaS), S3 object storage, Entra ID, EPFL's OPDo Elasticsearch (audit records, ISO 27701, see plan 240), Tempo, Icinga, GlitchTip, Matomo. What each is for and how to get access: Tools and access.
How a change gets deployed¶
- CI builds the images into Quay (
quay-its.epfl.ch/svc1751) and publishes the Helm chart fromhelm/toghcr.io: GitHub Actions forstageand release tags, gitlab.epfl.ch fordev(CI/CD Workflows, plan 2909). - A bot commit bumps the image tag in the GitOps overlay
(
chore(manifest): update epfl/co2-calculator (<env>)). - ArgoCD on that cluster auto-syncs and self-heals the
co2-calculator-<env>application fromoverlays/<env>.
Per-environment values are valuesInline in the overlay's
kustomization.yaml; the chart itself is versioned and pinned there.
Rolling back is reverting the GitOps commit. The dev → stage → main
promotion is in the Release runbook.
Configuration and secrets¶
Non-secret configuration is env vars in the overlay: APP_* for the
frontend, injected at container start by the image entrypoint, backend
settings by name. Secrets come from Infisical through the External
Secrets Operator in all three environments: one ExternalSecret pulls
every key under /epfl/co2-calculator into backend-secret, and separate
ones feed db-secret, quay-reg-cred and docker-reg-cred. Refresh
interval is 5 minutes; a changed value reaches the pods on the next
rollout restart. No secret is created by hand anymore. The key names
the backend reads are declared in backend/app/core/config.py; list what
is actually mounted with:
oc get secret backend-secret -n <namespace> -o json | jq '.data | keys'
Because of the wildcard, keys that only CI needs (release-please and Codecov tokens, registry credentials) are mounted into the pods too. Trim the Infisical folder, not this page.
Backups and restore¶
- Database: the nightly dump above, plus DSI's own backups and point-in-time recovery under the EPFL PostgreSQL SLA. Restore procedure, one-shot script and tools pod: private ops README. Last real restore: 2026-09-08 post-mortem.
- Files: S3 buckets are not versioned, by decision (Recovery objectives). A lost CSV is re-uploaded.
- Everything else: the Disaster Recovery Plan (private).
See also¶
- Deployment Topology, Environments, Tech Stack, Scalability
- CI/CD Pipeline and CI/CD Workflows
- Observability & SLOs, Frontend Error Monitoring, OAuth http-callback post-mortem
- Vendor docs: Kubernetes, Helm, ArgoCD, Prometheus
Not here, on purpose¶
No Jaeger (removed 2026-06-17, traces live in Tempo), no Loki, no Elasticsearch or Kibana for logs (the only Elasticsearch is EPFL's OPDo audit sink above), no service mesh, no in-cluster PostgreSQL. If you read otherwise elsewhere in these docs, that page is stale: fix it.