Doppler for Multi-Cloud Secrets

A team running across AWS, GCP, and Azure ends up defining the same secret three times, in three formats, with three rotation stories. Doppler centralizes the definition and syncs it to each environment, so there is one source of truth. This page wires Doppler into a Python service with a scoped service token.

Doppler is the multi-cloud, developer-friendly option in the enterprise secrets section, feeding the same validated settings model as every other source.

The problem it solves is one of definition, not storage. Every cloud already has a competent secret store; what none of them offers is a single place to say “this service needs these five keys, and here is what each one is in each environment”. Without that, the same conceptual secret exists as an AWS secret ARN, a GCP Secret Manager version, and an Azure Key Vault entry — three objects, three access policies, three chances for one to drift.

Secure implementation

# secrets/doppler.py
import os
import requests
from pydantic import SecretStr

DOPPLER_API = "https://api.doppler.com/v3/configs/config/secrets/download"

def fetch_doppler_secrets() -> dict[str, SecretStr]:
    token = os.environ["DOPPLER_TOKEN"]            # service token, injected at runtime
    resp = requests.get(
        DOPPLER_API,
        params={"format": "json"},
        auth=(token, ""),                          # token as basic-auth username
        timeout=5,
    )
    resp.raise_for_status()
    return {k: SecretStr(v) for k, v in resp.json().items()}  # mask every field

secrets = fetch_doppler_secrets()
db_url = secrets["DATABASE_URL"].get_secret_value()

The service token is the only thing injected; it is scoped to one project and config and can be rotated without touching the secrets it unlocks. Every fetched value becomes a SecretStr.

The timeout=5 argument is not decoration. requests has no default timeout at all, so omitting it means a Doppler outage or a network black hole can hang the request indefinitely — and since this call happens at startup, the process never becomes ready, the orchestrator’s probe fails, and the pod is killed and restarted into the same hang. A five-second timeout turns that into a fast, clear failure.

raise_for_status() is the other half of failing usefully. A 401 from a revoked token and a 200 with an empty body are very different problems, and letting the HTTP error propagate means the traceback names the status code rather than a KeyError several lines later when a key is missing from an empty dictionary.

Reading DOPPLER_TOKEN with os.environ[...] rather than .get() is deliberate too: a missing token should be a loud KeyError at startup, not a None passed into an auth header that produces a confusing 401.

Configuration reference

The first two rows describe two genuinely different integration styles, and choosing between them matters more than it appears. doppler run wraps the process and populates its environment before Python starts, so the application reads os.environ and knows nothing about Doppler at all — which is elegant, works with any language, and means secrets are visible to every child process and to anything that dumps the environment.

The API fetch keeps values inside the process. Nothing lands in os.environ, so an environment dump or a subprocess inherits nothing, and the application can refresh without restarting. The cost is a hard dependency on Doppler’s API at startup and a token to manage.

The rule that resolves it: use doppler run for local development, where the ergonomics are the point and the blast radius is one laptop; use the API fetch in production, where keeping secrets out of the process environment and being able to refresh without a restart are worth the extra code.

The config row encodes Doppler’s core structural idea. A project holds the schema — which keys exist — and a config holds one environment’s values. Because the key names are identical across configs, the application code is environment-agnostic in exactly the way the twelve-factor principle asks for, and a key missing from one environment is visible as a gap in the project’s own view rather than as a runtime failure during a deploy — which is the difference between noticing a problem while adding a setting and noticing it while a rollout is stuck.

Feeding Doppler into a settings model

The dictionary the fetch returns is workable and untyped. Wiring Doppler in as a settings source means the values arrive as validated fields, a missing key fails at startup with its name, and every other rule in the configuration layer — precedence, types, SecretStr masking — applies unchanged.

# config/settings.py
from typing import Any
from pydantic import SecretStr
from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
from secrets.doppler import fetch_doppler_secrets

class DopplerSource(PydanticBaseSettingsSource):
    def __init__(self, settings_cls):
        super().__init__(settings_cls)
        self._data = fetch_doppler_secrets()          # already SecretStr-wrapped

    def get_field_value(self, field, field_name: str) -> tuple[Any, str, bool]:
        return self._data.get(field_name.upper()), field_name, False

    def __call__(self) -> dict[str, Any]:
        return {k.lower(): v for k, v in self._data.items()}


