envsubstコマンドでシェル変数を環境変数で展開する方法｜テンプレートファイルの動的生成と実務活用も

この記事のポイント

・envsubst はテンプレートの $VAR を環境変数で一括置換するコマンド
・置換対象変数を限定する書き方で誤置換を防げる
・nginx.conf や Docker エントリーポイントとの組み合わせが実務の定番
・変数が未定義の場合は空文字に展開される点に注意

# インストール確認
which envsubst
# 出力例
/usr/bin/envsubst

# バージョン確認
envsubst --version
# 出力例
envsubst (GNU gettext-runtime) 0.21
Copyright (C) 2003-2020 Free Software Foundation, Inc.

# RHEL / Rocky Linux / AlmaLinux
sudo dnf install gettext -y

# Ubuntu / Debian
sudo apt install gettext-base -y

# 環境変数をセット
export SERVER_NAME=web01.example.com
export LISTEN_PORT=8080

# テンプレートをヒアドキュメントで渡す
envsubst << 'EOF'
server {
    listen $LISTEN_PORT;
    server_name $SERVER_NAME;
}
EOF

# 出力例
server {
    listen 8080;
    server_name web01.example.com;
}

# テンプレートファイルを作成
cat nginx.conf.template
server {
    listen $LISTEN_PORT;
    server_name $SERVER_NAME;
    root /var/www/$APP_NAME;
}

# 環境変数をセットして展開・出力
export SERVER_NAME=prod.example.com
export LISTEN_PORT=443
export APP_NAME=myapp

envsubst < nginx.conf.template > /etc/nginx/conf.d/myapp.conf

# 生成されたファイルを確認
cat /etc/nginx/conf.d/myapp.conf
server {
    listen 443;
    server_name prod.example.com;
    root /var/www/myapp;
}

# 危険な例（$uri が空文字に展開される）
cat nginx.conf.template
location / {
    proxy_pass http://$BACKEND_HOST;
    return 301 https://$host$uri;  # nginx 固有変数
}

export BACKEND_HOST=app.internal
envsubst < nginx.conf.template

# 出力（$uri が消える）
location / {
    proxy_pass http://app.internal;
    return 301 https://;    # $host も $uri も消えた
}

# BACKEND_HOST だけを展開する（$host・$uri はそのまま残る）
export BACKEND_HOST=app.internal

envsubst '$BACKEND_HOST' < nginx.conf.template > /etc/nginx/conf.d/proxy.conf

# 確認
cat /etc/nginx/conf.d/proxy.conf
location / {
    proxy_pass http://app.internal;
    return 301 https://$host$uri;    # nginx 固有変数は保持される
}

# 複数変数を限定指定
envsubst '$SERVER_NAME $LISTEN_PORT $APP_NAME' < nginx.conf.template > /etc/nginx/conf.d/myapp.conf

# entrypoint.sh の例
#!/bin/bash
set -e

# テンプレートから実際の設定ファイルを生成
envsubst '$SERVER_NAME $LISTEN_PORT' \
  < /etc/nginx/templates/default.conf.template \
  > /etc/nginx/conf.d/default.conf

# nginx を起動
exec nginx -g 'daemon off;'

# メールテンプレートファイル（mail.template）
Subject: [$ENV] バックアップ完了通知
To: $ADMIN_EMAIL

$HOSTNAME のバックアップが完了しました。
実行時刻: $TIMESTAMP
バックアップ先: $BACKUP_PATH

# バックアップスクリプト内での使用例
export ENV=production
export ADMIN_EMAIL=ops@example.com
export HOSTNAME=$(hostname)
export TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
export BACKUP_PATH=/backup/$(date '+%Y%m%d')

envsubst < mail.template | sendmail -t

# .github/workflows/deploy.yml の抜粋例
- name: Generate config from template
  env:
    DB_HOST: ${{ secrets.DB_HOST }}
    DB_NAME: ${{ secrets.DB_NAME }}
    APP_SECRET: ${{ secrets.APP_SECRET }}
  run: |
    envsubst '$DB_HOST $DB_NAME $APP_SECRET' \
      < config/app.conf.template \
      > config/app.conf

# NG（ローカル変数のため展開されない）
MY_VAR=hello
echo '$MY_VAR' | envsubst
# 出力: $MY_VAR（展開されない）

# OK（export すれば展開される）
export MY_VAR=hello
echo '$MY_VAR' | envsubst
# 出力: hello

# 実行前の変数確認スクリプト（必須チェック）
required_vars=(SERVER_NAME LISTEN_PORT APP_NAME)
for var in "${required_vars[@]}"; do
  if [ -z "${!var}" ]; then
    echo "Error: 環境変数 $var が未定義です" >&2
    exit 1
  fi
done

# チェック通過後に envsubst を実行
envsubst '$SERVER_NAME $LISTEN_PORT $APP_NAME' \
  < nginx.conf.template > /etc/nginx/conf.d/myapp.conf

export SERVER_NAME=prod.example.com

# NG（ダブルクォートはシェルが $SERVER_NAME を展開する）
envsubst "$SERVER_NAME" < template.conf > output.conf
# 第2引数が "prod.example.com" になるため変数名として認識されない

# OK（シングルクォートで変数名をそのまま渡す）
envsubst '$SERVER_NAME' < template.conf > output.conf

# $$ はリテラルの $ に展開される
cat template.txt
価格は $$1,000 です。サーバー: $SERVER_NAME

export SERVER_NAME=web01.example.com
envsubst '$SERVER_NAME' < template.txt

# 出力（$SERVER_NAME のみ展開、$$ はリテラル $ に変換）
価格は $1,000 です。サーバー: web01.example.com