Skip to content

🔐 Vault Objects — declaring the secrets a package needs

A Parts Config can declare, under vault_objects, the ConfigMaps and Secrets a package expects. Muppy turns each declaration into a Vault record it creates for you, seeded with the default values you wrote — and then leaves alone forever.

That last part is the whole point: the Parts Config declares what a deployment needs and a sensible starting content; the actual values are yours, edited in Muppy, and no redeployment ever overwrites them.

Declaring one

mpy_meta_config:
  vault_objects:
    - name: iksd
      scope: qualifier          # qualifier | instance
      type: secret              # secret | configmap
      default_values:
        cfgmap_type: envfile
        cfgmap_use_renderer: true
        cfgmap_file: |-
          # inouk_server_detect: IPs of the production servers.
          IKSD_PRODUCTION_SERVERS_IPS=

The name Muppy gives it

You never choose the Vault's code — Muppy builds it, and that is what makes the same declaration work across qualifiers and instances:

scope Generated code Shared by
qualifier {app_code}-{qualifier}-{type}-{name} every Release of that app in that qualifier
instance {app_code}-{qualifier}-{instance}-{type}-{name} that one Release

type: secret becomes k8s-secret in the code, type: configmap becomes cfgmap. A real example from a Muppy deployment: mpy18c-dev-k8s-secret-muppy-run-env.

Pick qualifier for anything that is a property of the environment — SMTP credentials, the IPs of your production servers. Pick instance for something genuinely specific to one deployment.

Life cycle — created once, never overwritten

This is the behaviour to internalise:

  1. At install, Muppy looks for a Vault whose code matches.
  2. If it does not exist, it is created, seeded from default_values.
  3. If it already exists, nothing happens. The Parts Config does not touch it — not its content, not its type, nothing.

So a Vault created this way is a plain local Muppy record. It carries no link back to the Parts Config, and editing it is safe: your values survive every later install, upgrade and Parts Config reload.

First install of a new qualifier

The first time you deploy into a qualifier, the Vault is created with the defaults — which for a value only you can know means an empty one. That install may well fail.

This is expected, and it is the normal way in:

  1. deploy, and let it fail
  2. open the Vault Muppy just created, fill in the value
  3. deploy again

Every subsequent install in that qualifier finds the Vault already filled and goes through.

Changing default_values afterwards has no effect on Vaults that already exist — it only changes what a new qualifier gets.

Where the values end up

A vault_objects entry reaches the pods, either as environment variables through a part's envFrom, or mounted as a file through volumes:

parts:
  gui:
    envFrom:
      - name: iksd
        secretRef:

Jobs do not read vault_objects

The database init and upgrade Jobs take their environment from the Package Profile fields DB 'init' Job ENV and DB 'upgrade' Job ENV, not from vault_objects. A variable that both the pods and the Jobs need must be declared on both sides — the Job Vault can pull it from another Vault with a renderer. The renderer runs in the Release's rendering context, so both vault_model and obj are available — which means a vault_objects code, though it varies per qualifier, can be computed rather than hard-coded:

IKB_SMTP_PASSWORD=@{ vault_model.get('muppy-signup-smtp').password }@

To read one variable out of a Vault created by vault_objects, use get_config_map_env_file_as_dict() — it reads cfgmap_file. Its twin get_env_vars_json() reads env_file and belongs to credential_type='envfile' Vaults; called on a secret or configmap one it returns an empty dict rather than failing.

See also