added repo
This commit is contained in:
Your Name
@@ -0,0 +1,149 @@
|
||||
# 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) |
|
||||
Reference in New Issue
Block a user