Files

T

2026-08-26 04:03:34 +05:30

5.6 KiB

Raw Blame History

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:

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

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

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

`teamSpec` conventions

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:

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):

Replace dp- with placeholder, backup with placeholder
Strip: p-, prd-, int-, dev-, -cluster
Replace: prod-ops → infra, -ase1c → -c, -ase1 → (empty), k8s- → (empty)
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)

5.6 KiB Raw Blame History