Compose ファイル展開リファレンス

Compose 仕様とは、複数のコンテナアプリケーションを定義するための、プラットフォームに中立な手法です。Compose の実装でサポートしているアプリケーションの 展開（デプロイ）(deployment) モデルは、サービスごとに必要となる実際の基盤や、ライフサイクルの制限を反映するには、Compose アプリケーションモデルが抽象的すぎるため、追加のメタデータが必要になる場合が あります(MAY) 。

Compose 仕様のデプロイに従うと、ユーザはサービス上に追加のメタデータを宣言できるようになります。そのため、Compose 実装はプラットフォーム上の適切なリソースから、ユーザが必要とする設定に一致するデータを取得できます。

定義

Compose Specification （仕様）は、サービス上で deploy （展開/デプロイ）サブセクションをオプションでサポートするように拡張されました。このセクションでは、サービスに対するランタイム要件を定義します。

endpoint_mode

endpoint_mode は、外部のクライアントがサービスに接続するための、 サービス ディスカバリ(service discovery) 手法を指定します。デフォルト値および利用可能な値はプラットフォーム固有ですが、どのような場合でも Compose 仕様では2つの適切な値を定義しています。

  • endpoint_mode: vip ：サービスに対して仮想 IP （VIP）を割り当てます。これはクライアントがネットワーク上のサービスに到達可能にするためのエンドポイントとして機能します。プラットフォームはクライアントとノードを実行しているサービス間の 経路(route) を要求しますが、クライアントはノードが何台かや、適切なサービスや IP アドレスやポートを知らなくても要求できます。

  • endpoint_mod: dnsrr ：プラットフォームはサービスのために DNS エントリをセットアップします。サービス名に対する DNS 問い合わせは、IP アドレス（ DNS ラウンドロビン）のリストを返し、クライアントはそれらの1つに直接接続します。

services:
  frontend:
    image: awesome/webapp
    ports:
      - "8080:80"
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

labels

labels はサービスに対してメタデータを指定します。これらのラベルは、サービスに対して「のみ」設定されるだけでなく、サービス用のあらゆるコンテナ「にも」設定されます。これは、プラットフォームが「サービス」という（Compose とは別の）固有の概念を持っていると想定しているためであり、それを Compose アプリケーション モデルと一致できるようにするためです。

services:
  frontend:
    image: awesome/webapp
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"

mode

mode はプラットフォーム上でサービスを実行するために使う複製モデル（レプリケーション モデル）を定義します。 global （物理ノードごとに1つのコンテナだけ）か replicated （コンテナの数を指定する）です。デフォルトは replicated です。

services:
  frontend:
    image: awesome/webapp
    deploy:
      mode: global

placement

placement はサービス コンテナを実行するプラットフォーム上の物理ノードを選択するための、 制約(constraint) や設定を指定します。

constraints

