envsubst : générer des configs dynamiques par variables d'environnement

Q: Pourquoi ma variable n'est-elle pas remplacée par envsubst ?

Parce qu'elle n'est pas exportée. envsubst ne substitue que les variables présentes dans l'environnement : il faut export MA_VAR=valeur avant l'appel. Une variable non définie est remplacée par une chaîne vide.

Q: envsubst ou Jinja2, lequel choisir ?

envsubst suffit pour de la substitution simple et rapide, sans dépendance. Dès qu'il faut des conditions, des boucles ou des filtres, on passe à un moteur de templates comme Jinja2 ou gomplate, plus expressifs.

envsubst remplace les variables d'environnement dans un texte ou un fichier modèle, pour générer des fichiers de configuration adaptés à chaque environnement sans les recréer à la main. Léger et sans dépendance, il fait partie de GNU gettext et brille dans les scripts shell et les pipelines CI/CD.

Ce guide s'adresse aux administrateurs système et développeurs qui veulent un templating simple. Vous allez voir la syntaxe, la substitution sélective, la génération de configs (nginx, Docker, Kubernetes), les bonnes pratiques et les limites face à des moteurs plus riches.

Ce que vous allez apprendre

Substituer des variables d'environnement dans un fichier modèle.
Limiter la substitution à certaines variables avec SHELL-FORMAT.
Générer des configurations dans un pipeline CI/CD.
Éviter les pièges (variables non exportées ou non définies).
Choisir entre envsubst et un moteur de templates plus complet.

envsubst fait partie du paquet GNU gettext, principalement utilisé pour l’internationalisation des logiciels, mais cette commande en particulier sert surtout à injecter des valeurs dynamiques dans des fichiers texte à partir des variables d’environnement du shell.

Prenons un exemple simple :

export NOM_SITE="mon-super-site.fr"
echo "Bienvenue sur \$NOM_SITE" | envsubst

Bienvenue sur mon-super-site.fr

Cela peut sembler basique, mais dans un contexte réel, comme la génération de fichiers de configuration comme nginx.conf, docker-compose.yml ou des manifestes Kubernetes, envsubst devient un outil clé pour automatiser les déploiements.

Avantages principaux :

Facile à intégrer dans des scripts shell ou des pipelines CI/CD.
Aucune dépendance externe (présent dans gettext, souvent préinstallé).
Permet de gérer des modèles de configuration dynamiques sans outils complexes.

C’est une solution légère, rapide et efficace pour tous les administrateurs systèmes et développeurs qui veulent automatiser la configuration sans passer par des outils de templating lourds.

Syntaxe de base et options disponibles

La commande envsubst possède une syntaxe simple et directe, conçue pour remplacer les variables d’environnement dans une entrée texte, généralement un fichier ou un flux standard.

Syntaxe générale

envsubst [OPTION] [SHELL-FORMAT]

Par défaut, envsubst lit l’entrée depuis stdin (entrée standard) et écrit le résultat sur stdout (sortie standard).

Exemple minimal

export HOSTNAME=serveur01
echo "Nom d'hôte : \$HOSTNAME" | envsubst

Nom d'hôte : serveur01

Format `SHELL-FORMAT`

L’argument [SHELL-FORMAT] permet de limiter les substitutions aux variables spécifiées :

envsubst '$USER $HOME' < input.txt

Cela permet d’éviter que certaines variables non voulues soient remplacées.

Utilisation simple avec des fichiers de configuration

L’usage typique de envsubst concerne la génération de fichiers de configuration dynamiques à partir de modèles contenant des variables d’environnement.

Étape 1 : Créer un fichier modèle

Ce fichier, souvent avec une extension comme .template, contient des variables sous forme $VAR ou ${VAR} :

# config.template
server {
  listen 80;
  server_name $SERVER_NAME;
  root /var/www/$SITE_DIR;
}

Étape 2 : Définir les variables d’environnement

Dans votre terminal ou script :

