added repo
This commit is contained in:
Your Name
@@ -0,0 +1,123 @@
|
||||
# AGENT_BOUNDARIES.md
|
||||
|
||||
> **Scope:** operations agents may perform on the `devops-infra-helm-charts` repo.
|
||||
> **Companion docs:** [SANCTITY_RULES.md](SANCTITY_RULES.md) (hard rules), [coding-guidelines/helm-values.md](coding-guidelines/helm-values.md) (style).
|
||||
|
||||
This document classifies every operation in this repo into Layer 1 / 2 / 3 with explicit blast radius and approval requirements. **An agent operating in this repo MUST consult this file before any write.**
|
||||
|
||||
---
|
||||
|
||||
## The 3-Layer Model (recap)
|
||||
|
||||
| Layer | Agent action | Safety gate |
|
||||
|-------|--------------|-------------|
|
||||
| **Layer 1 — Agent-Writable** | Generate diff, open PR. Do **not** apply directly to clusters. | PR review + Argo CD UI Sync click. |
|
||||
| **Layer 2 — Agent-Readable (Advisory)** | Research, analyse, recommend. Human executes. | Human review + manual execution. |
|
||||
| **Layer 3 — Agent-Blocked** | Refuse the write. Explain why. Cite this doc. | None applicable. |
|
||||
|
||||
---
|
||||
|
||||
## Per-operation classification
|
||||
|
||||
### Layer 1 — Agent-Writable (this repo's normal operating range)
|
||||
|
||||
All edits land via PR. A merge to `main` is then reconciled by Argo CD per cluster — most infra Applications use manual sync ([ADR-A5](../../wiki/analyses/ADR-A5-manual-sync-default-for-infra.md)), so the workload deploy is a separate human Sync click.
|
||||
|
||||
| Operation | File(s) touched | Blast radius | Required approvers |
|
||||
|-----------|-----------------|--------------|--------------------|
|
||||
| Edit `custom-values.yaml` for one app on one cluster | `helm-overrides/<cluster>/<app>/custom-values.yaml` | One Helm release on one cluster | Service / app owner |
|
||||
| Add a new app under an existing cluster | new dir + files in `helm-overrides/<cluster>/<app>/` | One new release | App owner + cluster owner; pair with Argo `Application` PR in sister repo |
|
||||
| Add a sidecar raw manifest alongside an existing app | `helm-overrides/<cluster>/<app>/<extra>.yaml` | Adds Kubernetes resources rendered alongside the Helm release | App owner |
|
||||
| Add a new override file under an existing app dir | new file in `helm-overrides/<cluster>/<app>/` | Layered into the same release if the Argo Application's `valueFiles` covers it | App owner |
|
||||
| Append to an existing chart's `Chart.yaml` `dependencies[]` | `helm-templates/<chart>/Chart.yaml` + refresh `Chart.lock` via `helm dependency update` | Affects every consumer of that chart | Platform team |
|
||||
| Bump a `dependencies[].version` in `Chart.yaml` | `helm-templates/<chart>/Chart.yaml` + `Chart.lock` | Same | Platform team — see [update-chart-version](../platform/procedures/update-chart-version.md) |
|
||||
| Add a new chart sibling for blue-green migration | new dir `helm-templates/<chart>-<variant>/` | Migration target only; old sibling stays live | Platform team — see [blue-green-chart-migration](../platform/procedures/blue-green-chart-migration.md) |
|
||||
| Edit the per-cluster Contour scheduling matrix | `contour-nodeselector-tolerations-summary.md` | Documentation; no runtime effect | Platform team |
|
||||
|
||||
### Layer 1 — HIGH RISK (write allowed, but require explicit approval and detailed rationale in PR)
|
||||
|
||||
| Operation | Why it's high risk |
|
||||
|-----------|--------------------|
|
||||
| Edit `helm-templates/<chart>/templates/` or `helm-templates/<chart>/values.yaml` | Most charts here are vanilla upstream pulled via `helm pull`. Edits silently fork the chart and get clobbered on the next upstream sync. **Only allowed if the fork is intentional and documented in that chart's `README.md` — see [fork-upstream-chart](../platform/procedures/fork-upstream-chart.md).** |
|
||||
| Delete a versioned sibling chart (`<chart>-green`, `<chart>-vX.Y.Z`, `<chart>-latest`, `<chart>-old`) | The variant is a blue-green migration target. Both versions may be live simultaneously. **Confirm zero references in `github.com/Meesho/devops-infra-argo-config` before deleting.** |
|
||||
| Edit `manifests/storageclass/*.yaml` | Cluster-wide singleton; affects every PVC. **Platform-team review required.** |
|
||||
| Edit `manifests/priorityclass/<cluster>/*.yaml` | Affects scheduling priority for every pod that references the class. Platform-team review. |
|
||||
| Edit `manifests/{jenkins-filestore-caching,jenkins-gcs-caching,jfrog-filestore-data}/{dev,prd}/` | Per-env stateful PV/PVCs; wrong reclaim policy can drop CI build caches or JFrog binary data. Platform-team review. |
|
||||
| Add a new cluster directory under `helm-overrides/` | Creates a new deployment target. **Pair with the cluster's `ApplicationSet` change in the sister repo. Per-cluster `nodeSelector` / `tolerations` / `computeClass` MUST be written from scratch, not copied from another cluster ([SANCTITY_RULES R5](SANCTITY_RULES.md)).** |
|
||||
| Change `fullnameOverride` in any `custom-values.yaml` | Service DNS, PVC binding, ConfigMap/Secret references, and downstream Argo Application names depend on it being stable. **Almost always wrong to touch.** |
|
||||
| Bulk find-replace across cluster directories ("normalise" labels, image tags, etc.) | The whole point of per-cluster overrides is divergence. Cross-cluster cleanup is its own PR with its own scope ([SANCTITY_RULES R6](SANCTITY_RULES.md)). |
|
||||
| Pin an image tag to a registry outside `asia-southeast1-docker.pkg.dev/meesho-devops-admin-0622/admin/sre/` | Production overrides go through Meesho's Artifact Registry mirror. Direct Docker Hub / Quay pulls are a supply-chain and rate-limit risk. |
|
||||
|
||||
### Layer 2 — Agent-Readable (advisory only)
|
||||
|
||||
Some operations a user might ask for touch systems an agent can analyse but not change.
|
||||
|
||||
| Operation | Why advisory |
|
||||
|-----------|--------------|
|
||||
| "Sync `<release>` now in Argo CD" | The Sync click is intentional human action. **Recommend the command (`argocd app sync <name>`) or the Argo CD UI path; do not execute.** |
|
||||
| "Restart pods for `<release>`" | kubectl operation against a workload cluster. Recommend `kubectl rollout restart deploy/<name> -n <ns>`; do not execute. |
|
||||
| "Why is this pod pending?" | Live cluster state. Recommend `kubectl describe pod` and walk [pod-pending-scheduling.md](../platform/runbooks/pod-pending-scheduling.md); do not infer. |
|
||||
| "Why did the chart not render?" | Reproduce locally with `helm template`; recommend the fix. Do not push without PR. |
|
||||
| "Add an alert rule for `<service>`" | Alert rules are in `victoria-metrics-alert*` chart values *here*, but routing/notifier config is elsewhere (Pulse / Slack webhook secrets). Recommend the right file; pair with the routing change. |
|
||||
| "What's broken on the GKE cluster itself?" | Cluster-level GCP / GKE issues are out of scope for this repo. Recommend the Terraform repo or the platform team. |
|
||||
| "Reconcile the Terraform drift for the cluster" | Out of scope — that's `terraform-gcp-infra`. Refuse + redirect. |
|
||||
|
||||
### Layer 3 — Agent-Blocked (refuse + explain)
|
||||
|
||||
| Operation | Why blocked | What would unblock |
|
||||
|-----------|-------------|--------------------|
|
||||
| Hand-edit `repository.yaml` | Owned by `registry-bootstrap` automation; manual edits are overwritten on the next bootstrap run. | Update the upstream registry that feeds registry-bootstrap. |
|
||||
| Bypass pre-commit hooks (`--no-verify`, `git commit -n`, removing the hook) | TruffleHog is the last-line secret scan. ([SANCTITY_RULES R4](SANCTITY_RULES.md)) | If a hit is a known false positive, confirm with the platform/security team in writing first. |
|
||||
| Push directly to `main` | Branch protection. ([SANCTITY_RULES R1](SANCTITY_RULES.md)) | (Never legitimate.) |
|
||||
| Force-push to `main` | Same. | (Never legitimate.) |
|
||||
| Run `helm install`, `helm upgrade`, or `kubectl apply` against any workload cluster | This is GitOps; in-cluster mutation creates drift Argo CD will reconcile away. | Use the Argo CD UI Sync flow, or the cluster's incident-response toolset. |
|
||||
| Curl / probe / interact with `int.meesho.int`, `prd.meesho.int`, `int.mrouter.int`, `prd.mrouter.int`, or any workload-traffic `*.meeshogcp.in` host | Production traffic surfaces. ([SANCTITY_RULES R3](SANCTITY_RULES.md)) | (Pre-commit hook telemetry to `observe.meeshogcp.in` is automated; that is hook infrastructure, not agent action.) |
|
||||
| Edit Argo `Application` / `ApplicationSet` manifests | They live in `github.com/Meesho/devops-infra-argo-config`. | Open a PR there. |
|
||||
| Modify a chart whose `helm-templates/<chart>/` is vanilla upstream, without a documented fork rationale | An accidental fork is silently clobbered on the next sync. | Follow [fork-upstream-chart](../platform/procedures/fork-upstream-chart.md) and document the fork in the chart's `README.md`. |
|
||||
| Copy a `custom-values.yaml` from one cluster to another verbatim | Per-cluster `nodeSelector` / `tolerations` / `computeClass` differ. ([SANCTITY_RULES R5](SANCTITY_RULES.md)) | Author the override from scratch using the per-cluster matrix in [contour-nodeselector-tolerations-summary.md](../../contour-nodeselector-tolerations-summary.md) and sibling files. |
|
||||
|
||||
---
|
||||
|
||||
## Cross-cuts: things to verify on **every** Layer 1 PR
|
||||
|
||||
Pre-commit hooks here are minimal — TruffleHog covers secrets; CAC and Yaak are no-ops because their gating paths don't exist in this repo. The agent is the next line of defence. On every PR, mentally run this checklist:
|
||||
|
||||
1. **Surgical scope.** The PR touches only the cluster × app the task asked for. No drive-by edits to neighbours.
|
||||
2. **Per-cluster scheduling rewritten, not copied.** If the change involves `nodeSelector` / `tolerations` / `computeClass`, every cluster has its own topology. Copy-and-rename is the most common silent bug. ([contour-nodeselector-tolerations-summary.md](../../contour-nodeselector-tolerations-summary.md))
|
||||
3. **`fullnameOverride` unchanged.** Unless the explicit headline of the PR is a release-name migration.
|
||||
4. **Image tags pin to Meesho's GAR mirror** (`asia-southeast1-docker.pkg.dev/meesho-devops-admin-0622/admin/sre/<image>`), not Docker Hub.
|
||||
5. **Versioned siblings preserved.** A delete or rename of a `<chart>-green` / `-latest` / `-vX.Y.Z` directory only proceeds after grepping `github.com/Meesho/devops-infra-argo-config` for references.
|
||||
6. **Chart.yaml + Chart.lock move together.** A `dependencies[].version` bump without a refreshed lockfile is incomplete.
|
||||
7. **Sister repo paired (where required).** A new app under a cluster needs a matching `Application` in the sister repo. A new cluster directory needs a matching `ApplicationSet` (or per-cluster Application set) in the sister repo. Note the pairing in the PR description.
|
||||
8. **No `*` or `latest` image tags introduced.** Argo CD's manual-sync default does not rescue you from a pulled-out-from-under-you image.
|
||||
9. **`manifests/` left alone unless the PR's headline says so.** `storageclass/` and `priorityclass/<cluster>/` are cluster-wide singletons.
|
||||
10. **TruffleHog passed.** Never bypass.
|
||||
|
||||
---
|
||||
|
||||
## Approval requirements summary
|
||||
|
||||
| Change category | Reviewer required | CMR required? |
|
||||
|-----------------|-------------------|---------------|
|
||||
| Single-cluster `custom-values.yaml` edit (no scheduling, no `fullnameOverride`) | App owner | Per BU policy |
|
||||
| Add a new app override under an existing cluster | App owner + cluster owner | **Yes** |
|
||||
| Add a new cluster directory | Platform team | **Yes** |
|
||||
| `Chart.yaml` `dependencies[].version` bump | Platform team | **Yes** for prod-fleet charts (Argo CD, Contour, VictoriaMetrics, ingress) |
|
||||
| Intentional fork of `helm-templates/<chart>/templates/` | Platform team — multi-reviewer | **Yes** |
|
||||
| Delete a versioned chart sibling | Platform team — confirm zero sister-repo references | **Yes** |
|
||||
| Edit `manifests/storageclass/` or `priorityclass/<cluster>/` | Platform team | **Yes** |
|
||||
| Pre/post-commit hook script change | Platform team + security (if hook scope changes) | Per CMR matrix |
|
||||
| `fullnameOverride` change | Platform team — multi-reviewer | **Yes** — emergency-only |
|
||||
|
||||
CMR = Change Management Request. Per Meesho process; not enforced in-repo, applied at org level.
|
||||
|
||||
---
|
||||
|
||||
## Escalation
|
||||
|
||||
If a request falls outside this matrix or you can't classify it cleanly:
|
||||
|
||||
1. Refuse the write.
|
||||
2. Cite this document + the row that matches (or explain why no row matches).
|
||||
3. Suggest the human asks the platform team or files a CMR.
|
||||
4. Do not improvise around the boundary.
|
||||
Reference in New Issue
Block a user