Secure environment-variable and secret-management patterns

Lessons 1 and 2 established that secrets must live outside source code, typically in environment variables. This lesson goes into the actual patterns for managing those variables reliably across a project's lifetime — from a single developer's laptop, through automated testing, to a production deployment serving real traffic. The right pattern depends heavily on which of those stages you're in, and mixing them up is a common source of both security incidents and frustrating "works on my machine" bugs.

Local development: .env files with python-dotenv

On a local machine, the simplest reliable pattern is a .env file loaded by the python-dotenv package. Install it alongside the OpenAI SDK:

pip install openai python-dotenv

# .env  (gitignored, as established in Lesson 2)
OPENAI_API_KEY=sk-proj-your-real-key-here
OPENAI_PROJECT_ID=proj_abc123
ENVIRONMENT=development

from dotenv import load_dotenv
import os
from openai import OpenAI

load_dotenv()  # reads .env into os.environ, if the file exists

client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

load_dotenv() reads the .env file in the current directory (or a parent directory) and inserts its key-value pairs into os.environ, exactly as if you had exported them in your shell. It is a no-op if no .env file is present, which is why it's safe to call unconditionally — in production, you typically won't ship a .env file at all, and the real environment variables (set by your hosting platform) will already be present in os.environ.

This is why os.environ["OPENAI_API_KEY"] (using square brackets, which raises a KeyError if missing) is often preferable to os.environ.get(...) at the point where you actually build the client: a missing key should be a loud, immediate failure, not a None that silently propagates until the first API call fails with a confusing authentication error.

Why .env files are a development convenience, not a production strategy

A .env file is just a text file. It has no encryption, no access control beyond the filesystem permissions of whatever machine it sits on, and no audit trail of who read it or when. That's an acceptable tradeoff on a single developer's laptop where the file never leaves the machine and the developer already has the access it protects. It is not acceptable for a production server, because:

• Multiple people and systems can reach a production host (other engineers, deployment tooling, monitoring agents), and a plaintext file widens the blast radius of any of those being compromised.
• There's no rotation or audit trail. If a key needs to be rotated, you must manually edit the file on every server; if you need to know whether the key was ever read by an unauthorized process, a flat file gives you no record.
• Backups and snapshots can capture it. A disk snapshot, a container image layer, or a backup job might inadvertently capture the .env file's contents.

Production: dedicated secret managers

In staging and production, secrets should come from a dedicated secret-management service rather than a file on disk. Common options include AWS Secrets Manager, Google Cloud Secret Manager, HashiCorp Vault, and third-party services like Doppler. They differ in details, but they share the same core properties that a flat file lacks:

• Access control: only specific IAM roles or service identities can read a given secret.
• Audit logging: every read is recorded — who accessed which secret, and when.
• Rotation support: secrets can be rotated centrally, often automatically, without redeploying every consumer.
• Encryption at rest, managed by the platform rather than by your application code.

The application-level pattern for using one is to abstract "where does the secret come from" behind a small interface, so your business logic doesn't care whether it's talking to a .env file or a cloud secret manager.

from abc import ABC, abstractmethod
import os


class SecretProvider(ABC):
    @abstractmethod
    def get_secret(self, name: str) -> str:
        ...


class EnvSecretProvider(SecretProvider):
    """Reads secrets from process environment variables (local/dev)."""

    def get_secret(self, name: str) -> str:
        value = os.environ.get(name)
        if not value:
            raise KeyError(f"Secret '{name}' is not set in the environment.")
        return value


class CloudSecretProvider(SecretProvider):
    """
    Reads secrets from a cloud secret manager. The real implementation
    would call the provider's SDK (e.g. boto3's secretsmanager client);
    this shape is what matters for the rest of the application.
    """

    def __init__(self, client, secret_prefix: str = ""):
        self._client = client
        self._prefix = secret_prefix

    def get_secret(self, name: str) -> str:
        full_name = f"{self._prefix}{name}"
        return self._client.fetch_secret_value(full_name)


def build_openai_client(provider: SecretProvider):
    from openai import OpenAI
    api_key = provider.get_secret("OPENAI_API_KEY")
    return OpenAI(api_key=api_key)

SecretProvider is an abstract base class defining a single method, get_secret. EnvSecretProvider implements it using os.environ, appropriate for local development or simple deployments where the platform injects environment variables directly (many container platforms do this even when the underlying secret lives in a secret manager — the platform fetches it and exposes it as an env var at container start). CloudSecretProvider implements the same interface against an injected client object, which means build_openai_client never needs to know which one it's talking to. This is the same dependency-injection principle used throughout this course's testing pattern, applied to configuration instead of to API calls.

A test that exercises this without any real cloud service or real key:

class FakeSecretsClient:
    def __init__(self, secrets: dict[str, str]):
        self._secrets = secrets

    def fetch_secret_value(self, name: str) -> str:
        if name not in self._secrets:
            raise KeyError(f"No such secret: {name}")
        return self._secrets[name]


def test_cloud_secret_provider_returns_value():
    fake_client = FakeSecretsClient({"prod/OPENAI_API_KEY": "sk-fake-prod-key"})
    provider = CloudSecretProvider(fake_client, secret_prefix="prod/")
    assert provider.get_secret("OPENAI_API_KEY") == "sk-fake-prod-key"
    print("PASS: CloudSecretProvider resolves a prefixed secret via the injected client")


def test_env_secret_provider_missing_raises(monkeypatch):
    monkeypatch.delenv("SOME_MISSING_SECRET", raising=False)
    provider = EnvSecretProvider()
    try:
        provider.get_secret("SOME_MISSING_SECRET")
        raised = False
    except KeyError:
        raised = True
    assert raised
    print("PASS: EnvSecretProvider raises KeyError for a missing variable")


test_cloud_secret_provider_returns_value()

Secrets and containers: avoid baking them into images

A related pattern worth calling out explicitly: never pass a secret as a Docker ARG or bake it into an image layer with ENV in a Dockerfile. Both approaches embed the value in the image itself, which means anyone with access to the image (in a registry, or via docker history) can extract it — even if you "remove" it in a later layer, because image layers are cumulative and inspectable individually.

# DO NOT DO THIS — the key becomes part of the image and its history
ENV OPENAI_API_KEY=sk-proj-realkeyvalue

Instead, inject secrets at container runtime, not build time — through your orchestration platform's secret-injection mechanism (Kubernetes Secrets mounted as environment variables, ECS task definition secrets pulled from Secrets Manager, and so on). The image itself should contain no secret material at all; it should only contain code that reads secrets from its environment, exactly as EnvSecretProvider does above.

Common Mistakes

• Committing a real .env file "just this once" for convenience. Even a single accidental commit puts the key into git history permanently, as covered in Lesson 2 — the .gitignore entry must exist before the file does.
• Using the same secret-loading code path in every environment without adapting it. Code written only for EnvSecretProvider tends to get copy-pasted into production as-is, because it "already works," even though production deserves the audit trail and access control a dedicated secret manager provides.
• Baking secrets into container images via build arguments or Dockerfile ENV instructions. This makes the secret retrievable by anyone who can pull or inspect the image, long after the original deployment.

Best Practices

• Match the secret storage mechanism to the environment: .env files for local development, a real secret manager for staging and production.
• Abstract secret retrieval behind a small interface (SecretProvider above) so switching mechanisms — or testing with a fake one — doesn't require touching business logic.
• Inject secrets at runtime, never at build time, so container images remain safe to store, share, and inspect.
• Fail immediately and loudly when a required secret is missing, rather than allowing the application to start in a partially configured state.