export SERVER_NAME=example.com
export SITE_DIR=html

Étape 3 : Générer le fichier final

Utilisez la commande envsubst pour produire un fichier prêt à l’emploi :

envsubst < config.template > config.conf

Le contenu du fichier config.conf :

server {
  listen 80;
  server_name example.com;
  root /var/www/html;
}

Cette méthode est idéale pour automatiser la configuration de serveurs web (nginx, Apache), services Docker ou applications Node.js, sans dupliquer les fichiers selon les environnements. Grâce à envsubst, un seul template suffit : ce sont les variables exportées qui font toute la différence.

Substitution sélective avec SHELL-FORMAT

Par défaut, envsubst remplace toutes les variables d’environnement présentes dans le fichier ou le texte. Mais dans certains cas, vous ne souhaitez substituer que certaines variables spécifiques. C’est là qu’intervient l’argument SHELL-FORMAT.

Syntaxe avec SHELL-FORMAT

envsubst '$VAR1 $VAR2' < input.template > output.conf

Seules $VAR1 et $VAR2 seront remplacées, les autres resteront inchangées.

Exemple concret :

Fichier db.template :

DB_HOST=$DB_HOST
DB_USER=$DB_USER
DB_PASS=$DB_PASS
DB_PORT=$DB_PORT

Variables d’environnement définies :

export DB_HOST=db.local
export DB_USER=admin
export DB_PASS=s3cret
export DB_PORT=5432

Les quatre variables sont bien définies, mais seules $DB_HOST et $DB_USER sont listées dans le SHELL-FORMAT ci-dessous, donc seules celles-là seront remplacées.

Commande :

envsubst '$DB_HOST $DB_USER' < db.template > db.conf

Résultat :

DB_HOST=db.local
DB_USER=admin
DB_PASS=$DB_PASS
DB_PORT=$DB_PORT

Les variables non listées dans le SHELL-FORMAT ($DB_PASS et $DB_PORT) sont laissées intactes.

Cette fonctionnalité permet une plus grande maîtrise lors de la substitution, surtout quand :

plusieurs outils manipulent le même fichier modèle.
certaines variables doivent être définies plus tard ou par un autre processus.
on souhaite éviter de remplacer accidentellement des variables critiques.

Intégration dans des pipelines CI/CD

La commande envsubst s’intègre parfaitement dans les pipelines de déploiement CI/CD, car elle permet de générer à la volée des fichiers de configuration adaptés à l’environnement cible (développement, staging, production...).

Exemple avec un manifeste Kubernetes :

Fichier deployment.yaml.template :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: $APP_NAME
spec:
  replicas: $REPLICAS
  template:
    spec:
      containers:
        - name: $APP_NAME
          image: $IMAGE_NAME

Variables exportées dans le pipeline :

export APP_NAME=mon-app
export REPLICAS=3
export IMAGE_NAME=registry.example.com/mon-app:latest

Intégration dans un pipeline Github :

jobs:
  deploy:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1

      - name: Generate deployment file
        run: |
          envsubst < .k8s/deployment.yaml.template > deployment.yaml
          kubectl apply -f deployment.yaml

Intégration dans GitLab CI/CD :

deploy:
  script:
    - envsubst < .k8s/deployment.tpl.yaml > deployment.yaml
    - kubectl apply -f deployment.yaml

Cette commande remplace les variables, puis transmet le résultat à kubectl.

Cas d’usage courants

Génération de fichiers docker-compose.yml
Configuration automatique d’applications Node.js, Python, PHP
Déploiement via Ansible ou Terraform avec des modèles simples

Avec envsubst, vos pipelines deviennent plus souples et moins dépendants de fichiers statiques, vous permettant de gérer facilement différents environnements sans duplicata de configuration.

Bonnes pratiques et précautions

L'utilisation de envsubst peut sembler triviale, mais quelques erreurs courantes peuvent causer des comportements inattendus. Voici les bonnes pratiques à suivre pour éviter les pièges les plus fréquents.

