gitadmin/devops-infra-argo-config-gcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

added repo

Browse Source
This commit is contained in:
Your Name
2026-08-26 04:03:34 +05:30
parent 2389ec1fd6
commit 1055e1394f
150 changed files with 12395 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude/00-overview.md
+33
View File
@@ -0,0 +1,33 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 00 — Overview
`devops-infra-argo-config` is the **infrastructure GitOps control plane** for Meesho's Kubernetes fleet. It defines which infrastructure tools run on which clusters using ArgoCD's App-of-Applications pattern.
## Role in the ecosystem
```text
devops-infra-argo-config (this repo) devops-infra-helm-charts
├── incubator/<env>/<cluster>.yaml ─────────► helm-templates/<chartDir>/
├── values/<env>/<cluster>-values.yaml ─────► helm-overrides/<cluster>/<valuesDir>/
├── generic-argo-apps-chart/ │ └── custom-values.yaml
└── projects/ └── ...
```
This repo tells ArgoCD **what to deploy and where**. The helm-charts repo provides **how to deploy it** (charts + override values).
## Key characteristics
- **Layer 1-T** — Agent-Writable (Tool-Mediated). Changes are PRs reviewed by the platform team.
- **App-of-Applications pattern** — One parent Application per cluster renders all child tool Applications via a single generic Helm chart.
- **~19 clusters** managed across `prd`, `int`, and `admin` environments.
- **20–50 infrastructure tools** per cluster (monitoring, ingress, secrets, CI/CD, policy, etc.).
- **Auto-sync** — Merge to the env branch deploys immediately with no staging gate.
## Branch → environment mapping
| Branch | Environment | ArgoCD namespace | Values dir |
| ------ | ----------- | ---------------- | ---------- |
| `main` | Production (prd) | `argocd-prd` | `values/prd/` |
| `develop` | Staging (stg) + Dev (dev) | `argocd-dev` | `values/dev/` |
| `pre-prod` | Integration (int) | `argocd-shared-int` | `values/int/` |
claude/01-repo-structure.md
+54
View File
@@ -0,0 +1,54 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 01 — Repository Structure
```text
devops-infra-argo-config/
├── incubator/ # Parent ArgoCD Applications (one per cluster)
│ │ # Structure varies by branch:
│ │ # main: prd/ + admin/
│ │ # develop: infra/ + apps/ (stg+dev clusters)
│ │ # pre-prod: prd/ + admin/ (int values in values/int/)
│ ├── prd/ # Production clusters (main branch)
│ │ ├── incubator-infra-k8s-central-prd-ase1.yaml
│ │ ├── incubator-infra-k8s-demand-prd-ase1.yaml
│ │ └── ... # ~15+ prd clusters
│ └── admin/ # Admin clusters (k8s-admin-prd, k8s-devops-admin, k8s-sec-admin)
│ └── ...
├── values/ # Per-cluster tool lists
│ ├── prd/
│ │ ├── incubator-infra-k8s-central-prd-ase1-values.yaml
│ │ └── ... # Mirrors incubator/prd/ 1:1
│ ├── int/ # Integration clusters (pre-prod branch only)
│ │ └── incubator-infra-k8s-shared-int-ase1-values.yaml
│ ├── dev/ # Stg+dev clusters (develop branch) — dir is named "dev"
│ │ ├── incubator-infra-k8s-central-stg-ase1-values.yaml
│ │ ├── incubator-infra-k8s-central-dev-ase1-values.yaml
│ │ └── ... # Both stg and dev cluster values
│ └── admin/
├── generic-argo-apps-chart/ # Single Helm chart that renders child Applications
│ ├── Chart.yaml # meesho-generic-argo-apps-chart v0.1.0
│ └── templates/
│ └── genericTemplate.yaml # Iterates appSpec[] → Application CRDs
├── projects/ # ArgoCD AppProject definitions
│ ├── sre-project.yaml # sre project (all namespaces/clusters)
│ └── sec-project.yaml # sec project (security-scoped)
├── external-name-service-incubator/ # Cross-cluster DNS routing Applications
├── external-name-service-template/ # Helm chart for ExternalName services
├── external-name-service-values/ # MCS topology values per zone
├── pre-commit-scripts/ # Git hooks (TruffleHog, CAC validate, Yaak)
├── post-commit-scripts/ # Metrics hooks
└── repository.yaml # Repo metadata (automation-owned, DO NOT EDIT)
```
## Directory editability by layer
| Directory | Purpose | Agent editable? |
| --------- | ------- | --------------- |
| `incubator/<env>/` | Parent Application YAMLs | Layer 1-T (new clusters only) |
| `values/<env>/` | Per-cluster tool lists (`appSpec[]`) | Layer 1-T ✓ |
| `generic-argo-apps-chart/` | Helm chart template | Layer 1-T HIGH RISK |
| `projects/` | ArgoCD AppProject RBAC | Layer 2 (advisory) |
| `external-name-service-*/` | Cross-cluster DNS | Layer 1-T (manual) |
| `pre-commit-scripts/` | Git hooks | Layer 3 (blocked) |
| `repository.yaml` | Automation-owned metadata | Layer 3 (blocked) |
claude/02-app-of-apps-pattern.md
+46
View File
@@ -0,0 +1,46 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 02 — App-of-Applications Pattern
## The chain
```text
incubator/<env>/<cluster>.yaml ← Parent Application (managed by ArgoCD on admin cluster)
│
│ source: this repo / generic-argo-apps-chart/
│ valueFiles: ../values/<env>/<cluster>-values.yaml
▼
generic-argo-apps-chart/templates/genericTemplate.yaml
│
│ iterates appSpec[] array
▼
One child ArgoCD Application per appSpec entry
│
│ source: devops-infra-helm-charts / helm-templates/<chartDir>/
│ valueFiles: helm-overrides/<cluster>/<valuesDir>/custom-values.yaml
▼
Deployed tool on target cluster (Contour, Kyverno, VictoriaMetrics, etc.)
```
## How it works
1. **Incubator Application** lives on the admin cluster's ArgoCD. It points at `generic-argo-apps-chart/` in this repo, using the cluster's values file.
2. **Generic chart** (`genericTemplate.yaml`) iterates over `appSpec[]` and renders one full ArgoCD Application manifest per entry.
3. **Child Applications** appear in ArgoCD, each pointing at a specific chart + override values in `devops-infra-helm-charts`.
4. **Auto-sync** is enabled — ArgoCD syncs child Applications immediately when the parent renders new manifests.
## Adding a new tool
Add one entry to `appSpec[]` in the cluster's values file. The generic chart renders the Application on the next sync — no YAML boilerplate needed.
## Key invariant (R2)
Each cluster requires exactly three things working together:
| File | Location | Role |
| ---- | -------- | ---- |
| Incubator Application | `incubator/<env>/<cluster>.yaml` | Parent — scans values file |
| Values file | `values/<env>/<cluster>-values.yaml` | Tool list (`appSpec[]`) |
| Generic chart | `generic-argo-apps-chart/` | Renderer — produces child Applications |
Breaking any leg of this triangle breaks the cluster's entire tooling. See [SANCTITY_RULES.md R2](../docs/global/SANCTITY_RULES.md).
claude/03-generic-chart-template.md
+41
View File
@@ -0,0 +1,41 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 03 — Generic Chart Template
## Purpose
Instead of maintaining one Application YAML per tool per cluster, `generic-argo-apps-chart/templates/genericTemplate.yaml` generates all Application CRDs dynamically from a single values file. Adding a tool = adding 4 lines to `appSpec[]`.
## Variable flow
```text
values file rendered Application
─────────── ────────────────────
appSpec[].name ──────────────────────────────► metadata.name: <name>-<mungedCluster>-<env>
appSpec[].namespace ─────────────────────────► spec.destination.namespace
appSpec[].nameOverride (optional) ───────────► metadata.name (overrides auto-generated)
appSpec[].chartDir ──────────────────────────► spec.source.path: helm-templates/<chartDir>
appSpec[].valuesDir ─────────────────────────► spec.source.helm.valueFiles: .../helm-overrides/<cluster>/<valuesDir>/custom-values.yaml
appSpec[].additionalValueFiles (optional) ───► extra helm valueFiles entries
teamSpec.devops.labels ──────────────────────► metadata.labels (bu, team, env, cluster)
teamSpec.devops.source.repoURL ──────────────► spec.source.repoURL
argocdSpec.namespace ────────────────────────► metadata.namespace (where Application CRD lives)
clusterSpec.destination.name ────────────────► spec.destination.name
```
## Cluster name munging
The template strips environment/region noise from the cluster name to produce a short Application name segment:
| Step | Transformation |
| ---- | -------------- |
| Strip | `k8s-`, `prd-`, `int-`, `dev-`, `-ase1` |
| Replace | `-ase1c` → `-c` |
Example: `k8s-central-prd-ase1` → `central-prd` → Application name: `keda-central-prd`
## Why this matters for agents
- Template changes are **fleet-wide** — a bug breaks every tool on every cluster simultaneously.
- `generic-argo-apps-chart/` edits are classified as **Layer 1-T HIGH RISK** — requires explicit platform-team sign-off and must be tested with `helm template` against multiple values files before merging.
- See [AGENT_BOUNDARIES.md](../docs/global/AGENT_BOUNDARIES.md) for the full classification.
claude/04-values-hierarchy.md
+68
View File
@@ -0,0 +1,68 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 04 — Values Hierarchy
Each cluster values file (`values/<env>/incubator-infra-<cluster>-values.yaml`) has exactly four top-level keys in this order:
## 1. clusterSpec — where to deploy
```yaml
clusterSpec:
destination:
server: "" # Always empty — use name-based routing
name: "k8s-central-prd-ase1" # GKE cluster name (must match incubator filename and helm-overrides/ folder)
```
## 2. argocdSpec — ArgoCD context
```yaml
argocdSpec:
namespace: argocd-prd # ArgoCD namespace where child Application CRDs are created
# prd → argocd-prd, stg → argocd-dev, int → argocd-shared-int
```
## 3. teamSpec — chart source and labels
```yaml
teamSpec:
devops:
source:
repoURL: https://github.com/Meesho/devops-infra-helm-charts # Allow-listed; do not change
targetRevision: main # prd=main, stg=develop, int=pre-prod
path: helm-templates # Chart root in the helm-charts repo
valueFiles: ../../helm-overrides/k8s-central-prd-ase1 # Relative path to cluster overrides
labels:
bu: infra # Always "infra" for this repo
team: devops # Maps to ArgoCD AppProject (sre or sec)
env: prd # Environment: prd, int, dev, admin
cluster: k8s-central-prd-ase1 # Must match clusterSpec.destination.name
```
## 4. appSpec — the editing surface
```yaml
appSpec:
- name: keda # Short tool name — used in Application name generation
namespace: keda-central-prd # Target Kubernetes namespace
chartDir: keda # Directory under helm-templates/ in helm-charts repo
valuesDir: keda # Directory under helm-overrides/<cluster>/ in helm-charts repo
# Optional fields:
- name: coredns
namespace: kube-system
chartDir: coredns
valuesDir: coredns
nameOverride: coredns-central-prd # Only for name collisions or >253 char names
additionalValueFiles:
- ../../helm-templates/coredns/gcp-ase1a-values.yaml # Region-shared overlay
```
## Cross-repo dependency
Every `appSpec` entry creates a dependency on `devops-infra-helm-charts`:
| appSpec field | Must exist in devops-infra-helm-charts |
| ------------- | -------------------------------------- |
| `chartDir` | `helm-templates/<chartDir>/` |
| `valuesDir` | `helm-overrides/<cluster>/<valuesDir>/custom-values.yaml` |
If either is missing, ArgoCD will fail to render the Application. Always verify in the sister repo before adding an appSpec entry. See [SANCTITY_RULES.md R3](../docs/global/SANCTITY_RULES.md).
claude/05-naming-conventions.md
+86
View File
@@ -0,0 +1,86 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 05 — Naming Conventions
Naming in this repo is **structural** — names are routing identifiers used by ArgoCD, not cosmetic labels. A mismatch between a filename, `metadata.name`, and `clusterSpec.destination.name` can cause silent misrouting. See [SANCTITY_RULES.md R9](../docs/global/SANCTITY_RULES.md).
## File naming
File naming and directory layout differ by environment:
| Env | Branch | Incubator dir | Incubator file prefix | Values dir |
| --- | ------ | ------------- | --------------------- | ---------- |
| prd | `main` | `incubator/prd/` | `incubator-infra-` | `values/prd/` |
| stg / dev (infra) | `develop` | `incubator/infra/` | `incubator-infra-` | `values/dev/` |
| stg / dev (apps) | `develop` | `incubator/apps/` | `incubator-apps-` | `values/dev/` |
| int | `pre-prod` | *(no incubator file — values only)* | `incubator-infra-` | `values/int/` |
| admin | `main` / `pre-prod` | `incubator/admin/` | `incubator-infra-` | `values/admin/` |
**Full filename patterns:**
| File type | Pattern | Example (prd) | Example (stg) |
| --------- | ------- | ------------- | ------------- |
| Incubator Application (infra) | `incubator-infra-<gke-cluster>.yaml` | `incubator-infra-k8s-central-prd-ase1.yaml` | `incubator-infra-k8s-central-stg-ase1.yaml` |
| Incubator Application (apps) | `incubator-apps-<gke-cluster>.yaml` | *(prd uses infra only)* | `incubator-apps-k8s-central-stg-ase1.yaml` |
| Values file | `incubator-infra-<gke-cluster>-values.yaml` | `values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml` | `values/dev/incubator-infra-k8s-central-stg-ase1-values.yaml` |
| AppProject | `<team>-project.yaml` | `sre-project.yaml` | — |
## Incubator ↔ values file invariant
The incubator filename (without `.yaml`) **must equal** `metadata.name` inside it, and must have a matching values file. Directory prefix and env segment both vary by branch:
```text
prd (main):
incubator/prd/incubator-infra-k8s-central-prd-ase1.yaml
metadata.name: incubator-infra-k8s-central-prd-ase1
valueFiles: ../values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml
stg (develop):
incubator/infra/incubator-infra-k8s-central-stg-ase1.yaml
metadata.name: incubator-infra-k8s-central-stg-ase1
valueFiles: ../values/dev/incubator-infra-k8s-central-stg-ase1-values.yaml
int (pre-prod):
(no incubator file — values/int/incubator-infra-k8s-shared-int-ase1-values.yaml only)
```
## ArgoCD Application name generation
Child Applications are named by the generic chart template:
```text
<appSpec.name>-<mungedCluster>-<env>
```
**Munging rules** (applied in order):
| Input | Output |
| ----- | ------ |
| Strip `k8s-` | `k8s-central-prd-ase1` → `central-prd-ase1` |
| Strip `-ase1` | `central-prd-ase1` → `central-prd` |
| Replace `-ase1c` → `-c` | `central-prd-ase1c` → `central-prd-c` |
| Strip `prd-`, `int-`, `dev-` | `prd-central` → `central` |
Result: `keda` on `k8s-central-prd-ase1` → **`keda-central-prd`**
## Namespace convention
| Pattern | When | Example |
| ------- | ---- | ------- |
| `<tool>-<mungedCluster>` | Default | `keda-central-prd` |
| Shared namespace | Multi-component tools | `victoriametrics` (all VM stack apps) |
| `kube-system` | System-level tools | CoreDNS, kube-dns |
| `<tool>-role-<cluster>` | Multi-instance | `contour-internal-0-central-prd` |
## GKE cluster naming pattern
```text
k8s-<bu>-<env>-<region>
k8s-<workload>-<env>-<region>
```
prd examples: `k8s-central-prd-ase1`, `k8s-demand-prd-ase1`, `k8s-datascience-prd-ase1`
stg examples: `k8s-central-stg-ase1`, `k8s-demand-stg-ase1`, `k8s-farmiso-stg-ase1`
dev examples: `k8s-central-dev-ase1`, `k8s-demand-dev-ase1`, `k8s-dengspark-dev-ase1`
int examples: `k8s-shared-int-ase1`
admin examples: `k8s-admin-prd-ase1`, `k8s-devops-admin-ase1`, `k8s-sec-admin-ase1`
claude/06-glossary.md
+39
View File
@@ -0,0 +1,39 @@
> Per [AI Blitz Plan §6](../docs/global/AGENT_BOUNDARIES.md). Layer: 1-T.
# 06 — Glossary and References
## Terms
| Term | Definition |
| ---- | ---------- |
| **Application** | ArgoCD custom resource defining a deployment: source repo, chart path, values, destination cluster/namespace. |
| **AppProject** | ArgoCD custom resource defining RBAC: which repos and namespaces a team's Applications may use. `sre` and `sec` are the two projects in this repo. |
| **App-of-Applications** | Pattern where a parent Application renders child Applications via a Helm chart. Used throughout this repo. |
| **Incubator** | The parent Application YAML (`incubator/<env>/<cluster>.yaml`) that points at the generic chart + values file. One per cluster. |
| **Generic chart** | `generic-argo-apps-chart/` — Helm chart whose template generates one ArgoCD Application per `appSpec[]` entry. |
| **Values file** | `values/<env>/<cluster>-values.yaml` — defines `clusterSpec`, `argocdSpec`, `teamSpec`, and `appSpec[]` for a cluster. |
| **appSpec** | The list of tools to deploy on a cluster. The primary editing surface in this repo. |
| **chartDir** | The chart directory name under `devops-infra-helm-charts/helm-templates/`. Must exist before referencing. |
| **valuesDir** | The override directory name under `devops-infra-helm-charts/helm-overrides/<cluster>/`. Must contain `custom-values.yaml`. |
| **mungedCluster** | The shortened cluster name segment used in Application names (e.g. `k8s-central-prd-ase1` → `central-prd`). |
| **nameOverride** | Optional `appSpec` field to override the auto-generated Application name. Use only for collisions or >253-char names. |
| **ExternalName service** | Kubernetes service type used for cross-cluster DNS routing in the `external-name-service-*` directories (MCS topology). |
| **Layer 1-T** | Tool-Mediated: agent generates YAML diff and opens PR; human reviews and merges. |
| **Layer 3** | Blocked: agent must refuse and explain why. |
## Key files
| File | Purpose |
| ---- | ------- |
| [CLAUDE.md](../CLAUDE.md) | Agent entry point — read first |
| [docs/global/AGENT_BOUNDARIES.md](../docs/global/AGENT_BOUNDARIES.md) | Complete Layer 1/2/3 operation map |
| [docs/global/SANCTITY_RULES.md](../docs/global/SANCTITY_RULES.md) | R1–R12 non-negotiable rules |
| [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 |
## Sister repos
| Repo | Relationship |
| ---- | ------------ |
| `devops-infra-helm-charts` | Helm charts and `custom-values.yaml` overrides. Every `chartDir` and `valuesDir` must exist here. |
| `devops-argo-config` | Same App-of-Applications pattern but for service/application workloads, not infrastructure tooling. |