# CLAUDE.md — `devops-infra-argo-config`

> **Layer 1-T (Tool-Mediated GitOps).** This repo is the ArgoCD control plane for infrastructure tooling across Meesho's Kubernetes fleet. Agent generates diffs and opens PRs. **Merge to the env branch is an immediate deploy — auto-sync has no staging gate.**
>
> | Environment | Branch | ArgoCD namespace | Values dir |
> | ----------- | ------ | ---------------- | ---------- |
> | Production (prd) | `main` | `argocd-prd` | `values/prd/` |
> | Staging (stg) + Dev (dev) | `develop` | `argocd-dev` | `values/dev/` |
> | Integration (int) | `pre-prod` | `argocd-shared-int` | `values/int/` |
>
> Per [AI Blitz Plan §4.2 + §5.2](docs/global/AGENT_BOUNDARIES.md). Layer: **1-T**.

---

## What this repo controls

`devops-infra-argo-config` is the **GitOps source of truth** for every ArgoCD `Application` that deploys **infrastructure tooling** (Contour, VictoriaMetrics, Grafana, Kyverno, KEDA, external-secrets, Vault, etc.) across ~19 Kubernetes clusters.

It does **not** manage service/application workloads — that's `devops-argo-config`.

### App-of-Applications pattern

```text
incubator/<env>/<cluster>.yaml          ← Parent Application (one per cluster, in ArgoCD)
    └── points at generic-argo-apps-chart/ + values/<env>/<cluster>-values.yaml
            └── renders one child Application per appSpec[] entry
                    └── each child sources charts + overrides from devops-infra-helm-charts
```

### Key directories

| Directory | Purpose |
| --------- | ------- |
| `incubator/<env>/` | Parent ArgoCD Application YAML, one per cluster |
| `values/<env>/` | Values files: `clusterSpec`, `teamSpec`, `argocdSpec`, `appSpec[]` |
| `generic-argo-apps-chart/` | Helm chart that renders child Applications from `appSpec` |
| `projects/` | ArgoCD `AppProject` definitions (`sre`, `sec`) |
| `external-name-service-*/` | Cross-cluster DNS routing (ExternalName / MCS topology) |

---

## Build / test / run / validate

There is no build step. Validation is done via Helm dry-run and pre-commit hooks.

```bash
# Render a values file through the generic chart (dry-run):
helm template generic-argo-apps-chart/ -f values/prd/<cluster>-values.yaml

# Lint a values file:
yamllint values/prd/<cluster>-values.yaml

# Run all pre-commit hooks:
pre-commit run --all-files

# Check which clusters have a specific tool:
grep -rl 'name: <tool>' values/
```

**Never use `--no-verify`** to skip pre-commit hooks. The hooks are: TruffleHog (secrets scan), CAC validate, Yaak.

---

## Naming conventions

### Values file filename

```text
values/<env>/incubator-infra-<gke-cluster-name>-values.yaml
```

Example: `values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml`

### Incubator file filename

```text
incubator/<env>/incubator-infra-<gke-cluster-name>.yaml
```

The incubator filename (without `.yaml`) must equal `metadata.name` of the ArgoCD Application inside it.

### appSpec `name` field

Short, lowercase, hyphen-separated tool identifier. Used in generated Application name:

```text
<name>-<mungedCluster>-<env>
```

**Cluster munging rules** (strips environment/region noise):
- Strip: `k8s-`, `prd-`, `int-`, `dev-`, `-ase1`
- Replace: `-ase1c` → `-c`
- Example: `k8s-central-prd-ase1` → `central-prd`

Result: `keda` on `k8s-central-prd-ase1` → Application name `keda-central-prd`.

### `namespace` convention

| Pattern | When |
| ------- | ---- |
| `<tool>-<mungedCluster>` | Default (e.g., `keda-central-prd`) |
| Shared namespace | Multi-component tools (e.g., `victoriametrics` for all VM stack apps) |
| `<tool>-role-<cluster>` | Multi-instance (e.g., `contour-internal-0-central-prd`) |

---

## Common tasks

### Add a tool to a cluster
→ See [docs/platform/procedures/add-tool-to-cluster.md](docs/platform/procedures/add-tool-to-cluster.md)
→ Skill: [skills/infra/add-tool.md](skills/infra/add-tool.md)

### Upgrade a chart version
→ See [docs/platform/procedures/upgrade-chart-version.md](docs/platform/procedures/upgrade-chart-version.md)
→ Skill: [skills/infra/upgrade-chart-version.md](skills/infra/upgrade-chart-version.md)

### Onboard a new cluster
→ See [docs/platform/procedures/add-new-cluster.md](docs/platform/procedures/add-new-cluster.md)
→ Skill: [skills/infra/onboard-cluster.md](skills/infra/onboard-cluster.md)

