Gestion des secrets dlt

dlt fournit une hiérarchie de configuration qui maintient les identifiants hors du code et permet au même pipeline de s’exécuter dans les environnements de développement local, CI/CD et production sans modifier le code.

L’ordre de priorité

dlt résout la configuration et les secrets selon cet ordre de priorité (du plus élevé au plus bas) :

1. Variables d’environnement
2. secrets.toml
3. config.toml
4. Intégrations avec des coffres-forts de secrets
5. Valeurs d’arguments par défaut

Les sources de priorité supérieure écrasent les inférieures. En pratique : les variables d’environnement sont utilisées en production et CI/CD (secrets injectés par le runtime), secrets.toml est utilisé localement (jamais commité dans le contrôle de version), et config.toml contient les paramètres non sensibles qui peuvent être commités.

Développement local : secrets.toml

Pour le développement local, créez un fichier .dlt/secrets.toml dans le répertoire de votre projet :

[sources.my_api]
api_key = "your-secret-key"

[destination.bigquery]
project_id = "your-project"
private_key = "-----BEGIN PRIVATE KEY-----\n..."
client_email = "service-account@project.iam.gserviceaccount.com"

Accédez à ces valeurs dans le code de votre pipeline avec dlt.secrets :

client = RESTClient(
    base_url="https://api.example.com",
    auth=BearerTokenAuth(token=dlt.secrets["sources.my_api.api_key"])
)

Ou utilisez le raccourci lorsque le nom de clé n’est pas ambigu :

auth=BearerTokenAuth(token=dlt.secrets.value)  # dlt infère le chemin depuis le contexte

Ne commitez jamais secrets.toml dans le contrôle de version. Ajoutez .dlt/secrets.toml à votre .gitignore immédiatement lors de la création d’un projet.

CI/CD et production : variables d’environnement

Dans les pipelines CI/CD et les environnements de production, utilisez des variables d’environnement. dlt mappe les variables d’environnement sur les clés de configuration en utilisant des doubles underscores comme séparateurs :

# Identifiants de la source API
export SOURCES__MY_API__API_KEY="your-secret-key"

# Identifiants de la destination BigQuery
export DESTINATION__BIGQUERY__PROJECT_ID="your-project"
export DESTINATION__BIGQUERY__PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."

La convention de nommage : préfixe SOURCES__ pour les identifiants de source, préfixe DESTINATION__ pour les identifiants de destination, puis le chemin de clé imbriqué avec des doubles underscores.

Pour GitHub Actions, stockez ces valeurs dans les secrets du dépôt et référencez-les dans votre workflow :

- name: Run pipeline
  env:
    SOURCES__MY_API__API_KEY: ${{ secrets.MY_API_KEY }}
    DESTINATION__BIGQUERY__PROJECT_ID: ${{ secrets.BIGQUERY_PROJECT_ID }}
  run: python my_pipeline.py

Pour les environnements Google Cloud (Cloud Run, Cloud Functions), utilisez Cloud Secret Manager ou Workload Identity Federation plutôt que des variables d’environnement contenant des identifiants bruts. dlt dispose d’intégrations avec des coffres-forts qui extraient les secrets des gestionnaires externes au moment de l’exécution.

Configuration non sensible : config.toml

Les paramètres qui ne sont pas des secrets mais qui doivent être configurables vont dans .dlt/config.toml :

[pipeline]
log_level = "INFO"
progress = "log"

[sources.my_api]
base_url = "https://api.example.com/v1"
page_size = 100

config.toml peut être commité dans le contrôle de version. Gardez-le exempt de mots de passe, tokens, clés privées et tout ce que vous ne voudriez pas dans un dépôt public.

Accès aux secrets dans le code

dlt offre plusieurs façons d’accéder aux valeurs de configuration :

# Chemin complet de la clé
api_key = dlt.secrets["sources.my_api.api_key"]

# Utiliser dlt.secrets.value avec le contexte du décorateur (dlt infère le chemin)
@dlt.source
def my_source(api_key=dlt.secrets.value):
    ...

# Utiliser dlt.config pour les valeurs non sensibles
page_size = dlt.config["sources.my_api.page_size"]

Lorsqu’un secret requis est manquant, dlt lève une erreur spécifique indiquant exactement quelle clé était attendue et dans quel format. Cela accélère le débogage des problèmes de configuration — il n’est pas nécessaire de chercher quel nom de variable d’environnement la bibliothèque attend.

La vue d’ensemble de bout en bout

Un pipeline conçu pour la gestion des secrets a cette structure :

my_pipeline/
├── .dlt/
│   ├── config.toml      # commité — paramètres non sensibles
│   └── secrets.toml     # dans .gitignore — identifiants locaux uniquement
├── my_pipeline.py       # commité — aucun secret dans le code
└── .gitignore           # inclut .dlt/secrets.toml

Le fichier Python référence dlt.secrets["..."] tout au long. En local, dlt lit depuis secrets.toml. En CI/CD, les variables d’environnement fournissent les mêmes valeurs. En production, les variables d’environnement ou les intégrations avec des coffres-forts font de même. Aucune modification de code entre les environnements — uniquement des modifications de configuration.

Cette séparation est le même principe que la configuration d’une application twelve-factor : stocker la configuration dans l’environnement, jamais dans le code. La hiérarchie de dlt facilite le respect de ce principe sans cérémonie.