class Settings(BaseSettings):
    model_config = SettingsConfigDict(extra="ignore")
    database_url: str
    api_key: SecretStr
    log_level: str = "INFO"

    @classmethod
    def settings_customise_sources(cls, settings_cls, init_settings,
                                   env_settings, dotenv_settings, file_secret_settings):
        return (init_settings, env_settings, DopplerSource(settings_cls))

Placing DopplerSource below env_settings keeps the precedence rule that runs through the whole configuration layer: an injected environment variable always wins. That is what lets an operator pin one value during an incident, and what lets a developer override a single field locally without touching the shared config.

extra="ignore" is the pragmatic choice here rather than forbid, because a Doppler config commonly holds keys for several consumers — a frontend build, a sidecar, an unrelated tool — and the model should not fail because a key it does not own exists. If a service owns its config outright, forbid is better; the point is choosing rather than inheriting whichever default happens to apply and discovering the consequences during an incident.

The .upper() and .lower() conversions bridge a naming convention: Doppler keys are conventionally uppercase like environment variables, while pydantic fields are lowercase. Doing the conversion once in the source keeps it out of every field definition and means adding a field requires no extra mapping.

Testing this source is straightforward for the same reason the AWS one was: init arguments sit above it in the order, so a test constructs Settings(database_url="...", api_key="...") and nothing reaches the network. That property is worth protecting deliberately — if a later refactor moves the Doppler fetch into __init__ of the settings class rather than into a source, every test that constructs settings starts making an HTTP call, and the suite becomes slow and flaky for reasons nobody connects to secrets management.

Deployment parity: local to production

1. Local dev — developers run doppler run -- python app.py; no .env, no plaintext.
2. CI — a CI-scoped service token fetches only the secrets the pipeline needs. See Doppler Service Tokens in CI Pipelines.
3. Staging/Production — each environment maps to a Doppler config; the same keys resolve to environment-specific values across providers.

Step one is the strongest argument for Doppler in a team that has been fighting .env files. There is no file to leak, no file to go stale, and no onboarding step where a new developer collects values from colleagues — they run one command and have exactly the same key set as production, with development values. The class of bug where a developer’s local file lacks a key that production requires simply does not arise, because the key list comes from the same project.

It is worth being honest about what that costs. doppler run requires every developer to install the CLI and authenticate, which is a real onboarding step, and it means a developer without network access cannot start the application at all — an offline flight, a conference wifi, a Doppler outage. Teams that care about that keep an escape hatch: doppler secrets download writes a local file that the standard .env path can read, used deliberately and temporarily rather than as the normal route. Treat it the way you would treat any other .env — gitignored, short-lived, and never the default.

The parity argument still holds through all of that. Whether a developer is running under the CLI or from a temporary download, the key names are the ones the project defines, so the failure where local development lacks a key production requires cannot occur.

Steps two and three should use separate tokens with separate scopes, and it is worth being deliberate about this rather than reusing one convenient token. A CI token that can read production secrets means anyone who can modify a pipeline can print them; a token scoped to the CI config can only ever expose test values.

The CI case has a further subtlety worth handling deliberately. Pipelines triggered by forks or by contributors outside the team should not receive a token at all, since a pipeline is a program a contributor can modify and a token in its environment is a token they can print. Most platforms already withhold protected variables from fork-triggered runs; the point is to check that yours does rather than assuming, and to make sure the jobs that genuinely need no secrets are the ones that run on those pipelines.

Local development benefits from the same scoping discipline for a different reason. A developer token that reads the production config is a production credential on a laptop, protected by whatever that laptop’s disk encryption and screen lock happen to be. Scoping developer tokens to the development config keeps the blast radius of a lost laptop to values that were never sensitive.

How syncs change the failure model

Doppler’s syncs push values into other systems — an AWS secret, a Kubernetes Secret, a platform’s environment variables — and they change the runtime picture more than the documentation suggests. With a sync in place, the application may never talk to Doppler at all: it reads a Kubernetes Secret that Doppler keeps updated, so Doppler’s availability stops being on the startup path.

