✨

docker-compose.ymlで使用可能な${VARIABLE:-default}とは？

に公開
Docker
tech

はじめに

Kong OSS版を触っている際に、docker-compose.ymlに記載されている${VARIABLE:-default}の表記に出会いました。
出会った当初、意味や挙動が分からず悩んでしまったので、残しておきます。

記載例:

docker-compose.yml
version: '3.9'

x-kong-config: &kong-env
  KONG_DATABASE: ${KONG_DATABASE:-off}
・・・略・・・
services:
  kong-migrations:
    image: "${KONG_DOCKER_TAG:-kong:latest}"
    command: kong migrations bootstrap
・・・略・・・

※コードの参照元：
https://github.com/Kong/docker-kong/blob/master/compose/docker-compose.yml

結論

dockerの公式リファレンスに記載がありました。
https://docs.docker.com/compose/environment-variables/

Both $VARIABLE and ${VARIABLE} syntax are supported. Additionally when using the 2.1 file format, it is possible to provide inline default values using typical shell syntax:
・${VARIABLE:-default} evaluates to default if VARIABLE is unset or empty in the environment.
・${VARIABLE-default} evaluates to default only if VARIABLE is unset in the environment.

つまり、

  • ${VARIABLE:-default}の構文：環境変数VARIABLEを使用する。ただしその環境変数が未設定、もしくは空の場合、デフォルト値としてdefaultが使用される。

  • ${VARIABLE:default}の構文では、環境変数VARIABLEを使用する。ただしその環境変数が未設定の場合のみ、デフォルト値としてdefaultが使用される。

となります。

そのため、「はじめに」の項目に記載した構文は以下の意味となります。
・KONG_DATABASE: ${KONG_DATABASE:-off}: 環境変数KONG_DATABASEを使用する。KONG_DATABASEが未設定、もしくは空の場合、デフォルト値としてoffを使用する。
・image: "${KONG_DOCKER_TAG:-kong:latest}": 環境変数KONG_DOCKER_TAGを使用する。KONG_DOCKER_TAGが未設定、もしくは空の場合、デフォルト値としてkong:latestを使用する。

指定した値やデフォルト値になるか実際に試してみる

さきほどのdocker-compose.ymlを使用します。
試してみる箇所はimage: "${KONG_DOCKER_TAG:-kong:latest}"とします。
この箇所で、環境変数にバージョン番号付きのイメージ名をセットした場合と、空の値をセットした場合を試してみます。

環境変数にバージョン番号付きのイメージ名をセットした場合

環境変数にバージョン番号付きのイメージ名をセットします。

> export KONG_DOCKER_TAG=kong:2.6.0

docker compose upでkongを立ち上げ、kongの中に入ってkongのバージョンを確認します。

bash-5.1$ echo $KONG_VERSION
2.6.0

指定のバージョンを使用したイメージになっていることが確認できました。

環境変数に空の値をセットした場合

環境変数に空の値をセットします。

> export KONG_DOCKER_TAG=""

さきほどと同様にdocker compose upで立ち上げ、kongのバージョンを確認します。

bash-5.1$ echo $KONG_VERSION
2.7.0

本記事執筆当時のkong:latestのバージョンは2.7.0となっているため、デフォルト値が使用されたことが分かりました。

https://hub.docker.com/layers/kong/library/kong/latest/images/sha256-4d3e93207305ace881fe9e95ac27717b6fbdd9e0ec1873c34e94908a4f4c9335?context=explore

補足

dockerの公式リファレンスにあった、上記${VARIABLE:-default}以降の説明について補足します。

Similarly, the following syntax allows you to specify mandatory variables:
・${VARIABLE:?err} exits with an error message containing err if VARIABLE is unset or empty in the environment.
・${VARIABLE?err} exits with an error message containing err if VARIABLE is unset in the environment.

マイナスの代わりに?を使用することもできるようです。
その場合、以下の挙動になります。

  • ${VARIABLE:?err}の構文では、環境変数VARIABLEを使用する。ただしその環境変数が未設定、もしくは空の場合、errを含むエラーメッセージを表示して終了する。
  • ${VARIABLE?err}の構文では、環境変数VARIABLEを使用する。ただしその環境変数が未設定の場合のみ、errを含むエラーメッセージを表示して終了する。

おわりに

${VARIABLE:-default}の表記の意味と挙動を、公式リファレンスと実際の例をもとに紹介しました。
docker-compose.ymlでデフォルト値を指定できることは知らなかったので、今後機会を見て使っていきます。
この記事が誰かのお役に立てれば幸いです。

Discussion