development-gitops-argo-cd-3darch/references/helm-values.md

# Helm Values Templates

Everything under `cluster/resources/**/values.yaml.jinja`: image wiring, the `global` block,
per-service sections, environment variables, probes, and replica counts.

Read this when creating or editing a values template, or when rendered `values.yaml` produces
invalid YAML or unexpected Helm behaviour.

---

## 1. Dual-layer rendering

Every `values.yaml.jinja` is rendered **twice**:

1. **By Copier** — substitutes `{{ variable }}` from the answer file, producing `values.yaml`.
2. **By Helm** — ArgoCD passes that `values.yaml` to `helm template` at sync time.

The file must therefore be valid Jinja2 *and* produce valid Helm values afterwards. A
mistake in layer 1 fails the render; a mistake in layer 2 fails the sync, potentially hours
later. Validate both (section 6).

---

## 2. Two categories of values file

| Category | Shape | Used for |
|---|---|---|
| Operator / config resources | Simple YAML, minimal templating | CRD instances — OperatorGroup, Subscription, ClusterSecretStore |
| Application workloads | Full Helm values with `global` + per-service sections | Platform services, MCP servers, notification, integration |

Both use the same `render()` macro pattern. Do not mix the `global` shape and the standalone
shape inside one file — pick the one matching the chart and follow it consistently.

---

## 3. Minimal structure (every file)

```jinja
{% macro render() %}
# --- values content here ---
key: {{ domain.get('sub', {}).get('field', '') }}
{% endmacro %}
{%- set result = render() -%}
{%- for line in result.split('\n') -%}
{% if line | trim | length != 0 -%}
{{ line }}
{% endif -%}
{%- endfor %}
```

---

## 4. Shared-chart workload structure

Services that share one Helm release read cluster-wide settings from a `global` block:

```yaml
global:
  is_internal: "{{ applications.get('global', {}).get('is_internal', '') }}"
  ca_env: {{ applications.get('global', {}).get('ca_env', '') }}
  ca_secret_name: {{ applications.get('global', {}).get('ca_secret_name', '') }}
  host: {{ applications.get('global', {}).get('host', '') }}
  ca_host: {{ applications.get('global', {}).get('ca_host', '') }}
  suffix_url: {{ applications.get('global', {}).get('suffix_url', '') }}
  maintenance: "{{ applications.get('global', {}).get('maintenance', 'false') }}"
  node_selector_app: "{{ applications.get('global', {}).get('node_selector_app', '') }}"
  mongo:
    host: {{ applications.get('global', {}).get('mongo', {}).get('host', '') }}
    port: {{ applications.get('global', {}).get('mongo', {}).get('port', '') }}
    user: {{ applications.get('global', {}).get('mongo', {}).get('user', '') }}

network:
  routes: []

<service-name>:
  enabled: true
  image:
    name: {{ applications.get('<service-name>', {}).get('image', {}).get('address', '') }}
    tag: {{ applications.get('<service-name>', {}).get('image', {}).get('tag', '') }}
  replicas: {{ applications.get('<service-name>', {}).get('replicas', 1) }}
```

`global` goes at the top of the file. All `global` sub-keys use the established names — do
not introduce synonyms (`hostname` for `host`, `env` for `ca_env`); the chart templates read
the exact keys.

---

## 5. Standalone workload structure

Charts that do not share a `global` block use the standard Helm shape:

```yaml
replicaCount: 1

image:
  repository: {{ domain.get('service', {}).get('image', {}).get('address', '') }}
  tag: {{ domain.get('service', {}).get('image', {}).get('tag', '') }}
  pullPolicy: Always

imagePullSecrets:
  - name: "storage-images"

service:
  type: ClusterIP
  port: 80

livenessProbe:
  httpGet:
    path: /health
    port: <app-port>
  periodSeconds: 60

readinessProbe:
  httpGet:
    path: /health
    port: <app-port>
  periodSeconds: 60

env:
  targetPort: <app-port>
  <env_var>: {{ domain.get('service', {}).get('env', {}).get('<env_var>', '') }}
```

---

## 6. Design rules

### Images

- Always wire address and tag from Copier variables; never hardcode image coordinates.
- Use `.get()` with an empty-string default for every image field.
- `pullPolicy: Always` for mutable tags (`latest`, environment-specific). `IfNotPresent`
  only for immutable digest-pinned images.
- Private registries need `imagePullSecrets` referencing the pre-existing secret — commonly
  `storage-images`.

### Booleans

Booleans passed into `global` (`is_internal`, `maintenance`, `enable_instana`) are **quoted
strings** because the chart templates treat them as strings. This is deliberate and differs
from Copier feature flags, which are real YAML booleans. Keep the two straight: flags gate
rendering, these gate chart behaviour.

### Environment variables

- Map every env var from a Copier variable via `.get()`; never hardcode.
- Group them under an `env:` key in the service's section.
- Document *which* env vars are required, never their values — secrets come from an external
  secret store, not from a values file.

### Probes

- Every application workload configures both `livenessProbe` and `readinessProbe`.
- Prefer `httpGet` on `/health` where the app exposes it.
- `periodSeconds: 60` is the default; change only when startup or health cadence demands it.

### Replicas

- Default to `1` via the Copier variable: `replicas: {{ domain.get('svc', {}).get('replicas', 1) }}`.
- Never hardcode — environments must scale independently.

### Blank-line stripping

- Wrap the full body in `{% macro render() %}` … `{% endmacro %}`.
- Always append the four-line stripping footer.
- Do not rely on `-` whitespace control inside the macro body for the same purpose.

---

## 7. Adding a new values file

1. Create it at `cluster/resources/{{ '<NNN-name>' if <flag> }}/values.yaml.jinja` — the
   expression identical to the `cluster/argocd/` side.
2. Open with `{% macro render() %}`.
3. Write the values body, sourcing every variable through a `.get()` chain.
4. Close with `{% endmacro %}` plus the stripping footer.
5. Confirm every referenced variable is declared in `copier.yaml`.
6. Render and validate.

A starting template is in `assets/example-cluster-resource/resources/values.yaml.jinja`.

---

## 8. Validation

```bash
# Render (Jinja2 layer)
copier copy . /tmp/gitops-render --overwrite --defaults

# Parse the rendered values (YAML layer)
python3 -c "import yaml; yaml.safe_load(open('/tmp/gitops-render/cluster/resources/<NNN-name>/values.yaml'))"

# Lint against the chart (Helm layer)
helm lint <path-to-chart> -f /tmp/gitops-render/cluster/resources/<NNN-name>/values.yaml

# See what Helm will actually produce
helm template <release> <path-to-chart> \
  -f /tmp/gitops-render/cluster/resources/<NNN-name>/values.yaml
```

---

## 9. Mistakes to avoid

- Omitting the `render()` wrapper — blank lines from unexpanded blocks produce invalid YAML.
- Hardcoding image tags, so every environment deploys the same version.
- Putting secrets in a values file instead of an ExternalSecret / ClusterSecretStore.
- Quoting numerics (replicas, ports) unless the chart explicitly expects a string.
- Mixing the `global` pattern and the standalone pattern in one file.
- Forgetting `imagePullSecrets` for a private-registry image — pods stall on `ImagePullBackOff`.
- Renaming a `global` sub-key to a synonym the chart does not read — the value silently
  becomes empty rather than erroring.