[Proposal] ${env:...} / ${file:...} interpolation in gateway config.toml

[renuka-fernando]

Summary

• Add ${env:NAME} / ${file:/path} interpolation to config.toml for the gateway-controller and policy-engine, with bash-style modifiers (:-default, :?required-or-fail).
• Solves two gaps: APIP_GW_* env overrides cannot index into [[array]] elements, and Helm cannot read Secret contents at render time.
• ${file:...} is recommended for secrets; ${env:...} for non-sensitive deployment values.
• ${file:...} paths gated by an allowlist configured via --config-file-source-allowlist / APIP_GW_CONFIG_FILE_SOURCE_ALLOWLIST (bootstrap; see Implementation Details).

Motivation

• Operators deploy the gateway in Kubernetes via the gateway-operator + gateway-helm-chart, and frequently need to inject sensitive values (passwords, client secrets, encryption keys, OAuth tokens) from k8s Secrets into specific fields of config.toml.
• Koanf APIP_GW_* env overrides cannot index into array elements. A flat env var like APIP_GW_CONTROLLER_AUTH_BASIC_USERS_0_PASSWORD does not splice into the nth element of [[controller.auth.basic.users]]. This is a known gap shared with Viper.
• Helm cannot read Secret/ConfigMap data at render time. lookup exists but it bakes plaintext into a ConfigMap, defeating the purpose of using a Secret.
• values.yaml-only arrays work, but require committing secret values to Git, which is unacceptable.
• The affected arrays of tables are real and central: [[controller.auth.basic.users]], [[controller.encryption.providers]], and its nested [[controller.encryption.providers.keys]].
• Without an interpolation mechanism, every operator builds their own initContainer + envsubst workaround, which leaves docker-compose, the all-in-one distribution, and bare-metal deployments unsolved.
• The same loader is used by gateway-controller and the policy-engine, so a single helper benefits both.

Proposal

