KV namespaces and variables

Practical guide to global, worker, job, and allocation KV — what keys exist, how to set them, and how to use them in templates and hooks.

Maand stores configuration in a KV store (SQLite key_value table). Values are grouped into namespaces. Think in four layers:

Read values with maand cat kv, templates (get), or hooks (maand.kv.get).
Write user config via workspace files or hooks — not by editing maand.db.

Persistence and purge: persistence.md · Index: README.md.

Namespace map

GLOBAL
  maand/bucket                   ← build: bucket_id, jobs, activejobs, job port names (active allocations)
  vars/bucket                    ← bucket.conf (your keys)

WORKER
  maand/worker                   ← build: per-label worker lists, CA cert
  maand/worker/<ip>              ← build: one host’s metadata
  maand/worker/<ip>/tags/<key>   ← build: workers.json tags

JOB
  maand/job/<job>                ← build: catalog metadata (synced)
  maand/prometheus               ← build: scrape catalog only (when prometheus server job exists)
  vars/bucket/job/<job>          ← vars.conf + bucket.jobs*.conf (synced)
  vars/job/<job>                 ← hooks only (merge, not wiped)
  secrets/job/<job>              ← hooks only (encrypted)

ALLOCATION (job on one worker)
  maand/job/<job>/worker/<ip>    ← build + deploy: certs, peers

Build-owned vs user-owned

Global (bucket) variables

vars/bucket — your bucket-wide settings

Source: workspace/bucket.conf (TOML).

port_range = "30000,39999"
environment = "production"
log_level = "info"

After maand build, every key lands in vars/bucket.

maand cat kv get vars/bucket environment
# production

Use in templates:

{{ get "vars/bucket" "log_level" }}

maand/bucket — system global metadata

Source: build (not edited directly).

maand cat kv get maand/bucket bucket_id
maand cat kv get maand/bucket api_http_port

Port numbers live only in maand/bucket. Use get "maand/bucket" "<port_name>" in templates and hooks (including cross-job reads; no demands required).

Worker variables

maand/worker/<ip> — one host

Source: workspace/workers.json + allocation state at build.

Example workers.json:

[
  {
    "host": "10.0.0.1",
    "hostname": "node-a",
    "labels": ["worker", "api"],
    "memory": "8192 mb",
    "cpu": "4000 mhz",
    "tags": { "zone": "us-east-1a", "rack": "r1" }
  }
]

maand cat kv get maand/worker/10.0.0.1 hostname
maand cat kv get maand/worker/10.0.0.1/tags zone

maand/worker — shared across workers (by label)

Source: build aggregates workers per label.

maand cat kv get maand/worker api_workers
# 10.0.0.1,10.0.0.2

Job variables

Three namespaces serve different purposes.

maand/job/<job> — catalog metadata (build)

Source: manifest.json, allocations, resource limits.

maand cat kv --jobs api
maand cat kv get maand/job/api workers
maand cat kv get maand/bucket api_http_port

Template (port from global namespace):

{{ get "maand/bucket" "api_http_port" }}

vars/bucket/job/<job> — job config from workspace

Sources:

1. workspace/jobs/<job>/vars.conf — checked in with the job; fully synced at build.
2. workspace/bucket.jobs.conf (or bucket.jobs.<env>.conf when job_config_selector is set) — bucket overrides per job; wins on key conflict.

# workspace/jobs/api/vars.conf
cluster_name = "prod-east"
feature_flags = "tls,v2"

# workspace/bucket.jobs.conf
[api]
memory = "512 mb"
cpu = "1500 mhz"
replicas_hint = "3"

memory / cpu from bucket.jobs*.conf also drive maand/job/api reservation fields. Other keys are KV-only.

Rebuild replaces the namespace from the merged file contents; keys removed from vars.conf are deleted from KV.

maand cat kv get vars/bucket/job/api cluster_name
maand cat kv get vars/bucket/job/api replicas_hint

See resources-and-placement.md.

vars/job/<job> — runtime config from hooks

Source: hooks — put_job_variable / maand.kv.put in hooks.

