Templates (.tpl)

Files ending in .tpl under workspace/jobs/<job>/ are rendered at deploy staging time with Go text/template. Output drops the .tpl suffix (e.g. config.json.tpl → config.json).

Related: deploy.md · KV namespaces · cli/hooks.md

When rendering runs

During maand deploy, after job files are copied to tmp/workers/<ip>/jobs/<job>/ and before rsync to the worker. Each active allocation gets its own render pass (per-worker KV and version context).

Template data (dot context)

Equivalent KV:

{{ getJobWorker "version" }}
{{ get "maand/job/api/worker/10.0.0.1" "version" }}

Template functions

Missing keys or disallowed namespaces panic at render time (deploy fails for that job), except getOptional which returns an empty string.

Deploy .tpl only: get, getOptional, getJob, getJobOptional, getJobWorker, getJobWorkerOptional, getWorker, getWorkerOptional, getSecret, scrapeConfigs, and ruleFiles are available on job templates at staging time.

_prometheus/scrape.yaml.tpl (build time) uses a smaller func map: get, getJob, getJobOptional, getSecret, keys — no getOptional, no getJobWorker, no getWorker, no scrapeConfigs, no .WorkerIP. See prometheus.md.

Go text/template built-ins are also available: eq, ne, lt, le, gt, ge, printf, and, or, not, len, index, range, if, define, template.

Hook scripts receive the same allocation context via env — see hook-api.md (ALLOCATION_INDEX, CURRENT_VERSION, NEW_VERSION, …).

Example

workspace/jobs/api/config.json.tpl:

{
  "cluster": "{{ get "vars/bucket/job/api" "cluster_name" }}",
  "version": "{{ .NewVersion }}",
  "target_version": "{{ getJobWorker "version" }}",
  "worker": "{{ .WorkerIP }}",
  "hostname": "{{ getWorker "hostname" }}",
  "listen_port": "{{ get "maand/bucket" "api_http_port" }}"
}

Populate vars/bucket/job/api via vars.conf or bucket.jobs*.conf. Use vars/job/api for hook-written values from pre_deploy / post_build.

Memory sizing (postgres-style)

workspace/jobs/postgres/postgresql.conf.tpl:

{{ define "pgMemUnit" -}}
{{- $mb := int . -}}
{{- if ge $mb 1024 -}}
{{- div $mb 1024 -}}GB
{{- else -}}
{{- $mb -}}MB
{{- end -}}
{{- end }}
{{- $memMB := int (get "vars/job/postgres" "memory") -}}
{{- $sharedMB := div $memMB 4 -}}
{{- $cacheMB := div (mul $memMB 3) 4 -}}
{{- $maintMB := min 2048 (div $memMB 16) -}}
{{- $workMB := min 128 (max 4 (div $memMB 64)) -}}
shared_buffers = {{ template "pgMemUnit" $sharedMB }}
effective_cache_size = {{ template "pgMemUnit" $cacheMB }}
maintenance_work_mem = {{ $maintMB }}MB
work_mem = {{ $workMB }}MB

Use {{ get (printf "maand/worker/%s" .WorkerIP) "postgres_allocation_index" }} for per-worker metadata from build.

Prometheus scrape configs

Jobs with _prometheus/scrape.yaml or scrape.yaml.tpl store unexpanded configs in KV at build. Template scrape files are rendered at build with job-level context (.Job, get, getSecret — not scrapeConfigs or .WorkerIP). {{ scrapeConfigs }} expands maand:port/* placeholders when the prometheus job is staged.

workspace/jobs/prometheus/prometheus.yml.tpl:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ['127.0.0.1:9090']
{{ scrapeConfigs }}

See prometheus.md for _prometheus/ layout, alerts, runbooks, and dashboards.

Secrets in templates

Use getSecret for values written by hooks (put_job_secret). Do not commit secrets in the workspace.

password = {{ getSecret "db_password" }}

Common errors

Debugging: debugging-deploy.md.