# Coding Guidelines — Values Files and appSpec Entries

> YAML authoring conventions for `devops-infra-argo-config`.
>
> **Scope:** `values/<env>/<cluster>-values.yaml` files and `appSpec` entries within them.

---

## Values file structure

Every values file has exactly four top-level keys in this order:

```yaml
clusterSpec:       # Cluster identity — destination for ArgoCD
argocdSpec:        # ArgoCD namespace
teamSpec:          # Source repo, labels, team identity
appSpec:           # List of tools to deploy to this cluster
```

Do not add other top-level keys. Do not reorder these keys.

---

## `clusterSpec` conventions

```yaml
clusterSpec:
  destination:
    server: ""                              # Leave empty — use name-based routing
    name: "k8s-central-prd-ase1"            # Must match the cluster name in GKE
```

- `server` is always empty string `""` — name-based routing is the standard.
- `name` must exactly match the GKE cluster name and the `helm-overrides/` folder in the sister repo.

---

## `argocdSpec` conventions

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

---

## `teamSpec` conventions

```yaml
teamSpec:
  devops:
    source:
      repoURL: https://github.com/Meesho/devops-infra-helm-charts
      targetRevision: main                  # Env-specific: prd=main, stg/dev=develop, int=pre-prod
      path: helm-templates                  # Chart root in the helm-charts repo
      valueFiles: ../../helm-overrides/k8s-central-prd-ase1   # Relative path to overrides
    labels:
      bu: infra                             # Always "infra" for this repo
      team: devops                          # Always "devops" — maps to sre AppProject
      env: prd                              # prd, int, dev, or admin
      cluster: k8s-central-prd-ase1         # Must match clusterSpec.destination.name
```

- `targetRevision` must match the environment branch: `main` (prd), `develop` (stg/dev), `pre-prod` (int). Deviating from this requires explicit justification.
- `valueFiles` is a relative path from the chart source to the cluster's override directory in `devops-infra-helm-charts`.
- Labels are used by the generic chart template for Application naming and metadata.

---

## `appSpec` entry conventions

Each entry in `appSpec` defines one ArgoCD child Application:

```yaml
appSpec:
  - name: keda                             # Short tool name (used in Application name generation)
    namespace: keda-central-prd             # Target namespace (auto-created by ArgoCD)
    chartDir: keda                          # Directory under helm-templates/ in helm-charts repo
    valuesDir: keda                         # Directory under helm-overrides/<cluster>/ in helm-charts repo
```

### Required fields

| Field | Description | Convention |
| ----- | ----------- | ---------- |
| `name` | Short tool identifier | Lowercase, hyphen-separated. Used in rendered Application name. |
| `namespace` | Kubernetes namespace for the tool | Pattern: `<tool>-<mungedCluster>` or shared namespace (e.g., `victoriametrics`, `kube-system`) |
| `chartDir` | Chart directory name in `helm-templates/` | Must exist in `devops-infra-helm-charts` |
| `valuesDir` | Override directory name in `helm-overrides/<cluster>/` | Must exist in `devops-infra-helm-charts` |

### Optional fields

| Field | When to use |
| ----- | ----------- |
| `nameOverride` | Only when the auto-generated name exceeds 253 chars or collides with another entry |
| `additionalValueFiles` | When a tool needs region-shared overlays (e.g., CoreDNS GCP zone values) |

### Ordering

New appSpec entries should be appended at the end of the list. Do not sort alphabetically — the order reflects deployment history and makes diffs cleaner.

---

## Namespace naming patterns

| Pattern | When |
| ------- | ---- |
| `<tool>-<mungedCluster>` | Default. Example: `keda-central-prd`, `contour-external-central-prd` |
| Shared namespace | When multiple tools share a namespace. Example: `victoriametrics` for all VM tools, `kube-system` for system tools |
| Tool-specific with role | Multi-instance tools. Example: `contour-internal-0-central-prd`, `contour-internal-1-central-prd` |

---

## Application name generation

The generic chart template generates names as:

```
<name>-<mungedCluster>-<env>
```

**Cluster munging rules** (applied in order by the Helm template):
1. Replace `dp-` with placeholder, `backup` with placeholder
2. Strip: `p-`, `prd-`, `int-`, `dev-`, `-cluster`
3. Replace: `prod-ops` → `infra`, `-ase1c` → `-c`, `-ase1` → (empty), `k8s-` → (empty)
4. Restore placeholders

**Example:** `k8s-central-prd-ase1` → `central-prd` → Application name: `keda-central-prd`

---

## YAML formatting

- 2-space indentation (no tabs).
- No trailing whitespace.
- Single newline at end of file.
- Quote strings only when YAML requires it (e.g., empty strings `""`).
- Use block style for lists (one `- ` per line), not flow style.

---

## Common mistakes

| Mistake | Why it's wrong | Fix |
| ------- | -------------- | --- |
| Adding `nameOverride` without justification | Breaks naming consistency; see R7 | Remove unless name > 253 chars or collision |
| `chartDir` that doesn't exist in helm-charts | ArgoCD will fail to render the Application | Verify with `ls helm-templates/<chartDir>/` |
| Duplicate `name` in same appSpec list | Two Applications will have the same name → conflict | Use unique tool names or `nameOverride` for multi-instance |
| Changing `targetRevision` away from env branch | All tools on the cluster pull from the wrong branch | Must match env: `main` (prd), `develop` (stg/dev), `pre-prod` (int) |