# _hooks/hook_setup.py (e.g. post_build)
import maand

def main():
    maand.put_job_variable("schema_version", "12")

Rebuild does not delete hook-written keys.

maand cat kv get vars/job/api schema_version

Template:

{{ get "vars/bucket/job/api" "cluster_name" }}
{{ get "vars/job/api" "schema_version" }}

secrets/job/<job> — encrypted secrets

Write only from hooks (put_job_secret). Read with getSecret in templates or the runtime API.

maand.put_job_secret("db_password", "s3cret")

maand cat kv get --reveal secrets/job/api db_password

Never put secrets in vars.conf or the workspace.

Allocation variables (job × worker)

Namespace: maand/job/<job>/worker/<ip>

Target deploy version is not stored here — use job-level maand/job/<job>/version, catalog fields in maand cat deployments, or template context .NewVersion / CURRENT_VERSION / NEW_VERSION in hooks.

maand cat kv get maand/job/api/worker/10.0.0.1 peer_workers
maand cat kv get maand/job/api/worker/10.0.0.1 api_allocation_index

Template (rendered per allocation):

{{ .NewVersion }}

Use template context .WorkerIP so one .tpl works on every worker:

{
  "peers": "{{ get (printf "maand/job/api/worker/%s" .WorkerIP) "peer_workers" }}",
  "target_version": "{{ .NewVersion }}"
}

End-to-end example

Layout

workspace/
├── bucket.conf
├── bucket.jobs.conf
├── workers.json
└── jobs/
    └── api/
        ├── manifest.json
        ├── vars.conf
        ├── Makefile
        └── config.json.tpl

bucket.conf

environment = "staging"
port_range = "30000,39999"

workers.json

[
  { "host": "10.0.0.1", "labels": ["worker", "api"], "memory": "4096 mb", "cpu": "2000 mhz" },
  { "host": "10.0.0.2", "labels": ["worker", "api"], "memory": "4096 mb", "cpu": "2000 mhz" }
]

manifest.json

{
  "version": "1.2.0",
  "selectors": ["worker", "api"],
  "resources": {
    "memory": { "min": "256 mb", "max": "1 gb" },
    "ports": { "api_http_port": {} }
  }
}

bucket.jobs.conf

[api]
memory = "512 mb"

vars.conf

service_name = "api-gateway"

config.json.tpl

{
  "env": "{{ get "vars/bucket" "environment" }}",
  "service": "{{ get "vars/bucket/job/api" "service_name" }}",
  "listen": "{{ get "maand/bucket" "api_http_port" }}",
  "peers": "{{ get (printf "maand/job/api/worker/%s" .WorkerIP) "peer_workers" }}",
  "version": "{{ .NewVersion }}"
}

Build and inspect

maand build

maand cat kv get vars/bucket environment          # staging
maand cat kv get maand/job/api workers              # 10.0.0.1,10.0.0.2
maand cat kv get vars/bucket/job/api service_name          # api-gateway
maand cat kv get maand/worker/10.0.0.1 worker_memory_mb
maand cat kv get maand/job/api/worker/10.0.0.1 peer_workers   # 10.0.0.2

Deploy renders config.json.tpl per worker using that worker’s allocation namespace, then rsyncs to /opt/worker/<bucket_id>/jobs/api/.

Runtime update from a hook (pre_deploy):

import maand

def main():
    maand.put_job_variable("deployed_at", maand.env("EVENT"))

Persisted when deploy checkpoints KV for that job.

Quick reference: where to put config

Inspecting KV

maand cat kv                              # all namespaces (truncated values)
maand cat kv --jobs api                   # job-related namespaces
maand cat kv --jobs api --workers 10.0.0.1
maand cat kv --active                     # latest non-deleted versions only
maand cat kv get maand/job/api version
maand cat kv get --reveal secrets/job/api my_secret

Related

• persistence.md — persistence, purge, access control
• templates.md — get, getSecret, template context
• hook-api.md — runtime API for reads/writes
• configuration.md — bucket.conf, bucket.jobs.conf, vars.conf