diff --git a/USAGEGUIDE.md b/USAGEGUIDE.md index 7cc205b9..b932aea3 100644 --- a/USAGEGUIDE.md +++ b/USAGEGUIDE.md @@ -16,8 +16,9 @@ 4. [Logging level](#logging-level) 5. [Usage examples](#usage-examples) 6. [How 1Password Items Map to Kubernetes Secrets](#how-1password-items-map-to-kubernetes-secrets) -7. [Configuring Automatic Rolling Restarts of Deployments](#configuring-automatic-rolling-restarts-of-deployments) -8. [Development](#development) +7. [Secret Templates](#secret-templates) +8. [Configuring Automatic Rolling Restarts of Deployments](#configuring-automatic-rolling-restarts-of-deployments) +9. [Development](#development) --- @@ -126,6 +127,76 @@ Titles and field names that include white space and other characters that are no --- +## Secret Templates + +By default, each field in a 1Password item maps directly to a key in the +Kubernetes Secret. **Secret templates** let you transform item data into custom +formats using [Go templates](https://pkg.go.dev/text/template) so that a +single `OnePasswordItem` can produce exactly the secret layout your application +expects. + +### Basic example + +```yaml +apiVersion: onepassword.com/v1 +kind: OnePasswordItem +metadata: + name: my-database-config +spec: + itemPath: "vaults/my-vault/items/my-db-item" + template: + data: + DSN: "postgresql://{{ .Fields.username }}:{{ .Fields.password }}@{{ .Fields.host }}:{{ .Fields.port }}/{{ .Fields.database }}" +``` + +Instead of creating a secret with individual keys for `username`, `password`, +`host`, `port`, and `database`, the operator creates a single `DSN` key whose +value is the rendered connection string. + +### Multiple keys + +You can define as many output keys as you need: + +```yaml +spec: + itemPath: "vaults/my-vault/items/my-item" + template: + data: + config.yaml: | + server: + username: {{ .Fields.username }} + password: {{ .Fields.password }} + DB_HOST: "{{ .Fields.host }}" +``` + +### Template context + +The following data is available inside templates: + +| Expression | Description | +|---|---| +| `{{ .Fields.