> Per [AI Blitz Plan §6](../AGENT_BOUNDARIES.md). Layer: 1-T.

# Coding Guidelines — Helm Values Files

Conventions for cluster values files (`values/<env>/incubator-infra-<cluster>-values.yaml`).

---

## File naming

```text
values/<values-dir>/incubator-infra-<gke-cluster-name>-values.yaml
```

The values directory name does **not** always match the environment name:

| Environment | Branch | Values dir | Example |
| ----------- | ------ | ---------- | ------- |
| prd | `main` | `values/prd/` | `values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml` |
| stg | `develop` | `values/dev/` | `values/dev/incubator-infra-k8s-central-stg-ase1-values.yaml` |
| dev | `develop` | `values/dev/` | `values/dev/incubator-infra-k8s-central-dev-ase1-values.yaml` |
| int | `pre-prod` | `values/int/` | `values/int/incubator-infra-k8s-shared-int-ase1-values.yaml` |
| admin | `main` / `pre-prod` | `values/admin/` | `values/admin/incubator-infra-k8s-devops-admin-ase1-values.yaml` |

Note: stg and dev clusters both live under `values/dev/` on the `develop` branch.

---

## Top-level structure

Four keys in this exact order — no additions, no reordering:

```yaml
clusterSpec:
argocdSpec:
teamSpec:
appSpec:
```

---

## `clusterSpec`

```yaml
clusterSpec:
  destination:
    server: ""                          # Always empty string — name-based routing only
    name: "k8s-central-prd-ase1"        # Must match GKE cluster name and helm-overrides/ folder
```

- `server` is always `""`. Never set a URL here.
- `name` is immutable after cluster registration. Changing it redirects all tooling.

---

## `argocdSpec`

```yaml
argocdSpec:
  namespace: argocd-prd                 # argocd-prd | argocd-dev | argocd-shared-int
```

| Environment | Namespace |
| ----------- | --------- |
| prd | `argocd-prd` |
| stg / dev | `argocd-dev` |
| int | `argocd-shared-int` |

---

## `teamSpec`

```yaml
teamSpec:
  devops:
    source:
      repoURL: https://github.com/Meesho/devops-infra-helm-charts
      targetRevision: main              # main | develop | pre-prod
      path: helm-templates
      valueFiles: ../../helm-overrides/<cluster>
    labels:
      bu: infra
      team: devops
      env: prd                          # prd | stg | dev | int | admin
      cluster: k8s-central-prd-ase1    # Must match clusterSpec.destination.name
```

**`repoURL` allow-list:** Only `https://github.com/Meesho/devops-infra-helm-charts` is permitted.

**`targetRevision`** must match the environment:

| Environment | `targetRevision` |
| ----------- | ---------------- |
| prd | `main` |
| stg / dev | `develop` |
| int | `pre-prod` |

**`valueFiles` path:** Relative from `helm-templates/` root (two levels up) to the cluster's override directory. Always `../../helm-overrides/<cluster>`.

**`labels.cluster`** must equal `clusterSpec.destination.name` exactly — it is used in Application name generation.

---

## `appSpec`

```yaml
appSpec:
  - name: keda                          # Short, lowercase, hyphen-separated tool name
    namespace: keda-central-prd         # Target K8s namespace
    chartDir: keda                      # Directory under helm-templates/ in helm-charts repo
    valuesDir: keda                     # Directory under helm-overrides/<cluster>/ in helm-charts repo
```

- One entry = one ArgoCD child Application.
- Generated name: `<name>-<mungedCluster>-<env>` (e.g. `keda-central-prd`).
- `chartDir` and `valuesDir` **must exist** in `devops-infra-helm-charts` before adding the entry (R3).

### Optional fields

```yaml
  - name: coredns
    namespace: kube-system
    chartDir: coredns
    valuesDir: coredns
    nameOverride: coredns-central-prd   # Only for name collisions or >253 char names (R7)
    additionalValueFiles:
      - ../../helm-templates/coredns/gcp-ase1a-values.yaml
```

---

## Common mistakes

| Mistake | Impact | Fix |
| ------- | ------ | --- |
| `server: <url>` instead of `""` | May route to wrong cluster | Always use `""` |
| Wrong `targetRevision` for env | Tools pull from wrong chart branch | Use `main`/`develop`/`pre-prod` per env |
| `chartDir` not in `helm-templates/` | ArgoCD render failure | Verify in `devops-infra-helm-charts` first |
| `valuesDir` missing `custom-values.yaml` | ArgoCD render failure | Add `custom-values.yaml` to the override dir |
| `labels.cluster` ≠ `clusterSpec.destination.name` | Application name munging uses wrong cluster | Keep them identical |
| Duplicate `name` in `appSpec` | Application name collision | Use `nameOverride` for multi-instance tools |