That is a significant operational improvement and it introduces a new failure mode. The value the application reads is now a copy, kept in step by a background process, so the question becomes how quickly a change propagates and what happens when it does not. A sync that stops working leaves a stale copy that continues to serve perfectly — the same silent failure as a rotation that stopped running.

# ops/sync_freshness.py — assert the synced copy matches the source
import os, requests

def sync_drift(project_keys: list[str]) -> list[str]:
    """Return keys whose synced value differs from Doppler's."""
    token = os.environ["DOPPLER_TOKEN"]
    live = requests.get(
        "https://api.doppler.com/v3/configs/config/secrets/download",
        params={"format": "json"}, auth=(token, ""), timeout=5,
    ).json()
    return [k for k in project_keys
            if os.environ.get(k) != live.get(k)]      # env came from the sync

Running that as a periodic check — comparing what the process actually has against what Doppler says it should have — catches a broken sync directly, and it reports key names only, so the output is safe to log and safe to attach to an alert. It is the sync equivalent of the credential-age check that catches stopped rotation.

Choosing between direct API access and a sync comes down to which dependency you prefer. Direct access means one fewer moving part and an immediate view of the current value, at the cost of Doppler being on your startup path. A sync removes that dependency and adds a propagation delay plus something else to monitor. Neither is wrong; what is wrong is having a sync and assuming it is instantaneous and infallible.

Security boundaries & guardrails

• Inject the service token at runtime; never commit it or bake it into an image.
• Scope each token to a single project and config; use read-only tokens for apps.
• Wrap fetched values in SecretStr and unwrap at the call site only.
• Set request timeouts so a Doppler outage fails fast instead of hanging startup.
• Rotate service tokens on a schedule, independent of the secrets they expose.
• Treat the token as equivalent in value to every secret it can read, because that is exactly what it is.

That last framing is the one to hold on to. A service token is not a lesser credential than the secrets behind it — it is a key that unlocks all of them, so it deserves the same handling as the most sensitive value in its config. Teams that treat the token casually because “it’s just a token” have effectively moved the whole config into whatever holds it — a CI variable, a manifest, a laptop’s shell profile.

The practical consequence is that the token belongs in whatever mechanism your platform provides for its most sensitive values, not in a general configuration store. A Kubernetes Secret rather than a ConfigMap; a protected, masked CI variable rather than a plain one; an orchestrator-injected value rather than a file. That sounds obvious written down, and the reason it is worth writing down is that “it’s only the Doppler token” is a phrase that gets said in review, and it is exactly backwards.

The independent-rotation property is what makes the token manageable. Because it authorises access rather than being a credential to a downstream system, rotating it affects nothing but Doppler access: issue a new one, deploy it, revoke the old. No database is touched and no other service is coordinated with, which makes token rotation cheap enough to do on a schedule.

Making it cheap is the point, because the alternative is a token that lives as long as the service. A token issued during an initial setup and never touched afterwards accumulates the same problems as any long-lived credential: nobody is certain where copies of it exist, whether a departed colleague still has one, or whether it appears in an old pipeline definition. Rotating quarterly, as a routine change rather than a response to anything, keeps that uncertainty from building up.

The read-only property deserves the same emphasis. Doppler distinguishes tokens that can read a config from those that can write to it, and an application never needs to write. Issuing read-only tokens for services means a compromised application can expose values — bad — but cannot silently change them, which is worse: a modified secret propagates to every consumer and is far harder to detect than a leaked one.

Refreshing without a restart

The implementation above fetches once at import, which is the right starting point and leaves one capability on the table: because Doppler holds the current value, a service that re-reads periodically picks up a changed secret without a deploy. That turns “update the value in Doppler” into a complete operation rather than the first half of one.

# secrets/doppler.py — periodic refresh with a bounded failure mode
import threading, time

_lock = threading.Lock()
_cache: tuple[float, dict] | None = None
TTL = 300
STALE_GRACE = TTL * 4          # keep serving briefly if Doppler is unreachable

