150 lines
5.6 KiB
Markdown
150 lines
5.6 KiB
Markdown
# 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) |
|