From 279d476d85a73450e8f99fea5bd2b741950f8129 Mon Sep 17 00:00:00 2001 From: stxkxs Date: Wed, 20 May 2026 10:11:56 -0700 Subject: [PATCH] docs: add AGENTS.md agent entry point MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md gives AI clients a repo-scoped quick start — what the repo provides, its contract surface, the common change recipes, and a link to the stack-wide Platform Reference. README points to it from the top. .plans/join-nanohype.md records the org-transfer plan. --- .plans/join-nanohype.md | 45 ++++++++++++++++++++++++++++++++++ AGENTS.md | 54 +++++++++++++++++++++++++++++++++++++++++ README.md | 2 ++ 3 files changed, 101 insertions(+) create mode 100644 .plans/join-nanohype.md create mode 100644 AGENTS.md diff --git a/.plans/join-nanohype.md b/.plans/join-nanohype.md new file mode 100644 index 0000000..066fb04 --- /dev/null +++ b/.plans/join-nanohype.md @@ -0,0 +1,45 @@ +# Join nanohype org + +Tactical plan for moving `stxkxs/aks-gitops` → `nanohype/aks-gitops`. + +Master plan: `/Users/bs/.claude/plans/so-i-want-to-snazzy-sun.md` Phase 1.3. + +## Transfer + +```sh +gh repo transfer stxkxs/aks-gitops nanohype +git remote set-url origin git@github.com:nanohype/aks-gitops.git +``` + +## Cross-references to fix + +```sh +grep -rn "stxkxs" --include="*.md" --include="*.yaml" --include="*.json" +``` + +Known references: + +- `CLAUDE.md:5` — `azure-aks` is the Bicep/Terraform companion (analogue of `aws-eks` for AKS). Determine whether this lives as a distinct repo or as the AKS path inside `landing-zone`. If distinct, transfer; if landing-zone-resident, update the reference to point at landing-zone's Azure components +- `CLAUDE.md:87` — "Relationship to Parent Repo" section references the same + +## App-of-Apps pointer + +The AKS infrastructure (Bicep/Terraform) creates the ArgoCD Application pointing here. After transfer, that pointer updates to `https://github.com/nanohype/aks-gitops`. + +## Azure-specific OIDC + +If CI workflows use Azure Federated Identity Credential, the `subject` field references org/repo (`repo:stxkxs/aks-gitops:ref:refs/heads/main`). Same pattern as landing-zone — update both old and new for a window, then transfer. + +## Verification + +```sh +gh repo view nanohype/aks-gitops # 200 +task validate # still passes +grep -rn "stxkxs" --include="*.md" --include="*.yaml" # zero or intentional only +``` + +## Notes + +- Mirrors eks-gitops structure exactly; transfer should be near-identical mechanics +- Karpenter is AKS Node Auto Provisioning here; that's an Azure concern, no transfer impact +- External Secrets uses `AzureKeyVaultProvider` — no org coupling diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0248267 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,54 @@ +# aks-gitops — agent entry point + +You're an AI client (or the author of one) about to add a cluster-level addon for Azure Kubernetes Service, register a workload as an ApplicationSet entry, or land a Grafana dashboard. This file gets you running in five minutes. For the wider picture — how this repo fits into the nanohype stack — read the [Platform Reference](https://github.com/nanohype/nanohype/blob/main/docs/platform-reference.md). + +## What this repo gives you + +ArgoCD App-of-Apps catalog for AKS clusters. The Azure-specific cousin of [`eks-gitops`](../eks-gitops/) — same App-of-Apps pattern, same ApplicationSet generators, AKS-specific addon set. + +Categories under `addons/`: + +- **`argo-platform/`** — Argo CD, Argo Workflows, Argo Rollouts, Argo Events (same as EKS) +- **`bootstrap/`** — cluster bootstrap: cert-manager, external-secrets-operator, metrics-server, azure-workload-identity (instead of IRSA), azure-disk-csi-driver, cluster-autoscaler with AKS-specific config +- **`networking/`** — ingress-nginx, cilium (where supported by Azure CNI), network-policies +- **`observability/`** — kube-prometheus-stack, loki, tempo, azure-monitor-opentelemetry-collector +- **`operations/`** — keda (native AKS integration), descheduler, reloader, vpa +- **`security/`** — kyverno, falco, trivy-operator, gatekeeper + +Plus: + +- **`applicationsets/`** — ApplicationSet generators that fan addons + tenant workloads out across clusters by label +- **`catalog/`** — per-addon catalog metadata +- **`environments/`** — per-cluster overlays +- **`dashboards/`** — Grafana dashboard JSON +- **`policies/`** — Kyverno + Gatekeeper policies enforced cluster-wide + +## Contract surface + +Identical to `eks-gitops` — same addon shape, same ApplicationSet pattern, same sync-wave ordering, same per-env values structure. Differences: + +- **Identity**: Azure Workload Identity (federated credentials) instead of AWS IRSA. Components in `landing-zone/components/azure/` provision the federated credentials; tenant ServiceAccounts annotate with `azure.workload.identity/client-id`. +- **Storage classes**: AKS uses `managed-csi-premium` / `azure-disk` by default. EKS uses `gp3` / `ebs-csi`. +- **Ingress**: usually ingress-nginx (same as EKS). Application Gateway Ingress Controller is also supported via `addons/networking/agic/` when an AppGW is provisioned by landing-zone. +- **Observability collector**: `azure-monitor-opentelemetry-collector` ships logs to Azure Monitor in addition to Grafana Cloud. + +## Add a new addon + +Same process as `eks-gitops/AGENTS.md` — see that file for the canonical recipe. Substitute `aks-gitops` paths and Azure-specific defaults where they differ. + +## Register a tenant workload + +Identical to EKS — the workload's source repo owns its `/gitops/applicationset-entry.yaml`. From this repo's side, register the workload in `applicationsets/apps-tenants.yaml`. + +## Conventions + +Identical to `eks-gitops/AGENTS.md` (Helm values: 2-space indent, all three env deltas required, sync-wave ordering, Kyverno policies cluster-wide). + +## Pointers + +- [`README.md`](README.md) — repo overview +- [`docs/`](docs/) — Azure-specific addon notes, AKS bootstrap process +- [`CLAUDE.md`](CLAUDE.md) — Claude Code session instructions +- [Platform Reference](https://github.com/nanohype/nanohype/blob/main/docs/platform-reference.md) — the stack-wide view +- [`eks-gitops/AGENTS.md`](../eks-gitops/AGENTS.md) — the EKS cousin +- [`landing-zone/AGENTS.md`](../landing-zone/AGENTS.md) — `components/azure/*` provisions the substrate this catalog targets diff --git a/README.md b/README.md index 21c988f..4ebb6ea 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ GitOps configuration for AKS cluster addons, managed by ArgoCD. Part of a multi-cloud GitOps strategy (`eks-gitops`, `gke-gitops`, `aks-gitops`). +**AI clients / agents start here:** [`AGENTS.md`](AGENTS.md). For the stack-wide view, see the [Platform Reference](https://github.com/nanohype/nanohype/blob/main/docs/platform-reference.md). + ## Features - **App-of-Apps pattern** with ArgoCD ApplicationSets for multi-cluster deployment