def get_secrets() -> dict[str, SecretStr]:
    global _cache
    now = time.monotonic()
    if _cache and now - _cache[0] < TTL:
        return _cache[1]
    with _lock:
        if _cache and time.monotonic() - _cache[0] < TTL:
            return _cache[1]                       # another thread refreshed
        try:
            _cache = (time.monotonic(), fetch_doppler_secrets())
        except Exception:
            if _cache and now - _cache[0] < STALE_GRACE:
                return _cache[1]                   # serve slightly stale, log it
            raise
        return _cache[1]

The grace period is what keeps a Doppler outage from becoming your outage. Configuration changes rarely, so a value that is twenty minutes old is almost certainly still correct, and serving it while logging a warning is a much better outcome than failing requests because a third-party API is briefly unavailable. The hard limit still exists — past STALE_GRACE the call raises rather than serving something genuinely old.

The double-checked lock is the same pattern used everywhere else in this section, and repeating it rather than inventing a variant is deliberate: one concurrency shape to review, one to test, and one place to fix if it turns out to be subtly wrong.

What this does not give you is a consumer that notices. A refreshed dictionary changes nothing for a connection pool built from the old value — as covered in the rotation patterns, consumers must compare and rebuild. Refreshing the cache is necessary and not sufficient, and a team that adds only the first half often concludes that refresh “does not work”.

Troubleshooting

• 401 Unauthorized — the service token is wrong, revoked, or scoped to a different config.
• Secret missing in one environment — it is defined in another Doppler config; check the environment mapping.
• Startup hangs — no request timeout; add one and fail fast.
• Local container can’t reach Doppler — proxy or DNS issue; see Syncing Doppler Secrets to Local Docker Containers.
• Value updated in Doppler but not in the app — the process read it once at startup; either restart or add a refreshing cache.

The missing-in-one-environment symptom is worth recognising as a schema problem rather than a value problem. Doppler’s project view lists which configs define each key, so a key present in staging and absent in production shows up as a gap in a table rather than as a KeyError during a deploy. Reviewing that view when adding a required setting — in the same change that adds the field to the settings model — closes the loop that .env.example files try and usually fail to close.

The stale-value symptom is the one most likely to be misread as a bug in Doppler. Someone updates a value, refreshes the dashboard to confirm it, and the running service continues with the old one — which looks like a propagation failure and is almost always a process that read once at startup and has no reason to read again. Establishing that first, by restarting one instance and seeing whether it picks up the change, separates a code question from a platform question in under a minute.

Environment mapping deserves a similar sanity check when a value looks wrong rather than missing. A service reading the staging config in production — because the token was copied from a staging deployment — produces values that are entirely valid and entirely incorrect, and no error occurs anywhere. Logging which Doppler config a token resolved to at startup, which the API reports, turns that into a single startup line anyone can check without touching the dashboard.

Key takeaways

The invariant: secrets are defined once in Doppler, fetched via a scoped runtime-injected service token, and held only as SecretStr. One source of truth, every cloud.

What Doppler is genuinely good at is the definition problem — one project describing which keys a service needs, one config per environment holding that environment’s values, and syncs pushing them wherever they are consumed. That removes the drift that appears when the same conceptual secret is maintained separately in three clouds, and it gives local development the same key set as production without a .env file in sight — which addresses the leak path that, in most teams, is responsible for more exposed credentials than every other mechanism combined.

What it does not do is issue dynamic, short-lived credentials, so a leaked Doppler-held secret is valid until someone rotates it. If that matters for a particular credential — a production database, a cloud role — a dynamic secrets engine is the better tool for that one value, and using both is entirely reasonable — Doppler holding the vendor keys and the service configuration, a dynamic engine issuing the database credentials, each doing what it is best at.

That combination is more common in practice than the tooling comparisons suggest, and it is worth naming because teams often treat the choice as exclusive. The question a given credential poses is not “which platform have we standardised on?” but “can this credential be minted on demand?” — and the answer differs per credential within a single service. A settings model with two sources handles that without the application knowing which value came from where. Choose per credential rather than per platform, and set request timeouts so an outage in whichever store you pick fails fast instead of hanging your startup.

If you are adopting Doppler into an existing service, the order that produces value soonest is to move local development first — replacing .env files with doppler run removes the most common leak path and needs no production change at all — then add the API fetch behind a settings source in one service, then extend it. Each step is independently useful, and the first one is reversible in a minute if the team decides the ergonomics do not suit them.