devops-infra-helm-charts-gcp/CLAUDE.md

# CLAUDE.md — `devops-infra-helm-charts`
# Auto-generated by /meesho-init. Edit freely — re-running suggests improvements, not overwrites.

> Agent entry point for Meesho's infrastructure Helm values + cached/forked charts repo.
>
> **Repo role:** GitOps source-of-truth for *what* infrastructure tooling runs on Meesho's GKE fleet, *where*, and *with what values*. Sister repo `devops-infra-argo-config` is the routing layer — it holds the Argo CD `Application` / `ApplicationSet` manifests that point at paths in this repo. A merge to `main` is a deploy event: Argo CD on each cluster reconciles from `main`.
>
> **Layer:** **Layer 1 — Agent-Writable** (config repo). Generate diffs, open PRs, do **not** apply directly. The default safety property is reviewer discipline + the Argo CD Sync click on each cluster. The longer-term goal is tool-mediated edits via a `helm-values-tool`; until that exists, direct edits to `helm-overrides/<cluster>/<app>/custom-values.yaml` via PR are the supported path. Direct edits to `helm-templates/<chart>/` are gated — see NEVER DO.
>
> **Out of scope:** application/service code (lives in service repos), Argo CD Application manifests (sister repo `devops-infra-argo-config`), workload-cluster `kubectl apply` operations (incident response, not authoring).
>
> See [docs/architecture.md](docs/architecture.md) for the full deploy lifecycle, cluster fleet, chart inventory, hook details, and gotchas.

## NEVER DO

- **NEVER** commit or push directly to `main`. Always work on a feature/fix branch and open a PR. A merge to `main` triggers Argo CD reconciliation against the live fleet.
- **NEVER** force push (`git push --force`). If absolutely required, use `--force-with-lease`.
- **NEVER** make requests to, curl, query, or interact with production endpoints: `int.meesho.int`, `prd.meesho.int`, `int.mrouter.int`, `prd.mrouter.int`, `*.meeshogcp.in`. These are production/pre-prod systems — any accidental call can affect live traffic or data.
- **NEVER** introduce backward-incompatible changes to chart `values.yaml` keys, image tags pinned in overrides, or `fullnameOverride` strings without explicit user approval. Argo CD will silently reconcile the change across every cluster that consumes the chart, and live releases (Service DNS, PVC binding) depend on the existing names.
- **NEVER** commit secrets in any form. The TruffleHog pre-commit hook is the last line of defense — **NEVER bypass it** with `--no-verify`, `git commit -n`, or by removing the hook. Real secrets belong in `external-secrets` (per-cluster) backed by GCP Secret Manager / Vault, not in `custom-values.yaml`.
- **NEVER** copy a `custom-values.yaml` from one cluster directory to another without rewriting `nodeSelector`, `tolerations`, and any `computeClass` references. Each cluster has a bespoke node-pool topology — see `contour-nodeselector-tolerations-summary.md`. GKE Autopilot clusters (`k8s-central-prd-ase1`, `k8s-dsgpu-prd-ase1`, `k8s-shared-int-ase1`) use `cloud.google.com/compute-class:` keys; standard clusters use `dedicated:` keys. Wrong values strand pods on wrong nodes or leave them pending.
- **NEVER** edit files under `helm-templates/<chart>/templates/` or `values.yaml` casually. Most are vanilla upstream charts pulled via `helm pull`. Edits silently fork the chart and get clobbered on the next upstream sync. If a fork is intentional, document the reason in that chart's `README.md` and call it out in the PR.
- **NEVER** delete a `<chart>` / `<chart>-<variant>` sibling without confirming no Argo Application in `devops-infra-argo-config` still references it. Versioned siblings (`argo-cd-green`, `contour-v1.33.3`, `keda-2.17.1`, `opentelemetry-collector-latest`, `sonarqube-old`, `victoria-metrics-cluster-latest`, etc.) exist to support in-flight blue-green migrations — both versions may be live simultaneously.
- **NEVER** edit `manifests/storageclass/*.yaml` or `manifests/priorityclass/<cluster>/*.yaml` without a PR-level reviewer. These are cluster-wide singletons — a wrong StorageClass affects every PVC; a wrong PriorityClass changes scheduling priority for every pod that references it.
- **NEVER** bump a `Chart.yaml` `dependencies[].version` without (a) reading the upstream changelog for breaking template changes, (b) re-running `helm dependency update` to refresh `Chart.lock`, and (c) calling out the bump in the PR description.
- **NEVER** "normalize" values across clusters in the same PR as a feature change. Surgical edits only — touch the cluster × application that was asked, leave the rest. Cross-cluster cleanups belong in their own PR.
- **NEVER** change `fullnameOverride` values in any `custom-values.yaml`. They are load-bearing — Service DNS names, PVC bindings, ConfigMap references, and Argo Application names downstream depend on them being stable.
- **NEVER** treat Argo CD `Application` / `ApplicationSet` manifests as part of this repo. They live in the sister repo `github.com/Meesho/devops-infra-argo-config`. Changes to routing, sync policies, or Application paths are PRs against that repo, not this one.

