GenesisSecret Schema

GenesisSecret is a declaration for retrieving secret values from an external secret store (currently 1Password) and generating them as Kubernetes Secrets.

GenesisSecret is not a Kubernetes CRD but a YAML schema that Tazuna reads. No GenesisSecret resource appears in the cluster; the applied result is a Secret.

From tazuna.yaml, it is referenced as a Manifest with type: genesissecret.

# tazuna.yaml
spec:
  manifests:
    - name: aws-credentials
      type: genesissecret
      path: ./genesissecrets/aws.yaml

The path for type: genesissecret points directly to a single YAML file (unlike other Manifest types that point to a directory).

Root (`GenesisSecret`)

Field	Type	Required	Default	Description
`apiVersion`	string	-	-	Indicates the schema version. The value is currently not validated.
`kind`	string	-	-	Indicates the resource kind. The value is currently not validated.
`spec`	GenesisSecretSpec	Yes	-	The GenesisSecret body.

There is no struct field corresponding to apiVersion / kind; writing them is ignored without being read. By convention, writing apiVersion: tazuna.pepabo.com/v1 / kind: GenesisSecret makes it easier to align if validation is added later.

GenesisSecretSpec

Field	Type	Required	Default	Description
`provider`	string	-	`""`	Specifies the Provider to retrieve from. The current Manager does not reference the value. The Provider for the entire Tazuna run (the 1Password implementation) is determined at `tazuna apply` startup.
`secrets`	[GenesisSecretGenerate]	Yes	-	Retrieval targets. Multiple may be written.
`outputs`	[GenesisSecretOutput]	Yes	-	Output destinations. Multiple may be written.

GenesisSecretGenerate

Each element of secrets[]. Represents one “Provider-side item.”

Field	Type	Required	Default	Description
`uri`	string	Yes	-	URI pointing to the Provider item. See `uri` format for details.
`items`	map<string, GenesisSecretGenerateItem>	Yes	-	Mapping from keys returned by the Provider to keys in the output Secret.
`preferLabel`	bool	-	`false`	Whether to key the fields returned by the Provider by label name. When `false`, they are keyed by ID (which may be a random string). Set to `true` when you want to write human-assigned field names from 1Password as `items` keys.

`uri` Format

In the 1Password Provider, the url.Parse result is interpreted with the first path segment as the vault name and the second as the item name. The scheme and host are not used in the current version.

tazuna secret-to-genesissecret writes them out in this form when auto-generating:

op://<op-host>/<vault>/<item>

Example:

uri: op://example.1password.com/Platform/aws-credentials

The scheme and host pass parsing but are not referenced. Think of them as space reserved for distinguishing between Providers in the future, and you are safe.

GenesisSecretGenerateItem

The structure corresponding to the values of the items map (keys are the Provider-returned field’s ID or label).

Field	Type	Required	Default	Description
`mapTo`	string	Yes	-	The `data` key name in the output Kubernetes Secret. The value retrieved from the Provider is stored under this key in the Secret.

Example:

items:
  accessKeyID:
    mapTo: AWS_ACCESS_KEY_ID
  secretAccessKey:
    mapTo: AWS_SECRET_ACCESS_KEY

The items key accessKeyID corresponds to the Provider-side field name (the label name when preferLabel: true), and mapTo becomes the key name in the Kubernetes Secret as-is. If the items key does not exist on the Provider side, an error is raised.

GenesisSecretOutput

Each element of outputs[]. Represents one “output destination.”

Field	Type	Required	Default	Description
`kubernetesSecret`	GenesisSecretOutputKubernetesSecret	Conditional (*)	`null`	Specify when the output destination is a Kubernetes Secret.
`stdout`	object	-	`null`	Defined in the schema but not supported in the current version. If `kubernetesSecret` is `null`, a runtime error is raised.

(*) In the current version, each element of outputs[] requires kubernetesSecret. While stdout exists structurally, if kubernetesSecret == nil, it fails with the error .spec.output currently supports only KubernetesSecret.

GenesisSecretOutputKubernetesSecret

Field	Type	Required	Default	Description
`namespace`	string	Yes	-	Namespace of the output Secret.
`name`	string	Yes	-	Name of the output Secret.
`labels`	map<string, string>	-	`null`	Labels added to the output Secret.
`annotations`	map<string, string>	-	`null`	Annotations added to the output Secret.
`type`	string	-	`Opaque`	The corev1 SecretType. An empty string is treated as `Opaque` (Kubernetes’s default `Opaque`, not strictly `kubernetes.io/opaque`). You can specify `kubernetes.io/tls` and so on.
`context`	string	-	`""`	Exists structurally but not referenced by the current Manager implementation. The output cluster is Tazuna’s overall current-context.

Resolution Flow

During tazuna apply, a type: genesissecret Manifest is processed as follows.

Read the YAML file pointed to by manifests[].path (relative to the directory of tazuna.yaml itself).
Pass each element of spec.secrets[] to the Provider and retrieve the field set.
Merge the results of all secrets[] into one map[string]string, renaming keys using items’s mapTo (if a key collides, the later one wins).
For each kubernetesSecret of spec.outputs[], CreateOrUpdate a Kubernetes Secret with the specified namespace / name.
- The merged map goes into StringData as-is.
- labels / annotations / type are set as declared.

On tazuna destroy, the same Provider retrieval runs, and the Secrets identified by outputs[].kubernetesSecret’s namespace / name are deleted.

On tazuna build, only one Secret YAML (corresponding to outputs[0].kubernetesSecret) is written to stdout (even if multiple outputs are declared, only the first is targeted by build).

State and always-sync

Secrets generated from GenesisSecret are always classified as always-sync in tazuna state diff. They are not targets of ContentHash-based diffing; the Provider side is the source of truth and they are synchronized every time. See Diff type / always-sync for details.

Examples

Minimal example:

apiVersion: tazuna.pepabo.com/v1
kind: GenesisSecret
spec:
  secrets:
    - uri: op://example.1password.com/Platform/aws-credentials
      preferLabel: true
      items:
        accessKeyID:
          mapTo: AWS_ACCESS_KEY_ID
        secretAccessKey:
          mapTo: AWS_SECRET_ACCESS_KEY
  outputs:
    - kubernetesSecret:
        namespace: default
        name: aws-credentials

Example outputting type: kubernetes.io/tls:

apiVersion: tazuna.pepabo.com/v1
kind: GenesisSecret
spec:
  secrets:
    - uri: op://example.1password.com/Platform/tls-wildcard
      preferLabel: true
      items:
        certificate:
          mapTo: tls.crt
        privateKey:
          mapTo: tls.key
  outputs:
    - kubernetesSecret:
        namespace: ingress-nginx
        name: wildcard-tls
        type: kubernetes.io/tls
        labels:
          managed-by: tazuna

Reference from tazuna.yaml: tazuna.yaml manifest-type-specific fields
Provider terminology: Provider (SecretProvider)
Write an existing Secret out to 1Password and GenesisSecret: tazuna secret-to-genesissecret
Term: GenesisSecret

Keyboard shortcuts

Tazuna