8.2 KiB
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) mainargocd-prdvalues/prd/Staging (stg) + Dev (dev) developargocd-devvalues/dev/Integration (int) pre-prodargocd-shared-intvalues/int/Per AI Blitz Plan §4.2 + §5.2. 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
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.
# 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
values/<env>/incubator-infra-<gke-cluster-name>-values.yaml
Example: values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml
Incubator file filename
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:
<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 → Skill: skills/infra/add-tool.md
Upgrade a chart version
→ See docs/platform/procedures/upgrade-chart-version.md → Skill: skills/infra/upgrade-chart-version.md
Onboard a new cluster
→ See docs/platform/procedures/add-new-cluster.md → Skill: skills/infra/onboard-cluster.md
Remove a tool from a cluster
→ See docs/platform/procedures/deboard-tool-from-cluster.md → Skill: skills/infra/add-tool.md (covers removal)
Roll out a tool across all clusters
→ See docs/platform/procedures/fleet-wide-tool-rollout.md → Skill: skills/infra/fleet-wide-rollout.md
Debug ArgoCD sync failure
→ See docs/platform/runbooks/argocd-sync-failure.md
Debug Helm render failure
→ See 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
Key reference docs
| Document | Purpose |
|---|---|
| docs/global/AGENT_BOUNDARIES.md | Complete Layer 1/2/3 operation map with blast radii |
| docs/global/SANCTITY_RULES.md | R1–R12 non-negotiable rules |
| docs/global/escalation-matrix.md | When to page a human |
| docs/global/coding-guidelines/infra-argo.md | YAML authoring conventions (combined reference) |
| docs/global/coding-guidelines/argocd.md | ArgoCD Application manifest conventions (incubator files) |
| docs/global/coding-guidelines/helm.md | Helm values file conventions (clusterSpec, teamSpec, appSpec) |
| docs/platform/schemas/values-file-schema.md | appSpec field reference |
| docs/platform/schemas/incubator-values-schema.md | Incubator Application YAML reference |
| index.md | Full doc tree navigation |
| wiki/entities/DevOps Infra ArgoCD Config.md | Architecture + scale overview |