• Add a small expansion pass in the config loader that scans string-valued leaves of the merged config map for ${source:ref[:modifier]} tokens and substitutes resolved values in place, before unmarshal into the typed struct.
• Built-in sources in v1: env and file. (fileRaw deferred — see Implementation Details.)
• ${file:/path} trims trailing whitespace from file contents; ${env:NAME} reads an environment variable.
• Modifiers (env only): ${env:NAME:-default} (default if unset/empty) and ${env:NAME:?msg} (required, fails startup).
• Escape: $${ -> literal ${. One level only.
• Substitution applies to TOML string values only; partial substitution inside a string is supported ("https://${env:HOST}:${env:PORT}/v1").
• Non-string fields are interpolated by wrapping the placeholder in quotes; Koanf coerces the resolved string at unmarshal time.
• Missing required value (no default, env unset, or file missing) -> startup error, never a silent empty string.
• File source: must exist, max 1 MiB, symlinks resolved, path-allowlisted via --config-file-source-allowlist / APIP_GW_CONFIG_FILE_SOURCE_ALLOWLIST (bootstrap config — cannot live in config.toml itself). Defaults and enforcement rule live in Implementation Details.
• Resolved values are never logged. Only references (${file:/secrets/gateway-controller/admin-password}) appear in diagnostic surfaces.

Why ${file:...} is preferred over ${env:...} for secrets

A core reason this proposal adds file: at the same time as env: is so we can recommend file projection for any sensitive value.

Detailed comparison — env var risks vs mounted file advantages

Env var risks:

• Visible to every process in the container via /proc/<pid>/environ.
• Inherited by child processes (entrypoint scripts, the policy-engine subprocess, debug shells).
• Leak into crash dumps, panic stack traces, error reporters, /debug/vars-style endpoints.
• Show up in kubectl describe pod, docker inspect, audit logs -- especially if a chart misconfigures value: instead of valueFrom:.
• Cannot be rotated without a pod restart.
• Sticky in process memory for the lifetime of the process.

Mounted file advantages:

• Scoped to the container that mounts them -- sidecars do not see them by default.
• tmpfs-backed in Kubernetes when the source is a Secret -- never hits disk.
• POSIX permissions enforceable (defaultMode: 0400).
• Kubelet refreshes file contents on Secret update (the app must re-read, but rotation is at least possible).
• Doesn't leak into env-dumping diagnostic surfaces.
• Auditable at the filesystem layer.

Industry alignment: Kubernetes docs, OWASP Secrets Management Cheat Sheet, AWS Secrets Manager, GCP Secret Manager, and Vault Agent all default to file projection for secrets.

Recommendation: use ${file:...} for any secret; reserve ${env:...} for non-sensitive deployment-specific values such as cluster domain, log level, feature flags.

Configuration Changes

[controller.logging]
level = "${env:APIP_GW_LOG_LEVEL:-info}"

[controller.controlplane]
apim_oauth2_client_id     = "${env:CP_CLIENT_ID:?CP_CLIENT_ID must be set}"
apim_oauth2_client_secret = "${file:/secrets/gateway-controller/cp/client-secret}"

[[controller.auth.basic.users]]
username = "admin"
password = "${file:/secrets/gateway-controller/admin-password}"
roles    = ["admin"]

[[controller.encryption.providers]]
type = "aes-gcm"

[[controller.encryption.providers.keys]]
version = "key-v1"
file    = "${env:ENCRYPTION_KEY_PATH:-/secrets/gateway-controller/encryption/primary-key}"

[router]
gateway_host  = "api.${env:CLUSTER_DOMAIN:-cluster.local}"
listener_port = "${env:LISTENER_PORT:-8080}"   # Koanf coerces string -> int

Companion Kubernetes wiring (illustrative)

Lives in the user's manifests / values.yaml:

extraEnv:
  - name: CP_CLIENT_ID
    valueFrom:
      secretKeyRef: { name: cp-oauth, key: clientId }
  - name: CLUSTER_DOMAIN
    value: prod.example.internal

extraVolumes:
  - name: admin-password
    secret:
      secretName: gateway-admin
      defaultMode: 0400
  - name: cp-client-secret
    secret:
      secretName: cp-oauth
      items: [{ key: clientSecret, path: client-secret }]
      defaultMode: 0400
  - name: encryption-keys
    secret: { secretName: gateway-encryption, defaultMode: 0400 }

extraVolumeMounts:
  - { name: admin-password,     mountPath: /secrets/gateway-controller/admin-password, subPath: password, readOnly: true }
  - { name: cp-client-secret,   mountPath: /secrets/gateway-controller/cp,             readOnly: true }
  - { name: encryption-keys,    mountPath: /secrets/gateway-controller/encryption,     readOnly: true }

Before / after example -- moving a secret out of Git

Before -- the only way to put a secret into an array-of-tables element today is to commit it to values.yaml:

# values.yaml (checked in)
gateway:
  config:
    controller:
      auth:
        basic:
          users:
            - username: admin
              password: "hunter2"   # plaintext in Git -- not acceptable
              roles: [admin]

After -- the value lives in a Kubernetes Secret; config.toml references it:

# config.toml (rendered by Helm from values.yaml; no secret material in Git)
[[controller.auth.basic.users]]
username = "admin"
password = "${file:/secrets/gateway-controller/admin-password}"
roles    = ["admin"]

# values.yaml (checked in) -- only declares the wiring, not the value
extraVolumes:
  - name: admin-password
    secret: { secretName: gateway-admin, defaultMode: 0400 }
extraVolumeMounts:
  - { name: admin-password, mountPath: /secrets/gateway-controller/admin-password, subPath: password, readOnly: true }

Open Debate: drop APIP_GW_* Koanf env overrides entirely?

Once ${env:NAME} interpolation exists, the platform has two ways to set a value from env: Koanf's APIP_GW_* provider and ${env:...} inside config.toml. A live design question is whether to delete the Koanf env path and standardise on ${env:...} alone.

For dropping it:

• One mental model — no more "which one wins?" / "do I need both?" questions; the proposal's existing two-ways drawback goes away.
• The hand-maintained switch table in gateway/gateway-controller/pkg/config/config.go:472-505 (short-name aliases + underscore-collision fixes) is deleted outright — a class of silent bugs and per-field maintenance disappears.
• The "Koanf cannot index [[arrays]]" gap evaporates rather than being worked around; there is only one mechanism and it works inside arrays naturally.
• Discoverability improves: grep '${env:' configs/config.toml is the complete list of env knobs. Today operators have to read struct tags + the switch table.
• Defaults co-located with override points: level = "${env:APIP_GW_LOG_LEVEL:-info}" puts default and override on one line.

Against dropping it:

• Breaking change. Existing operators setting APIP_GW_* env vars (docker-compose, all-in-one, custom k8s manifests, helm extraEnv) silently get defaults. Worst case: a secret env var is set, override is ignored, the gateway boots with a placeholder default and the failure mode is delayed.
• Migration cost is non-trivial: sweep docker-compose files, the all-in-one distribution, integration tests, BDD step files, and shipped docs.
• "Auto-overridable on every new field" turns into "explicitly overridable only where the config.toml advertises a token" — more discipline, but also more friction when adding a new tunable.
• Helm-chart consumers who bypass values.yaml via Pod extraEnv lose that path; they must switch to chart values or ${file:...}.

Recommendation: drop it. Pre-1.0 / SNAPSHOT versions are exactly when this cut is cheapest, and the simplification compounds (no switch table, no array-indexing gap, one mechanism to document). Conditions:

1. Do an inventory sweep first — confirm APIP_GW_* usage is bounded to the dozen entries in the switch table plus a handful in compose files. If the count blows up, reconsider scope.
2. Migrate the shipped gateway/configs/config.toml to expose every name currently in the switch table as field = "${env:APIP_GW_SAME_NAME:-default}" before deleting the Koanf env loader. Operators keep the same env-var names; the resolution path changes silently. This converts "breaking change" into "behaves the same in practice."
3. Keep the APIP_GW_ prefix as a documentation convention in shipped defaults so the platform's env footprint stays grep-able in kubectl describe pod.
4. Single release with a clear CHANGELOG entry listing the removed mechanism and the ${env:...} migration recipe. No deprecation dance on SNAPSHOT.

If accepted, the proposal reframes from "additive feature" to "replacement": the Motivation loses the Koanf-array-gap argument, Drawbacks loses the two-ways bullet and gains a breaking-change bullet, Alternative 5 is rejected on stronger grounds, and the "two distinct env-var mechanisms" bullet in Implementation Details is deleted.

Implementation Details

• Loader module placement. The expansion pass lives in a new shared module common/configinterpolate/, imported by both the gateway-controller and policy-engine config loaders. Keeping it in common/ (rather than duplicating per binary) ensures the grammar, escape rules, and allowlist semantics stay identical across the two binaries — both of which read their own config.toml independently at startup (no config.toml content is forwarded between binaries via xDS).

• Where the expansion pass slots into Koanf. Koanf is built to load and merge multiple providers (TOML file + APIP_GW_* env) into a single map in one pass; the expansion step runs on the already-merged map, not between providers. Concrete flow:

  1. Koanf loads config.toml via the TOML provider.
  2. Koanf merges the env provider (APIP_GW_*) on top — env values override file values.
  3. common/configinterpolate/ walks k.Raw(), substitutes ${...} in every string-valued leaf, and writes the substituted map back into the same Koanf instance via confmap.Provider(expanded, ".") — Koanf does not mutate values in place, so an explicit reload is required for UnmarshalWithConf to see the resolved values.
  4. Koanf unmarshals the resulting map into the typed config struct (Koanf handles string→int/bool/duration coercion at this point).

• RawConfig snapshot for policies (policy-engine only). Today cfg.PolicyEngine.RawConfig = k.Raw() is captured after env merge and passed to every policy via reg.SetConfig(...) for CEL ${config} resolution in systemParameters. With this proposal, that snapshot is taken after the expansion pass, so policies that reference config (e.g. an Advanced Rate Limit policy reading a Redis password via ${config.controller...}) get the resolved value directly rather than the literal ${file:...} token. Trade-off: every loaded policy is in the trust boundary for any secret materialised into config.toml. Policy authors must not log values pulled from ${config}; this becomes part of the policy-authoring guidance and the policy-review checklist.

• Env-override values are part of the interpolation input. Because expansion runs after Koanf's merge, an env override may itself contain ${...} (e.g. APIP_GW_CONTROLLER_LOGGING_LEVEL="${env:DEBUG_LEVEL:-info}") and will be expanded. There is no "do not re-expand env overrides" carve-out; the path allowlist is the sole gate against ${file:/etc/passwd}-style abuse from a hostile env var.

• Two distinct env-var mechanisms — do not conflate. APIP_GW_* env overrides and ${env:NAME} interpolation are separate features and interact only via the merge order above:

  • APIP_GW_* overrides are matched by Koanf's env provider, stripped of the prefix, and mapped to a dotted Koanf key path (e.g. APIP_GW_CONTROLLER_SERVER_API_PORT → controller.server.api_port). The gateway-controller additionally carries a hand-maintained switch table (pkg/config/config.go) that hard-maps a small set of names — controlplane_host, gateway_registration_token, controller_controlplane_insecure_skip_verify, etc. — to their dotted paths, because the default _ → . rule would split fields that contain literal underscores (e.g. insecure_skip_verify). The policy-engine uses only the generic __ → literal-_ escape rule, no custom table.
  • ${env:NAME} interpolation reads an environment variable by its exact name and substitutes the resulting string into the TOML position where the token appears. It does not go through the prefix, the lowercasing, the _ → . rule, or the controller's switch table. NAME is whatever the operator wrote — CP_CLIENT_ID, CLUSTER_DOMAIN, etc.
  • Practical consequence: operators do not need to learn the APIP_GW_* naming rules to use ${env:...}, and there is no risk of an interpolation name accidentally colliding with a Koanf override path.

• Allowlist enforcement rule for ${file:...}. The check applies to the input path, not the resolved symlink target:

  1. Apply filepath.Clean() to the path inside ${file:...}; reject if the cleaned path contains ...
  2. Reject unless the cleaned path is prefixed by one of the configured allowlist directories (with a trailing-separator check so /secrets does not match /secrets-other).
  3. Open the file with os.ReadFile (or equivalent); the OS resolves any symlinks transparently.
  4. The resolved target is not re-checked against the allowlist.

  Why no re-check. Kubernetes Secret mounts symlink /secrets/foo → ..data/foo → /var/lib/kubelet/pods/<uuid>/...; the realpath is kubelet-managed, unpredictable, and changes across pod restarts. Re-checking the resolved target would make ${file:...} unusable in the canonical target deployment (k8s). Vault Agent, the OpenTelemetry Collector file source, and Kubernetes' own Secret-to-env projection all treat the mounted path as the trust boundary — not the realpath. The operator owns the contents of allowlisted directories; if an untrusted actor can create symlinks inside /secrets/, the threat is broader than this feature can address.

  What this protects against. Typos and hostile env-overrides that walk into sensitive paths (${file:/proc/self/environ}, ${file:/etc/passwd}, ${file:../../etc/shadow}) — those fail at step 1 or 2 without ever opening anything.

• Per-binary allowlist defaults and configuration. Defaults: gateway-controller -> /etc/gateway-controller, /secrets/gateway-controller; policy-engine -> /etc/gateway-runtime, /secrets/gateway-runtime. Per-binary (rather than shared) so the controller can't read from /secrets/gateway-runtime and vice versa — catches wrong-pod mount mistakes and keeps blast radius tight. Runtime defaults use gateway-runtime (the container/deployment name operators see in Helm and kubectl) rather than policy-engine (the binary inside the container). The broad /secrets default is intentionally not included.

  • The allowlist is bootstrap config — it must be applied before the interpolator expands ${file:...} references, so it cannot live inside config.toml itself (chicken-and-egg). Three sources, standard precedence (CLI flag > env var > defaults):
    • CLI flag: --config-file-source-allowlist=/etc/gateway-controller,/secrets/gateway-controller,/custom/path
    • Env var: APIP_GW_CONFIG_FILE_SOURCE_ALLOWLIST (comma-separated)
    • Compiled-in defaults (above)
  • Helm chart exposes a first-class value gateway.config.fileSourceAllowlist: [] that renders the env var, so operators don't have to memorise the variable name. Falls back to chart defaults if unset.
  • What the allowlist is and isn't. It restricts which paths the ${file:...} interpolation feature will resolve. It is not an OS-level access control — the gateway process can still open any file the kernel permits, the same as any process in the container. The allowlist exists to (a) catch accidental leakage of mounted paths through log lines / analytics / upstream headers and (b) prevent path-traversal-style typos (${file:/proc/self/environ}, ${file:../../etc/shadow}).
  • Why /var/run/secrets is excluded by default. It's the standard mount point for the auto-mounted Kubernetes service account token (/var/run/secrets/kubernetes.io/serviceaccount/token) and is therefore readable on every pod by default. Excluding the parent dir keeps casual ${file:/var/run/secrets/...} access to the SA token off the table. Operators using secret-injector sidecars (Vault Agent, external-secrets, cert-manager) that mount under /var/run/secrets/<vendor>/ extend the allowlist explicitly as part of wiring those sidecars.

• fileRaw deferred from v1. A fileRaw variant (verbatim, no trimming) was considered for use cases like multi-line PEM blocks but rejected — gateway PEM material is fed via path-valued fields (cert_file, key_file), not inlined into config.toml. Adding fileRaw later if a concrete need emerges is easy; removing shipped syntax is not.

• Why escape is one level only ($${...} -> ${...}, no $$$ counting rule).

  • Grep/lint regex stays trivial (\$\{[^}]+\}); a counting rule breaks one-liners.
  • No demonstrated need — the rare "I want a literal $${X} in my output" case is handled cleanly by ${file:/path/to/snippet}.
  • Forward-compatible: nobody writes $$$ today, so the syntax space stays reserved if a real use case appears.
  • Smaller bug surface — counting-style escape rules have historically shipped with off-by-one bugs (early Docker Compose interpolation is a known example).

• Interpolating non-string fields. To interpolate into a non-string field (int, bool, duration), wrap the placeholder in quotes — e.g. listener_port = "${env:PORT:-8080}". The quoted form makes it a TOML string the interpolator can substitute; Koanf then coerces the resolved string to the declared field type at unmarshal time, so the field still ends up as the correct type.

• Startup summary log line. Emit a single info-level line at boot with counts only, e.g. config interpolation: resolved 12 references (env=8, file=4). Counts are not sensitive; values and references are deliberately omitted. Helps operators confirm overrides are wired correctly without exposing structure or contents. Counting unit: one reference = one ${...} token (so "https://${env:H}:${env:P}" counts as 2).

• Per-key debug log line. At debug level, log one entry per resolved reference: the destination Koanf key path, the source (env / file), and the reference text (env name or file path) — never the resolved value. Example: config interpolation: controller.controlplane.apim_oauth2_client_secret <- file:/secrets/gateway-controller/cp/client-secret. Lets operators debug "did my Secret mount land in the right field?" without needing to dump config or risk leaking the value. Disabled at info and above.

Drawbacks

• Two ways to inject scalars now exist: APIP_GW_* Koanf env overrides and ${env:...}. We keep both because Koanf overrides are convenient for top-level scalars; this proposal documents when to reach for which.

Alternatives Considered

Alternative 1: Kustomize overlays

• What: Layer Kustomize on top of the helm-rendered output, patching specific values from a Secret-backed generator.
• Why rejected: Architecturally wrong fit (operator owns the render); doesn't actually solve the "read from Secret" problem.

Pros / cons

• Pros: Familiar k8s tool; declarative; no code change.
• Cons: Doesn't compose with the delivery flow -- the gateway-operator deploys the helm chart programmatically (internal/helmgateway/deploy.go), so a Kustomize layer would have to wrap the operator's output. Two templating layers; the operator no longer owns its artifacts. And Kustomize cannot read Secret contents at render time either -- same fundamental constraint as Helm.

Alternative 2: initContainer + envsubst

• What: Mount the unrendered config.toml as a template, run envsubst (or a sed pass) in an initContainer that writes the rendered file to an emptyDir, then run the gateway against the rendered file.
• Why rejected: Solves one deployment topology, leaves others broken; pushes complexity into every operator's manifests.

Pros / cons

• Pros: Works today with no code change; uses standard k8s primitives.
• Cons:
  • Kubernetes-only band-aid. The gateway also runs in docker-compose, in the all-in-one distribution, and bare-metal; fixing only k8s leaves the gap on every other surface.
  • envsubst is fragile around $ characters in passwords / random tokens.
  • Adds a container, two volume mounts, and changes to deployment.yaml.
  • Doesn't help with file sources -- envsubst only does env.

Alternative 3: Inline-table marker form (password = { from_env = "X" } / password = { from_file = "/y" })

• What: Use a TOML inline table as a sentinel that the loader detects and replaces with the resolved scalar.
• Why rejected: Loses partial substitution, complicates schemas, and the type story is worse than the string-coercion approach.

Pros / cons

• Pros: No string-scanner; explicit; could enforce types per source.
• Cons:
  • TOML fields become polymorphic (string | inline-table) -- schemas, code generators, and IDE plugins all stumble.
  • Doesn't compose with partial substitution: you cannot put it inside "https://${env:HOST}".
  • Non-string types (int, bool) need their own handling.
  • Introduces a second syntax in addition to the one Koanf env overrides already provide; exactly what we want to avoid.

Alternative 4: Go template syntax ({{ env "X" }}, {{ file "Y" }})

This is the most important alternative because it's the obvious suggestion for a Go shop.

• What: Run the raw config.toml through text/template with a small allowed function set (env, file, maybe default, required).
• Why rejected: Helm collision alone is disqualifying; the rest reinforces it. The use cases are "get one scalar from env or file with an optional default" -- ${...} matches the surface area perfectly without becoming a programming language inside config.toml.

Pros / cons — full rejection rationale (a) through (f) and middle-ground considered

• Pros: Familiar to anyone who has written a Helm chart; rich functions if we later want them; well-trodden in the Go ecosystem.
• Cons (each one is significant):
  • (a) Collision with Helm's own templating. config.toml is already rendered by Helm's Go-template engine inside gateway-helm-chart/templates/gateway/gateway-config.yaml. If the runtime also uses Go-template syntax, every {{ env "X" }} literal that needs to survive into the final file has to be escaped against Helm first using ugly constructs like {{ printf "{{ env %q }}" "ADMIN_PASSWORD" }} or {{ }} literal escapes. Users will get this wrong constantly, and Helm template errors are some of the worst messages in the ecosystem. ${...} has no collision because Helm does not interpret it.
  • (b) Power you don't want in a config file. Go templates bring if, range, with, define, pipelines, and (by convention) sprig. Once available, someone will put logic in config.toml. Config files that are also programs are hard to audit, hard to diff in PRs, hard to reason about for security.
  • (c) Error ergonomics. Go template errors like template: :3:14: executing "" at <env "X"> are notoriously bad. ${...} parser errors can be pointed at the exact source location: config.toml:42: ${env:CP_CLIENT_ID} not set.
  • (d) Whitespace control complexity ({{- / -}}) -- another foot-gun, especially in TOML where whitespace inside strings matters.
  • (e) Convention. ${source:ref} is what Envoy, Loki, Grafana Agent, Tempo, Promtail, OpenTelemetry Collector, Vector, and Fluent Bit all use for runtime config interpolation. Go templates are conventional for generating whole files (Helm, Hugo, kubectl) -- not for embedded substitution inside config that the runtime reads at startup.
  • (f) Footprint. Go templates with a restricted function set is hundreds of lines of glue, a separate parser, and an ongoing question of "what funcs do we expose?". ${...} is a scanner in ~80 lines.
• Middle-ground considered: Go templates with a non-default delimiter pair (e.g. << env "X" >>) and a tiny allowed function set, to avoid the Helm collision in (a).
  • This dodges (a) but keeps (b), (c), (d), (f). Also breaks (e) -- it's a custom dialect nobody else uses.

Alternative 5: Extend APIP_GW_* env overrides to support array indices

• What: Teach Koanf (or wrap it) to parse APIP_GW_CONTROLLER_AUTH_BASIC_USERS_0_PASSWORD and splice into element 0.
• Why rejected: Solves only half the problem (arrays) and makes the secret-in-env problem worse.

Pros / cons

• Pros: Stays in the env-var world; no new syntax in config.toml.
• Cons: Doesn't solve file sources (still leaks via env). Naming convention gets ugly fast for nested arrays. Upstream Koanf doesn't support this; would mean carrying a fork or a wrapper. Doesn't help with partial substitution into a larger string.

Compatibility

• Backwards compatible?: Yes -- configs without ${...} are unchanged; existing APIP_GW_* env overrides continue to override TOML values exactly as before (Koanf still merges env on top of file; the new expansion pass runs on the already-merged map).
• Requires migration?: No -- opt-in syntax. Operators only adopt it where they want to.
• Breaking changes?: No, with one caveat: any pre-existing config that contains a literal ${...} substring would now be interpreted. The escape $${...} covers the corner case, and a one-time grep across our shipped samples will catch anything we own.

References

• Koanf -- current config library, env-override conventions.
• Envoy bootstrap config: environment variable substitution -- closest prior art for ${ENV_VAR} in a control-plane-adjacent config.
• OpenTelemetry Collector configuration env vars -- ${env:NAME} and ${env:NAME:-default} style.
• Loki / Grafana Agent / Promtail config expansion -- same ${ENV} / ${file:...} pattern.
• Docker Compose variable interpolation -- canonical reference for ${VAR:-default} and ${VAR:?err} semantics.
• Kubernetes: using Secrets as files vs env vars -- justification for preferring file projection.
• OWASP Secrets Management Cheat Sheet.
• gateway-helm-chart extraEnv / extraEnvFrom / extraVolumes hooks: kubernetes/helm/gateway-helm-chart/templates/gateway/controller/deployment.yaml and .../gateway-runtime/deployment.yaml.
• gateway-operator helm integration: kubernetes/gateway-operator/internal/helmgateway/deploy.go.