Keystore

Keystore #

The keystore is a node-local file of secrets referenced from pizza.yml — API keys and tokens never have to live in the config file itself. Entries resolve through ${keystore:NAME} references:

node:
  embedding:
    endpoints:
      - name: openai
        url: https://api.openai.com/v1/embeddings
        api_key: ${keystore:openai}

The file is <config dir>/keystore.json — next to the config file it serves, so one instance per config (multi-instance hosts keep separate keystores) and it never enters the data directory’s lifecycle. It is written 0600 and replaced atomically; entries never enter cluster metadata, raft logs, or API responses — views answer with a masked hint only (sk-…4f2a).

Keystore hot-reload

Keystore hot-reload #

Rotating a secret no longer restarts the node. ${keystore:...} references re-resolve into the running configuration on demand: console edits trigger the reload themselves, and out-of-band changes (a CLI edit, a replaced mounted Secret) are one call away.

curl -X POST http://127.0.0.1:28000/_node/_local/keystore/_reload \
  -H 'Authorization: Bearer pz_bootstrap_key'

The answer says exactly what happened — key names only, values stay write-only:

{
  "entries": 3,
  "read_only": false,
  "references": 2,
  "changed": ["node.embedding.endpoints", "catalog.join_token"],
  "unchanged": 0,
  "failed": []
}

A rotated embedding API key applies to the next inference call; a rotated catalog.join_token to the next join attempt. A reference whose entry disappeared keeps its running value and lands in failed until the entry returns — reload never aborts the node the way a missing entry aborts boot.