constraints は、サービス コンテナを実行するため、プラットフォームのノードが 確実に必要としなければいけない 、 :ruby:`必須(REQUIRED) の属性を定義します。リスト形式またはマップ形式の文字列で指定します。

deploy:
  placement:
    constraints:
      - disktype=ssd

deploy:
  placement:
    constraints:
      disktype: ssd

preferences

preferences は、サービス コンテナを実行するため、プラットフォームのノードが 満たすべき(SHOULD) 属性を定義します。リスト形式またはマップ形式の文字列で指定します。

deploy:
  placement:
    preferences:
      - datacenter=us-east

deploy:
  placement:
    preferences:
      datacenter: us-east

replicas

サービスを複製 replicated （これがデフォルトです）する場合、 replicas では常に 実行すべき(SHOULD) コンテナの数を指定します。

services:
  frontend:
    image: awesome/webapp
    deploy:
      mode: replicated
      replicas: 6

resources

resources 設定は、プラットフォーム上でコンテナを実行するにあたり、物理リソースの制限を設定します。それぞれの制限は、次のようにして設定します。

  • limis ：プラットフォームは、コンテナに指定した以上の割り当てを防ぐ 必要があります(MUST) 。

  • reservations ：プラットフォームは少なくとも設定した容量をコンテナに対して確実に割り当てる 必要があります(MUST) 。

services:
  frontend:
    image: awesome/webapp
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
          pids: 1
        reservations:
          cpus: '0.25'
          memory: 20M

cpus

cpus はコンテナが利用できる割り当て可能な CPU リソース（コア数として指定）を、制限または予約する設定をします。

memory

memory コンテナが割り当て可能なメモリ容量を、制限または予約する設定をします。設定は バイト値 の文字列で表します。

pids

pid はコンテナの PID 上限を調整するために、整数値で設定します。

devices

devices はコンテナが利用できるデバイスの予約を設定します。予約リストの中にある場合、以下のパラメータで各オブジェクトを設定できます： capabilities 、 drievr 、 count 、 device_ids 、 options です。

デバイスは capabilities のリストを使って予約するために、 capabilities のフィールドのみが飛鳥です。予約が成功するためには、デバイスが全ての必要な capabilities を満たす 必要があります(MUST) 。

capabilities

capabilities はリストまたは文字列で設定し、一般的なケーパビリティとドライバ固有のケーパビリティの両方で表せます。現時点では、以下の一般的なケーパビリティを認識します。

  • gpu ：グラフィクス アクセラレータ

  • tpu ：AI アクセラレータ

名前の衝突を避けるため、ドライバ固有のケーパビリティには、ドライバ名をプレフィクスとして指定する 必要があります(MUST) 。たとえば、 nVidia CUDA で有効なアクセラレータを予約するには、次のようにします。

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["nvidia-compute"]
driver

デバイスの予約には、 driver フィールドを使って異なるドライバを要求できます。この値は、文字として指定します。

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["nvidia-compute"]
          driver: nvidia
count

count を all にするか指定がない場合、 Compose 実装は要求したケーパビリティを満たすドライバすべてを予約する 必要があります(MUST) 。そうでない場合には、 Compose 実装は、少なくても指定された数のデバイスを予約する必要があります。値は整数値で指定します。

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["tpu"]
          count: 2

count と device_ids フィールドは どちらか片方しか使えません(exclusive) 。Compose 実装は両方が指定された場合にエラーを返す 必要があります(MUST) 。

device_ids

device_ids が指定された場合、Compose 実装は、要求したケーパビリティを満たし、指定した ID を提供するデバイスを予約する 必要があります(MUST) 。値は文字列のリストとして指定します。

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["gpu"]
          device_ids: ["GPU-f123d1c9-26bb-df9b-1c23-4a731f61d8c7"]

count と device_ids フィールドは どちらか片方しか使えません(exclusive) 。Compose 実装は両方が指定された場合にエラーを返す 必要があります(MUST) 。

options

ドライバのオプションは、 options でキーバリューのペアとして設定できます。

deploy:
  resources:
    reservations:
      devices:
        - capabilities: ["gpu"]
          driver: gpuvendor
          options:
            virtualization: false

restart_policy

restart_policy はコンテナが終了した場合、どのように再起動するかを指定します。 restart_policy の指定がなければ、 Compose 実装はサービス設定で restart フィールドが設定されているとみなす 必要があります(MUST) 。

  • condition ： noen 、 on-failure 、 any11 のどれか1つです（デフォルト： ``any ）

  • delay ：再起動を試みるまで待機する時間を :ref:`期間 <compose-spec-specifying-duration>`で指定します（デフォルト：0）。

  • max_attemps ：コンテナ再起動を中断するまで、何度試みるかを設定します（デフォルト：諦めません）。設定した window （期間）で再起動が成功しない場合、試行は設定された max_attempts 値として数えません。たとえば、 max_attempts` を ``2 に指定すると、最初の試行で再起動に失敗したとしても、少なくとも2回目を試行する 必要があります(MUST) 。

  • window`` ：再起動が成功したと判断するまで待機する時間を :ref:`期間 <compose-spec-specifying-duration>`で指定します（デフォルト：即時）。

deploy:
     restart_policy:
       condition: on-failure
       delay: 5s
       max_attempts: 3
       window: 120s

rollback_config

rollback_config は、更新に失敗した場合、サービスをどのようにロールバックするかを設定します。

  • parallelism ：同時にコンテナをロールバックする数です。 0 を指定すると、全コンテナのロールバックを一斉に行います。

  • delay ：各コンテナのグループがロールバックするまで待機する時間です（デフォルトは 0s）。

  • failure_action ：ロールバックに失敗した場合にどうするか設定します。 continue か pause のどちらかです（デフォルトは pause ）。

  • monitor ：各タスクのロールバックが失敗するまで監視する期間です（ ns|us|ms|s|m|h ）（デフォルトは 0s）。

  • max_failure_ratio ：ロールバック中に許容される失敗の割合（デフォルトは 0）。

  • order ：ロールバック中に処理する順番。 stop-first （古いタスクを停止してから、新しいタスクを開始）、 start-first （まず新しいタスクを起動するため、実行中のタスクが瞬間的に重複）のどちらかです。（デフォルトは stop-first ）

update_config

update_config は、どのようにしてサービスを更新すべきか設定します。ローリングアップデートの設定に役立ちます。

  • parallelism ：同時にコンテナを更新する数です。

  • delay ：各コンテナのグループが更新するまで待機する時間です。

  • failure_action ：更新に失敗した場合にどうするか設定します。 continue か pause のどちらかです（デフォルトは pause ）。

  • monitor ：各タスク更新が失敗するまで監視する期間です（ ns|us|ms|s|m|h ）（デフォルトは 0s）。

  • max_failure_ratio ：更新中に許容される失敗の割合。

  • order ：更新中に処理する順番。 stop-first （古いタスクを停止してから、新しいタスクを開始）、 start-first （まず新しいタスクを起動するため、実行中のタスクが瞬間的に重複）のどちらかです。（デフォルトは stop-first ）

deploy:
  update_config:
    parallelism: 2
    delay: 10s
    order: stop-first

参考

Compose file deploy reference

https://docs.docker.com/compose/compose-file/deploy/