83 lines
5.4 KiB
Markdown
83 lines
5.4 KiB
Markdown
> Per AI Blitz Plan §global. Layer: 1. Repo: devops-infra-helm-charts.
|
||
|
||
# Agent Operations Guide
|
||
|
||
A meta-guide for any AI agent (or human contributor wearing the agent hat) doing work in this repo. Read this first; it tells you which other docs to load and in what order.
|
||
|
||
## Pre-flight (always, every task)
|
||
|
||
Before reading any task-specific file:
|
||
|
||
1. **Read the repo-root `CLAUDE.md`.** It is the authoritative source for the NEVER-DO list, cluster naming, versioned siblings, multi-Contour pattern, and the Layer constraint summary. Everything else in `docs/` derives from it.
|
||
2. **Read [AGENT_BOUNDARIES.md](./AGENT_BOUNDARIES.md)** to confirm which Layer the operation lives in.
|
||
3. **Read [SANCTITY_RULES.md](./SANCTITY_RULES.md)** to confirm the operation is not on the don't-touch list.
|
||
4. **Read [`wiki/entities/DevOps Infra Helm Charts.md`](../../wiki/entities/DevOps%20Infra%20Helm%20Charts.md)** for the conceptual model (this repo as values store; sister repo as routing layer).
|
||
5. **Skim [`docs/architecture.md`](../architecture.md)** if the task touches more than one chart or cluster.
|
||
|
||
If the task targets a specific chart family (Contour, Vault, Argo CD, observability stack), also load the relevant coding guideline before editing:
|
||
- [coding-guidelines/helm-values.md](./coding-guidelines/helm-values.md) — values-file conventions
|
||
- [coding-guidelines/argocd.md](./coding-guidelines/argocd.md) — Argo CD interaction model
|
||
- [coding-guidelines/observability.md](./coding-guidelines/observability.md) — VM / Mimir / Loki / Tempo / Grafana
|
||
|
||
## Authoring loop
|
||
|
||
The supported edit path for almost every task in this repo:
|
||
|
||
1. **Branch off `main`.** Never push to `main`. The branch name should describe the cluster × app being touched.
|
||
2. **Edit the single targeted file** under `helm-overrides/<cluster>/<app>/custom-values.yaml` (or sibling `<extra>.yaml`). No drive-by edits to other apps in the same directory. No cross-cluster "normalization" in the same PR.
|
||
3. **Dry-run with `helm template`** to confirm the values render. Use the command from the root `CLAUDE.md` Quick reference table:
|
||
```
|
||
helm template <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml
|
||
```
|
||
4. **Commit.** The pre-commit hooks run automatically:
|
||
- **TruffleHog** — secret scan, blocking. NEVER bypass. See [claude/08-pre-commit-and-hooks.md](../../claude/08-pre-commit-and-hooks.md).
|
||
- CAC and Yaak hooks are gated/no-op on this repo.
|
||
5. **Open a PR.** Pair with a sister-repo PR if a new Argo Application is being introduced.
|
||
6. **Reviewer + Argo CD UI Sync are the safety gates.** Once the PR is merged to `main`, Argo CD on the target cluster reconciles. Per-cluster `syncPolicy` (auto vs manual) is set in the sister repo `Meesho/devops-infra-argo-config`, not here.
|
||
|
||
See [platform/procedures/onboard-app-to-cluster.md](../platform/procedures/onboard-app-to-cluster.md) and [platform/procedures/update-chart-version.md](../platform/procedures/update-chart-version.md) for two of the most common authoring loops.
|
||
|
||
## When to refuse
|
||
|
||
Refuse the operation outright if it falls into one of these categories. Cite [SANCTITY_RULES.md](./SANCTITY_RULES.md) in the refusal:
|
||
|
||
- Direct push to `main`, or any `--force` push.
|
||
- Bypassing the pre-commit hook (`--no-verify`, `git commit -n`).
|
||
- Curl / probe / query against any production endpoint (`*.meesho.int`, `*.mrouter.int`, `*.meeshogcp.in`).
|
||
- Edit to `repository.yaml` (owned by `registry-bootstrap`).
|
||
- Edit to an Argo `Application` / `ApplicationSet` manifest (lives in sister repo).
|
||
- Cross-cluster copy-paste of `nodeSelector` / `tolerations` / `computeClass` without rewrite.
|
||
- Deletion of a versioned-sibling chart without confirming zero sister-repo references.
|
||
|
||
## When to escalate
|
||
|
||
If the operation is potentially valid but exceeds Layer-1 authority — chart fork, dep bump with breaking changes, StorageClass/PriorityClass edit, Vault HA work — stop and escalate per [escalation-matrix.md](./escalation-matrix.md). The escalation matrix maps each situation to an owner and a channel.
|
||
|
||
## Tooling commands (cheat sheet)
|
||
|
||
The repo-root `CLAUDE.md` Quick reference table is the source of truth. Reproduced here for convenience:
|
||
|
||
| Task | Command |
|
||
|------|---------|
|
||
| Install pre-commit hooks | `pre-commit install --hook-type pre-commit --hook-type pre-push --hook-type post-commit` |
|
||
| Re-run pre-commit on staged changes | `pre-commit run` |
|
||
| Render a chart locally | `helm template <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml` |
|
||
| Refresh subchart deps | `helm dependency update helm-templates/<chart>` |
|
||
| Diff against live release | `helm diff upgrade <release> helm-templates/<chart> -f helm-overrides/<cluster>/<app>/custom-values.yaml` |
|
||
| Lint a chart | `helm lint helm-templates/<chart>` |
|
||
| Find which clusters override an app | `find helm-overrides -maxdepth 2 -type d -name '<app>'` |
|
||
|
||
## Output discipline
|
||
|
||
- Generate diffs and PRs; do not apply directly to clusters. In-cluster mutation is incident response, not authoring.
|
||
- Surgical edits only. Touch the cluster × application asked for; leave the rest.
|
||
- Cross-link reasoning to ADRs in [`wiki/analyses/`](../../wiki/analyses/) where helpful.
|
||
|
||
## See also
|
||
|
||
- [AGENT_BOUNDARIES.md](./AGENT_BOUNDARIES.md)
|
||
- [SANCTITY_RULES.md](./SANCTITY_RULES.md)
|
||
- [escalation-matrix.md](./escalation-matrix.md)
|
||
- [coding-guidelines/helm-values.md](./coding-guidelines/helm-values.md)
|
||
- [../architecture.md](../architecture.md)
|