# Incubator Application YAML Schema

> Field-by-field documentation of the incubator Application YAML files.
>
> **File location:** Varies by env/branch:
> - prd (`main`): `incubator/prd/incubator-infra-<cluster>.yaml`
> - stg/dev (`develop`): `incubator/infra/incubator-infra-<cluster>.yaml` (or `incubator/apps/incubator-apps-<cluster>.yaml` for app workloads)
> - int (`pre-prod`): no incubator file — values only in `values/int/`
> - admin: `incubator/admin/incubator-infra-<cluster>.yaml`
>
> **Purpose:** Each incubator file is a single ArgoCD `Application` that acts as the **parent** in the App-of-Applications pattern. It points at `generic-argo-apps-chart/` and its corresponding values file. ArgoCD renders the generic chart to produce one child Application per `appSpec` entry.

---

## Full example

```yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: incubator-infra-k8s-central-prd-ase1
  namespace: argocd-prd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: 'https://github.com/Meesho/devops-infra-argo-config'
    targetRevision: main        # prd=main, stg=develop, int=pre-prod
    path: generic-argo-apps-chart
    helm:
      valueFiles:
      - ../values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml
  destination:
    name: in-cluster
    namespace: argocd-prd
```

---

## `metadata`

| Field | Type | Required | Editable | Notes |
| ----- | ---- | -------- | -------- | ----- |
| `name` | string | yes | no | Must match the filename without `.yaml`. Convention: `incubator-infra-<gke-cluster-name>`. This name is an identifier — changing it breaks ArgoCD tracking. |
| `namespace` | string | yes | no | Env-specific: `argocd-prd` (prd), `argocd-dev` (stg/dev), `argocd-shared-int` (int). This is the namespace in the **admin** cluster where ArgoCD runs, not the target cluster. |
| `finalizers[0]` | string | yes | no | Always `resources-finalizer.argocd.argoproj.io`. Ensures ArgoCD deletes child Applications when the parent is deleted. Do not remove. |

### Filename ↔ name invariant (R9)

The incubator filename (without `.yaml`) **must equal** `metadata.name`. These are routing keys used by ArgoCD:

```text
prd:  incubator/prd/incubator-infra-k8s-central-prd-ase1.yaml
                         └── metadata.name: incubator-infra-k8s-central-prd-ase1

stg:  incubator/infra/incubator-infra-k8s-central-stg-ase1.yaml
                           └── metadata.name: incubator-infra-k8s-central-stg-ase1
```

---

## `spec.project`

| Field | Type | Required | Editable | Notes |
| ----- | ---- | -------- | -------- | ----- |
| `project` | string | yes | no | Always `default` for incubator Applications. The child Applications use `sre` or `sec` projects. |

---

## `spec.source`

| Field | Type | Required | Editable | Notes |
| ----- | ---- | -------- | -------- | ----- |
| `repoURL` | string | yes | no | Always `https://github.com/Meesho/devops-infra-argo-config`. Changing this is a Layer 3 operation. |
| `targetRevision` | string | yes | no | Environment-specific: `main` (prd), `develop` (stg), `pre-prod` (int). Changing to any other value requires sign-off. |
| `path` | string | yes | no | Always `generic-argo-apps-chart`. Points to the Helm chart in this repo. |
| `helm.valueFiles[0]` | string | yes | yes | Relative path from the chart root to the cluster's values file. Convention: `../values/<env>/incubator-infra-<cluster>-values.yaml`. The `..` is required because ArgoCD resolves paths relative to `path` (i.e., relative to `generic-argo-apps-chart/`). |

### `valueFiles` path convention

The path is relative to the chart directory (`generic-argo-apps-chart/`), so you go up one level to reach the repo root:

```text
generic-argo-apps-chart/  (chart root)
    └── ../values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml
                └── resolves to: values/prd/incubator-infra-k8s-central-prd-ase1-values.yaml
```

---

## `spec.destination`

| Field | Type | Required | Editable | Notes |
| ----- | ---- | -------- | -------- | ----- |
| `name` | string | yes | no | Always `in-cluster`. Incubator Applications run on the **admin cluster** where ArgoCD is installed, not on the target cluster. Child Applications (from `appSpec`) deploy to the target cluster. |
| `namespace` | string | yes | no | Env-specific: `argocd-prd` (prd), `argocd-dev` (stg/dev), `argocd-shared-int` (int). This is where ArgoCD creates the child Application objects. |

---

## What this file controls vs. what it doesn't

| Controlled by this file | Controlled by the values file |
| ----------------------- | ----------------------------- |
| Which generic chart to use | Which tools deploy (`appSpec[]`) |
| Which values file to use | Target cluster name (`clusterSpec`) |
| ArgoCD namespace | Chart source repo and revision (`teamSpec`) |
| Parent Application name | Per-tool namespace, chartDir, valuesDir |

---

## Files that must exist when this file is created

| File | Where | Why |
| ---- | ----- | --- |
| `values/<env>/incubator-infra-<cluster>-values.yaml` | This repo | Referenced by `helm.valueFiles` |
| `generic-argo-apps-chart/` | This repo | The chart being rendered |

See also: [values-file-schema.md](values-file-schema.md) for the values file structure, and [add-new-cluster.md](../procedures/add-new-cluster.md) for the full cluster onboarding procedure.