Secret provider

A Secret provider abstracts where a type: genesissecret Manifest fetches secrets from. You declare providers in tazuna.yaml’s spec.providers[] and bind them by specifying that name in each GenesisSecret YAML’s spec.provider.

This page summarizes how the provider registry works and how to declare the two built-in providers, onepassword and envfile.

Registry basics

At startup the Runner assembles a provider registry. The registry contains two kinds of entries.

• Each provider declared in tazuna.yaml’s spec.providers[]
• The built-in default-op (for 1Password)

default-op is always registered in the registry and does not need to be declared. When a GenesisSecret’s spec.provider is an empty string, this default-op is chosen as the backward-compatibility fallback.

When you write a name in a GenesisSecret’s spec.provider, the provider is looked up from the provider registry by that name and used.

# GenesisSecret YAML
apiVersion: tazuna.pepabo.com/v1
kind: GenesisSecret
spec:
  provider: ops-envfile   # <- match this with spec.providers[].name in tazuna.yaml
  secrets:
    - uri: env://ignored
      items:
        DATABASE_URL:
          mapTo: DATABASE_URL
  outputs:
    - kubernetesSecret:
        namespace: default
        name: app-config

Declaring spec.providers[]

Write it in tazuna.yaml’s spec.providers[].

# tazuna.yaml
spec:
  providers:
    - name: primary-op
      type: onepassword
      onepassword: {}
    - name: ops-envfile
      type: envfile
      envfile:
        path: ./secrets/ops.env
  manifests:
    - name: app-config
      type: genesissecret
      path: ./genesissecrets/app-config.yaml

Config inconsistent with type (e.g. envfile: written even though type: onepassword) is rejected by validation.

type: onepassword

A provider that retrieves values from 1Password items. The built-in implementation calls the op CLI to pull values out. The onepassword additional config can currently be an empty object (the field is split out only to leave room for future extension).

spec:
  providers:
    - name: primary-op
      type: onepassword
      onepassword: {}

On the GenesisSecret side, write spec.secrets[].uri in the form op://<host>/<vault>/<item>. See GenesisSecret schema - uri format for details.

type: envfile

A provider that reads values from a local file in dotenv format (KEY=VALUE, one pair per line). It is useful for unit tests that don’t depend on 1Password, cases where you want to feed local secrets in CI, and situations right before bootstrap where 1Password authentication is not yet available.

spec:
  providers:
    - name: ops-envfile
      type: envfile
      envfile:
        path: ./secrets/ops.env

The contents of ./secrets/ops.env are one pair per line, as follows.

DATABASE_URL=postgres://localhost/app
API_TOKEN=ghp_xxx

On the GenesisSecret side, spec.secrets[].uri is not used (because envfile returns the key-values of a single file as-is). Make the keys of items match the key names in the envfile.

spec.provider resolution flow

The handling of a GenesisSecret’s spec.provider value is as follows.

If the referenced name does not exist in spec.providers[], apply fails with an error. At the tazuna check stage too, references to undefined names will be rejected by validation in the future.

Validation

During tazuna check and at the startup of each command, spec.providers[] is subject to the following checks.

• Each name must be unique.
• name must not be an empty string.
• name must not be default-op (a reserved name).
• type must be one of onepassword / envfile.
• There must be no config inconsistent with type (such as envfile: attached to type: onepassword).
• envfile.path is required when type: envfile.

Related

• The whole of GenesisSecret: GenesisSecret Schema
• The schema-side entry: tazuna.yaml - Providers
• Terminology: Provider (SecretProvider)