Utilisez des guillemets simples autour des variables

Lorsque vous passez des variables à envsubst, utilisez des guillemets simples (') pour empêcher leur expansion prématurée par le shell.

# Correct
envsubst '$DB_USER $DB_PASS'

# Incorrect : le shell remplace déjà les variables
envsubst "$DB_USER $DB_PASS"

2. Exportez toutes les variables nécessaires

envsubst ne remplace que les variables déjà exportées. Si une variable n’est pas exportée, elle ne sera pas substituée.

export API_KEY=abc123
envsubst '$API_KEY' < config.template > config.yaml

Sans export, la variable restera vide dans le fichier final.

3. Gérez les variables non définies

Si une variable mentionnée dans le template n’est pas définie, envsubst la remplacera par une chaîne vide, ce qui peut casser un fichier de configuration :

# config.template
api_key=$API_KEY

# Résultat si API_KEY n’est pas définie
api_key=

Utilisez des valeurs par défaut en Bash :

export API_KEY=${API_KEY:-defaultkey}

Ou vérifiez explicitement la présence des variables :

: "${API_KEY:?Variable API_KEY non définie}"

4. Vérifiez le résultat

Avant d’appliquer une configuration générée, affichez-la dans le terminal :

envsubst < config.template

Ou validez le fichier via des outils comme nginx -t, kubectl apply --dry-run=client, etc.

Respecter ces bonnes pratiques garantit une utilisation fiable et prévisible de envsubst, notamment dans des scripts automatisés où chaque détail compte.

Alternatives et limites de `envsubst`

Bien que envsubst soit léger et pratique, il présente aussi des limites qui peuvent le rendre insuffisant pour certains cas d’usage avancés. Connaître ses alternatives permet de choisir l’outil le mieux adapté selon vos besoins.

Limitations de `envsubst`

Pas de logique conditionnelle : impossible d’ajouter des blocs if, else, ou de tester la présence de variables.
Pas de boucles : on ne peut pas générer dynamiquement des sections répétitives.
Pas de gestion d’erreurs native : aucune alerte si une variable est absente ou vide.
Remplacement simple uniquement : pas de support pour les fonctions ou les transformations de variables.

Alternatives plus puissantes

Jinja2 (Python)

Permet d’utiliser une syntaxe expressive avec des conditions, boucles, et filtres :

{% if DEBUG %}
debug = true
{% endif %}

Idéal pour les projets complexes, souvent utilisé avec des templates Ansible ou dans des scripts Python.

envplate (Go)

Utilitaire très rapide et conçu pour les containers Docker. Il peut injecter les variables dans plusieurs fichiers.

https://github.com/kreuzwerker/envplate

mustache / handlebars (JavaScript)

Systèmes de templating simples, orientés substitution de données JSON dans des fichiers modèles. Disponibles dans de nombreux langages.

gomplate (Go)

Plus avancé que envsubst, avec des fonctions intégrées, des sources multiples (fichiers, API, Vault...), et des conditions.

https://github.com/hairyhenderson/gomplate

Conclusion : utilisez envsubst pour des substitutions simples et rapides dans vos fichiers de configuration. Mais pour des besoins plus dynamiques ou structurés, tournez-vous vers Jinja2, gomplate ou d’autres moteurs de templates adaptés aux workflows DevOps modernes.

FAQ : questions fréquentes

Qu'est-ce qu'envsubst ?

envsubst est une commande du paquet GNU gettext qui remplace les variables d'environnement dans un texte ou un fichier modèle. On l'utilise pour générer des fichiers de configuration adaptés à chaque environnement, notamment en CI/CD.

Comment n'appliquer envsubst qu'à certaines variables ?

En passant un argument SHELL-FORMAT : envsubst '$VAR1 $VAR2' < modele. Seules les variables listées entre guillemets simples sont remplacées, les autres restent intactes dans le fichier de sortie.

Pourquoi ma variable n'est-elle pas remplacée par envsubst ?