182 lines
8.2 KiB
Markdown
182 lines
8.2 KiB
Markdown
# 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 |
|