envsubst — Umgebungsvariablen in Texten ersetzen

envsubst gehört zu GNU gettext und ersetzt in einem Text alle Referenzen der Form $VAR und ${VAR} durch die Werte gleichnamiger Umgebungsvariablen. Anders als eval oder eine Shell führt es dabei keine Shell-Expansion durch – keine Befehlssubstitution, kein Globbing, keine Anführungszeichen-Tricks –, sondern tauscht ausschließlich Variablen aus. Genau das macht es zum sicheren Werkzeug, um Templates wie nginx-Konfigurationen, .env-Dateien oder Kubernetes-Manifeste mit Werten aus der Umgebung zu füllen. Mit einem Argument wie '$VAR1 $VAR2' begrenzt du die Ersetzung auf bestimmte Variablen, sodass andere Platzhalter (etwa nginx-eigene wie $uri) unangetastet bleiben. Dieser Guide zeigt dir die Aufrufe, die du im Alltag von Docker-Entrypoints bis CI/CD-Pipelines wirklich brauchst.

Grundlegende Verwendung

envsubst < <template> > <output> — Ersetzt alle $VAR- und ${VAR}-Referenzen durch ihre Werte.

envsubst < config.template > config.conf

echo '$HOME' | envsubst — Ersetzt Variablen in weitergeleitetem Text.

echo 'Hello $USER, your home is $HOME' | envsubst

envsubst < <template> — Gibt den ersetzten Inhalt auf stdout aus.

envsubst < nginx.conf.template

cat <template> | envsubst > <output> — Leitet ein Template durch envsubst.

cat docker-compose.yml.tmpl | envsubst > docker-compose.yml

Variablen einschränken

envsubst '$VAR1 $VAR2' < <template> — Ersetzt nur bestimmte Variablen (alle anderen bleiben unverändert).

envsubst '$DB_HOST $DB_PORT' < config.template > config.conf

envsubst '${VAR1}' < <template> — Ersetzt nur eine einzige bestimmte Variable.

envsubst '${APP_VERSION}' < version.txt.tmpl > version.txt

envsubst --variables '<shell-format>' — Listet alle im Argument referenzierten Variablennamen auf.

envsubst --variables "$(cat nginx.conf.template)"

Docker- und Container-Einsatz

envsubst < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf — Erzeugt eine nginx-Konfiguration im Docker-Entrypoint.

envsubst '${NGINX_HOST} ${NGINX_PORT}' < default.conf.template > /etc/nginx/conf.d/default.conf

envsubst < app.env.template > .env — Erzeugt während des Deployments eine .env-Datei aus einem Template.

envsubst < app.env.template > .env

envsubst '$VAR' < template — Ersetzt nur ausgewählte Variablen; alle übrigen ${...}-Referenzen bleiben wörtlich erhalten.

echo 'Home: $HOME, behalten: ${BUILD_ID}' | envsubst '$HOME'

CI/CD und Skripte

export VAR=value && envsubst < template > output — Setzt eine Variable und ersetzt sie in einer Befehlskette.

export VERSION=1.2.3 && envsubst < manifest.yml.tmpl > manifest.yml

VAR=value envsubst < template — Definiert eine Variable inline für den envsubst-Aufruf.

APP_NAME=myapp envsubst < deploy.yaml.tmpl

env $(cat .env | xargs) envsubst < template — Lädt Variablen aus einer .env-Datei und ersetzt sie.

env $(cat .env | xargs) envsubst < config.template > config.conf

envsubst < k8s/deployment.yaml.tmpl | kubectl apply -f - — Füllt ein Kubernetes-Manifest und wendet es direkt an.

export IMAGE_TAG=v2.0 && envsubst < k8s/deployment.yaml.tmpl | kubectl apply -f -

Typische Muster

for f in *.tmpl; do envsubst < "$f" > "${f%.tmpl}"; done — Verarbeitet alle Template-Dateien und entfernt die Endung .tmpl.

for f in conf/*.tmpl; do envsubst < "$f" > "${f%.tmpl}"; done

envsubst --variables "$(cat template)" | sort — Listet alle für ein Template benötigten Variablen auf.

envsubst --variables "$(cat nginx.conf.template)" | sort

envsubst < template | diff template - — Zeigt, was in einem Template ersetzt wurde.

envsubst < config.template | diff config.template -

Fazit

Die Stärke von envsubst ist die sichere, eng begrenzte Ersetzung: Es tauscht nur $VAR/${VAR} aus und führt im Gegensatz zu eval oder einer Shell keinerlei Befehle aus – ideal, um nicht vertrauenswürdige Templates zu füllen. Übergibst du eine Shell-Format-Zeichenkette wie '$DB_HOST $DB_PORT', beschränkt envsubst die Ersetzung exakt auf diese Variablen; alle anderen Platzhalter (etwa nginx-eigene wie $uri) bleiben wörtlich stehen. Beachte dabei eine Falle: Nicht gesetzte Variablen werden kommentarlos durch einen leeren String ersetzt, nicht etwa als Fehler gemeldet – prüfe mit envsubst --variables, ob wirklich alle benötigten Werte in der Umgebung stehen, bevor du das Ergebnis weiterverwendest. Einen $$-Escape für ein literales Dollarzeichen kennt envsubst nicht; um eine Referenz wörtlich zu erhalten, nimmst du sie einfach aus der Liste der zu ersetzenden Variablen heraus.

Weiterführende Links

GNU gettext: envsubst Invocation – offizielle Referenz zu Aufruf und Optionen (englisch)
GNU gettext: The Programmer's View – Handbuch zum gesamten gettext-Paket, zu dem envsubst gehört (englisch)