100 lines
6.2 KiB
Markdown
100 lines
6.2 KiB
Markdown
# Documentation Index — `devops-infra-argo-config`
|
||
|
||
> Navigation guide for agents and humans working in this repository.
|
||
|
||
---
|
||
|
||
## Layout
|
||
|
||
```text
|
||
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
|
||
|
||
1. Read [CLAUDE.md](CLAUDE.md) — repo role, naming conventions, forbidden actions, validation commands.
|
||
2. Read [docs/global/AGENT_BOUNDARIES.md](docs/global/AGENT_BOUNDARIES.md) — what you may and may not touch.
|
||
3. Read [docs/global/SANCTITY_RULES.md](docs/global/SANCTITY_RULES.md) — non-negotiable rules.
|
||
|
||
### For human PR reviewers
|
||
|
||
1. Skim [docs/global/coding-guidelines/infra-argo.md](docs/global/coding-guidelines/infra-argo.md) — YAML conventions.
|
||
2. Check [docs/platform/schemas/values-file-schema.md](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](docs/platform/procedures/add-tool-to-cluster.md) |
|
||
| Upgrade a chart version | [docs/platform/procedures/upgrade-chart-version.md](docs/platform/procedures/upgrade-chart-version.md) |
|
||
| Deboard a tool from a cluster | [docs/platform/procedures/deboard-tool-from-cluster.md](docs/platform/procedures/deboard-tool-from-cluster.md) |
|
||
| Roll out a tool across all clusters | [docs/platform/procedures/fleet-wide-tool-rollout.md](docs/platform/procedures/fleet-wide-tool-rollout.md) |
|
||
| Onboard a new cluster | [docs/platform/procedures/add-new-cluster.md](docs/platform/procedures/add-new-cluster.md) |
|
||
| Debug a sync failure | [docs/platform/runbooks/argocd-sync-failure.md](docs/platform/runbooks/argocd-sync-failure.md) |
|
||
| Debug a Helm render error | [docs/platform/runbooks/render-failure.md](docs/platform/runbooks/render-failure.md) |
|
||
| Find inconsistencies across clusters | [docs/platform/runbooks/values-drift.md](docs/platform/runbooks/values-drift.md) |
|
||
| Debug a stuck deployment | [docs/platform/runbooks/deployment-stuck.md](docs/platform/runbooks/deployment-stuck.md) |
|
||
| Understand when to escalate | [docs/global/escalation-matrix.md](docs/global/escalation-matrix.md) |
|
||
| Understand why we use one generic chart | [wiki/analyses/ADR-I1-generic-chart-per-cluster.md](wiki/analyses/ADR-I1-generic-chart-per-cluster.md) |
|
||
| Understand the incubator pattern | [wiki/analyses/ADR-I2-incubator-pattern.md](wiki/analyses/ADR-I2-incubator-pattern.md) |
|
||
| See repo ownership and relationships | [wiki/entities/DevOps Infra ArgoCD Config.md](wiki/entities/DevOps%20Infra%20ArgoCD%20Config.md) |
|