feat: support mounting secrets as files via _FILE env vars

Add _FILE variant support for 18 secret environment variables in the
container entrypoint. When a _FILE-suffixed variable (e.g.
OPENAI_API_KEY_FILE) points to a mounted file, its contents are read
into the base variable at startup. This avoids exposing secrets through
/proc/1/environ and subprocess environments in Kubernetes deployments.

Add a pre-commit sync check in build.py that detects secret fields in
build.yaml (by field name heuristic) and verifies they all have
corresponding _FILE entries in entrypoint.sh, so new providers with
secrets cannot be added without extending _FILE support.

Add auto-generated documentation in distribution/README.md with the
supported variable list and a Kubernetes Pod spec example.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Nathan Weinberg <nweinber@redhat.com>

Author: nathan-weinberg

build/build.py

@@ -31,6 +31,15 @@
 
 OGX_GIT_REPO = "https://github.com/opendatahub-io/ogx.git"
 
+PINNED_DEPENDENCIES = ["milvus-lite>=3.0.0", "pymilvus!=2.6.10"]
+
+CONSTRAINTS_FILE = Path("distribution/constraints.txt")
+
+_SECRET_FIELD_WORDS = {"password", "secret", "token", "credential"}
+_SECRET_FIELD_SUBSTRINGS = {"api_key", "access_key"}
+_SECRET_FIELD_EXCLUDE_SUFFIXES = ("_file", "_path", "_url", "_dir")
+
+
 STRIPPED_PROVIDER_TYPES = {
     "inline::sentence-transformers",
     "inline::milvus",
@@ -452,6 +461,85 @@ def generate_containerfile(version: str):
     print(f"Successfully generated {output_path}")
 
 
+def _is_secret_field(field_name: str) -> bool:
+    """Heuristic: does this YAML config field name hold a secret value?"""
+    lower = field_name.lower()
+    if lower.endswith(_SECRET_FIELD_EXCLUDE_SUFFIXES):
+        return False
+    words = set(lower.split("_"))
+    if words & _SECRET_FIELD_WORDS:
+        return True
+    return any(sub in lower for sub in _SECRET_FIELD_SUBSTRINGS)
+
+
+def _extract_secret_env_vars_from_yaml(yaml_path: Path) -> set[str]:
+    """Walk build.yaml and return env var names referenced by secret fields."""
+    env_ref = re.compile(r"\$\{env\.([^:}]+):[=+]")
+    secrets: set[str] = set()
+
+    def _walk(node, parent_key=""):
+        if isinstance(node, dict):
+            for key, value in node.items():
+                _walk(value, parent_key=key)
+        elif isinstance(node, list):
+            for item in node:
+                _walk(item, parent_key=parent_key)
+        elif isinstance(node, str):
+            if _is_secret_field(parent_key):
+                for match in env_ref.finditer(node):
+                    secrets.add(match.group(1))
+
+    with open(yaml_path) as f:
+        from yaml import safe_load
+
+        data = safe_load(f)
+    _walk(data)
+    return secrets
+
+
+def _extract_entrypoint_secrets(entrypoint_path: Path) -> set[str]:
+    """Extract the secret var names from the entrypoint.sh for-loop."""
+    text = entrypoint_path.read_text()
+    match = re.search(r"for _secret_var in\s*\\(.*?);\s*do", text, re.DOTALL)
+    if not match:
+        print(f"Error: could not find _secret_var loop in {entrypoint_path}")
+        sys.exit(1)
+    body = match.group(1).replace("\\", " ")
+    return {v for v in body.split() if v}
+
+
+def verify_file_secrets_sync():
+    """Verify that entrypoint.sh _FILE list matches secrets in build.yaml."""
+    yaml_path = Path("build/build.yaml")
+    entrypoint_path = Path("distribution/entrypoint.sh")
+
+    yaml_secrets = _extract_secret_env_vars_from_yaml(yaml_path)
+    entrypoint_secrets = _extract_entrypoint_secrets(entrypoint_path)
+
+    missing_from_entrypoint = yaml_secrets - entrypoint_secrets
+    extra_in_entrypoint = entrypoint_secrets - yaml_secrets
+
+    if missing_from_entrypoint or extra_in_entrypoint:
+        print(
+            "Error: distribution/entrypoint.sh _FILE secret list is out of sync "
+            "with build/build.yaml."
+        )
+        if missing_from_entrypoint:
+            print(f"  Add to entrypoint.sh:    {sorted(missing_from_entrypoint)}")
+        if extra_in_entrypoint:
+            print(f"  Remove from entrypoint.sh: {sorted(extra_in_entrypoint)}")
+        print(
+            "\nWhen adding a new provider with secret fields (api_key, password, "
+            "token, etc.) to build/build.yaml, also add the env var to the "
+            "_FILE resolution loop in distribution/entrypoint.sh."
+        )
+        sys.exit(1)
+
+    print(
+        f"Verified {len(yaml_secrets)} secret env vars have _FILE support in entrypoint.sh"
+    )
+
+
 def main():
     config = BuildConfig()
 
@@ -501,6 +589,9 @@ def main():
     print("Generating Containerfile...")
     generate_containerfile(config.ogx_version)
 
+    print("Verifying _FILE secret sync...")
+    verify_file_secrets_sync()
+
     print("Done!")
 
 

build/gen_distro_docs.py

@@ -1,7 +1,8 @@
 #!/usr/bin/env python3
 
-import yaml
 import re
+
+import yaml
 from pathlib import Path
 
 
@@ -182,6 +183,57 @@ def gen_distro_table(providers_data, runtime_provider_types=None):
     return "\n".join(table_lines)
 
 
+def extract_file_secret_vars():
+    """Extract the secret env var names from entrypoint.sh's _FILE resolution loop."""
+    entrypoint = REPO_ROOT / "distribution" / "entrypoint.sh"
+    text = entrypoint.read_text()
+    match = re.search(r"for _secret_var in\s*\\(.*?);\s*do", text, re.DOTALL)
+    if not match:
+        return []
+    body = match.group(1).replace("\\", " ")
+    return sorted(v for v in body.split() if v)
+
+
+def gen_file_secrets_section(secret_vars):
+    """Generate a markdown section documenting _FILE secret support."""
+    if not secret_vars:
+        return ""
+
+    var_list = "\n".join(f"- `{var}` → `{var}_FILE`" for var in secret_vars)
+
+    return f"""
+## Mounting Secrets as Files
+
+Instead of passing secrets directly as environment variables (which exposes them in
+`/proc/1/environ` and subprocess environments), you can mount them as files and
+point to them with `_FILE`-suffixed variables. At container startup, the entrypoint
+reads each file and populates the corresponding environment variable.
+
+For example, to inject `OPENAI_API_KEY` from a mounted Kubernetes Secret:
+
+```yaml
+env:
+  - name: OPENAI_API_KEY_FILE
+    value: /run/secrets/openai-api-key
+volumeMounts:
+  - name: openai-secret
+    mountPath: /run/secrets/openai-api-key
+    subPath: api-key
+    readOnly: true
+volumes:
+  - name: openai-secret
+    secret:
+      secretName: openai-credentials
+```
+
+Setting both the base variable and its `_FILE` variant is an error (mutually exclusive).
+
+### Supported variables
+
+{var_list}
+"""
+
+
 def gen_distro_docs():
     build_path = REPO_ROOT / "build" / "build.yaml"
     readme_path = REPO_ROOT / "distribution" / "README.md"
@@ -246,8 +298,13 @@ def gen_distro_docs():
             "definitions.\n"
         )
 