### Remove a tool from a cluster
→ See [docs/platform/procedures/deboard-tool-from-cluster.md](docs/platform/procedures/deboard-tool-from-cluster.md)
→ Skill: [skills/infra/add-tool.md](skills/infra/add-tool.md) (covers removal)

### Roll out a tool across all clusters
→ See [docs/platform/procedures/fleet-wide-tool-rollout.md](docs/platform/procedures/fleet-wide-tool-rollout.md)
→ Skill: [skills/infra/fleet-wide-rollout.md](skills/infra/fleet-wide-rollout.md)

### Debug ArgoCD sync failure
→ See [docs/platform/runbooks/argocd-sync-failure.md](docs/platform/runbooks/argocd-sync-failure.md)

### Debug Helm render failure
→ See [docs/platform/runbooks/render-failure.md](docs/platform/runbooks/render-failure.md)

---

## Forbidden actions

These are hard stops — not warnings. Attempting them will be blocked by hooks, branch protection, or agent halt.

| Action | Why forbidden | Rule |
| ------ | ------------- | ---- |
| Edit `repository.yaml` | Owned by `registry-bootstrap` automation | R5 |
| Push directly to `main`, `develop`, or `pre-prod` | Auto-sync = immediate deploy to that env; branch protection enforced | R1, R11 |
| Run `argocd app sync` / `kubectl apply` | Out of scope; this repo is GitOps-only | AGENT_BOUNDARIES.md Layer 3 |
| Delete an incubator file without confirming cluster is decommissioned | Orphans tooling fleet-wide | AGENT_BOUNDARIES.md Layer 3 |
| Use `--no-verify` to skip pre-commit hooks | Bypasses TruffleHog; may commit secrets | R10 |
| Add secrets/credentials to YAML | TruffleHog blocks commit; accidental commit requires history purge | R6 |
| Add `nameOverride` without justification | Breaks naming consistency | R7 |
| Edit `generic-argo-apps-chart/` without platform-team sign-off | Template change breaks ALL clusters immediately | AGENT_BOUNDARIES.md Layer 1-T HIGH RISK |
| Modify `clusterSpec.destination.name` or `teamSpec.source.repoURL` | Redirects all tools to wrong cluster/repo | AGENT_BOUNDARIES.md Layer 1-T HIGH RISK |

---

## Layer constraint summary

| Layer | Applies to | Agent action |
| ----- | ---------- | ------------ |
| **Layer 1-T** | `appSpec` edits, new cluster onboarding, chart upgrades | Generate diff via tool or direct edit → open PR |
| **Layer 1-T HIGH RISK** | `generic-argo-apps-chart/` edits, `clusterSpec.destination`, `repoURL` changes | PR only, with explicit platform-team sign-off in body |
| **Layer 2** | ArgoCD sync commands, `argocd app diff` | Advisory only — suggest, do not execute |
| **Layer 3** | `repository.yaml`, `kubectl apply`, direct push to `main`/`develop`/`pre-prod`, incubator deletion | Hard stop — refuse and explain |

Full classification: [docs/global/AGENT_BOUNDARIES.md](docs/global/AGENT_BOUNDARIES.md)

---

## Key reference docs

| Document | Purpose |
| -------- | ------- |
| [docs/global/AGENT_BOUNDARIES.md](docs/global/AGENT_BOUNDARIES.md) | Complete Layer 1/2/3 operation map with blast radii |
| [docs/global/SANCTITY_RULES.md](docs/global/SANCTITY_RULES.md) | R1–R12 non-negotiable rules |
| [docs/global/escalation-matrix.md](docs/global/escalation-matrix.md) | When to page a human |
| [docs/global/coding-guidelines/infra-argo.md](docs/global/coding-guidelines/infra-argo.md) | YAML authoring conventions (combined reference) |
| [docs/global/coding-guidelines/argocd.md](docs/global/coding-guidelines/argocd.md) | ArgoCD Application manifest conventions (incubator files) |
| [docs/global/coding-guidelines/helm.md](docs/global/coding-guidelines/helm.md) | Helm values file conventions (clusterSpec, teamSpec, appSpec) |
| [docs/platform/schemas/values-file-schema.md](docs/platform/schemas/values-file-schema.md) | appSpec field reference |
| [docs/platform/schemas/incubator-values-schema.md](docs/platform/schemas/incubator-values-schema.md) | Incubator Application YAML reference |
| [index.md](index.md) | Full doc tree navigation |
| [wiki/entities/DevOps Infra ArgoCD Config.md](wiki/entities/DevOps%20Infra%20ArgoCD%20Config.md) | Architecture + scale overview |