45 lines
2.2 KiB
Markdown
45 lines
2.2 KiB
Markdown
# ADR 0004: Use secret references and explicit environment bootstrap
|
|
|
|
Status: accepted
|
|
|
|
Date: 2026-09-06
|
|
|
|
## Context
|
|
|
|
Consumers need credentials without storing them in YAML and need a consistent
|
|
way to load locally provisioned secret files. WeatherReporter already implements
|
|
useful directory-loading code. Ordinary configuration loading must remain free
|
|
of implicit process mutation, and operators must understand blocked secret files.
|
|
|
|
## Decision
|
|
|
|
Represent secrets as ConfigKit-owned typed references to environment-variable
|
|
names. Resolve only surviving references; retain names, never credentials, in
|
|
configuration trees and inspection. Offer directory bootstrap as a separate,
|
|
explicit startup operation, reusing WeatherReporter code where applicable.
|
|
Existing environment variables win even when empty. Report skipped files and
|
|
partial failures without values. Keep bootstrap provenance separate from later
|
|
lookup provenance rather than imply an unchanged environment between calls.
|
|
General environment-variable configuration overlays are not on the roadmap.
|
|
The [current reference contract](../config.md#typed-secret-references) and
|
|
[bootstrap contract](../config.md#explicit-secrets-directory-bootstrap) own the
|
|
implemented behavior.
|
|
|
|
## Alternatives considered
|
|
|
|
- Literal secrets or interpolated YAML: familiar but allows credentials into
|
|
configuration artifacts and expands conventions and redaction obligations.
|
|
- Application-only directory loaders: keeps process mutation outside the library
|
|
but preserves duplicated infrastructure and inconsistent skip/error semantics.
|
|
- Implicit bootstrap during loading: convenient but hides process mutation and
|
|
makes repeated or concurrent loads difficult to reason about.
|
|
- Directory values overriding existing environment: simple, but defeats explicit
|
|
deployment environment choices and obscures why a credential was selected.
|
|
|
|
## Consequences
|
|
|
|
Applications migrate secret fields, choose startup ordering, and retain bootstrap
|
|
reports. ConfigKit owns bounded loading, reference validation, safe reporting and
|
|
inspection; applications own credential use. No multi-variable transaction or
|
|
protection against concurrent process-environment mutation is promised.
|