+        secret_vars = extract_file_secret_vars()
+        file_secrets_section = gen_file_secrets_section(secret_vars)
+
         with open(readme_path, "w") as readme_file:
-            readme_file.write(header + table_content + "\n" + dep_only_note)
+            readme_file.write(
+                header + table_content + "\n" + dep_only_note + file_secrets_section
+            )
 
         print(f"Successfully generated {readme_path}")
         print(

distribution/README.md

@@ -1,6 +1,61 @@
 #!/bin/sh
 set -e
 
+# Resolve _FILE variants for secret environment variables.
+#
+# For each secret variable (e.g. OPENAI_API_KEY), if the corresponding
+# _FILE variant (OPENAI_API_KEY_FILE) is set, read the file contents
+# into the base variable. This lets Kubernetes operators mount secrets
+# as files instead of injecting them via env vars, avoiding exposure
+# through /proc/1/environ and subprocess environments.
+resolve_file_secret() {
+  _rfs_var="$1"
+  _rfs_file_var="${_rfs_var}_FILE"
+  eval "_rfs_file_val=\${${_rfs_file_var}:-}"
+  eval "_rfs_var_val=\${${_rfs_var}:-}"
+
+  if [ -n "$_rfs_file_val" ] && [ -n "$_rfs_var_val" ]; then
+    printf 'Error: both %s and %s are set (mutually exclusive)\n' \
+      "$_rfs_var" "$_rfs_file_var" >&2
+    exit 1
+  fi
+
+  if [ -n "$_rfs_file_val" ]; then
+    if [ ! -f "$_rfs_file_val" ]; then
+      printf 'Error: %s references %s, which is not a regular file\n' \
+        "$_rfs_file_var" "$_rfs_file_val" >&2
+      exit 1
+    fi
+    _rfs_content="$(cat "$_rfs_file_val")"
+    eval "export ${_rfs_var}=\$_rfs_content"
+    unset "$_rfs_file_var"
+  fi
+}
+
+for _secret_var in \
+    ANTHROPIC_API_KEY \
+    AWS_ACCESS_KEY_ID \
+    AWS_BEDROCK_BEARER_TOKEN \
+    AWS_SECRET_ACCESS_KEY \
+    AZURE_API_KEY \
+    BRAVE_SEARCH_API_KEY \
+    DOCLING_SERVE_API_KEY \
+    GEMINI_ACCESS_TOKEN \
+    GEMINI_API_KEY \
+    MILVUS_TOKEN \
+    OPENAI_API_KEY \
+    PGVECTOR_PASSWORD \
+    POSTGRES_PASSWORD \
+    QDRANT_API_KEY \
+    TAVILY_SEARCH_API_KEY \
+    VLLM_API_TOKEN \
+    VLLM_EMBEDDING_API_TOKEN \
+    WATSONX_API_KEY \
+; do
+  resolve_file_secret "$_secret_var"
+done
+unset _secret_var
+
 # Resolve config path
 if [ -n "$RUN_CONFIG_PATH" ] && [ -f "$RUN_CONFIG_PATH" ]; then
   CONFIG="$RUN_CONFIG_PATH"