devops-infra-argo-config-gcp/docs/platform/schemas/values-file-schema.md

Values File Schema — Annotated Field Reference

Field-by-field documentation of the cluster values files used by the generic ArgoCD chart.

File location: values/<env>/incubator-infra-<cluster>-values.yaml

Consumer: generic-argo-apps-chart/templates/genericTemplate.yaml reads these values to render one ArgoCD Application per appSpec entry.

---

Top-level structure

clusterSpec:     # REQUIRED — cluster identity and routing
argocdSpec:      # REQUIRED — ArgoCD operational config
teamSpec:        # REQUIRED — source repo, labels, team identity
appSpec:         # REQUIRED — list of tools to deploy (may be empty [])

---

clusterSpec

clusterSpec:
  destination:
    server: ""                    # String. Always empty — name-based routing is standard.
    name: "k8s-central-prd-ase1"  # String. REQUIRED. GKE cluster name.
                                  # Must match: incubator file name, helm-overrides/<cluster>/ folder,
                                  # and teamSpec.devops.labels.cluster.

Field	Type	Required	Editable	Notes
destination.server	string	yes	no	Always "". Name-based routing is used instead.
destination.name	string	yes	no	GKE cluster name. Changing this redirects ALL tools — HIGH RISK.

---

argocdSpec

argocdSpec:
  namespace: argocd-prd           # String. ArgoCD namespace where Applications are created.
                                  # prd → argocd-prd | stg/dev → argocd-dev | int → argocd-shared-int

Field	Type	Required	Editable	Notes
namespace	string	yes	no	Env-specific: argocd-prd (prd), argocd-dev (stg/dev), argocd-shared-int (int). Changing is HIGH RISK.

---

teamSpec

teamSpec:
  devops:                         # Object. Team block — always "devops" for infra tooling.
    source:
      repoURL: https://github.com/Meesho/devops-infra-helm-charts   # String. Helm charts source.
      targetRevision: main        # String. Git ref for chart source in devops-infra-helm-charts.
                                  # prd → main | stg/dev → develop | int → pre-prod
      path: helm-templates        # String. Root path for charts in the source repo.
      valueFiles: ../../helm-overrides/k8s-central-prd-ase1          # String. Relative path to overrides.
    labels:
      bu: infra                   # String. Business unit. Always "infra" for this repo.
      team: devops                # String. Maps to ArgoCD AppProject name.
      env: prd                    # String. Environment: prd, int, dev, admin.
      cluster: k8s-central-prd-ase1  # String. Must match clusterSpec.destination.name.

Field	Type	Required	Editable	Notes
source.repoURL	string	yes	no	Chart source repo. Changing this is HIGH RISK.
source.targetRevision	string	yes	no	Env-specific: main (prd), develop (stg/dev), pre-prod (int). Changing to any other value is HIGH RISK.
source.path	string	yes	no	Always helm-templates.
source.valueFiles	string	yes	no	Relative path from chart to helm-overrides/<cluster>.
labels.bu	string	yes	no	Always infra.
labels.team	string	yes	no	Maps to AppProject. Usually devops → sre project.
labels.env	string	yes	no	Matches cluster environment.
labels.cluster	string	yes	no	Must match clusterSpec.destination.name. Used in Application name munging.

---

appSpec (the main editing surface)

appSpec:
  - name: keda                          # String. REQUIRED. Short tool name.
    namespace: keda-central-prd          # String. REQUIRED. Target Kubernetes namespace.
    chartDir: keda                       # String. REQUIRED. Chart directory in helm-templates/.
    valuesDir: keda                      # String. REQUIRED. Override directory in helm-overrides/<cluster>/.
    nameOverride: ""                     # String. OPTIONAL. Custom Application name.
    additionalValueFiles:                # List[String]. OPTIONAL. Extra values files.
      - ../../helm-templates/coredns/gcp-ase1a-values.yaml

Field reference

Field	Type	Required	Editable	Notes
name	string	yes	yes	Short tool identifier. Used in auto-generated Application name: <name>-<mungedCluster>-<env>. Lowercase, hyphen-separated.
namespace	string	yes	yes	Target K8s namespace. Auto-created by ArgoCD (CreateNamespace=true). Convention: <tool>-<mungedCluster> or shared namespace.
chartDir	string	yes	yes	Directory under devops-infra-helm-charts/helm-templates/. Must exist.
valuesDir	string	yes	yes	Directory under devops-infra-helm-charts/helm-overrides/<cluster>/. Must exist and contain custom-values.yaml.
nameOverride	string	no	yes	Overrides the auto-generated Application name. Use only for collisions or >253 char names. See R7.
additionalValueFiles	list	no	yes	Extra Helm values files merged during render. Paths are relative to the chart source.

How appSpec entries become ArgoCD Applications

The generic chart template (genericTemplate.yaml) iterates over appSpec and for each entry:

1. Computes the Application name: <name>-<mungedCluster>-<env> (or nameOverride if set).
2. Sets the source: repoURL + path/<chartDir> from teamSpec.devops.source.
3. Sets the values: valueFiles/<valuesDir>/custom-values.yaml + any additionalValueFiles.
4. Sets the destination: clusterSpec.destination.name + namespace.
5. Sets the project: from teamSpec.devops.labels.team (maps to AppProject).
6. Sets syncPolicy: CreateNamespace=true.
7. Adds finalizer: resources-finalizer.argocd.argoproj.io.

Rendered Application example

For name: keda on k8s-central-prd-ase1:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: keda-central-prd
  namespace: argocd-prd
  labels:
    bu: infra
    team: devops
    env: prd
    cluster: k8s-central-prd-ase1
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: devops
  source:
    repoURL: https://github.com/Meesho/devops-infra-helm-charts
    targetRevision: main
    path: helm-templates/keda
    helm:
      valueFiles:
      - ../../helm-overrides/k8s-central-prd-ase1/keda/custom-values.yaml
  destination:
    name: k8s-central-prd-ase1
    server: ""
    namespace: keda-central-prd
  syncPolicy:
    syncOptions:
      - CreateNamespace=true

---

Cluster name munging rules

Used by the generic template to produce short Application names:

Step	Transformation	Example
1	Preserve dp- and backup (placeholder swap)	dp-foo stays dp-foo
2	Strip p-, prd-, int-, dev-, -cluster	k8s-central-prd-ase1 → k8s-central-ase1
3	Replace prod-ops → infra	—
4	Replace -ase1c → -c	k8s-central-prd-ase1c → central-c
5	Strip -ase1	k8s-central-ase1 → k8s-central
6	Strip k8s-	k8s-central → central

Net result: k8s-central-prd-ase1 → central-prd