6.2 KiB
6.2 KiB
Documentation Index — devops-infra-argo-config
Navigation guide for agents and humans working in this repository.
Layout
devops-infra-argo-config/
├── CLAUDE.md ← Agent entry point (read first)
├── index.md ← This file
├── repository.yaml ← Ownership metadata (automation-owned, do not hand-edit)
│
├── docs/
│ ├── global/
│ │ ├── SANCTITY_RULES.md ← Non-negotiable rules R1–R12
│ │ ├── AGENT_BOUNDARIES.md ← Layer 1-T map, blast radii, what agents may/may not touch
│ │ ├── escalation-matrix.md ← When to page a human and who to contact
│ │ └── coding-guidelines/
│ │ ├── infra-argo.md ← Combined YAML authoring conventions (values files + appSpec)
│ │ ├── argocd.md ← ArgoCD Application manifest conventions (incubator files)
│ │ └── helm.md ← Helm values file conventions (clusterSpec, teamSpec, appSpec)
│ │
│ ├── platform/
│ │ ├── procedures/
│ │ │ ├── add-tool-to-cluster.md ← Add, update, or remove an appSpec entry
│ │ │ ├── add-new-cluster.md ← Onboard a new cluster (incubator + values files)
│ │ │ ├── upgrade-chart-version.md ← Change chartDir for one or many clusters
│ │ │ ├── deboard-tool-from-cluster.md ← Safely remove a tool from a cluster
│ │ │ └── fleet-wide-tool-rollout.md ← Add a tool to multiple clusters in one PR
│ │ │
│ │ ├── runbooks/
│ │ │ ├── argocd-sync-failure.md ← Sync failure decision tree
│ │ │ ├── render-failure.md ← Helm render errors (ComparisonError)
│ │ │ ├── values-drift.md ← Detect and fix inconsistencies across cluster values files
│ │ │ └── deployment-stuck.md ← Pod pending/crashloop after sync
│ │ │
│ │ └── schemas/
│ │ ├── values-file-schema.md ← Annotated appSpec schema — every field explained
│ │ └── incubator-values-schema.md ← Incubator Application YAML field reference
│ │
│ └── golden-prs.md ← Golden PRs for benchmark suite (generated)
│
├── skills/
│ └── infra/
│ ├── add-tool.md ← Agent skill: add tool to cluster
│ ├── upgrade-chart-version.md ← Agent skill: bump chartDir version
│ ├── fleet-wide-rollout.md ← Agent skill: roll out a tool across many clusters
│ └── onboard-cluster.md ← Agent skill: onboard a new cluster
│
├── wiki/
│ ├── entities/
│ │ └── DevOps Infra ArgoCD Config.md ← Wiki entity page
│ └── analyses/
│ ├── ADR-I1-generic-chart-per-cluster.md ← ADR: why one generic Helm chart
│ └── ADR-I2-incubator-pattern.md ← ADR: why the incubator + App-of-Apps pattern
│
├── generic-argo-apps-chart/ ← Helm chart: renders child Applications from appSpec
├── incubator/<env>/ ← Parent ArgoCD Application per cluster
├── values/<env>/ ← appSpec lists defining which tools deploy per cluster
├── projects/ ← ArgoCD AppProject definitions (sre, sec)
├── external-name-service-incubator/ ← Cross-cluster DNS routing Application manifests
├── external-name-service-template/ ← Helm chart for ExternalName services
└── external-name-service-values/ ← MCS topology values per zone
Quick navigation
For agents
- Read CLAUDE.md — repo role, naming conventions, forbidden actions, validation commands.
- Read docs/global/AGENT_BOUNDARIES.md — what you may and may not touch.
- Read docs/global/SANCTITY_RULES.md — non-negotiable rules.
For human PR reviewers
- Skim docs/global/coding-guidelines/infra-argo.md — YAML conventions.
- Check docs/platform/schemas/values-file-schema.md — appSpec field reference.
By task
| I want to... | Read this |
|---|---|
| Add a tool to a cluster | docs/platform/procedures/add-tool-to-cluster.md |
| Upgrade a chart version | docs/platform/procedures/upgrade-chart-version.md |
| Deboard a tool from a cluster | docs/platform/procedures/deboard-tool-from-cluster.md |
| Roll out a tool across all clusters | docs/platform/procedures/fleet-wide-tool-rollout.md |
| Onboard a new cluster | docs/platform/procedures/add-new-cluster.md |
| Debug a sync failure | docs/platform/runbooks/argocd-sync-failure.md |
| Debug a Helm render error | docs/platform/runbooks/render-failure.md |
| Find inconsistencies across clusters | docs/platform/runbooks/values-drift.md |
| Debug a stuck deployment | docs/platform/runbooks/deployment-stuck.md |
| Understand when to escalate | docs/global/escalation-matrix.md |
| Understand why we use one generic chart | wiki/analyses/ADR-I1-generic-chart-per-cluster.md |
| Understand the incubator pattern | wiki/analyses/ADR-I2-incubator-pattern.md |
| See repo ownership and relationships | wiki/entities/DevOps Infra ArgoCD Config.md |