## Repo at a glance

GitOps Helm values + cached/forked charts for Meesho's GKE infra fleet. Sister repo `devops-infra-argo-config` holds the Argo `Application` / `ApplicationSet` manifests that point at paths in this repo. **A merge to `main` is a deploy** — Argo CD on each cluster reconciles from `main`.

> See [docs/architecture.md](docs/architecture.md) for the full deploy lifecycle, cluster fleet, chart inventory, hook details, and gotchas.

## Repository layout

| Path | Purpose |
|------|---------|
| `helm-templates/<chart>/` | 74 cached/forked upstream charts (Argo CD, Contour, VictoriaMetrics, Grafana, Mimir, Loki, Tempo, Vault, Keda, Kyverno, Jenkins, JFrog, etc.). Some are thin wrappers (deps in `Chart.yaml`); some carry full vendored `templates/`. |
| `helm-overrides/<cluster>/<app>/custom-values.yaml` | Cluster × application Helm values overrides. Edited daily. |
| `helm-overrides/<cluster>/<app>/<extra>.yaml` | Raw manifests applied alongside the Helm release (e.g., `computeclass/*-cc.yaml`, `elastic-cluster/argo-launch.yaml`, `external-dns-services/*.yaml`). |
| `manifests/storageclass/`, `manifests/priorityclass/<cluster>/` | Cluster-wide singletons. High blast radius. |
| `manifests/{jenkins-filestore-caching,jenkins-gcs-caching,jfrog-filestore-data}/{dev,prd}/` | Per-env one-shot PV/PVC manifests. |
| `pre-commit-scripts/` | TruffleHog secret scan (active); CAC and Yaak hooks (no-op here, gated on paths this repo doesn't have). |
| `post-commit-scripts/` | Cursor AI commit metric collector (background, non-blocking). |
| `repository.yaml` | Owners (auto-managed). Primary: `siddharth.pal@meesho.com`. Secondary: `samarth.nag@meesho.com`. |
| `contour-nodeselector-tolerations-summary.md` | Per-cluster Contour scheduling matrix. **Read before editing any Contour values.** |

## Cluster naming

| Pattern | Meaning |
|---------|---------|
| `k8s-<bu>-prd-ase1[c]` | Standard GKE prod cluster, BU-owned. BUs: `central`, `central-mqkafka`, `supply`, `supply-dev`, `demand`, `dataengg`, `datascience`, `dengspark`, `dengspark-di`, `dengspark-notebook`, `dscispark`, `dsgpu`, `farmiso`, `ml-platform`, `admin`, `sec-admin`, `devops-admin`. All in `asia-southeast1`, fleet `meesho-admin-prd-0622`. |
| `k8s-shared-int-ase1` | Shared **integration** (pre-prod) cluster. Only non-prod cluster in the repo. |
| `k8s-aurva-prd-ase1` | Aurva integration. Minimal override set. |
| `db-<numeric-id>-...` | Auto-named dataplane/data-tier clusters. Minimal overrides (`kube-state-metrics`, `victoria-metrics-agent`). Use `fullnameOverride: <kind>-dbc-<bu>-prd`. |

## Editing workflow

1. Branch off `main`. Don't push to `main`.
2. Edit the **single** `helm-overrides/<cluster>/<app>/custom-values.yaml` (or `<app>/<extra>.yaml`) the task targets. Don't drive-by-edit other apps in the same dir.
3. If the change is per-cluster, mirror **only** if the user asked — and rewrite per-cluster scheduling fields (see NEVER DO).
4. `git commit` — TruffleHog runs automatically. If it blocks, fix the secret (don't bypass).
5. Open a PR. Reviewer checks blast radius. Merge to `main`.
6. Argo CD on the target cluster syncs (auto or manual sync, per the Application's `syncPolicy` in `devops-infra-argo-config`).

## Common patterns

- **Multi-Contour clusters** — `contour-external`, `contour-external-1`, `contour-internal-0`, `contour-internal-1`, `contour-internal-intra-{0,1}` are all separate Helm releases per cluster. Each has its own node pool / dedicated taint or compute class. Cross-reference `contour-nodeselector-tolerations-summary.md`.
- **Versioned chart siblings** — `argo-cd` ↔ `argo-cd-green`, `contour` ↔ `contour-v1.33.3`, `keda` ↔ `keda-2.17.1`, `opentelemetry-collector` ↔ `-latest`, `victoria-metrics-{cluster,agent}` ↔ `-latest`, `sonarqube` ↔ `sonarqube-old`. The variant is the upgrade target. Both can be live at once.
- **Image registry** — production overrides pin `asia-southeast1-docker.pkg.dev/meesho-devops-admin-0622/admin/sre/<image>` (Meesho's Artifact Registry mirror), not Docker Hub.
- **Secrets via External Secrets Operator** — most clusters have an `external-secrets/` override; secrets are sourced from GCP Secret Manager / Vault. Reference secret names; never paste secret values.

## Quick reference

This repo has no build, test, or lint commands. Everything is declarative YAML. Useful local commands:

| Task | Command |
|------|---------|
| Install pre-commit hooks (one-time) | `pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type post-commit` |
| Re-run pre-commit on staged changes | `pre-commit run` |
| Render a chart locally to inspect output | `helm template <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml` |
| Refresh subchart deps after `Chart.yaml` bump | `helm dependency update helm-templates/<chart>` |
| Diff a release against the rendered template | `helm diff upgrade <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml` (requires `helm-diff` plugin and kube context) |
| Lint a chart | `helm lint helm-templates/<chart>` |
| Find which clusters override a given app | `find helm-overrides -maxdepth 2 -type d -name '<app>'` |

## Layer constraint summary

| Operation | Layer | Agent action |
|-----------|-------|--------------|
| Edit `helm-overrides/<cluster>/<app>/custom-values.yaml` (single cluster × app) | **Layer 1** | Generate the diff, open a PR. Reviewer + Argo CD Sync click are the safety gates. |
| Add a new app override under an existing cluster | **Layer 1** | Same — pair with the matching `Application` PR in `devops-infra-argo-config`. |
| Add a new cluster directory under `helm-overrides/` | **Layer 1 (HIGH RISK)** | Open a PR; pair with the cluster's `ApplicationSet` change in the sister repo. Verify per-cluster `nodeSelector` / `tolerations` / `computeClass` are written from scratch, not copied. |
| Bump a `Chart.yaml` `dependencies[].version` in `helm-templates/<chart>/` | **Layer 1 (HIGH RISK)** | Read upstream changelog, run `helm dependency update`, refresh `Chart.lock`, call out the bump in the PR. |
| Edit `helm-templates/<chart>/templates/` or `values.yaml` | **Layer 1 (HIGH RISK)** | Most charts are vanilla upstream; an edit silently forks the chart and gets clobbered on the next sync. Only allowed if the fork is intentional and documented in that chart's `README.md`. |
| Delete a versioned sibling chart (`<chart>-green`, `-vX.Y.Z`, `-latest`, `-old`) | **Layer 1 (HIGH RISK)** | Confirm no Argo Application in `devops-infra-argo-config` still references it. |
| Edit `manifests/storageclass/*.yaml` or `manifests/priorityclass/<cluster>/*.yaml` | **Layer 1 (HIGH RISK)** | Cluster-wide singleton; affects every PVC / scheduling priority. Requires platform-team review. |
| Run `helm install` / `helm upgrade` against a live cluster | **Out of scope** | This is GitOps; in-cluster mutation is incident response, not authoring. Use Argo CD UI Sync. |
| Run `kubectl apply -f` against a workload cluster | **Out of scope** | Drift will reappear on next reconciliation. |
| Hand-edit `repository.yaml` | **Layer 3** | Owned by `registry-bootstrap` automation. Refuse + redirect upstream. |
| Edit Argo `Application` / `ApplicationSet` manifests | **Out of scope (sister repo)** | These live in `github.com/Meesho/devops-infra-argo-config`. Open the PR there. |
| Recommend a curl/probe against `int.meesho.int`, `prd.meesho.int`, `*.mrouter.int`, or workload `*.meeshogcp.in` services | **Layer 3** | Production traffic surfaces — refuse. (Pre-commit hook telemetry to `observe.meeshogcp.in` is automated infrastructure, not agent-initiated.) |

<!-- meesho-init: generated-at=2026-05-05T17:31:45Z base-sha=debd20fcc510e19bfe3123a08247dde39790643b+dirty -->