|
|
|
@@ -1,5 +1,10 @@
|
|
|
|
# Main-relative secrets directories
|
|
|
|
# Main-relative secrets directories
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Status: planned, not implemented. [ADR 0023](../adr/0023-explicit-configured-secrets-bootstrap.md)
|
|
|
|
|
|
|
|
supersedes ADR 0004 and records explicit configured bootstrap and optional
|
|
|
|
|
|
|
|
overwrite. The decisions below preserve ordinary loading without environment
|
|
|
|
|
|
|
|
writes and the existing direct-directory helper's Go signature.
|
|
|
|
|
|
|
|
|
|
|
|
## Motivation and baseline
|
|
|
|
## Motivation and baseline
|
|
|
|
|
|
|
|
|
|
|
|
Applications can use `SearchConfig` to select their main configuration file
|
|
|
|
Applications can use `SearchConfig` to select their main configuration file
|
|
|
|
@@ -63,8 +68,10 @@ declaration and any diagnostics in source-local coordinates. [Document-root cont
|
|
|
|
### Companion helper and prepared main source
|
|
|
|
### Companion helper and prepared main source
|
|
|
|
|
|
|
|
|
|
|
|
The companion accepts the main `Source`, including a `SearchConfig` source,
|
|
|
|
The companion accepts the main `Source`, including a `SearchConfig` source,
|
|
|
|
and returns a secrets report and a prepared main source. The public name and
|
|
|
|
and returns a secrets report and a prepared main source. Its options accept an
|
|
|
|
option type below are illustrative.
|
|
|
|
explicit host `FilesystemContext` for main preparation and an optional overwrite
|
|
|
|
|
|
|
|
choice. Represent overwrite as `*bool`: nil defers to YAML, while a supplied
|
|
|
|
|
|
|
|
false or true takes precedence. The public names below are illustrative.
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
main := configkit.SearchConfig("demo", search)
|
|
|
|
main := configkit.SearchConfig("demo", search)
|
|
|
|
@@ -83,6 +90,15 @@ contents with the selected file's identity and filesystem context so the later
|
|
|
|
load consumes that same main document. Keep its remaining controls, including
|
|
|
|
load consumes that same main document. Keep its remaining controls, including
|
|
|
|
imports and collection declarations, available to normal loading.
|
|
|
|
imports and collection declarations, available to normal loading.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Apply the supplied host context using the existing main-file root rules during
|
|
|
|
|
|
|
|
preparation. Without an explicit context, derive the usual context from the
|
|
|
|
|
|
|
|
selected main file. Capture the resolved canonical base and containment root
|
|
|
|
|
|
|
|
with the document. Later loading uses that captured context when no explicit
|
|
|
|
|
|
|
|
context is supplied. An explicit later context must resolve to the same context;
|
|
|
|
|
|
|
|
diagnose an incompatible context rather than silently rebinding the prepared
|
|
|
|
|
|
|
|
source. A caller needing a different root prepares the original source again.
|
|
|
|
|
|
|
|
This rule applies to ordinary loading options and layered main `Input` alike.
|
|
|
|
|
|
|
|
|
|
|
|
The helper prepares only the main document. Composition, import acquisition,
|
|
|
|
The helper prepares only the main document. Composition, import acquisition,
|
|
|
|
inheritance, typed decoding, application resolution, secret lookup, and
|
|
|
|
inheritance, typed decoding, application resolution, secret lookup, and
|
|
|
|
validation run through the subsequent ordinary or layered load. Main
|
|
|
|
validation run through the subsequent ordinary or layered load. Main
|
|
|
|
@@ -91,27 +107,57 @@ Source records, diagnostics, placements, imports, and main-relative companions
|
|
|
|
use the selected main's identity and context.
|
|
|
|
use the selected main's identity and context.
|
|
|
|
|
|
|
|
|
|
|
|
Release library-owned file handles before the helper returns, including on
|
|
|
|
Release library-owned file handles before the helper returns, including on
|
|
|
|
error. Prepared sources retain captured document data and passive filesystem
|
|
|
|
error. Prepared sources are reusable snapshots of the main contents, with
|
|
|
|
context and follow the source reuse contract without sharing mutable load
|
|
|
|
passive filesystem context and no shared mutable load state. Reusing one neither
|
|
|
|
state. Later imports and resources observe the filesystem when accessed. A
|
|
|
|
rediscovers nor rereads the main file and does not repeat bootstrap. This differs
|
|
|
|
later load reads the environment at its normal secret-resolution step.
|
|
|
|
from reusing the original `File` or `SearchConfig` source. Later imports and
|
|
|
|
|
|
|
|
resources observe the filesystem when accessed. A later load reads the environment
|
|
|
|
|
|
|
|
at its normal secret-resolution step. Each load accounts for the captured main
|
|
|
|
|
|
|
|
under its normal source limits and creates its own source and inspection records.
|
|
|
|
[Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Source resource contexts](../config.md#source-resource-contexts)
|
|
|
|
[Complete-on-return loading](../adr/0008-complete-on-return-loading.md) · [Source resource contexts](../config.md#source-resource-contexts)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### Preparation failures and return values
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use the existing error families at their respective boundaries. Discovery,
|
|
|
|
|
|
|
|
main-file acquisition, YAML parsing, bootstrap-control validation, and preparation
|
|
|
|
|
|
|
|
context failures return `LoadError` with applicable source records and source-local
|
|
|
|
|
|
|
|
diagnostics. Secret-directory inspection, reads, and environment writes return
|
|
|
|
|
|
|
|
`SecretsError` with the existing safe diagnostics. Do not introduce another error
|
|
|
|
|
|
|
|
or reporting framework.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Return a secrets report on every attempt. Before directory processing begins,
|
|
|
|
|
|
|
|
it has no entries; after processing begins, it retains the entries and outcomes
|
|
|
|
|
|
|
|
observed so far. On any error, return a zero, unusable prepared `Source`. Earlier
|
|
|
|
|
|
|
|
environment writes remain reported and are not rolled back. A caller must handle
|
|
|
|
|
|
|
|
the failure before attempting configuration loading.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
On success, return a reusable prepared source, including when no directory was
|
|
|
|
|
|
|
|
declared. Optional search exhaustion returns the absent-main source and an empty
|
|
|
|
|
|
|
|
report. Preparation validates YAML and the bootstrap settings needed for its
|
|
|
|
|
|
|
|
operation; it does not claim the later configuration load will succeed. Normal
|
|
|
|
|
|
|
|
version checks, composition, decoding, and application validation remain in that
|
|
|
|
|
|
|
|
load. A later incompatible-context error is a loading error and does not undo
|
|
|
|
|
|
|
|
bootstrap writes.
|
|
|
|
|
|
|
|
|
|
|
|
### Shared bootstrap and overwrite behavior
|
|
|
|
### Shared bootstrap and overwrite behavior
|
|
|
|
|
|
|
|
|
|
|
|
Extend the existing direct-directory helper with an optional named Boolean
|
|
|
|
Keep `LoadSecretsIntoEnvironment(string) (*SecretsReport, error)` unchanged,
|
|
|
|
option, keeping existing calls valid. The option type name in this example is
|
|
|
|
including its nonvariadic function type and preservation behavior. Add a separately
|
|
|
|
provisional.
|
|
|
|
named options-bearing helper for explicit overwrite. Changing the existing helper
|
|
|
|
|
|
|
|
to accept variadic options would preserve ordinary calls but break assignments to
|
|
|
|
|
|
|
|
its existing function type. The new public names below are provisional.
|
|
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
```go
|
|
|
|
report, err := configkit.LoadSecretsIntoEnvironment("/etc/demo/secrets")
|
|
|
|
report, err := configkit.LoadSecretsIntoEnvironment("/etc/demo/secrets")
|
|
|
|
report, err = configkit.LoadSecretsIntoEnvironment(
|
|
|
|
report, err = configkit.LoadSecretsIntoEnvironmentWithOptions(
|
|
|
|
"/etc/demo/secrets",
|
|
|
|
"/etc/demo/secrets",
|
|
|
|
configkit.SecretsOptions{Overwrite: true},
|
|
|
|
configkit.SecretsOptions{Overwrite: true},
|
|
|
|
)
|
|
|
|
)
|
|
|
|
```
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
Both helpers use the same directory-bootstrap implementation. With overwrite
|
|
|
|
The existing helper, options-bearing helper, and main-config companion use the
|
|
|
|
|
|
|
|
same directory-bootstrap implementation. The direct helper's Boolean option
|
|
|
|
|
|
|
|
defaults to false; it has no YAML policy to override. With overwrite
|
|
|
|
disabled, existing variables win, including empty ones, with presence checked
|
|
|
|
disabled, existing variables win, including empty ones, with presence checked
|
|
|
|
again immediately before application as today. With overwrite enabled,
|
|
|
|
again immediately before application as today. With overwrite enabled,
|
|
|
|
eligible files are read even for existing variables and their values replace
|
|
|
|
eligible files are read even for existing variables and their values replace
|
|
|
|
@@ -136,7 +182,7 @@ environment transaction guarantees continues to apply.
|
|
|
|
|
|
|
|
|
|
|
|
Keep bootstrap reporting separate from the subsequent configuration's secret
|
|
|
|
Keep bootstrap reporting separate from the subsequent configuration's secret
|
|
|
|
lookup evidence. Each operation describes what it observed and performed.
|
|
|
|
lookup evidence. Each operation describes what it observed and performed.
|
|
|
|
[Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap) · [Secret references and explicit bootstrap](../adr/0004-secret-references-and-explicit-bootstrap.md)
|
|
|
|
[Secrets bootstrap](../config.md#explicit-secrets-directory-bootstrap) · [Explicit configured bootstrap](../adr/0023-explicit-configured-secrets-bootstrap.md)
|
|
|
|
|
|
|
|
|
|
|
|
### Filesystem scope
|
|
|
|
### Filesystem scope
|
|
|
|
|
|
|
|
|
|
|
|
@@ -152,23 +198,29 @@ later extension requiring decisions about file-type and symlink capabilities.
|
|
|
|
bootstrap. Retain source-local positions for diagnostics.
|
|
|
|
bootstrap. Retain source-local positions for diagnostics.
|
|
|
|
- Factor main-file selection and capture for use by the companion helper and
|
|
|
|
- Factor main-file selection and capture for use by the companion helper and
|
|
|
|
normal acquisition. Add a prepared-source handoff with retained main contents,
|
|
|
|
normal acquisition. Add a prepared-source handoff with retained main contents,
|
|
|
|
identity, context, and ownership. Select an API for supplying applicable
|
|
|
|
identity, context, and ownership. Supply the preparation filesystem context and
|
|
|
|
main-root constraints and representing an absent or explicit Go overwrite
|
|
|
|
optional Go overwrite choice as described above. Preserve per-load accounting,
|
|
|
|
choice, including `false`.
|
|
|
|
diagnose incompatible later contexts, and implement the failure/return contract.
|
|
|
|
- Add the optional overwrite setting to direct-directory bootstrap and reuse
|
|
|
|
- Preserve the current direct-directory signature and add a separately named
|
|
|
|
that operation from the companion helper, with matching reports and failures.
|
|
|
|
options-bearing helper. Reuse directory bootstrap from all three entry points,
|
|
|
|
|
|
|
|
with matching reports and failures. Finalize public names during implementation.
|
|
|
|
- Verify discovery from a different working directory, canonical main paths,
|
|
|
|
- Verify discovery from a different working directory, canonical main paths,
|
|
|
|
optional search exhaustion, declaration scope, default and explicit
|
|
|
|
optional search exhaustion, declaration scope, default and explicit
|
|
|
|
overwrite choices, Go-over-YAML precedence, and both helper interfaces.
|
|
|
|
overwrite choices, Go-over-YAML precedence, and all helper interfaces. Include
|
|
|
|
|
|
|
|
assignment of the unchanged helper to its existing function type.
|
|
|
|
Cover empty values, dot entries, read failures before writes, and partial
|
|
|
|
Cover empty values, dot entries, read failures before writes, and partial
|
|
|
|
write failures. Verify bootstrap includes entries unused by typed fields and
|
|
|
|
write failures. Verify bootstrap includes entries unused by typed fields and
|
|
|
|
that later load failures preserve bootstrap effects.
|
|
|
|
that later load failures preserve bootstrap effects.
|
|
|
|
- Verify prepared-source reuse, handle cleanup, normal loading without
|
|
|
|
- Verify error types, empty and partial reports, and unusable prepared sources on
|
|
|
|
|
|
|
|
failure. Cover absent-main success and failed later loads without rollback.
|
|
|
|
|
|
|
|
- Verify prepared-source reuse after main-file changes and discovery changes,
|
|
|
|
|
|
|
|
live later imports and environment lookup, equivalent and incompatible later
|
|
|
|
|
|
|
|
contexts, handle cleanup, normal loading without
|
|
|
|
environment writes, and agreement with selected-file provenance, placement,
|
|
|
|
environment writes, and agreement with selected-file provenance, placement,
|
|
|
|
relative imports, and main-relative companions. Use disposable credential
|
|
|
|
relative imports, and main-relative companions. Use disposable credential
|
|
|
|
values and deterministic failure seams in line with the
|
|
|
|
values and deterministic failure seams in line with the
|
|
|
|
[testing policy](../policy/testing.md).
|
|
|
|
[testing policy](../policy/testing.md).
|
|
|
|
- Document the startup workflow and add a consumer example. Record the prepared
|
|
|
|
- Document the startup workflow and add a consumer example. Implement the
|
|
|
|
main-source handoff and optional overwrite policy in an ADR referencing
|
|
|
|
ownership decision in ADR 0023 and update the canonical configuration contract,
|
|
|
|
ADR 0004, and update the canonical configuration contract and affected
|
|
|
|
public source documentation, and affected component documentation when the
|
|
|
|
architecture and component documentation when implemented.
|
|
|
|
behavior lands. Retire the roadmap reference in architecture policy at that time.
|
|
|
|
|