147 lines
8.0 KiB
Markdown
147 lines
8.0 KiB
Markdown
|
|
# Main-relative secrets directories
|
||
|
|
|
||
|
|
## Motivation and baseline
|
||
|
|
|
||
|
|
Applications can use `SearchConfig` to select their main configuration file
|
||
|
|
during a load. They can also call `LoadSecretsIntoEnvironment` during startup,
|
||
|
|
but that helper takes a native directory path before the load begins. A relative
|
||
|
|
argument uses the process working directory. Using a directory beside the
|
||
|
|
discovered file therefore requires the application to take over main-file
|
||
|
|
selection or perform a preliminary load. [Configuration discovery](../config.md#configuration-discovery) · [Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap)
|
||
|
|
|
||
|
|
ConfigKit already carries the selected main's filesystem context into layered
|
||
|
|
loading. It resolves effective typed `Secret` references after application
|
||
|
|
resolution and before final validation. Those two points provide the base for
|
||
|
|
the directory and the set of credential names to read. [Main-relative contexts](../adr/0022-main-relative-context.md) · [Typed secret references](../config.md#typed-secret-references)
|
||
|
|
|
||
|
|
## Target behavior
|
||
|
|
|
||
|
|
### Declaration and path resolution
|
||
|
|
|
||
|
|
An application opts in through Go when calling `Load` or `LoadLayered`. The
|
||
|
|
selected main document supplies one relative directory through its root control
|
||
|
|
mapping. For example, the following declaration in `/etc/demo/config.yml`
|
||
|
|
selects `/etc/demo/secrets` when discovery selects that main file.
|
||
|
|
|
||
|
|
```yaml
|
||
|
|
config:
|
||
|
|
secrets_dir: secrets
|
||
|
|
|
||
|
|
api_key: DEMO_API_KEY
|
||
|
|
```
|
||
|
|
|
||
|
|
Interpret the declaration at the main document's root before placement and
|
||
|
|
composition. Diagnose a declaration used without opt-in or in an unsupported
|
||
|
|
source-control context. Nested application data follows the existing
|
||
|
|
`config` rules. The location comes from the main document even when an import,
|
||
|
|
overlay, CLI override, default, or application resolution supplies the final
|
||
|
|
credential name. Environment lookup alone applies when there is no declaration,
|
||
|
|
including when an optional search finds no main file.
|
||
|
|
|
||
|
|
Resolve the directory from the selected main file's canonical base within its
|
||
|
|
existing filesystem root. For a discovered symlink, the base is the selected
|
||
|
|
file's canonical target directory. Parent-relative paths follow the same
|
||
|
|
containment rule as other main-relative inputs. The declaration must be a
|
||
|
|
nonempty relative path and requires a usable main-file context. Keep the
|
||
|
|
declaration and any diagnostics in source-local coordinates. [Document-root controls](../adr/0020-document-root-controls.md) · [Layered loading](../config.md#layered-loading)
|
||
|
|
|
||
|
|
### Lookup within a load
|
||
|
|
|
||
|
|
The usual opt-in mode checks the environment first. A present variable wins,
|
||
|
|
including an empty one, which produces the existing empty-secret failure. For
|
||
|
|
an unset variable, read the file whose name matches the effective typed
|
||
|
|
`Secret` reference. The directory is accessed only if a reference needs a file.
|
||
|
|
|
||
|
|
An application can also select file-first lookup for a load. An absent file
|
||
|
|
allows environment lookup. A file that is present but unreadable or invalid
|
||
|
|
produces a safe diagnostic, and an empty file follows the existing rule that a
|
||
|
|
resolved credential must be nonempty. If neither source supplies a credential,
|
||
|
|
report the failure at the affected configuration field.
|
||
|
|
|
||
|
|
Resolve surviving references at the existing secret-resolution step and share
|
||
|
|
the lookup result for repeated names within that load. Use the existing
|
||
|
|
secret-file checks, content rules, and per-file and cumulative byte limits for
|
||
|
|
the files read. Exact-name lookup leaves unrelated directory entries alone.
|
||
|
|
Close library-owned handles during the load. Final validation sees the
|
||
|
|
resolved credentials, with byte access through `Secret.Value()`. Inspection
|
||
|
|
can distinguish the environment and a file as the credential provider while
|
||
|
|
keeping credential bytes outside diagnostics, history, and effective YAML.
|
||
|
|
|
||
|
|
### Explicit startup export
|
||
|
|
|
||
|
|
Applications that start SDKs or subprocesses which read the environment can
|
||
|
|
explicitly request file-first loading and environment export. This is a
|
||
|
|
startup operation distinct from the ordinary load entry points. Go code
|
||
|
|
authorizes writes and overwrites. The main-file declaration selects the
|
||
|
|
directory.
|
||
|
|
|
||
|
|
Complete configuration loading and validation before writing to the process
|
||
|
|
environment. Export the values of the file-backed effective references used
|
||
|
|
by that successful load, once per name. Each successful write sets the
|
||
|
|
variable to the same value used by the returned configuration. If a file is
|
||
|
|
absent and lookup uses an existing environment value, leave that variable alone.
|
||
|
|
Invoke this operation during startup before starting concurrent work. It runs
|
||
|
|
synchronously and reports successful writes and partial failures without
|
||
|
|
credential bytes, following the existing bootstrap reporting model. ConfigKit
|
||
|
|
does not roll back earlier writes when a later write fails.
|
||
|
|
|
||
|
|
Ordinary `Load` and `LoadLayered` resolve credentials for their own results
|
||
|
|
without writing to the environment. The existing
|
||
|
|
`LoadSecretsIntoEnvironment(directory)` remains the explicit startup helper
|
||
|
|
for callers supplying a directory independently. [Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Secret references and explicit bootstrap](../adr/0004-secret-references-and-explicit-bootstrap.md)
|
||
|
|
|
||
|
|
## Work needed
|
||
|
|
|
||
|
|
- Extend main-document control parsing and the public load options to capture
|
||
|
|
the opted-in declaration and bind it to the main context already obtained
|
||
|
|
during acquisition. Carry the binding into secret resolution without another
|
||
|
|
search or parse.
|
||
|
|
- Reuse the secret-file reading and validation rules for exact-name lookup.
|
||
|
|
Extend the operation-local lookup to report value-free filesystem failures
|
||
|
|
and retain the provider for inspection separately from configuration value
|
||
|
|
provenance.
|
||
|
|
- Add the explicit startup operation around the shared load lifecycle. Use the
|
||
|
|
resolved file values for export and reuse the bootstrap reporting semantics
|
||
|
|
where they fit.
|
||
|
|
- Verify discovery from a different working directory, canonical main paths,
|
||
|
|
declaration scope, both lookup orders, and effective references after
|
||
|
|
composition and application resolution. Cover unused and missing files,
|
||
|
|
empty values, read errors, safe inspection, and startup export after
|
||
|
|
validation, including partial writes and absence of writes on a failed load.
|
||
|
|
Use disposable credential values and deterministic failure seams in line
|
||
|
|
with the [testing policy](../policy/testing.md).
|
||
|
|
- Document the resulting contract and a consumer startup example. Record the
|
||
|
|
architectural decision to add file-backed resolution and explicit startup
|
||
|
|
export alongside ADR 0004, and align the current architecture and component
|
||
|
|
documentation when the feature lands.
|
||
|
|
|
||
|
|
## Open Decisions
|
||
|
|
|
||
|
|
### Startup API and export failure reporting
|
||
|
|
|
||
|
|
**Recommendation.** Provide explicit startup entry points corresponding to
|
||
|
|
ordinary and layered loading, backed by the same load implementation. Return
|
||
|
|
the configuration outcome and the export report so callers can distinguish a
|
||
|
|
failed load from a successful load followed by an environment write failure.
|
||
|
|
The successful load's private file values can be handed directly to export
|
||
|
|
within the call, which keeps the application flow short and the lifetime of
|
||
|
|
those values local to the startup operation.
|
||
|
|
|
||
|
|
**Alternative.** Export from a successfully returned result through a separate
|
||
|
|
explicit call. This gives applications control over when to perform the writes
|
||
|
|
and avoids a parallel pair of load entry points. It requires a result contract
|
||
|
|
for retaining the original file-backed assignments or defining how later
|
||
|
|
application edits to the result affect export.
|
||
|
|
|
||
|
|
### Filesystem scope
|
||
|
|
|
||
|
|
**Recommendation.** Support discovered and explicitly selected host files
|
||
|
|
first, including their existing main-root options. These cover the requested
|
||
|
|
deployment pattern and allow reuse of the existing native secret-file checks.
|
||
|
|
|
||
|
|
**Alternative.** Support caller-supplied filesystems with a usable main-file
|
||
|
|
context in the same change. This aligns with companion inputs and supports
|
||
|
|
virtual filesystems. It requires an explicit decision about file-type and
|
||
|
|
symlink handling where a caller filesystem exposes different metadata or
|
||
|
|
access capabilities.
|