Compose file version 3 reference 日本語訳

[Compose file version 3 reference](https://docs.docker.com/compose/compose-file/compose-file-v3/) の日本語訳。

このリファレンスページのトピックは compose ファイルの構造を反映するために、トップレベルキーのアルファベット順に編成されています。
``build`` , ``deploy`` , ``depends_on`` , ``networks`` などの構成ファイルのセクションを定義するトップレベルのキーが、サブトピックとしてそれらをサポートするオプションとともに列記されます。
これは compose ファイルの ``<key>: <option>: <value>`` インデント構造に紐づけされます。

# サービス構成リファレンス

compose ファイルは ``services`` , ``networks`` , ``volumes`` を定義する YAML ファイルです。
compose ファイルのデフォルトパスは ``./docker-compose.yml`` です。

>Tip: このファイルには ``.yml`` または ``.yaml`` 拡張子のいずれかを使用でき、両方とも機能します。

サービス定義には、コマンドラインパラメーターを ``docker run`` に渡すのと同じように、そのサービスに対して開始された各コンテナーに適用される構成が含まれます。
同様にネットワークとボリュームの定義は ``docker network create`` と ``docker volume create`` に類似しています。

``docker run`` と同様に Dockerfile で指定された [CMD](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#cmd) , [EXPOSE](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#expose) , [VOLUME](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#volume) , [ENV](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#env) などのオプションはデフォルトで適用されます。
再び ``docker-compose.yml`` へ指定する必要はありません。

Bash のような ``${VARIABLE}`` 構文を使用して、環境変数を使用できます。
詳細については [変数の置換](#変数の置換) を参照してください。

このセクションにはバージョン 3 のサービス定義でサポートされているすべての構成オプションの一覧が掲載されています。

## build

ビルド時に適用される構成オプション。

[build](#build) は、ビルドコンテキストへのパスを含む文字列として指定できます。

```yaml
version: "3.8"
services:
  webapp:
    build: ./dir
```

または [context](#context) で指定されたパスと、オプションで [dockerfile](#dockerfile) と [args](#args) を持つオブジェクトとして指定できます。

```yaml
version: "3.8"
services:
  webapp:
    build:
      context: ./dir
      dockerfile: Dockerfile-alternate
      args:
        buildno: 1
```

[build](#build) だけでなく [image](#image) も指定した場合、 Compose は [image](#image) で指定された ``webapp`` とオプションの ``tag`` を使用してビルドされたイメージに名前を付けます:

```yaml
build: ./dir
image: webapp:tag
```

これにより ``./dir`` から作成された ``webapp`` という名前のイメージとタグが作成されます。

> ``docker stack deploy`` を使用する場合の注意
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [build](#build) オプションは無視されます。
> ``docker stack`` コマンドは、デプロイ前にイメージをビルドしません。

### context

Dockerfile を含むディレクトリへのパス、または git リポジトリへの URL のいずれか。

指定された値が相対パスの場合、 Compose ファイルの場所からの相対パスとして解釈されます。
ここで指定されるディレクトリは Docker デーモンへ送信されるビルドコンテキストでもあります。

Compose はビルドを実行して自動生成された名前でタグを付け、ビルドされたイメージを使用します。

```yaml
build:
  context: ./dir
```

### dockerfile

代替 Dockerfile を指定します。

Compose はビルド用代替ファイルを使用します。
ビルドパスも指定する必要があります。

```yaml
build:
  context: .
  dockerfile: Dockerfile-alternate
```

### args

ビルド引数を追加します。
これはビルドプロセス中に限りアクセス可能な環境変数です。

まず Dockerfile で引数を指定します。

```dockerfile
ARG buildno
ARG gitcommithash

RUN echo "Build number: $buildno"
RUN echo "Based on commit: $gitcommithash"
```

次に [build](#build) キーの下に引数を指定します。
マッピングまたはリストを渡すことができます。

```yaml:マップ形式
build:
  context: .
  args:
    buildno: 1
    gitcommithash: cdc3b19
```

```yaml:リスト形式
build:
  context: .
  args:
    - buildno=1
    - gitcommithash=cdc3b19
```

> ビルド引数のスコープ
>
> Dockerfile で [FROM](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#from) 命令の前に [ARG](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#arg) を指定すると、 [FROM](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#from) の下のビルド命令で [ARG](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#arg) を使用できなくなります。
> 両方の場所で引数を使用できるようにする必要がある場合は、 [FROM](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#from) 命令で引数を指定します。
> 使用法の詳細については、ドキュメント [ ARG と FROM の相互作用を理解する](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#arg-%E3%81%A8-from-%E3%81%AE%E7%9B%B8%E4%BA%92%E4%BD%9C%E7%94%A8%E3%82%92%E7%90%86%E8%A7%A3%E3%81%99%E3%82%8B) を参照してください。

ビルド引数を指定するときに値を省略できます。
その場合、ビルド時の値は Compose が実行されている環境の値になります。

```yaml
args:
  - buildno
  - gitcommithash
```

> 真偽値使用時のヒント
>
> YAML 真偽値 ("true", "false", "yes", "no", "on", "off") はパーサーが文字列として解釈するように、必ず二重引用符で括らなければなりません。

### cache_from

> バージョン 3.2 ファイル形式から導入されました。

エンジンがキャッシュの解決に使用するイメージの一覧を指定します。

```yaml
build:
  context: .
  cache_from:
    - alpine:latest
    - corp/web_app:3.14
```

### labels

> バージョン 3.3 ファイル形式から導入されました。

ビルドされたイメージへ [Docker ラベル](https://docs.docker.com/config/labels-custom-metadata/) を使用してメタデータを追加します。
配列または辞書のいずれかを使用できます。

ラベルが他のソフトウェアで使用されているラベルと競合しないように逆 DNS 表記を使用することをお勧めします。

```yaml:辞書形式
build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""
```

```yaml:配列形式
build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"
```

### network

> バージョン 3.4 ファイル形式から導入されました。

ビルド中に [RUN](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#run) 命令のために接続するネットワークコンテナを設定します。

```yaml
build:
  context: .
  network: host
```

```yaml
build:
  context: .
  network: custom_network_1
```

ビルド中にネットワークを無効にするには ``none`` を使用します。

```yaml
build:
  context: .
  network: none
```

### shm_size

> バージョン 3.5 ファイル形式から導入されました。

このビルドのコンテナの ``/dev/shm`` パーティションのサイズを設定します。
バイト数を表す整数値または [バイト値](#バイト値の指定) を表す文字列として指定します。

```yaml
build:
  context: .
  shm_size: '2gb'
```

```yaml
build:
  context: .
  shm_size: 10000000
```

### target

> バージョン 3.4 ファイル形式から導入されました。

[target](#target) に指定されたステージを、 Dockerfile に記述された定義に沿ってビルドします。
詳細については [マルチステージビルドのドキュメント](https://docs.docker.com/develop/develop-images/multistage-build/) を参照してください。

```yaml
build:
  context: .
  target: prod
```

## cap_add, cap_drop

コンテナ機能を追加または削除します。
コンテナ機能の完全な一覧については ``man 7 capabilities`` を参照してください。

```yaml
cap_add:
  - ALL

cap_drop:
  - NET_ADMIN
  - SYS_ADMIN
```

> ``docker stack deploy`` 使用時の注意
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) ``cap_add`` と ``cap_drop`` オプションは無視されます。

## cgroup_parent

任意のコンテナの親 cgroup を指定します。

```yaml
cgroup_parent: m-executor-abcd
```

> ``docker stack deploy`` 使用時の注意
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [cgroup_parent](#cgroup_parent) オプションは無視されます。

## command

既定のコマンドを上書きします。

```yaml
command: bundle exec thin -p 3000
```

[command](#command) は [dockerfile](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#cmd) と同様の方法でリストにすることもできます。

```yaml
command: ["bundle", "exec", "thin", "-p", "3000"]
```

## configs

サービスごとの [configs](#configs) 構成を使用して、サービスごとに [configs](#configs) へのアクセスを許可します。
2 つの異なる構文バリアントがサポートされています。

> 注: 構成は当該スタックファイルの ``最上位の configs 構成`` にすでに存在しているか、定義されている必要があります。
> 定義されていない場合、スタックの展開は失敗します。

``configs`` の詳細については [configs](https://docs.docker.com/engine/swarm/configs/) を参照してください。

### 短い構文

短い構文バリアントは、構成名のみを指定します。
これによりコンテナに構成へのアクセスが許可され、コンテナ内の ``/<config_name>`` にマウントされます。
参照元の名前と宛先マウントポイントは両方とも構成名に設定されます。

次の例では短い構文を使用して ``redis`` サービスに ``my_config`` および ``my_other_config`` 構成へのアクセスを許可しています。
``my_config`` の値はファイル ``./my_config.txt`` の内容に設定され、 ``my_other_config`` は外部リソースとして定義されます。
つまり ``docker config create`` コマンドまたは他のスタックのデプロイを実行することにより Docker ですでに定義されています。
外部構成が存在しない場合スタックのデプロイは ``config not found`` エラーで失敗します。

> バージョン 3.3 ファイル形式から導入されました。
>
> [configs](#configs) 定義は compose ファイル形式のバージョン 3.3 以降でのみサポートされています。

```yaml
version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - my_config
      - my_other_config
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true
```

### 長い構文

長い構文によりサービスのタスクコンテナ内で構成を作成する方法がより細かくなります。


* ``source`` : Docker に存在する構成の名前。
* ``target`` : サービスのタスクコンテナにマウントされるファイルのパスと名前。
指定しない場合デフォルトは ``/<source>`` です。
* ``uid`` と ``gid`` : サービスのタスクコンテナ内にマウントされた構成ファイルの所有者の数値 UID または GID。
  指定されていない場合 Linux では両方ともデフォルトで ``0`` になります。
  Windows ではサポートされていません。
* ``mode`` : サービスのタスクコンテナ内にマウントされるファイルの 8 進表記のアクセス許可。
  たとえば ``0444`` は誰でも読み取り可能なことを表します。
  デフォルトは ``0444`` です。
  [configs](#configs) は一時ファイルシステムにマウントされているため、書き込み可能にすることはできません。
  したがって書き込み可能ビットを設定すると ``configs`` は無視されます。
  実行可能ビットを設定できます。
  UNIX ファイルのアクセス許可モードに慣れていない場合は [アクセス許可計算ツール](http://permissions-calculator.org/) が便利です。

次の例ではコンテナ内で ``my_config`` の名前を ``redis_config`` に設定し、モードを 
``0440`` (グループ読み取り可能)に設定し、ユーザーとグループを ``103`` に設定します。
``redis`` サービスは ``my_other_config`` 設定にアクセスできません。

```yaml
version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    configs:
      - source: my_config
        target: /redis_config
        uid: '103'
        gid: '103'
        mode: 0440
configs:
  my_config:
    file: ./my_config.txt
  my_other_config:
    external: true
```

複数の [configs](#configs) へのサービスアクセスを許可でき、長い構文と短い構文を混在させることができます。
``config`` を定義することは、その ``config`` へのサービスアクセスを許可することを意味するものではありません。

## container_name

生成されたデフォルト名ではなく、カスタムコンテナ名を指定します。

```yaml
container_name: my-web-container
```

Docker コンテナー名は一意である必要があるため、カスタム名を指定した場合、サービスを 1 コンテナーを超えてスケ​​ーリングすることはできません。
カスタム名を指定した状態でサービスをスケーリングしようとするとエラーが発生します。

> ``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [container_name](#container_name) オプションは無視されます

## credential_spec

> [credential_spec](#credential_spec) オプションはバージョン 3.3 ファイル形式から導入されました。
>
> Compose ファイルでの group Managed Service Account(gMSA) 構成の使用は、ファイル形式バージョン 3.8 以降でサポートされています。

マネージドサービスアカウントの資格情報仕様を構成します。
このオプションは Windows コンテナーを使用するサービスに限り使用されます。
[credential_spec](#credential_spec) は ``file://<filename>`` または ``registry://<value-name>`` の形式である必要があります。

``file:`` を使用する場合、参照されるファイルは Docker データディレクトリの ``CredentialSpecs`` サブディレクトリに存在する必要があります。
Windowsではデフォルトで ``C:\ProgramData\Docker\`` になります。
次の例では ``C:\ProgramData\Docker\CredentialSpecs\my-credential-spec.json`` から資格情報の仕様をロードします。

```yaml
credential_spec:
  file: my-credential-spec.json
```

``registry:`` を使用する場合、資格情報の仕様はデーモンのホスト上の Windows レジストリから読み取られます。
指定された名前のレジストリ値は、次の場所にある必要があります。

```batch
HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs
```

次の例では、レジストリの ``my-credential-spec`` という名前の値から資格情報仕様をロードします。

```yaml
credential_spec:
  registry: my-credential-spec
```

### gMSA 構成の記述例

次の例に示すように、サービスの gMSA 資格情報仕様を構成する場合は [configs](#configs) で資格情報仕様を指定するだけで済みます。

```yaml
version: "3.8"
services:
  myservice:
    image: myimage:latest
    credential_spec:
      config: my_credential_spec

configs:
  my_credentials_spec:
    file: ./my-credential-spec.json|
```

## depends_on

サービス間の依存関係を表現します。
サービスの依存関係により、次の動作が発生します。

* ``docker-compose up`` は依存関係の順序でサービスを開始します。
  次の例では ``db`` と ``redis`` は ``web`` の前に開始されます。
* ``docker-compose up SERVICE`` には、自動的に ``SERVICE`` の依存関係が含まれます。
  以下の例では ``docker-compose up web`` も ``db`` と ``redis`` を作成して開始します。
* ``docker-compose stop`` は、依存関係の順序でサービスを停止します。
  次の例では ``db`` と ``redis`` の前に ``web`` が停止しています。

```yaml:単純な記述例
version: "3.8"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres
```

> [depends_on](#depends_on) を使用する際に注意すべきことがいくつかあります:
>
> * [depends_on](#depends_on) は ``db`` と ``redis`` が「準備完了」になるのを待たずに ``web`` を開始します - ``db`` と ``redis`` が開始されるまで待つだけです。
>  サービスの準備が整うのを待つ必要がある場合は、この問題とそれを解決するための戦略の詳細について [起動順序の制御](https://docs.docker.com/compose/startup-order/) を参照してください。
> * バージョン 3 は [depends_on](#depends_on) の条件形式をサポートしなくなりました。
> * バージョン 3 の compose ファイルを使用して [スウォームモードでスタックをデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [depends_on](#depends_on) オプションは無視されます。

## deploy

> バージョン 3 ファイル形式から導入されました。

サービスのデプロイと実行に関連する構成を指定します。
これは [docker stack deploy](https://docs.docker.com/engine/reference/commandline/stack_deploy/) を使用して [スウォーム](https://docs.docker.com/engine/swarm/) にデプロイする場合に限り有効であり、 ``docker-compose up`` と ``docker-compose run`` では無視されます。

```yaml
version: "3.8"
services:
  redis:
    image: redis:alpine
    deploy:
      replicas: 6
      placement:
        max_replicas_per_node: 1
      update_config:
        parallelism: 2
        delay: 10s
      restart_policy:
        condition: on-failure
```

いくつかのサブオプションが利用可能です:

### endpoint_mode

> バージョン 3.2 ファイル形式から導入されました。

スウォームに接続する外部クライアントのサービス検出方法を指定します。
  
* ``endpoint_mode: vip`` - Docker はクライアントがネットワーク上のサービスに到達するためのフロントエンドとして機能する仮想 IP(VIP)をサービスに割り当てます。
  Docker は、サービスに参加しているノードの数や IP アドレスまたはポートをクライアントが知らなくても、クライアントとサービスで使用可能なワーカーノードの間でリクエストをルーティングします。
  (これは既定の動作です)

* ``endpoint_mode: dnsrr`` -  DNS ラウンドロビン(DNSRR)サービス検出は、単一の仮想 IP を使用しません。
  Docker は、サービス名の DNS クエリが IP アドレスのリストを返すように、サービスの DNS エントリを設定します。
クライアントはこれらのいずれかに直接接続します。
DNS ラウンドロビンは、独自のロードバランサーを使用する場合、または Windows と Linux のハイブリッドアプリケーションに役立ちます。

```yaml
version: "3.8"

services:
  wordpress:
    image: wordpress
    ports:
      - "8080:80"
    networks:
      - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: vip

  mysql:
    image: mysql
    volumes:
       - db-data:/var/lib/mysql/data
    networks:
       - overlay
    deploy:
      mode: replicated
      replicas: 2
      endpoint_mode: dnsrr

volumes:
  db-data:

networks:
  overlay:
```

[endpoint_mode](#endpoint_mode) のオプションはスウォームモードの CLI コマンド [docker service create](https://docs.docker.com/engine/reference/commandline/service_create/) のフラグとしても機能します。
スウォームに関連するすべての docker コマンドのクイックリストについては、スウォームモードの CLI コマンドを参照してください。

スウォームモードでのサービス検出とネットワークの詳細については、スウォームモードトピックの [サービス検出の構成](https://docs.docker.com/engine/swarm/networking/#configure-service-discovery) のトピックを参照してください。

### labels

サービスのラベルを指定します。
これらのラベルはサービスにのみ設定され、サービスのコンテナには設定されません。

```yaml
version: "3.8"
services:
  web:
    image: web
    deploy:
      labels:
        com.example.description: "This label will appear on the web service"
```

代わりにコンテナにラベルを設定するには [deploy](#deploy) の外側で [labels](#labels) キーを使用します。

```yaml
version: "3.8"
services:
  web:
    image: web
    labels:
      com.example.description: "This label will appear on all containers for the web service"
```

### mode

* ``global`` :スウォームノードごとに正確に 1 つのコンテナ
* ``replicated`` :指定された数のコンテナ

デフォルトは ``replicated`` です。
(詳細については [スウォーム](https://docs.docker.com/engine/swarm/) トピックの [複製とグローバルサービス](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/#replicated-and-global-services) を参照してください)

```yaml
version: "3.8"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    deploy:
      mode: global
```

### placement

制約と設定の配置を指定します。
構文と使用可能な [制約](https://docs.docker.com/engine/reference/commandline/service_create/#specify-service-constraints---constraint) と [設定](https://docs.docker.com/engine/reference/commandline/service_create/#specify-service-placement-preferences---placement-pref) の種類、 [ノー​​ド毎の最大レプリカ数の指定](https://docs.docker.com/engine/reference/commandline/service_create/#specify-maximum-replicas-per-node---replicas-max-per-node) の詳細については ``docker service create`` のドキュメントを参照してください。

```yaml
version: "3.8"
services:
  db:
    image: postgres
    deploy:
      placement:
        constraints:
          - "node.role==manager"
          - "engine.labels.operatingsystem==ubuntu 18.04"
        preferences:
          - spread: node.labels.zone
```

### max_replicas_per_node

バージョン 3.8 ファイル形式から導入されました。

サービスが ``replicated`` (既定値)である場合は、 [ノードで実行できるレプリカの数を常に制限](https://docs.docker.com/engine/reference/commandline/service_create/#specify-maximum-replicas-per-node---replicas-max-per-node) します。

実行中のノードよりも多くのタスクが要求されると以下のエラーが発生します。

```bash
no suitable node(max replicas per node limit exceed)
```

```yaml
version: "3.8"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
      placement:
        max_replicas_per_node: 1
```

### replicas

サービスが ``replicated`` (既定値)である場合は、任意の時点で実行する必要があるコンテナーの数を指定します。

```yaml
version: "3.8"
services:
  worker:
    image: dockersamples/examplevotingapp_worker
    networks:
      - frontend
      - backend
    deploy:
      mode: replicated
      replicas: 6
```

### resources

リソースの制約を設定します。

> Compose ファイルバージョン 3 から変更されました。
>
> [resources](#resources) セクションは、バージョン 3 より前の Compose ファイルの [古いリソース制約オプション](https://docs.docker.com/compose/compose-file/compose-file-v2/#cpu-and-other-resources) ( ``cpu_shares`` , ``cpu_quota`` , ``cpuset`` , ``mem_limit`` , ``memswap_limit`` , ``mem_swappiness`` )を置換します。
> Compose ファイル形式のバージョン 2 とバージョン 3 の違いについては [バージョン 2.x から 3.x へのアップグレード](https://docs.docker.com/compose/compose-file/compose-versioning/#upgrading) を参照してください。

これらはそれぞれ単一の値であり [docker service create](https://docs.docker.com/engine/reference/commandline/service_create/) の対応物に類似しています。

この一般的な例では、 ``redis`` サービスは 50M 以下のメモリと ``0.50`` (シングルコアの 50%)の使用可能な処理時間(CPU)を使用するように制限されており、 ``20M`` のメモリと ``0.25`` の CPU 時間が(常に利用可能なリソースとして)予約されています。

```yaml
version: "3.8"
services:
  redis:
    image: redis:alpine
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 50M
        reservations:
          cpus: '0.25'
          memory: 20M
```

以下のトピックでは、スウォーム内のサービスまたはコンテナーにリソース制約を設定するために使用可能なオプションについて説明します。

> 非スウォームモードコンテナにリソースを設定するオプションをお探しですか?
>
> ここで説明するオプションは [deploy](#deploy) キーとスウォームモードに固有です。
スウォーム以外のデプロイメントにリソース制約を設定する場合は [ファイル形式バージョン 2 の CPU、メモリ、およびその他のリソースオプション](https://docs.docker.com/compose/compose-file/compose-file-v2/#cpu-and-other-resources) を使用してください。
> さらに不明点がある場合は GitHub のイシュー [docker/compose/4513](https://github.com/docker/compose/issues/4513) に関する議論を参照してください。

#### Out Of Memory Exceptions (OOME)

サービスまたはコンテナがシステムで利用可能なメモリよりも多くのメモリを使用しようとすると Out Of Memory Exception(OOME) が発生し、コンテナまたは Docker デーモンがカーネル OOM キラーによって強制終了される可能性があります。
これを防ぐには、アプリケーションが適切なメモリを備えたホストで実行されていることを確認し [メモリ不足のリスクを理解する](https://docs.docker.com/config/containers/resource_constraints/#understand-the-risks-of-running-out-of-memory) を参照してください。

### restart_policy

コンテナが終了したときにコンテナを再起動するかどうかと、再起動する方法を構成します。
[restart](#restart) を置き換えます。

* ``condition`` :
  * ``none``
  * ``on-failure``
  * ``any`` (既定値)
* ``delay`` : 再起動の試行間隔の待機時間を [期間](#期限の指定) として指定します。 (既定値: 5s)
* ``max_attempts`` : コンテナの再起動を断念するまでに試行する回数(既定値: 断念しません )
  ``window`` に指定された期間内に再起動が成功しない場合、再起動の試行は ``max_attempts`` にカウントされません。
  たとえば ``max_attempts`` が ``2`` に設定されていて、最初の試行で再起動が失敗した場合、 3 回以上の再起動が試行される可能性があります。
* ``window`` : 再起動が成功したかどうかを判断するまでの待機時間を [期間](#期限の指定) として指定します(既定値: 即時判断します)。

```yaml
version: "3.8"
services:
  redis:
    image: redis:alpine
    deploy:
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
```

### rollback_config

バージョン 3.7 ファイル形式から導入されました。

更新が失敗した場合にサービスをロールバックする方法を構成します。

* ``parallelism`` : 一度にロールバックするコンテナーの数。
  0 に設定すると、すべてのコンテナが同時にロールバックします。
* ``delay`` : 各コンテナグループのロールバック中に待機する時間(デフォルトは ``0s`` )。
* ``failure_action`` : ロールバックが失敗した場合の対処方法。
  * ``continue``
  * ``pause`` (既定値)
* ``monitor`` : 失敗を監視するための各タスク更新後の期間(既定値は ``5s`` )
  注意: 0 を指定すると既定値の ``5s`` が使用されます。
  * ``ns``
  * ``us``
  * ``ms``
  * ``s``
  * ``m``
  * ``h``
* ``max_failure_ratio`` : ロールバック中の許容できない失敗率 (既定値は 0)
* ``order`` : ロールバック中の操作の順序。(既定値は ``stop-first`` )
  * ``stop-first`` (新しいタスクを開始する前に古いタスクを停止します)
  * ``start-first`` (新しいタスクが最初に開始され、実行中のタスクが一時的に重複します)

### update_config

サービスの更新方法を構成します。
ローリングアップデートの構成に役立ちます。

* ``parallelism`` : 一度に更新するコンテナーの数。
* ``delay`` : コンテナのグループを更新するまで待機する時間。
* ``failure_action`` : 更新が失敗した場合の対処方法。
  * ``continue``
  * ``rollback``
  * ``pause`` (既定値)
* ``monitor`` : 失敗を監視するための各タスク更新後の期間(既定値は ``5s`` )
  注意: 0 を指定すると既定値の ``5s`` が使用されます。
  * ``ns``
  * ``us``
  * ``ms``
  * ``s``
  * ``m``
  * ``h``
* ``max_failure_ratio`` : 更新中に許容できる失敗率。
* ``order`` : 更新中の操作の順序。(既定値 ``stop-first`` )
  注意: v3.4 以上である場合に限りサポートしています。
  * ``stop-first`` (新しいタスクを開始する前に古いタスクを停止します)
  * ``start-first`` (新しいタスクが最初に開始され、実行中のタスクが一時的に重複します)

> バージョン 3.4 ファイル形式から導入されました。
>
> ``order`` オプションは v3.4 以降の Compose ファイル形式でのみサポートされます。

```yaml
version: "3.8"
services:
  vote:
    image: dockersamples/examplevotingapp_vote:before
    depends_on:
      - redis
    deploy:
      replicas: 2
      update_config:
        parallelism: 2
        delay: 10s
        order: stop-first
```

### ``docker stack deploy`` ではサポートされません。

( ``docker-compose up`` と ``docker-compose run`` でサポートされる)以下のサブオプションは、 ``docker stack deploy`` または [deploy](#deploy) キーではサポートされません。

* [build](#build)
* [cgroup_parent](#cgroup_parent)
* [container_name](#container_name)
* [devices](#devices)
* [tmpfs](#tmpfs)
* [external_links](#external_links)
* [links](#links)
* [network_mode](#network_mode)
* [restart](#restart)
* [security_opt](#security_opt)
* [userns_mode](#userns_mode)

> Tip
>
> 詳細は [サービス、スウォームと docker-stack.yml ファイルのボリュームを構成する方法](#サービススウォームおよびスタックファイルのボリューム) に関するセクションを参照してください。
> ボリュームはサポートされていますが、スウォームとサービスを操作するには、名前付きボリュームとして構成するか、必要なボリュームにアクセスできるノードに制限されているサービスに関連付ける必要があります。

## devices

デバイスの紐づけのリストです。
docker クライアント作成オプションの ``--device`` と同じ形式を使用します。

```yaml
devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
```

> ``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [devices](#devices) オプションは無視されます。

## dns

カスタム DNS サーバー。
単一の値またはリストにすることができます。

```yaml:単一の値
dns: 8.8.8.8
```

```yaml:リスト形式
dns:
  - 8.8.8.8
  - 9.9.9.9
```

## dns_search

カスタム DNS 検索ドメイン。
単一の値またはリストにすることができます。

```yaml:単一の値
dns_search: example.com
```

```yaml:リスト形式
dns_search:
  - dc1.example.com
  - dc2.example.com
```

## entrypoint

デフォルトの [entrypoint](#entrypoint) を上書きします。

```yaml
entrypoint: /code/entrypoint.sh
```

[entrypoint](#entrypoint) は [dockerfile と同様の方法でリストにする](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#entrypoint) こともできます。

```yaml
entrypoint: ["php", "-d", "memory_limit=-1", "vendor/bin/phpunit"]
```

> 注意
>
> [entrypoint](#entrypoint) を設定すると、 Dockerfile の [ENTRYPOINT](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#entrypoint) 命令を使用してサービスのイメージに設定されているエントリーポイントが上書きされます。
> イメージに設定されているデフォルトコマンドも削除されます。
> (Dockerfile 上に [CMD](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9#cmd) 命令が記述されていても無視されます)

## env_file

ファイルから環境変数を追加します。
単一の値またはリストにすることができます。

``docker-compose -f FILE`` を使用して Compose ファイルを指定した場合、 [env_file](#env_file) 内のパスは Compose ファイルが存在するディレクトリが基準となります。

[environment](#environment) セクションで宣言された環境変数は、これらの値を上書きします。
これは値が空または未定義の場合でも当てはまります。

```yaml:単一の値
env_file: .env
```

```yaml:リスト形式
env_file:
  - ./common.env
  - ./apps/web.env
  - /opt/runtime_opts.env
```

Compose は、 env ファイルの各行が ``VAR=VAL`` 形式であることを想定しています。
``#`` で始まる行はコメントとして扱われ、無視されます。
空白行も無視されます。

```bash
# Set Rails/Rack environment
RACK_ENV=development
```

> 注意
>
> サービスに [build](#build) オプションが指定されている場合、環境ファイルで定義された変数はビルド中に自動的に可視化されません。
> [build](#build) の [args](#args) サブオプションを使用してビルド時の環境変数を定義してください。

``VAL`` の値はそのまま使用され、まったく変更されません。
たとえば、値が引用符で囲まれている場合(シェル変数の場合によくあることです)、引用符は Compose に渡される値に含まれます。

リスト内のファイルの順序は、複数回表れる変数に割り当てる値を決定する上で重要であることに注意してください。
リスト内のファイルは上から下に処理されます。
ファイル ``a.env`` で指定され、ファイル ``b.env`` で異なる値が割り当てられた同じ変数について ``b.env`` が下(後)に列記されている場合、 ``b.env`` に指定された値が採用されます。
たとえば ``docker-compose.yml`` で次の宣言が与えられた場合:

```yaml:docker-compose.yml
services:
  some-service:
    env_file:
      - a.env
      - b.env
```

後に続くファイル:

```bash:a.env
VAR=1
```

さらに後に続くファイル:

```bash:b.env
VAR=hello
```

``$VAR`` は ``hello`` となります。

## environment

環境変数を登録します。
配列または辞書形式のいずれかを使用できます。
ブール値(true, false, yes, no)は、 YML パーサーによって True または False に変換されないように引用符で囲む必要があります。

キーのみを持つ環境変数は、 Compose が実行されているマシンの設定値に解決されます。
これはシークレット値またはホスト固有の値に役立ちます。

```yaml:辞書形式
environment:
  RACK_ENV: development
  SHOW: 'true'
  SESSION_SECRET:
```

```yaml:配列形式
environment:
  - RACK_ENV=development
  - SHOW=true
  - SESSION_SECRET
```

> 注意
>
> サービスに [build](#build) オプションが指定されている場合、 [environment](#environment) で定義された変数はビルド中に自動的に可視化されません。
> [build](#build) の [args](#args) サブオプションを使用して、ビルド時の環境変数を定義してください。

## expose

ポートをホストマシンに公開せず、リンクされたサービスに限定して公開します。
ポートはリンクされたサービスに限りアクセスできます。
指定できるのは内部ポートのみです。

```yaml
expose:
  - "3000"
  - "8000"
```

## external_links

当該 ``docker-compose.yml`` の外部、または Compose の外部で開始されたコンテナー(特に共有サービスまたは共通サービスを提供するコンテナー)へのリンクを定義します。
コンテナ名とリンクエイリアス( ``CONTAINER:ALIAS`` )の双方を指定する場合、 [external_links](#external_links) は古いオプションである [links](https://docs.docker.com/compose/compose-file/compose-file-v3/compose-file-v2#links) に似た記述方式に従います。

```yaml
external_links:
  - redis_1
  - project_db_1:mysql
  - project_db_1:postgresql
```

> 注意
>
> 外部で作成されたコンテナは、それらにリンクしているサービスと同じネットワークの少なくとも 1 つに接続されている必要があります。
> [links](https://docs.docker.com/compose/compose-file/compose-file-v3/compose-file-v2#links) は古いオプションです。
> 代わりに [networks](#networks) を使用することをお勧めします。

> ``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 場合、 [external_links](#external_links) オプションは無視されます。

## extra_hosts

ホスト名の紐づけを登録します。
docker クライアントの ``--add-host`` パラメーターと同じ値を使用します。

```yaml
extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"
```

IP アドレスとホスト名を持つエントリは、このサービスのコンテナ内の ``/etc/hosts`` に作成されます。

```bash:/etc/hosts
162.242.195.82  somehost
50.31.209.229   otherhost
```

## healthcheck

当該サービスのコンテナが ``healthy`` であるかどうかを判断するために実行されるチェックを構成します。
[healthcheck](#healthcheck) がどのように機能するかの詳細については、 [HEALTHCHECK Dockerfile 命令](https://qiita.com/JhonnyBravo/items/c743a20c539c1aaaa2a9) のドキュメントを参照してください。

```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

``interval`` 、 ``timeout`` 、 ``start_period`` が [期間](#期限の指定) として指定されます。

> ``start_period`` オプションはバージョン 3.4 ファイル形式から導入されました。

``test`` は文字列またはリストのいずれかである必要があります。
リストの場合、最初の項目は ``NONE`` 、 ``CMD`` 、または ``CMD-SHELL`` のいずれかである必要があります。
文字列の場合は ``CMD-SHELL`` の後にその文字列を指定するのと同じです。

```yaml
# Hit the local web app
test: ["CMD", "curl", "-f", "http://localhost"]
```

上記と同じですが、 ``/bin/sh`` でラップされています。
以下の両方の形式は同等です。

```yaml:リスト形式
test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
```

```yaml:文字列形式
test: curl -f https://localhost || exit 1
```

イメージに設定されたデフォルトの [healthcheck](#healthcheck) を無効にするには、 ``disable: true`` を使用します。
これは ``test: ["NONE"]`` を指定するのと同じです。

```yaml
healthcheck:
  disable: true
```

## image

コンテナを開始するイメージを指定します。
``repository/tag`` または部分的なイメージ ID のいずれかです。

```yaml
image: redis
```

```yaml
image: ubuntu:18.04
```

```yaml
image: tutum/influxdb
```

```yaml
image: example-registry.com:4000/postgresql
```

```yaml
image: a4bc65fd
```

イメージが存在しない場合、 [build](#build) を指定していない限り、 Compose はイメージをプルしようとします。
[build](#build) 指定した場合は、指定されたオプションを使用してイメージをビルドし、指定されたタグでタグ付けします。

## init

> バージョン 3.7 ファイル形式から導入されました。

シグナルを転送してプロセスを刈り取るコンテナ内で [init](#init) を実行します。
このオプションを ``true`` に設定すると、サービスでこの機能が有効になります。

```yaml
version: "3.8"
services:
  web:
    image: alpine:latest
    init: true
```

> 使用されるデフォルトの [init](#init) バイナリは [Tini](https://github.com/krallin/tini) です。
> デーモンホストの ``/usr/libexec/docker-init`` にインストールされます。
> [init-path 構成オプション](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-configuration-file) を使用して、カスタム [init](#init) バイナリを使用するようにデーモンを構成できます。

## isolation

コンテナの分離テクノロジを指定します。
Linux でサポートされている値は ``default`` のみです。
Windows の許容値は ``default`` 、 ``process`` 、 ``hyperv`` です。
詳細については [Docker Engine のドキュメント](https://docs.docker.com/engine/reference/commandline/run/#specify-isolation-technology-for-container---isolation) を参照してください。

## labels

[Docker ラベル](https://docs.docker.com/config/labels-custom-metadata/) を使用してメタデータをコンテナーに追加します。
配列または辞書形式のいずれかを使用できます。

ラベルが他のソフトウェアで使用されているラベルと競合しないように、逆 DNS 表記を使用することをお勧めします。

```yaml:辞書形式
labels:
  com.example.description: "Accounting webapp"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
```

```yaml:配列形式
labels:
  - "com.example.description=Accounting webapp"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"
```

## links

> 警告
>
> ``--link`` フラグは Docker の古い機能です。
> 最終的には削除される可能性があります。
> どうしても使い続ける必要がない限り ``--link`` を使用する代わりに [ユーザー定義のネットワーク](https://docs.docker.com/compose/networking/) を使用して 2 つのコンテナ間の通信を容易にすることをお勧めします。
>
> ユーザー定義ネットワークがサポートしていない ``--link`` で実行できる機能の 1 つは、コンテナー間で環境変数を共有することです。
> ただしボリュームなどの他の仕組みを使用して、より制御された方法でコンテナー間で環境変数を共有できます。

別のサービスのコンテナにリンクします。
サービス名とリンクエイリアス( ``SERVICE:ALIAS`` )の両方を指定するか、サービス名のみを指定します。

```yaml
web:
  links:
    - "db"
    - "db:database"
    - "redis"
```

リンクされたサービスのコンテナは、エイリアスと同じホスト名、またはエイリアスが指定されていない場合はサービス名で到達可能です。

サービス間の通信を有効化するために [links](#links) は必須ではありません。
デフォルトでは、どのサービスもそのサービスの名前で他のサービスに到達できます。
( [Compose におけるネットワークに記述されている links のトピック](https://docs.docker.com/compose/networking/#links) も参照してください)

[links](#links) も [depends_on](#depends_on) と同じ方法でサービス間の依存関係を表すため、サービスの起動順序を決定します。

> 注意
>
> [links](#links) と [networks](#networks) の両方を定義する場合、それらの間にリンクがあるサービスは、通信するために少なくとも 1 つの共通のネットワークを共有する必要があります。

>``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 場合、 [links](#links) オプションは無視されます。

## logging

サービスのログ構成。

```yaml
logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"
```

[driver](#driver) の名前は [docker run の --log-driver オプション](https://docs.docker.com/config/containers/logging/configure/) と同様に、サービスコンテナーのロギングドライバーを指定します。

デフォルト値は ``json-file`` です。

```yaml
driver: "json-file"
```

```yaml
driver: "syslog"
```

```yaml
driver: "none"
```

>注意
>
> ``json-file`` と ``journald`` ドライバーのみが、 ``docker-compose up`` と ``docker-compose logs`` から直接ログを利用できるようにします。
> 他のドライバーを使用してもログは出力されません。

``docker run`` の ``--log-opt`` オプションと同様に ``options`` キーを使用してロギングドライバーのロギングオプションを指定します。

ロギングオプションはキーと値のペアです。
``syslog`` オプションの例:

```yaml
driver: "syslog"
options:
  syslog-address: "tcp://192.168.0.42:123"
```

デフォルトのドライバー [json-file](https://docs.docker.com/config/containers/logging/json-file/) には、保存されるログの量を制限するオプションがあります。
ログの保存量を制限するには、最大ストレージサイズ( ``max-size`` )と最大ファイル数( ``max-file`` )にキーと値のペアを使用します。

```yaml
options:
  max-size: "200k"
  max-file: "10"
```

上記の例ではログファイルが 200kB の ``max-size`` に達するまでログファイルを保存してからローテーションします。
保存される個々のログファイルの数は、 ``max-file`` 値で指定されます。
ログが最大制限を超えると古いログファイルが削除され、新しいログを保存できるようになります。

ロギングストレージを制限する ``docker-compose.yml`` ファイルの例を次に示します。

```yaml
version: "3.8"
services:
  some-service:
    image: some-service
    logging:
      driver: "json-file"
      options:
        max-size: "200k"
        max-file: "10"
```

> 使用可能なログオプションは、使用するログドライバーによって異なります。
>
> ログファイル数とストレージサイズを制御する上記の例では [json-file ドライバー](https://docs.docker.com/config/containers/logging/json-file/) に固有のオプションを使用しています。
> これらの特定のオプションは、他のロギングドライバーでは使用できません。
> サポートされているロギングドライバーとそのオプションの完全なリストについては [ロギングドライバー](https://docs.docker.com/config/containers/logging/configure/) のドキュメントを参照してください。

## network_mode

ネットワークモード。
docker クライアントの ``--network`` パラメータと同じ値に加えて、特別な形式 ``service:[service name]`` を使用します。

```yaml
network_mode: "bridge"
```

```yaml
network_mode: "host"
```

```yaml
network_mode: "none"
```

```yaml
network_mode: "service:[service name]"
```

```yaml
network_mode: "container:[container name/id]"
```

> 注意
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) このオプションは無視されます。
> ``network_mode: "host"`` を [links](#links) と混在させることはできません。

## networks

参加するネットワーク。
トップレベルの [networks](#networks) キー配下のエントリを参照します。

```yaml
services:
  some-service:
    networks:
     - some-network
     - other-network
```

### aliases

ネットワーク上のサービスのエイリアス(代替ホスト名)。
同じネットワーク上の他のコンテナは、サービス名またはこのエイリアスのいずれかを使用して、サービス内のコンテナへ接続できます。

[aliases](#aliases) はネットワーク内で閉じているため、同じサービスが異なるネットワーク上で異なるエイリアスを持つことができます。

> 注意
>
> ネットワーク間のエイリアスは、複数のコンテナー、さらには複数のサービスで共有できます。
> 上記の場合、名前がどのコンテナに解決されるかは正確には保証されません。

一般的な形式を次に示します。

```yaml
services:
  some-service:
    networks:
      some-network:
        aliases:
          - alias1
          - alias3
      other-network:
        aliases:
          - alias2
```

以下の例では 2 つのネットワーク( ``new`` と ``legacy`` )とともに、 3 つのサービス( ``web`` 、 ``worker`` 、 ``db`` )が提供されています。
``db`` サービスは、 ``new`` ネットワーク上のホスト名 ``db`` または ``database`` と、 ``legacy`` ネットワーク上の ``db`` または ``mysql`` で到達可能です。

```yaml
version: "3.8"

services:
  web:
    image: "nginx:alpine"
    networks:
      - new

  worker:
    image: "my-worker-image:latest"
    networks:
      - legacy

  db:
    image: mysql
    networks:
      new:
        aliases:
          - database
      legacy:
        aliases:
          - mysql

networks:
  new:
  legacy:
```

### ipv4_address, ipv6_address

ネットワーク参加時の当該サービスのコンテナーの静的 IP アドレスを指定します。

トップレベル [networks](#networks) セクションの対応するネットワーク構成には、各静的アドレスをカバーするサブネット構成を持つ ``ipam`` ブロックが必要です。

> IPv6 アドレシングが必要な場合は ``enable_ipv6`` オプションを設定する必要があり、バージョン 2.x の Compose ファイルを使用する必要があります。
> 現在 IPv6 オプションはスウォームモードでは機能しません。

```yaml:記述例
version: "3.8"

services:
  app:
    image: nginx:alpine
    networks:
      app_net:
        ipv4_address: 172.16.238.10
        ipv6_address: 2001:3984:3989::10

networks:
  app_net:
    ipam:
      driver: default
      config:
        - subnet: "172.16.238.0/24"
        - subnet: "2001:3984:3989::/64"
```

## pid

```yaml
pid: "host"
```

PID モードをホスト PID モードに設定します。
これにより、コンテナとホストオペレーティングシステム間の PID アドレス空間の共有がオンになります。
このフラグで起動されたコンテナは、ベアメタルマシン名前空間内の他のコンテナにアクセスして操作できます。
その逆も可能です。

## ports

ポートを公開します。

>注意
>
> ポートマッピングは ``network_mode: host`` と互換性がありません

### 短い構文

両方のポート( ``HOST:CONTAINER`` )を指定するか、コンテナポートのみを指定します(エフェメラルホストポートが選択されます)。

> 注意
>
> ポートを ``HOST:CONTAINER`` 形式でマッピングする場合、 YAML は``xx:yy`` 形式の数値をベース 60 の値として解析するため、 60 未満のコンテナポートを使用すると誤った結果が発生する可能性があります。
> このため、ポートマッピングを常に文字列として明示的に指定することをお勧めします。

```yaml
ports:
  - "3000"
  - "3000-3005"
  - "8000:8000"
  - "9090-9091:8080-8081"
  - "49100:22"
  - "127.0.0.1:8001:8001"
  - "127.0.0.1:5000-5010:5000-5010"
  - "6060:6060/udp"
  - "12400-12500:1240"
```

### 長い構文

長い形式の構文では、短い形式では表現できない追加のフィールドを構成できます。

* ``target`` : コンテナ内のポート
* ``published`` : 公開されているポート
* ``protocol`` : ポートプロトコル ( ``tcp`` または ``udp`` )
* mode:
  * host: 各ノードでホストポートを公開する。
  * ingress: 負荷分散を目的とするスウォームモードポート。

```yaml
ports:
  - target: 80
    published: 8080
    protocol: tcp
    mode: host
```

> 長い形式の構文はバージョン 3.2 ファイル形式から導入されました。

## restart

```yaml
restart: "no"
```

``no`` はデフォルトの [再起動ポリシー](https://docs.docker.com/config/containers/start-containers-automatically/#use-a-restart-policy) であり、どのような状況であってもコンテナを再起動しません。

```yaml
restart: always
```

``always`` を指定すると、コンテナは常に再起動します。

```yaml
restart: on-failure
```

終了コードが ``on-failure`` エラーを示している場合、 ``on-failure`` ポリシーはコンテナを再起動します。

```yaml
restart: unless-stopped
```

``unless-stopped`` は、コンテナが(手動またはその他の方法で)停止している場合を除いて、常にコンテナを再起動します。

> ``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) 再起動オプションは無視されます。

## secrets

サービスごとの [secrets](#secrets) 構成を使用して、サービスごとにシークレットへのアクセスを許可します。
2 つの異なる構文バリアントがサポートされています。

> ``docker stack deploy`` 使用時の注意事項
>
> ``secret`` は Compose ファイルの最上位の [secrets](#secrets) 構成にすでに存在しているか、定義されている必要があります。
> そうでない場合、スタックの展開は失敗します。

詳細は [secrets](https://docs.docker.com/engine/swarm/secrets/) を参照してください。

### 短い構文

短い構文バリアントは ``secret`` の名前のみを指定します。
これによりコンテナにシークレットへのアクセスが許可され、コンテナ内の ``/run/secrets/<secret_name>`` にマウントされます。
ソース名と宛先マウントポイントは両方ともシークレット名に設定されます。

次の例では短い構文を使用して ``redis`` サービスに ``my_secret`` および ``my_other_secret`` シークレットへのアクセスを許可しています。
``my_secret`` の値はファイル ``./my_secret.txt`` の内容に設定され、 ``my_other_secret`` は外部リソースとして定義されています。
つまり Docker ですでに定義されています。
``docker secret create`` コマンドを実行するか、別の ``docker stack deployment`` を実行します。
外部シークレットが存在しない場合、スタックの展開は失敗し、 ``secret not found`` というエラーが発生します。

```yaml
version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - my_secret
      - my_other_secret
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true
```

### 長い構文

長い構文により、サービスのタスクコンテナ内でシークレットを作成する方法がより細かくなります。

* ``source`` : Docker に存在するシークレットの名前。
* ``target`` : サービスのタスクコンテナの ``/run/secrets/`` にマウントされるファイルの名前。
  指定されていない場合、デフォルトは ``source`` です。
* ``uid`` と ``gid`` : サービスのタスクコンテナの ``/run/secrets/`` 内のファイルを所有する数値の UID または GID。
  指定しない場合、両方ともデフォルトで ``0`` になります。
* ``mode`` : サービスのタスクコンテナの ``/run/secrets/`` にマウントするファイルの権限。
  8 進表記で指定してください。
  たとえば ``0444`` は ``誰でも読取可能`` であることを表します。
  Docker 1.13.1 のデフォルトは ``0000`` ですが、新しいバージョンでは ``0444`` です。
  シークレットは一時ファイルシステムにマウントされているため、書き込み可能にすることはできません。
  したがって書き込み可能ビットを設定すると、シークレットは無視されます。
  実行可能ビットは設定できます。
  UNIX ファイルのアクセス許可モードに慣れていない場合は、この [アクセス許可計算ツール](http://permissions-calculator.org/) が役立つ場合があります。

次の例では、コンテナ内で ``my_secret`` の名前を ``redis_secret`` に設定し、 ``mode`` を ``0440`` (グループ読み取り可能) に設定し、 ``user`` と ``group`` を ``103`` に設定します。
``redis`` サービスは ``my_other_secret`` シークレットにアクセスできません。

```yaml
version: "3.8"
services:
  redis:
    image: redis:latest
    deploy:
      replicas: 1
    secrets:
      - source: my_secret
        target: redis_secret
        uid: '103'
        gid: '103'
        mode: 0440
secrets:
  my_secret:
    file: ./my_secret.txt
  my_other_secret:
    external: true
```

複数のシークレットへのアクセスをサービスに許可したり、長い構文と短い構文を混在させたりすることができます。
シークレットを定義することは、シークレットへのサービスアクセスを許可することを意味するものではありません。

## security_opt

各コンテナのデフォルトのラベル付けスキームを上書きします。

```yaml
security_opt:
  - label:user:USER
  - label:role:ROLE
```

> ``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [security_opt](#security_opt) オプションは無視されます。

## stop_grace_period

コンテナが ``SIGTERM`` (または ``stop_signal`` で指定された停止シグナル)を処理しない場合にコンテナの停止を試行するときに、 ``SIGKILL`` を送信する前の待機時間を指定します。
[期間](#期限の指定) として指定されます。

```yaml
stop_grace_period: 1s
```

```yaml
stop_grace_period: 1m30s
```

デフォルトでは ``stop`` はコンテナが終了するまで 10 秒間待機してから ``SIGKILL`` を送信します。

## stop_signal

コンテナを停止するための代替信号を設定します。
デフォルトでは ``stop`` は ``SIGTERM`` を使用します。
[stop_signal](#stop_signal) を使用して代替信号を設定すると、 ``stop`` は代わりにその信号を送信します。

```yaml
stop_signal: SIGUSR1
```

## sysctls

コンテナに設定するカーネルパラメータ。
配列または辞書形式のいずれかを使用できます。

```yaml:辞書形式
sysctls:
  net.core.somaxconn: 1024
  net.ipv4.tcp_syncookies: 0
```

```yaml:配列形式
sysctls:
  - net.core.somaxconn=1024
  - net.ipv4.tcp_syncookies=0
```

カーネルで名前空間が設定されている ``sysctls`` のみを使用できます。
Docker は、ホストシステムも変更するコンテナー内の ``sysctls`` の変更をサポートしていません。
サポートされている ``sysctls`` の概要については、 [実行時に名前空間付きカーネルパラメーター(sysctls)を構成する](https://docs.docker.com/engine/reference/commandline/run/#configure-namespaced-kernel-parameters-sysctls-at-runtime) を参照してください。

> ``docker stack deploy`` 使用時の注意事項
>
> このオプションでは [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) Docker Engine 19.03 以降が必要です。

## tmpfs

> バージョン 3.6 ファイル形式から導入されました。

コンテナ内に一時ファイルシステムをマウントします。
単一の値またはリストを指定することができます。

```yaml:単一の値
tmpfs: /run
```

```yaml:リスト
tmpfs:
  - /run
  - /tmp
```

> ``docker stack deploy`` 使用時の注意事項
>
> Compose ファイル(バージョン 3-3.5)を使用して [スウォームモードでスタックをデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) このオプションは無視されます。

コンテナ内に一時ファイルシステムをマウントします。
``size`` パラメーターは [tmpfs](#tmpfs) マウントのサイズをバイト単位で指定します。
デフォルトでは無制限です。

```yaml
- type: tmpfs
  target: /app
  tmpfs:
    size: 1000
```

## ulimits

コンテナのデフォルトの ``ulimits`` を上書きします。
単一の制限を整数として指定するか、 ``soft`` / ``hard`` 制限をマッピング指定できます。

```yaml
ulimits:
  nproc: 65535
  nofile:
    soft: 20000
    hard: 40000
```

## userns_mode

```yaml
userns_mode: "host"
```

Docker デーモンがユーザー名前空間で構成されている場合、このサービスのユーザー名前空間を無効にします。
詳細については [dockerd](https://docs.docker.com/engine/reference/commandline/dockerd/#disable-user-namespace-for-a-container) を参照してください。

> ``docker stack deploy`` 使用時の注意事項
>
> [スタックをスウォームモードでデプロイする場合](https://docs.docker.com/engine/reference/commandline/stack_deploy/) [userns_mode](#userns_mode) オプションは無視されます。

## volumes

サービスのサブオプションとして指定されたホストパスまたは名前付きボリュームをマウントします。

単一サービスの定義の一部としてホストパスをマウントでき、最上位の [volumes](#volumes) キーで定義する必要はありません。

ただし複数のサービス間でボリュームを再利用する場合は、最上位の [volumes](#volumes) キーで名前付きボリュームを定義します。
サービス、スウォーム、およびスタックファイルで名前付きボリュームを使用します。

> バージョン 3 ファイル形式から変更されました。
>
> トップレベルの [volumes](#volumes) キーは名前付きボリュームを定義し、各サービスの [volumes](#volumes) リストから名前付きボリュームを参照します。
> これにより、以前のバージョンの Compose ファイル形式の ``volumes_from`` が置き換えられます。

この例は ``web`` サービスによって使用されている名前付きボリューム( `` mydata`` )と、単一のサービス( ``db`` サービス配下の [volumes](#volumes) の最初のパス)に対して定義されたバインドマウントを示しています。
``db`` サービスも ``dbdata`` ( ``db`` サービス配下の [volumes](#volumes) の 2 番目のパス)と呼ばれる名前付きボリュームを使用しますが、名前付きボリュームをマウントするための古い文字列形式を使用して定義します。
以下に示すように、名前付きボリュームは最上位の [volumes](#volumes) キーの下に列記されている必要があります。

```yaml
version: "3.8"
services:
  web:
    image: nginx:alpine
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

  db:
    image: postgres:latest
    volumes:
      - "/var/run/postgres/postgres.sock:/var/run/postgres/postgres.sock"
      - "dbdata:/var/lib/postgresql/data"

volumes:
  mydata:
  dbdata:
```

> 注意
>
> ボリュームの一般的な情報については [ボリュームの使用](https://docs.docker.com/storage/volumes/) と [ボリュームプラグイン](https://docs.docker.com/engine/extend/plugins_volume/) のセクションを参照してください。

### 短い構文

短い構文では、一般的な ``[SOURCE:]TARGET[:MODE]`` 形式を使用します。
ここで ``SOURCE`` はホストパスまたはボリューム名のいずれかです。
``TARGET`` はボリュームがマウントされているコンテナパスです。
標準モードは、 ``ro`` ( ``read-only`` )と ``rw`` ( ``read-write`` )です(既定値)。

ホストに相対パスをマウントできます。
これは使用されている Compose 構成ファイルのディレクトリを基準にして展開されます。
相対パスは常に ``.``または ``...`` で始まる必要があります

```yaml
volumes:
  # パスのみを指定し、エンジンにボリュームの作成を許可します
  - /var/lib/mysql

  # 絶対パスによるマッピングを指定します
  - /opt/data:/var/lib/mysql

  # ホスト上のパス(Compose ファイルを基準とする相対パス)を指定します
  - ./cache:/tmp/cache

  # ユーザーを基準とする相対パスを指定します
  - ~/configs:/etc/configs/:ro

  # 名前付きボリュームを指定します
  - datavolume:/var/lib/mysql
```

### 長い構文

> バージョン 3.2 ファイル形式から導入されました。

長い形式の構文では、短い形式では表現できない追加のフィールドを構成できます。

* ``type`` : マウントタイプ
  * ``volume``
  * ``bind``
  * ``tmpfs``
  * ``npipe``
* ``source`` : マウントのソース、バインドマウントのホスト上のパス、または最上位の [volumes](#volumes) キーで定義されたボリュームの名前。
  ``tmpfs`` マウントには適用されません。
* ``target`` : ボリュームがマウントされているコンテナ内のパス
* ``read_only`` : ``read-only`` のボリュームとして設定するフラグ
* ``bind`` : 追加のバインドオプションを構成する
  * ``propagation`` : バインドに使用される伝播モード
* ``volume`` : 追加のボリュームオプションを構成する
  * ``nocopy`` : ボリュームの作成時にコンテナからのデータのコピーを無効にするフラグ
* ``tmpfs`` : 追加の ``tmpfs`` オプションを構成します
  * ``size`` : ``tmpfs`` マウントのサイズ(バイト単位)

```yaml
version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - type: volume
        source: mydata
        target: /data
        volume:
          nocopy: true
      - type: bind
        source: ./static
        target: /opt/app/static

networks:
  webnet:

volumes:
  mydata:
```

> 注意
>
> バインドマウントを作成する場合、長い構文を使用するには、参照フォルダーを事前に作成する必要があります。
> 短い構文を使用すると、フォルダが存在しない場合はその場で作成されます。
> 詳細については [バインドマウントのドキュメント](https://docs.docker.com/storage/bind-mounts/#differences-between--v-and---mount-behavior) を参照してください。

### サービス、スウォーム、およびスタックファイルのボリューム

> ``docker stack deploy`` 使用時の注意事項
>
> サービス、スウォーム、および ``docker-stack.yml`` ファイルを操作する場合、サービスをサポートするタスク(コンテナー)はスウォーム内の任意のノードにデプロイでき、これはサービスが更新される度に毎回異なるノードになる可能性があることに注意してください。

指定されたソースを持つ名前付きボリュームがない場合、 Docker はサービスの背後にあるタスクごとに匿名ボリュームを作成します。
匿名ボリュームは、関連するコンテナーが削除された後も保持されません。

データを永続化する場合は、名前付きボリュームとマルチホスト対応のボリュームドライバーを使用して、どのノードからでもデータにアクセスできるようにします。
または、サービスに制約を設定して、ボリュームが存在するノードにタスクがデプロイされるようにします。

例として [Docker Labs の votingapp サンプル](https://github.com/docker/labs/blob/master/beginner/chapters/votingapp.md) の ``docker-stack.yml`` ファイルは ``postgres`` データベースを実行する ``db`` というサービスを定義しています。
これは、スウォーム上のデータを永続化するための名前付きボリュームとして構成され、 ``manager`` ノードでのみ実行するように制約されています。
当該ファイルから関連する記述を例示します:

```yaml
version: "3.8"
services:
  db:
    image: postgres:9.4
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend
    deploy:
      placement:
        constraints: [node.role == manager]
```

### domainname, hostname, ipc, mac_address, privileged, read_only, shm_size, stdin_open, tty, user, working_dir

これらはそれぞれ単一の値であり、対応する [docker run](https://docs.docker.com/engine/reference/run/) に類似しています。
``mac_address`` は古いオプションであることに注意してください。

```yaml
user: postgresql
working_dir: /code

domainname: foo.com
hostname: foo
ipc: host
mac_address: 02:42:ac:11:65:43

privileged: true


read_only: true
shm_size: 64M
stdin_open: true
tty: true
```

# 期限の指定

``check`` のサブオプションである ``interval`` や ``timeout`` など、一部の構成オプションは、次のような形式の文字列で期限を受け入れます。

```yaml
2.5s
10s
1m30s
2h32m
5h34m56s
```

以下の単位をサポートしています。

* ``us``
* ``ms``
* ``s``
* ``m``
* ``h``

# バイト値の指定

[build](#build) のサブオプションである [shm_size](#shm_size) など、一部の構成オプションは、次のような形式の文字列でバイト値を受け入れます。

```yaml
2b
1024kb
2048k
300m
1gb
```

以下の単位をサポートしています。

* ``b``
* ``k``
* ``m``
* ``g``

以下の代替記法もサポートしています。

* ``kb``
* ``mb``
* ``gb``

現時点では 10 進値はサポートされていません。

# ボリューム構成リファレンス

サービス宣言の一部としてその場で [volumes](#volumes) を宣言することは可能です。
[volumes](#volumes) セクションでは、複数のサービスで再利用でき( ``volumes_from`` に依存せずに)、  docker コマンドラインまたは API を使用して簡単に取得および検査できる名前付きボリュームを作成できます。
詳細については [docker volume](https://docs.docker.com/engine/reference/commandline/volume_create/) サブコマンドのドキュメントを参照してください。

[volumes](#volumes) の一般的な情報については、 [volumes の使用](https://docs.docker.com/storage/volumes/) と [volume プラグイン](https://docs.docker.com/engine/extend/plugins_volume/) を参照してください。

これは、データベースのデータディレクトリがボリュームとして別のサービスと共有され、定期的にバックアップできる 2 つのサービスのセットアップの例です。

```yaml
version: "3.8"

services:
  db:
    image: db
    volumes:
      - data-volume:/var/lib/db
  backup:
    image: backup-service
    volumes:
      - data-volume:/var/lib/backup/data

volumes:
  data-volume:
```

トップレベルの [volumes](#volumes) キーの下のエントリは空にすることができます。
その場合、エンジンによって構成されたデフォルトのドライバー(ほとんどの場合 ``local`` ドライバー)が使用されます。
オプションで以下のキーを使用して構成できます。

## driver

当該ボリュームに使用するボリュームドライバーを指定します。
デフォルトでは Docker Engine が使用するように構成されているドライバー(ほとんどの場合 ``local`` )が使用されます。
ドライバが利用できない場合、 ``docker-compose up`` がボリュームを作成しようとするとエンジンはエラーを返します。

```yaml
driver: foobar
```

## driver_opts

このボリュームのドライバーに渡すキーと値のペアとしてオプションのリストを指定します。
これらのオプションはドライバーによって異なります。
詳細については各ドライバーのドキュメントを参照してください。

```yaml
volumes:
  example:
    driver_opts:
      type: "nfs"
      o: "addr=10.40.0.199,nolock,soft,rw"
      device: ":/docker/example"
```

## external

``true`` に設定すると、当該ボリュームが Compose の外部で作成されます。
ボリュームが存在しない場合、 ``docker-compose up`` はボリュームを作成しようとはせず、エラーを発生させます。

バージョン 3.3 以下の形式では、 [external](#external) を以下のボリューム構成キーと組み合わせて使用​​することはできません。

* [driver](#driver)
* [driver_opts](#driver_opts)
* [labels](#labels)

この制限は、バージョン 3.4 以降では撤廃されました。

以下の例では、 ``[projectname]_data`` という名前のボリュームを作成しようとする代わりに、 Compose は単に ``data`` という名前の既存のボリュームを探し、それを ``db`` サービスのコンテナにマウントします。

```yaml
version: "3.8"

services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data

volumes:
  data:
    external: true
```

> バージョン 3.4 ファイル形式から非推奨となりました。
>
> ``external.name`` はバージョン 3.4 ファイル形式から非推奨となりました。
> 代わりに [name](#name) を使用してください。

Compose ファイル内でボリュームを参照するために使用される名前とは別に、ボリュームの名前を指定することもできます。

```yaml
volumes:
  data:
    external:
      name: actual-name-of-volume
```

> ``docker stack deploy`` 使用時の注意事項
>
> ( [dockercompose up](https://docs.docker.com/compose/reference/up/) の代わりに) ``docker stack deploy`` を使用してアプリを [スウォームモード](https://docs.docker.com/engine/swarm/) で起動すると、存在しない [external](#external) ボリュームが作成されます。
スウォームモードでは、サービスによって定義されるときにボリュームが自動的に作成されます。
サービスタスクが新しいノードでスケジュールされると [swarmkit](https://github.com/docker/swarmkit/blob/master/README.md) はローカルノードにボリュームを作成します。
詳細については [moby/moby#29976](https://github.com/moby/moby/issues/29976) を参照してください。

## labels

[Docker ラベル](https://docs.docker.com/config/labels-custom-metadata/) を使用してメタデータをコンテナーに追加します。
配列または辞書形式のいずれかを使用できます。

ラベルが他のソフトウェアで使用されているラベルと競合しないように、逆 DNS 表記を使用することをお勧めします。

```yaml:辞書形式
labels:
  com.example.description: "Database volume"
  com.example.department: "IT/Ops"
  com.example.label-with-empty-value: ""
```

```yaml:配列形式
labels:
  - "com.example.description=Database volume"
  - "com.example.department=IT/Ops"
  - "com.example.label-with-empty-value"
```

## name

> バージョン 3.4 ファイル形式から導入されました。

当該ボリュームのカスタム名を設定します。
[name](#name) フィールドは、特殊文字を含むボリュームを参照するために使用できます。
[name](#name) はそのまま使用され、スタック名で範囲制限されません。

```yaml
version: "3.8"
volumes:
  data:
    name: my-app-data
```

[external](#external) プロパティと組み合わせて使用​​することもできます。

```yaml
version: "3.8"
volumes:
  data:
    external: true
    name: my-app-data
```

# ネットワーク構成リファレンス

トップレベルの [networks](#networks) キーを使用すると、作成するネットワークを指定できます。

* Compose による Docker ネットワーク機能の使用とすべてのネットワークドライバーオプションの詳細については [ネットワークガイド](https://docs.docker.com/compose/networking/) を参照してください。
* ネットワークに関する [Docker Labs](https://github.com/docker/labs/blob/master/README.md) のチュートリアルは、 [拡張可能で移殖可能な Docker コンテナネットワークの設計](https://github.com/docker/labs/blob/master/networking/README.md) から始めてください。

## driver

当該ネットワークに使用するドライバーを指定します。

デフォルトのドライバーは、使用している Docker エンジンの構成方法によって異なりますが、ほとんどの場合、単一のホスト上の ``bridge`` であり、スウォーム上の ``overlay`` です。

ドライバが利用できない場合、 Docker Engine はエラーを返します。

```yaml
driver: overlay
```

### bridge

Docker はデフォルトで単一ホストの ``bridge`` ネットワークを使用します。
ブリッジネットワークを操作する方法の例については、 [ブリッジネットワーク](https://github.com/docker/labs/blob/master/networking/A2-bridge-networking.md) に関する Docker Labs チュートリアルを参照してください。

### overlay

``overlay`` ドライバーは、 [スウォーム](https://docs.docker.com/engine/swarm/) の複数のノードにまたがる名前付きネットワークを作成します。

* スウォームモードのサービスで ``overlay`` ネットワークを構築して使用する方法の実用的な例については、 [オーバーレイネットワークとサービス検出](https://github.com/docker/labs/blob/master/networking/A3-overlay-networking.md) に関する Docker Labs チュートリアルを参照してください。
  
* 内部でどのように機能するかについての詳細については、 [オーバーレイドライバーネットワークアーキテクチャ](https://github.com/docker/labs/blob/master/networking/concepts/06-overlay-networks.md) のネットワークコンセプトを参照してください。

### host or none

* ``host`` : ホストのネットワークスタックを使用します。
* ``none`` : ネットワークを使用しません。

``docker run --net=host`` または ``docker run --net=none`` と同等です。
``docker stack`` コマンドを使用する場合に限り使用されます。
``docker-compose`` コマンドを使用する場合は、代わりに [network_mode](#network_mode) を使用してください。

共通のビルドで特定のネットワークを使用する場合は、 2 番目の yaml ファイルの例で説明されているように ``[network]`` を使用します。

``host`` や ``none`` などの組み込みネットワークを使用するための構文は少し異なります。
``host`` または ``none`` (Docker が自動作成したネットワーク名)と Compose が使用できるエイリアス(次の例では ``hostnet`` または ``nonet`` )を使用して外部ネットワークを定義し、エイリアスを使用してそのネットワークへのサービスアクセスを許可します。

```yaml
version: "3.8"
services:
  web:
    networks:
      hostnet: {}

networks:
  hostnet:
    external: true
    name: host
```

```yaml
services:
  web:
    ...
    build:
      ...
      network: host
      context: .
      ...
```

```yaml
services:
  web:
    ...
    networks:
      nonet: {}

networks:
  nonet:
    external: true
    name: none
```

## driver_opts

このネットワークのドライバーに渡すキーと値のペアとしてオプションのリストを指定します。
これらのオプションはドライバーによって異なります。
詳細については各ドライバーのドキュメントを参照してください。
[driver_opts](#driver_opts) は任意のオプションです。

```yaml
driver_opts:
  foo: "bar"
  baz: 1
```

## attachable

> バージョン 3.2 ファイル形式から導入されました。

[driver](#driver) が ``overlay`` に設定されている場合に限り使用されます。
``true`` に設定するとスタンドアロンコンテナはサービスに加えて、当該ネットワークに接続できます。
スタンドアロンコンテナがオーバーレイネットワークに接続されている場合、他の Docker デーモンから、オーバーレイネットワークに接続されているサービスならびにスタンドアロンコンテナと通信できます。

```yaml
networks:
  mynet1:
    driver: overlay
    attachable: true
```

## enable_ipv6

IPv6 ネットワークを有効にします。

> Compose ファイルバージョン 3 ではサポートされていません。
>
> ``enable_ipv6`` では、バージョン 2 の Compose ファイルを使用する必要があります。
> このディレクティブは Swarm モードではまだサポートされてません。

## ipam

カスタム IPAM 構成を指定します。
これはいくつかのプロパティを持つオブジェクトであり、各プロパティは任意のオプションです。

* ``driver`` : デフォルトの代わりに使用する IPAM ドライバー。
* ``config`` : ``config`` ブロックが 0 個以上あり、それぞれに次のキーのいずれかが含まれているリスト。
  * ``subnet`` : ネットワークセグメントを表す CIDR 形式のサブネット

```yaml:記述例
ipam:
  driver: default
  config:
    - subnet: 172.28.0.0/16
```

> 注意
>
> ``gateway`` などの追加の IPAM 構成は、現時点ではバージョン 2 である場合に限り適用されます。

## internal

デフォルトでは Docker はブリッジネットワークへ接続して外部接続を提供します。
外部で分離されたオーバーレイネットワークを作成する場合は、このオプションを ``true`` に設定してください。

## labels

[Docker ラベル](https://docs.docker.com/config/labels-custom-metadata/) を使用してメタデータをコンテナーに追加します。
配列または辞書形式のいずれかを使用できます。

ラベルが他のソフトウェアで使用されているラベルと競合しないように、逆 DNS 表記を使用することをお勧めします。

```yaml:辞書形式
labels:
  com.example.description: "Financial transaction network"
  com.example.department: "Finance"
  com.example.label-with-empty-value: ""
```

```yaml:配列形式
labels:
  - "com.example.description=Financial transaction network"
  - "com.example.department=Finance"
  - "com.example.label-with-empty-value"
```

## external

``true`` に設定すると、ネットワークが Compose の外部で作成されます。
ネットワークが存在しない場合、 ``docker-compose up`` はネットワークを自動作成しようとはせず、エラーを発生させます。

バージョン 3.3 以下のフォーマットでは [external](#external) を以下のネットワーク構成キーと組み合わせて使用​​することはできません。

* [driver](#driver)
* [driver_opts](#driver_opts)
* [ipam](#ipam)
* [internal](#internal)

この制限はバージョン 3.4 以降では撤廃されました。

以下の例では ``proxy`` は外界へのゲートウェイです。
Compose は ``[projectname]_outside`` というネットワークを作成する代わりに、単に ``outside`` と呼ばれる既存のネットワークを探し、 ``proxy`` サービスのコンテナをそれに接続します。

```yaml
version: "3.8"

services:
  proxy:
    build: ./proxy
    networks:
      - outside
      - default
  app:
    build: ./app
    networks:
      - default

networks:
  outside:
    external: true
```

> バージョン 3.5 ファイル形式では非推奨です。
>
> ``external.name`` はバージョン 3.5 から非推奨となりました。
> 代わりに [name](#name) を使用してください。

Compose ファイル内でネットワークを参照するために使用される名前とは別に、ネットワークの名前を指定することもできます。

```yaml
version: "3.8"
networks:
  outside:
    external:
      name: actual-name-of-network
```

## name

> バージョン 3.5 から導入されました。

このネットワークのカスタム名称を設定します。
[name](#name) フィールドは、特殊文字を含むネットワークを参照するために使用できます。
[name](#name) はそのまま使用され、スタック名で範囲制限されません。

```yaml
version: "3.8"
networks:
  network1:
    name: my-app-net
```

[external](#external) プロパティと組み合わせて使用​​することもできます。

```yaml
version: "3.8"
networks:
  network1:
    external: true
    name: my-app-net
```

# configs 構成リファレンス

トップレベルの [configs](#configs) 宣言は、このスタック内のサービスに付与できる [configs](https://docs.docker.com/engine/swarm/configs/) を定義または参照します。
構成の参照元は ``file`` または ``external`` のいずれかです。

* ``file`` : ``config`` は指定されたパスにあるファイルの内容を使用して作成されます。
* ``external`` : ``true`` に設定されている場合、当該 ``config`` がすでに作成されていることを表します。
  当該 ``config`` が既に作成されている場合、 Docker はそれを作成しようとはしません。
  ``config`` が存在しない場合は ``config not found`` というエラーが発生します。
* ``name`` : Docker の ``config`` オブジェクトの名前。
  このフィールドは、特殊文字を含む [configs](#configs) を参照するために使用できます。
  ``name`` はそのまま使用され、スタック名で範囲制限されません。
  バージョン 3.5 のファイル形式から導入されました。
* ``driver`` と ``driver_opts`` : カスタムシークレットドライバーの名前、およびキーと値のペアとして渡されるドライバー固有のオプション。
  バージョン 3.8 のファイル形式から導入されました。
  ``docker stack`` を使用する場合に限りサポートされます。
* ``template_driver`` : 使用するテンプレートドライバーの名前。
  これは、シークレットペイロードをテンプレートとして評価するかどうかと、評価する方法を制御します。
  ドライバが設定されていない場合、テンプレートは使用されません。
  現在サポートされている唯一のドライバーは、 go 言語を使用する ``golang`` です。
  バージョン 3.8 のファイル形式から導入され、 ``docker stack`` を使用する場合に限りサポートされます。
  テンプレート化された [configs](#configs) の例については、 [テンプレート化された config の使用](https://docs.docker.com/engine/swarm/configs/#example-use-a-templated-config) を参照してください。

以下の例では、スタックがデプロイされたときに ``my_first_config`` が( `` <stack_name>_my_first_config`` として)作成され、 `` my_second_config`` は Docker にすでに存在します。

```yaml
configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external: true
```

外部構成のもう 1 つのバリエーションは、 Docker の [configs](#configs) の名前がサービス内に存在する名前と異なる場合です。
次の例は、 ``redis_config`` と呼ばれる外部構成を使用するように前の例を変更します。

```yaml
configs:
  my_first_config:
    file: ./config_data
  my_second_config:
    external:
      name: redis_config
```

スタック内の各サービスに ``config`` へのアクセスを許可する必要があります。

# シークレット構成リファレンス

トップレベルの [secrets](#secrets) 宣言は、このスタック内のサービスに付与できる [secrets](https://docs.docker.com/engine/swarm/secrets/) を定義または参照します。
シークレットの参照元は ``file`` または ``external`` のいずれかです。

* ``file`` : シークレットは、指定されたパスにあるファイルの内容で作成されます。
* ``external`` : ``true`` に設定されている場合、当該シークレットがすでに作成されていることを表します。
  すでに作成されている場合、 Docker はそれを作成しようとはしません。
  シークレットが存在しない場合は、 ``secret not found`` というエラーが発生します。
* ``name`` : Docker の ``secret`` オブジェクトの名前。
  このフィールドは、特殊文字を含む [secrets](#secrets) を参照するために使用できます。
  ``name`` はそのまま使用され、スタック名で範囲制限されません。
  バージョン 3.5 のファイル形式から導入されました。
* ``template_driver`` : 使用するテンプレートドライバーの名前。
  これは、シークレットペイロードをテンプレートとして評価するかどうかと、評価する方法を制御します。
  ドライバが設定されていない場合、テンプレートは使用されません。
  現在サポートされている唯一のドライバーは、 go 言語を使用する``golang`` です。
  バージョン 3.8 のファイル形式から導入され、 ``docker stack`` を使用する場合に限りサポートされます。

以下の例では、スタックがデプロイされると、 ``my_first_secret`` は``<stack_name>_my_first_secret`` として作成され、 ``my_second_secret`` は Docker にすでに存在します。

```yaml
secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true
```

外部の [secrets](#secrets) のもう 1 つのバリエーションは、 Docker の ``secret`` の名前がサービス内に存在する名前と異なる場合です。
次の例は、 ``redis_secret`` と呼ばれる外部の ``secret`` を使用するように前の例を変更しています。

```yaml:Composeファイルv3.5以上
secrets:
  my_first_secret:
    file: ./secret_data
  my_second_secret:
    external: true
    name: redis_secret
```

```yaml:Composeファイルv3.4以下
my_second_secret:
  external:
    name: redis_secret
```

スタック内の各サービスに [secrets](#secrets) へのアクセスを許可する必要があります。

# 変数の置換

構成オプションには、環境変数を含めることができます。
Compose は ``docker-compose`` が実行されるシェル環境の変数値を使用します。
たとえば、シェルに ``POSTGRES_VERSION=9.3`` が含まれていて、次の構成を指定するとします。

```yaml
db:
  image: "postgres:${POSTGRES_VERSION}"
```

この構成で ``docker-compose up`` を実行すると、 Compose はシェルで ``POSTGRES_VERSION`` 環境変数を探し、その値で置き換えます。
この例では Compose は構成を実行する前に、 [image](#iamge) を ``postgres:9.3`` に解決します。

環境変数が設定されていない場合、 Compose は空の文字列に置き換えます。
上記の例では、 ``POSTGRES_VERSION`` が設定されていない場合、 [image](#iamge) オプションの値は ``postgres:`` です。

Compose が自動的に検索する ``.env`` ファイルを使用して、環境変数のデフォルト値を設定できます。
シェル環境で設定された値は、 ``.env`` ファイルで設定された値を上書きします。

> ``docker stack deploy`` 使用時の注意事項
>
> ``.env`` ファイル機能は、 ``docker-compose up`` コマンドを使用した場合に限り機能します。
> ``docker stack deploy`` では機能しません。

``$VARIABLE`` と ``${VARIABLE}`` の両方の構文がサポートされています。
さらに 2.1 ファイル形式を使用する場合、一般的なシェル構文を使用してインラインのデフォルト値を提供することができます。

* ``${VARIABLE:-default}`` は、環境内で ``VARIABLE`` が設定されていないか空の場合 ``default`` と評価されます。
* ``${VARIABLE-default}`` は、環境で ``VARIABLE`` が設定されていない場合に限り ``default`` と評価されます。

同様に次の構文では、必須変数を指定できます。

* ``${VARIABLE:?err}`` は、環境内で ``VARIABLE`` が設定されていないか空の場合 ``err`` を含むエラーメッセージで終了します。
* ``${VARIABLE?err}`` は環境で ``VARIABLE`` が設定されていない場合、 ``err`` を含むエラーメッセージで終了します。

``${VARIABLE/foo/bar}`` などの他の拡張シェルスタイルの機能はサポートされていません。

構成で文字通りのドル記号が必要な場合は、 ``$$`` (二重ドル記号)を使用できます。
これにより Compose が値を補間することも防止されるため、 ``$$`` を使用すると Compose で処理したくない環境変数を参照できます。

```yaml
web:
  build: .
  command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE"
```

忘れて単一のドル記号( ``$`` )を使用すると Compose は値を環境変数として解釈し、次のように警告します。

```bash
The VAR_NOT_INTERPOLATED_BY_COMPOSE is not set. Substituting an empty string.
```

# 拡張フィールド

> バージョン 3.4 ファイル形式から導入されました。

拡張フィールドを使用して、構成フラグメントを再利用することができます。
これらの特別なフィールドは Compose ファイルのルートにあり、名前が ``x-`` 文字シーケンスで始まる限り、任意の形式にすることができます。

> 注意
>
> 3.7 形式(3.x シリーズの場合)および 2.4 形式(2.x シリーズの場合)以降、拡張フィールドは ``service`` , ``volume`` , ``network`` , ``config`` , ``secret`` 定義のルートでも使用できます。

```yaml
version: '3.4'
x-custom:
  items:
    - a
    - b
  options:
    max-size: '12m'
  name: "custom"
```

これらのフィールドの内容は Compose によって無視されますが、 [YAML アンカー](https://yaml.org/spec/1.2/spec.html#id2765878) を使用してリソース定義に挿入できます。
たとえば複数のサービスで同じログ構成を使用する場合は、次のようにします。

```yaml
logging:
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file
```

Compose ファイルは次のように記述できます。

```yaml
version: '3.4'
x-logging:
  &default-logging
  options:
    max-size: '12m'
    max-file: '5'
  driver: json-file

services:
  web:
    image: myapp/web:latest
    logging: *default-logging
  db:
    image: mysql:latest
    logging: *default-logging
```

[YAML マージタイプ](https://yaml.org/type/merge.html) を使用して、拡張フィールドの値を部分的に上書きすることもできます。

```yaml:記述例
version: '3.4'
x-volumes:
  &default-volume
  driver: foobar-storage

services:
  web:
    image: myapp/web:latest
    volumes: ["vol1", "vol2", "vol3"]
volumes:
  vol1: *default-volume
  vol2:
    << : *default-volume
    name: volume02
  vol3:
    << : *default-volume
    driver: default
    name: volume-local
```

# Compose ドキュメント

* [ユーザーガイド](https://docs.docker.com/compose/)
* [Compose のインストール](https://docs.docker.com/compose/install/)
* [Compose ファイルバージョンとアップグレード](https://docs.docker.com/compose/compose-file/compose-versioning/)
* [Compose を使用したサンプルアプリケーション](https://docs.docker.com/compose/samples-for-compose/)
* [コマンドラインリファレンス](https://docs.docker.com/compose/reference/)