docker-compse規范 · docker-compose規范文檔

# Compose 規范 [TOC] ## 文檔狀態本文檔指定用于定義多容器應用程序的Compose文件格式。本文檔的分發是無限的。本文檔中的關鍵字“必須”，“不得”，“必須”，“應”，“應禁止”，“應”，“不應”，“推薦”，“可以”和“可選”是按照[RFC 2119中的](https://tools.ietf.org/html/rfc2119)描述進行解釋。 ### 要求和可選屬性 Compose規范包括旨在面向本地[OCI](https://opencontainers.org/)容器運行時的屬性，公開了Linux內核特定的配置選項，還包括一些Windows容器特定的屬性，以及與群集上的資源放置，復制的應用程序分發和可伸縮性有關的云平臺功能。我們承認，預計不會有Compose實現支持**所有**屬性，并且對某些屬性的支持取決于平臺，并且只能在運行時進行確認。用于控制Compose文件中受支持屬性的版本化架構的定義（由設計了Compose文件格式的[docker-compose](https://github.com/docker/compose)工具建立）并未為最終用戶屬性提供任何保證。該規范定義了預期的配置語法和行為，但是-除非另有說明-支持其中任何一個都是可選的。使用不支持的屬性來解析Compose文件的Compose實現應警告用戶。我們建議實現者支持這些運行模式： * 默認值：警告用戶有關不支持的屬性，但忽略它們 * 嚴格：警告用戶有關不支持的屬性，并拒絕撰寫文件 * 寬松：忽略不受支持的屬性和未知屬性（在創建實現時規范尚未定義） ## Compose應用模型 Compose規范允許您定義一個與平臺無關的基于容器的應用程序。這樣的應用程序被設計為一組容器，它們必須與足夠的共享資源和通信通道一起運行。應用程序的計算組件被定義為`services`。服務是在平臺上實現的抽象概念，通過一次或多次運行相同的容器映像（和配置）來實現。服務通過`networks`相互通信。在本規范中，網絡是一種平臺功能抽象，用于在連接在一起的服務內的容器之間建立IP路由。低層的，特定于平臺的網絡選項被歸入“網絡”定義中，并且可以在某些平臺上部分實現。服務將持久性數據存儲并共享到`volumes`。該規范將這種持久性數據描述為具有全局選項的高級文件系統掛載。特定于平臺的實際實現細節被分組到Volumes定義中，并且可以在某些平臺上部分實現。某些服務需要依賴于運行時或平臺的配置數據。為此，規范定義了一個專用概念：`configs`。從服務容器的角度來看，配置與卷具有可比性，因為它們是安裝在容器中的文件。但是實際定義涉及不同的平臺資源和服務，這些資源和服務由該類型抽象。一個`secret`是配置數據的敏感數據不應該在沒有安全方面的考慮會暴露一個特定的味道。密匙作為文件裝入容器時可供服務使用，但是提供敏感數據的特定于平臺的資源足夠具體，值得在Compose規范中使用不同的概念和定義。卷，配置和機密之間的區別允許實現在服務級別上提供可比的抽象，但涵蓋適當平臺資源的特定配置，以供充分確定的數據使用。一個**項目**是一個平臺上的應用程序規范的個體部署。項目的名稱用于將資源分組在一起，并將它們與其他應用程序或具有不同參數的同一Compose指定應用程序的其他安裝隔離。在平臺上創建資源的Compose實現必須按項目在資源名稱前添加前綴并設置標簽`com.docker.compose.project`。 ### 說明性的例子以下示例通過一個具體的示例應用程序說明了Compose規范概念。該示例是非規范的。考慮將應用程序分為前端Web應用程序和后端服務。在運行時使用由基礎結構管理的HTTP配置文件（提供外部域名）和由平臺的安全機密存儲注入的HTTPS服務器證書對運行時進行配置。后端將數據存儲在持久卷中。兩種服務都在隔離的后端網絡上相互通信，而前端也連接到前端網絡，并公開端口443供外部使用。 ``` (External user) --> 443 [frontend network] | +--------------------+ | frontend service |...ro...<HTTP configuration> | "webapp" |...ro...<server certificate> #secured +--------------------+ | [backend network] | +--------------------+ | backend service | r+w ___________________ | "database" |=======( persistent volume ) +--------------------+ \_________________/ ``` 該示例應用程序由以下部分組成： * 2個服務，由Docker映像支持：`webapp`和`database` * 1個秘密（HTTPS證書），已注入前端 * 1個配置（HTTP），注入到前端 * 1個永久卷，附加到后端 * 2個網絡 ```yml services: frontend: image: awesome/webapp ports: - "443:8043" networks: - front-tier - back-tier configs: - httpd-config secrets: - server-certificate backend: image: awesome/database volumes: - db-data:/etc/data networks: - back-tier volumes: db-data: driver: flocker driver_opts: size: "10GiB" configs: httpd-config: external: true secrets: server-certificate: external: true networks: # The presence of these objects is sufficient to define them front-tier: {} back-tier: {} ``` 此示例說明了卷，配置和機密之間的區別。盡管所有這些文件都作為已掛載的文件或目錄公開給服務容器，但只能將一個卷配置為可讀寫訪問。機密和配置是只讀的。通過卷配置，您可以選擇一個卷驅動程序并通過驅動程序選項來根據實際基礎結構調整卷管理。Config和Secrets依賴于平臺服務，并在`external`未作為應用程序生命周期的一部分進行管理的情況下進行聲明：Compose實現將使用特定于平臺的查找機制來檢索運行時值。 ## Compose文件 Compose文件是一個[YAML](http://yaml.org/)文件，用于定義`version`（已棄用），`services`（必需），`networks`,`volumes`,`configs`和`secrets`。Compose文件的默認路徑是`compose.yaml`（首選）或`compose.yml`在工作目錄中。撰寫實現也應支持`docker-compose.yaml`并向`docker-compose.yml`后兼容。如果兩個文件都存在，則Compose實現必須首選規范文件`compose.yaml`。可以將多個Compose文件組合在一起以定義應用程序模型。YAML文件的組合必須通過根據用戶設置的Compose文件順序附加/覆蓋YAML元素來實現。簡單的屬性和映射被最高順序的Compose文件覆蓋，列表通過追加合并。每當合并的互補文件托管在其他文件夾中時，相對路徑都必須根據第**一個**Compose文件的父文件夾進行解析。由于某些Compose文件元素都可以表示為單個字符串或復雜對象，因此合并必須應用于擴展形式。 ### Profiles 配置文件允許針對各種用途和環境調整Compose應用程序模型。Compose實現應允許用戶定義一組活動配置文件。確切的機制是特定于實現的，并且可以包括命令行標志，環境變量等。 “Services”頂級元素支持`profiles`用于定義命名配置文件列表的屬性。`profiles`必須始終啟用未設置屬性的服務。如果列出`profiles`的服務與活動服務都不匹配，則該服務必須被Compose實現忽略，除非該服務由命令明確指定。在這種情況下，`profiles`必須將其添加到活動配置文件集中。所有其他頂級元素均不受其影響，`profiles`并且始終處于活動狀態。引用其他服務（通過`links`，`extends`或共享資源的語法`service:xxx`）不能自動啟用，否則將被有效簡忽視的組成部分。相反，Compose實現必須返回一個錯誤 #### 說明性的例子 ```yaml services: foo: image: foo bar: image: bar profiles: - test baz: image: baz depends_on: - bar profiles: - test zot: image: zot depends_on: - bar profiles: - debug ``` * 在沒有啟用配置文件的情況下分析的撰寫應用程序模型僅包含`foo`服務。 * 如果`test`啟用了概要文件，則模型包含服務`bar`，`baz`這些服務由`test`概要文件和`foo`始終啟用的服務啟用。 * 如果配置文件`debug`被啟用，模型同時包含`foo`和`zot`服務，但不`bar`和`baz`，因此該模型無效有關`depends_on`的約束`zot`。 * 如果配置文件`debug`和`test`啟用，模型包含了所有服務：`foo`，`bar`，`baz`和`zot`。 * 如果Compose實現是`bar`作為要運行的顯式服務執行的，則`test`即使*用戶*`test`未啟用配置文件，配置文件也將處于活動狀態。 * 如果Compose實現是`baz`作為要運行的顯式服務執行的，則該服務`baz`和配置文件`test`將處于活動狀態，`bar`并將被`depends_on`約束拉入。 * 如果`zot`使用要運行的顯式服務執行Compose實現，則該模型對于since的`depends_on`約束將再次無效，并且沒有列出任何共同點。`zot``zot``bar``profiles` * 如果`zot`使用要運行的顯式服務執行Compose實施并`test`啟用了配置文件，則將`debug`自動啟用配置文件，并且將服務`bar`作為啟動服務`zot`和的依賴項引入`bar`。 ## Version `version`規范定義了頂級屬性以實現向后兼容，但僅提供信息。 Compose實現不應使用此版本來選擇用于驗證Compose文件的確切模式，而應在設計時選擇最新的模式。 Compose實現應驗證它們可以完全解析Compose文件。如果某些字段未知，通常是因為Compose文件是用規范的較新版本定義的字段編寫的，則Compose實現應警告用戶。撰寫實現可以提供忽略未知字段的選項（由“松散”模式定義） ## Services 服務是應用程序中計算資源的抽象定義，可以獨立于其他組件進行縮放/替換。服務由一組容器支持，這些容器由平臺根據復制要求和放置限制運行。由容器支持的服務由Docker映像和運行時參數集定義。使用這些參數完全創建服務中的所有容器。組成文件必須將`services`根元素聲明為映射，其鍵是服務名稱的字符串表示形式，其值是服務定義。服務定義包含應用于該服務啟動的每個容器的配置。每個服務還可以包括一個Build部分，該部分定義了如何為該服務創建Docker鏡像。組合實現可以支持使用該服務定義構建docker映像。如果未實現，則應忽略“build”部分，并且必須仍然認為“Compose”文件有效。構建支持是Compose規范的可選方面，在[此](build.md)進行詳細說明每個服務定義運行時約束和要求以運行其容器。本`deploy`節對這些限制進行了分組，并允許平臺調整部署策略，以最有效地滿足容器與可用資源的需求。部署支持是Compose規范的可選方面，在[此](deploy.md)進行詳細描述。如果未實現，則應忽略“部署”部分，并且仍必須認為“Compose”文件有效。 ### deploy `deploy`指定服務的部署和生命周期的配置，定義[在這里](deploy.md)。 ### blkio_config `blkio_config` 定義了一組配置選項來設置此服務的塊IO限制 ```yml services: foo: image: busybox blkio_config: weight: 300 weight_device: - path: /dev/sda weight: 400 device_read_bps: - path: /dev/sdb rate: '12mb' device_read_iops: - path: /dev/sdb rate: 120 device_write_bps: - path: /dev/sdb rate: '1024k' device_write_iops: - path: /dev/sdb rate: 30 ``` #### device_read_bps，device_write_bps 為給定設備上的讀/寫操作設置限制，以每秒字節數為單位。列表中的每個項目必須有兩個鍵： * `path`：定義到受影響設備的符號路徑。 * `rate`：可以是代表字節數的整數值，也可以是表示字節值的字符串。 #### device_read_iops，device_write_iops 為給定設備上的讀/寫操作設置每秒的操作限制。列表中的每個項目必須有兩個鍵： * `path`：定義到受影響設備的符號路徑。 * `rate`：作為一個整數值，表示每秒允許的操作數。 #### weight 修改分配給該服務的帶寬相對于其他服務的比例。取10到1000之間的整數值，默認值為500。 #### weight_device 根據設備微調帶寬分配。列表中的每個項目都必須具有兩個鍵： * `path`：定義到受影響設備的符號路徑。 * `weight`：介于10到1000之間的整數。 ### cpu_count `cpu_count` 定義服務容器可用的CPU數量。 ### cpu_percent `cpu_percent` 定義可用CPU的可用百分比。 ### cpu_shares `cpu_shares` 定義（作為整數值）服務容器相對于其他容器的相對CPU權重。 ### cpu_period `cpu_period`當平臺基于Linux內核時，允許Compose實現配置CPU CFS（完全公平調度程序）期限。 ### cpu_quota `cpu_quota` 當平臺基于Linux內核時，允許Compose實現配置CPU CFS（完全公平調度程序）配額 ### cpu_rt_runtime `cpu_rt_runtime`在支持實時調度程序的情況下為平臺配置CPU分配參數。可以是以微秒為單位的整數值，也可以是**specifying-durations***。 ```yml cpu_rt_runtime: '400ms' cpu_rt_runtime: 95000` ``` ### cpu_rt_period `cpu_rt_period` configures CPU allocation parameters for platform with support for realtime scheduler. Can be either an integer value using microseconds as unit or a [duration](#specifying-durations). `cpu_rt_period`在支持實時調度程序的情況下為平臺配置CPU分配參數。可以是以微秒為單位的整數值，也可以是**pecifying-durations***。 ```yml cpu_rt_period: '1400us' cpu_rt_period: 11000` ``` ### cpus *棄用：使用[deploy.reservations.cpus](deploy.md)* `cpus`定義要分配給服務容器的（潛在虛擬）CPU的數量。這是一個小數。`0.000`表示沒有限制。 ### cpuset `cpuset`定義允許執行的顯式CPU。可以是范圍`0-3`或列表`0,1` ### build `build`指定從源創建容器圖象，限定的構建配置[這里](build.md)。 ### cap_add `cap_add`將其他容器[功能](http://man7.org/linux/man-pages/man7/capabilities.7.html)指定為字符串。 ``` cap_add: - ALL ``` ### cap_drop `cap_drop`指定要作為字符串刪除的容器[功能](http://man7.org/linux/man-pages/man7/capabilities.7.html)。 ``` cap_drop: - NET_ADMIN - SYS_ADMIN ``` ### cgroup_parent `cgroup_parent`指定容器的可選父[cgroup](http://man7.org/linux/man-pages/man7/cgroups.7.html)。 ``` cgroup_parent: m-executor-abcd ``` ### command `command`覆蓋容器鏡像（即Dockerfile`CMD`）聲明的默認命令。 ``` command: bundle exec thin -p 3000 ``` 該命令也可以是列表，類似于[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd)： ``` command: [ "bundle", "exec", "thin", "-p", "3000" ] ``` ### configs `configs`使用每個服務的`configs`配置，基于每個服務授予對配置的訪問權限。支持兩種不同的語法變體。如果平臺上不存在配置或未在`configs`此Compose文件的部分中定義配置，則Compose實現必須報告錯誤。為配置定義了兩種語法。為了保持符合本規范，實現必須支持兩種語法。實現必須允許在同一文檔中使用短語法和長語法。 #### 短語法簡短的語法變體僅指定配置名稱。這將授予容器對配置的訪問權限，并將其安裝在`/<config_name>`容器內。源名稱和目標安裝點都設置為配置名稱。以下示例使用短語法來授予`redis`服務對`my_config`和`my_other_config`配置的訪問權限。的值`my_config`設置為file的內容`./my_config.txt`，并`my_other_config`定義為外部資源，這意味著它已在平臺中定義。如果外部配置不存在，則部署必須失敗。 ```yml services: redis: image: redis:latest configs: - my_config configs: my_config: file: ./my_config.txt my_other_config: external: true ``` #### 長語法長語法提供了在服務的任務容器中如何創建配置的更多粒度。 * `source`：平臺中存在的配置名稱。 * `target`：要在服務的任務容器中掛載的文件的路徑和名稱。`/<source>`如果未指定，則默認為。 * `uid`和`gid`：擁有服務的任務容器中已掛載的配置文件的數字UID或GID。未指定時的默認值為USER正在運行的容器。 * `mode`：服務的任務容器中裝入的文件的[權限](http://permissions-calculator.org/)，以八進制表示法。默認值是世界可讀的（`0444`）。可寫位必須被忽略。可執行位可以設置。下面的示例設置的名稱`my_config`，以`redis_config`在容器內，將模式設定為`0440`（組可讀），并且將所述用戶和組`103`。該`redis`服務無權訪問該`my_other_config`配置。 ```yml services: redis: image: redis:latest configs: - source: my_config target: /redis_config uid: "103" gid: "103" mode: 0440 configs: my_config: external: true my_other_config: external: true ``` 您可以授予服務訪問多個配置的權限，并且可以混合長短語法。 ### container_name `container_name`是一個字符串，它指定一個自定義容器名稱，而不是生成的默認名稱 ```yml container_name: my-web-container ``` 如果Compose文件指定一個，則撰寫實現不得將服務擴展到一個容器之外`container_name`。嘗試這樣做必須導致錯誤。如果存在，`container_name`則應遵循以下內容的正則表達式格式：`[a-zA-Z0-9][a-zA-Z0-9_.-]+` ### credential_spec `credential_spec`為托管服務帳戶配置憑據規范。組成支持使用Windows容器的服務的實現，必須支持credential\_spec`file:`和`registry:`協議。撰寫實現還可以支持自定義用例的附加協議。在`credential_spec`必須在格式`file://<filename>`或`registry://<value-name>`。 ```yml credential_spec: file: my-credential-spec.json ``` 使用時`registry:`，將從守護程序主機上的Windows注冊表中讀取憑據規范。具有給定名稱的注冊表值必須位于： HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs 以下示例從`my-credential-spec`注冊表中命名的值加載憑據規范： ```yml credential_spec: registry: my-credential-spec ``` #### gMSA憑據規范配置示例為服務配置gMSA憑據規范時，您只需使用即可指定憑據規范`config`，如以下示例所示： ```yml services: myservice: image: myimage:latest credential_spec: config: my_credential_spec configs: my_credentials_spec: file: ./my-credential-spec.json| ``` ### depends_on `depends_on` 表示服務之間的啟動和關閉依賴關系。 #### 短語法簡短的語法變體僅指定依賴項的服務名稱。服務依賴項導致以下行為： * Compose實現必須按依賴關系順序創建服務。在以下示例中，在`web`之前創建`db`和`redis`。 * Compose實現必須按依賴關系順序刪除服務。在以下示例中，在`db`和`redis`刪除之前將其`redis`刪除。簡單的例子： ```yml services: web: build: . depends_on: - db - redis redis: image: redis db: image: postgres ``` Compose實現必須保證在啟動依賴服務之前已經啟動了依賴服務。Compose實現可以在啟動依賴服務之前，等待依賴服務“ready”。 #### 長語法長格式語法允許配置其他不能以短格式表示的字段。 * `condition`：滿足依賴關系的條件 * `service_started`：等效于上述簡短語法 * `service_healthy`：指定在啟動依賴項服務之前，依賴項應為“healthy”狀態（如**healthcheck**所示）。 * `service_completed_successfully`：指定在啟動依賴項服務之前，期望依賴項可以成功完成。服務依賴項導致以下行為： * Compose實現必須按依賴關系順序創建服務。在以下示例中，在`web`之前創建`db`和`redis`。 * Compose實現必須等待運行狀況檢查傳遞標記為的依賴項`service_healthy`。在下面的示例中，`db`在`web`創建之前應該是“healthy”的。 * Compose實現必須按依賴關系順序刪除服務。在以下示例中，在`redis`和`db`之前將其刪除`web`。簡單的例子： ```yml services: web: build: . depends_on: db: condition: service_healthy redis: condition: service_started redis: image: redis db: image: postgres ``` Compose實現必須保證在啟動依賴服務之前已經啟動了依賴服務。Compose實現必須確保`service_healthy`在啟動依賴服務之前，標有的依賴服務是“healthy”。 ### device_cgroup_rules `device_cgroup_rules`定義此容器的設備cgroup規則列表。該格式與Linux內核在“[Control Groups Device Whitelist Controller](https://www.kernel.org/doc/html/latest/admin-guide/cgroup-v1/devices.html)“指定的格式相同。 ```yml device_cgroup_rules: - 'c 1:3 mr' - 'a 7:* rmw' ``` ### devices `devices`為創建的容器定義設備映射的列表。 ```yml devices: - "/dev/ttyUSB0:/dev/ttyUSB0" ``` ### dns `dns`定義要在容器網絡接口配置上設置的自定義DNS服務器。可以是單個值或列表。 ```yml dns: 8.8.8.8 ``` ```yml dns: - 8.8.8.8 - 9.9.9.9 ``` ### dns_opt `dns_opt`列出要傳遞到容器的DNS解析器（`/etc/resolv.conf`Linux上的文件）的自定義DNS選項。 ```yml dns_opt: - use-vc - no-tld-query ``` ### dns_search `dns`定義要在容器網絡接口配置上設置的自定義DNS搜索域。可以是單個值或列表。 ```yml dns_search: example.com ``` ```yml dns_search: - dc1.example.com - dc2.example.com ``` ### domainname `domainname`聲明用于服務容器的自定義域名。必須是有效的RFC 1123主機名。 ### entrypoint `entrypoint`覆蓋Docker映像的默認entrypoint（即`ENTRYPOINT`由Dockerfile設置）。當由Compose文件配置時，撰寫實現必須清除Docker映像上的所有默認命令-`ENTRYPOINT`以及`CMD`Dockerfile中的指令`entrypoint`。如果[`command`](spec.md)還設置了if，則它將用作參數以`entrypoint`替換Docker映像的`CMD` ```yml entrypoint: /code/entrypoint.sh ``` entrypoint也可以是列表，類似于[Dockerfile](https://docs.docker.com/engine/reference/builder/#cmd)： ```yml entrypoint: - php - -d - zend_extension=/usr/local/lib/php/extensions/no-debug-non-zts-20100525/xdebug.so - -d - memory_limit=-1 - vendor/bin/phpunit ``` ### env_file `env_file`根據文件內容將環境變量添加到容器中。 ```yml env_file: .env ``` `env_file`也可以是列表。列表中的文件必須從上至下進行處理。對于在兩個環境文件中指定的相同變量，列表中最后一個文件的值必須保留。 ```yml env_file: - ./a.env - ./b.env ``` 相對路徑必須從Compose文件的父文件夾中解析。由于絕對路徑會阻止Compose文件的可移植性，因此當使用set路徑時，Compose實現應向用戶發出警告`env_file`。在[環境](spec.md)(environment)部分聲明的環境變量必須覆蓋這些值–即使這些值是空的或未定義的，這也適用。 #### Env_file format env文件中的每一行必須采用`VAR[=[VAL]]`格式。以開頭開頭的行`#`必須被忽略。空白行也必須被忽略。值`VAL`用作原始字符串，根本沒有修改。如果該值用引號引起來（shell變量通常是這種情況），則引號必須**包含**在傳遞給由Compose實現創建的容器的值中。 `VAL`可以省略，在這種情況下，變量值為空字符串。`=VAL`可以省略，在這種情況下，變量未**設置**。 ```bash # Set Rails/Rack environment RACK_ENV=development VAR="quoted" ``` ### environment `environment`定義在容器中設置的環境變量。`environment`可以使用數組或映射。任何布爾值；true，false，yes，no，必須用引號引起來，以確保YAML解析器不會將其轉換為True或False。環境變量可以由單個鍵聲明（沒有值等于符號）。在這種情況下，Compose實現應依靠某些用戶交互來解決該值。如果未設置，則該變量未設置并且將從服務容器環境中刪除。鍵值語法： ```yml environment: RACK_ENV: development SHOW: "true" USER_INPUT: ``` 數組語法: ```yml environment: - RACK_ENV=development - SHOW=true - USER_INPUT ``` 為服務同時設置`env_file`和時，`environment`由設置的值`environment`具有優先權。 ### expose `expose`定義Compose實現必須從容器公開的端口。這些端口必須可供鏈接服務訪問，并且不應發布到主機上。只能指定內部容器端口。 ```yml expose: - "3000" - "8000" ``` ### extends 在當前文件或其他可選的覆蓋配置中擴展另一個服務。您可以`extends`在任何服務上與其他配置鍵一起使用。該`extends`值必須是使用必需鍵`service`和可選`file`鍵定義的映射。 ```yaml extends: file: common.yml service: webapp ``` 如果支持，則Compose實現必須`extends`以以下方式進行處理： * `service`定義被引用為基礎的服務的名稱，例如`web`或`database`。 * `file`是定義該服務的Compose配置文件的位置。 #### Restrictions 以下限制適用于所引用的服務： * 依賴于其他服務的服務不能用作基礎。因此，任何引入對另一服務的依賴關系的密鑰都不兼容`extends`。這樣的鍵的非窮舉的列表是：`links`，`volumes_from`，`container`模式（`ipc`，`pid`，`network_mode`和`net`），`service`模式（在`ipc`，`pid`和`network_mode`），`depends_on`。 * 服務不能使用以下方式的循環引用`extends` 在所有這些情況下，Compose實現都必須返回錯誤。 #### Finding referenced service `file`值可以是： * 不存在。這表明正在引用同一Compose文件中的另一個服務。 * 文件路徑，可以是： * 相對路徑。該路徑被認為是相對于主要Compose文件的位置而言的。 * 絕對路徑。 `service`在所標識的引用的Compose文件中，必須存在以表示的服務。組合實現必須在以下情況下返回錯誤： * `service`找不到由表示的服務 * `file`找不到由表示的撰寫文件 #### Merging service definitions 必須以以下方式合并兩個服務定義（當前Compose文件中的*主要*一個，并由所指定的一個*引用*`extends`）： * 映射：*主*服務定義的映射中的鍵將覆蓋*引用的*服務定義的映射中的鍵。未覆蓋的鍵按原樣包含。 * 序列：將項目組合在一起，形成一個新的序列。保留元素的順序，其中*引用的*項目排在最前面，*主要的*項目排在后面。 * 標量：*主要*服務定義中的鍵優先于所*引用*鍵中的鍵 ##### Mappings 下面的鍵應該被視為映射：`build.args`，`build.labels`，`build.extra_hosts`，`deploy.labels`，`deploy.update_config`，`deploy.rollback_config`，`deploy.restart_policy`，`deploy.resources.limits`，`environment`，`healthcheck`，`labels`，`logging.options`，`sysctls`，`storage_opt`，`extra_hosts`，`ulimits`。適用的一個例外`healthcheck`是，除非*引用的*映射也指定了*主*映射，`disable: true`否則無法指定*主*映射。在這種情況下，Compose實現必須返回錯誤。`disable: true` 例如，下面的輸入： ```yaml services: common: image: busybox environment: TZ: utc PORT: 80 cli: extends: service: common environment: PORT: 8080 ``` 為`cli`服務生成以下配置。如果使用數組語法，則會產生相同的輸出。 ```yaml environment: PORT: 8080 TZ: utc image: busybox ``` 下的項目`blkio_config.device_read_bps`，`blkio_config.device_read_iops`，`blkio_config.device_write_bps`，`blkio_config.device_write_iops`，`devices`和`volumes`也被視為映射，其中關鍵的是在容器內的目標路徑。例如，下面的輸入： ```yaml services: common: image: busybox volumes: - common-volume:/var/lib/backup/data:rw cli: extends: service: common volumes: - cli-volume:/var/lib/backup/data:ro ``` 為`cli`服務生成以下配置。請注意，現在裝入的路徑指向新的卷名，并且`ro`已應用標志。 ```yaml image: busybox volumes: - cli-volume:/var/lib/backup/data:ro ``` 如果*引用的*服務定義包含`extends`映射，則將其下的項目簡單地復制到新的*合并*定義中。然后再次開始合并過程，直到沒有`extends`剩余鍵為止。例如，下面的輸入： ```yaml services: base: image: busybox user: root common: image: busybox extends: service: base cli: extends: service: common ``` 為`cli`服務生成以下配置。在這里，`cli`服務`user`從`common`服務中獲取密鑰，而服務又從服務中獲取此密鑰`base`。 ```yaml image: busybox user: root ``` ##### Sequences 以下鍵應被視為序列：`cap_add`，`cap_drop`，`configs`，`deploy.placement.constraints`，`deploy.placement.preferences`，`deploy.reservations.generic_resources`，`device_cgroup_rules`，`expose`，`external_links`，`ports`，`secrets`，`security_opt`。合并導致的所有重復項都將被刪除，因此序列僅包含唯一元素。例如，下面的輸入： ```yaml services: common: image: busybox security_opt: - label:role:ROLE cli: extends: service: common security_opt: - label:user:USER ``` 為`cli`服務生成以下配置。 ```yaml image: busybox security_opt: - label:role:ROLE - label:user:USER ``` 在使用情況下列表語法，下面的鍵也應被視為序列：`dns`，`dns_search`，`env_file`，`tmpfs`。與上述序列字段不同，不會刪除合并產生的重復項。 ##### Scalars 服務定義中任何其他允許的鍵都應視為標量。 ### external_links `external_links`將服務容器鏈接到此Compose應用程序外部管理的服務。`external_links`使用平臺查找機制定義要檢索的現有服務的名稱。`SERVICE:ALIAS`可以指定表單的別名。 ```yml external_links: - redis - database:mysql - database:postgresql ``` ### extra_hosts `extra_hosts`將主機名映射添加到容器網絡接口配置（`/etc/hosts`對于Linux）。值必須以的形式設置其他主機的主機名和IP地址`HOSTNAME:IP`。 ```yml extra_hosts: - "somehost:162.242.195.82" - "otherhost:50.31.209.229" ``` Compose實現必須在容器的網絡配置中創建具有IP地址和主機名的匹配條目，這意味著對于Linux，這`/etc/hosts`將獲得額外的內容： ``` 162.242.195.82 somehost 50.31.209.229 otherhost ``` ### group_add `group_add`指定容器內用戶必須是其成員的其他組（按名稱或編號）。當多個容器（以不同用戶身份運行）需要全部在一個共享卷上讀取或寫入同一文件時，這是一個有用的示例。該文件可以歸所有容器共享的組所有，并在中指定`group_add`。 ```yml services: myservice: image: alpine group_add: - mail ``` `id`在創建的容器中運行必須顯示該用戶屬于該`mail`組，如果`group_add`未聲明，則不會是這種情況。 ### healthcheck `healthcheck`聲明運行的檢查以確定此服務的容器是否“healthy”。這將覆蓋服務的Docker映像設置的[HEALTHCHECK Dockerfile指令](https://docs.docker.com/engine/reference/builder/#healthcheck)。 ```yml healthcheck: test: ["CMD", "curl", "-f", "http://localhost"] interval: 1m30s timeout: 10s retries: 3 start_period: 40s ``` `interval`，`timeout`和`start_period`被[指定為持續時間](spec.md)(specifying-durations)。 `test`定義Compose實現將運行以檢查容器運行狀況的命令。它可以是字符串或列表。如果它是一個列表，第一項必須是`NONE`，`CMD`或`CMD-SHELL`。如果是字符串，則等效于指定`CMD-SHELL`后跟該字符串。 ```yml # Hit the local web app test: ["CMD", "curl", "-f", "http://localhost"] ``` using`CMD-SHELL`將使用容器的默認外殼程序（`/bin/sh`對于Linux）運行配置為字符串的命令。以下兩種形式是等效的： ```yml test: ["CMD-SHELL", "curl -f http://localhost || exit 1"] ``` ```yml test: curl -f https://localhost || exit 1 ``` `NONE`禁用運行狀況檢查，并且在禁用按圖像設置的運行狀況檢查時最有用。或者，可以通過設置禁用由圖像設置的運行狀況檢查`disable: true`： ```yml healthcheck: disable: true ``` ### hostname `hostname`聲明用于服務容器的自定義主機名。必須是有效的RFC 1123主機名。 ### image `image`指定從其開始容器的圖像。圖片必須遵循開放容器規范的[可尋址鏡像格式](digests.md)，如`[<registry>/][<project>/]<image>[:<tag>|@<digest>]`。 ```yml image: redis image: redis:5 image: redis@sha356:0ed5d5928d4737458944eb604cc8509e245c3e19d02ad83935398bc4b991aac7 image: library/redis image: docker.io/library/redis image: my_private.registry:5000/redis ``` 如果平臺上不存在該映像，則Compose實現必須嘗試基于來拉取它`pull_policy`。具有構建支持的組合實現可以為最終用戶提供替代選項，以控制從源中拉出構建映像的優先級，但是拉出映像必須是默認行為。 `image`只要`build`聲明了一個節，就可以從Compose文件中省略它。如果沒有`image`Compose文件，缺少構建支持的Compos實施必須失敗。 ### init `init`在容器內運行一個初始化進程（PID 1）以轉發信號并獲取進程。設置此選項可以`true`為服務啟用此功能。 ```yml services: web: image: alpine:latest init: true ``` 使用的初始化二進制文件是特定于平臺的。 ### ipc `ipc`配置服務容器設置的IPC隔離模式。可用的值是特定于平臺的，但是Compose規范定義了特定的值，如果支持，則必須按照說明來實現： * `shareable`這為容器提供了自己的私有IPC名稱空間，并有可能與其他容器共享。 * `service:{name}`這使容器加入另一個（`shareable`）容器的IPC名稱空間。 ```yml ipc: "shareable" ipc: "service:[service name]" ``` ### isolation `isolation`指定容器的隔離技術。支持的值是特定于平臺的。 ### labels `labels`將元數據添加到容器。您可以使用數組或映射。建議您使用反向DNS表示法，以防止標簽與其他軟件使用的標簽沖突。 ```yml labels: com.example.description: "Accounting webapp" com.example.department: "Finance" com.example.label-with-empty-value: "" ``` ```yml labels: - "com.example.description=Accounting webapp" - "com.example.department=Finance" - "com.example.label-with-empty-value" ``` Compose實現必須創建帶有規范標簽的容器： * `com.docker.compose.project`在由Compose實施創建的所有資源上設置為用戶項目名稱 * `com.docker.compose.service`在服務容器上設置服務名稱，該名稱在Compose文件中定義該`com.docker.compose`標簽的前綴被保留。在Compose文件中使用此前綴指定標簽必須導致運行時錯誤。 ### links `links`定義到另一個服務中的容器的網絡鏈接。既可以指定服務名稱，也可以指定鏈接別名（`SERVICE:ALIAS`），也可以僅指定服務名稱。 ```yml web: links: - db - db:database - redis ``` 必須以與別名相同的主機名訪問鏈接服務的容器，如果未指定別名，則必須以服務名訪問。不需要鏈接即可使服務進行通信-如果未設置特定的網絡配置，則任何服務都必須能夠以該服務的名稱到達`default`網絡上的任何其他服務。如果服務確實聲明了它們所連接的網絡，則`links`不應覆蓋網絡配置，并且未連接至共享網絡的服務也將無法通信。Compose實現可能不會警告用戶有關此配置不匹配的信息。鏈接還以與[depends_on](spec.md)相同的方式表示服務之間的隱式依賴關系，因此它們確定了服務啟動的順序。 ### logging `logging`定義服務的日志記錄配置。 ```yml logging: driver: syslog options: syslog-address: "tcp://192.168.0.42:123" ``` 該`driver`名稱指定服務容器的日志記錄驅動程序。默認值和可用值是特定于平臺的。可以將特定于驅動程序的選項設置`options`為鍵值對。 ### network_mode `network_mode`設置服務容器網絡模式。可用值是特定于平臺的，但是Compose規范定義了特定值，如果受支持，則必須按照說明來實現： * `none`禁用所有容器聯網 * `host`這使容器可以原始訪問主機的網絡接口 * `bridge`橋接網絡模式，可以隔離與主機的網絡 * `service:{name}`這使容器只能訪問指定的服務 ```yml network_mode: "host" network_mode: "none" network_mode: "service:[service name]" ``` ### networks `networks`定義服務容器所連接到的網絡，并引用[頂級`networks`密鑰](spec.md)(networks-top-level-element)下的條目。 ```yml services: some-service: networks: - some-network - other-network ``` #### aliases `aliases`在網絡上聲明此服務的備用主機名。同一網絡上的其他容器可以使用服務名稱或此別名來連接到服務的容器之一。由于`aliases`是網絡范圍的，因此同一服務在不同的網絡上可以具有不同的別名。 > **注意**：網絡范圍內的別名可以由多個容器甚至多個服務共享。如果是這樣，則不能保證名稱解析到哪個容器。通用格式如下所示： ```yml services: some-service: networks: some-network: aliases: - alias1 - alias3 other-network: aliases: - alias2 ``` 在下面的示例中，服務`frontend`將能夠`backend`在主機名`backend`或網絡`database`上訪問該服務`back-tier`，并且服務`monitoring`將能夠在網絡或網絡上訪問相同的`backend`服務。`db``mysql``admin` ```yml services: frontend: image: awesome/webapp networks: - front-tier - back-tier monitoring: image: awesome/monitoring networks: - admin backend: image: awesome/backend networks: back-tier: aliases: - database admin: aliases: - mysql networks: front-tier: back-tier: admin: ``` #### ipv4_address, ipv6_address 加入網絡后，為此服務的容器指定一個靜態IP地址。 [頂層網絡部分中](spec.md)(networks)的相應網絡配置必須具有一個`ipam`塊，其中子網配置覆蓋每個靜態地址。 ```yml services: frontend: image: awesome/webapp networks: front-tier: ipv4_address: 172.16.238.10 ipv6_address: 2001:3984:3989::10 networks: front-tier: ipam: driver: default config: - subnet: "172.16.238.0/24" - subnet: "2001:3984:3989::/64" ``` #### link_local_ips `link_local_ips`指定鏈接本地IP的列表。本地鏈路IP是特殊IP，它們屬于眾所周知的子網，并且由運營商完全管理，通常取決于部署它們的體系結構。實現是特定于平臺的。例子： ```yaml services: app: image: busybox command: top networks: app_net: link_local_ips: - 57.123.22.11 - 57.123.22.13 networks: app_net: driver: bridge ``` #### priority `priority`指示Compose實施應以哪種順序將服務的容器連接到其網絡。如果未指定，則默認值為0。在以下示例中，由于應用程序服務具有最高優先級，因此它首先連接到app_net_1。然后，它連接到app_net_3，然后連接到app_net_2，后者使用默認優先級值0。 ```yaml services: app: image: busybox command: top networks: app_net_1: priority: 1000 app_net_2: app_net_3: priority: 100 networks: app_net_1: app_net_2: app_net_3: ``` ### mac_address `mac_address`設置服務容器的MAC地址。 ### mem_limit *棄用：使用[deploy.limits.memory](deploy.md)* ### mem_reservation *棄用：使用[deploy.reservations.memory](deploy.md)* ### mem_swappiness `mem_swappiness`定義為主機內核交換容器使用的匿名內存頁面的百分比（0到100之間的值）。 * 值為0將關閉匿名頁面交換。 * 值100會將所有匿名頁面設置為可交換。默認值是特定于平臺的。 ### memswap_limit `memswap_limit`定義允許交換到磁盤的內存容器的數量。這是一個修飾符屬性，僅在`memory`同時設置時才有意義。使用交換允許容器在耗盡所有可用內存后將多余的內存需求寫入磁盤。經常將內存交換到磁盤的應用程序會降低性能。 * 如果`memswap_limit`設置為正整數，那么這兩個`memory`和`memswap_limit`必須設定。`memswap_limit`表示可以使用的內存和交換總量，并`memory`控制非交換內存使用的總量。因此，如果`memory`\=“ 300m”和`memswap_limit`\=“ 1g”，則容器可以使用300m的內存和700m（1g-300m）的交換空間。 * 如果`memswap_limit`設置為0，則必須忽略該設置，并將該值視為未設置。 * 如果`memswap_limit`將設置為與相同的值`memory`，并且`memory`將其設置為正整數，則該容器無權進行交換。請參閱阻止容器使用交換。 * 如果`memswap_limit`未設置，并且`memory`已`memory`設置，那么如果主機容器配置了交換內存，則容器可以使用與設置一樣多的交換。例如，如果未設置`memory`\=“ 300m”，`memswap_limit`則該容器總共可以使用600m的內存和交換空間。 * 如果`memswap_limit`將其顯式設置為-1，則允許容器使用無限交換，最高不超過主機系統上可用的數量。 ### oom_kill_disable 如果`oom_kill_disable`設置為true，則Compose實現必須配置平臺，以便在內存不足時不會終止容器。 ### oom_score_adj `oom_score_adj`調整在發生內存不足的情況下容器要被平臺殺死的優先級。值必須在\[-1000,1000\]范圍內。 ### pid `pid`設置由Compose實現創建的容器的PID模式。支持的值是特定于平臺的。 ### pids_limit `pids_limit`調整容器的PID限制。設置為-1表示無限制的PID。 ```yml pids_limit: 10 ``` ### platform `platform`使用`os[/arch[/variant]]`語法定義將在其上運行此服務的目標平臺容器。聲明聲明時，撰寫實現必須使用此屬性來確定將拉動映像的版本和/或在哪個平臺上執行服務的構建。 ```yml platform: osx platform: windows/amd64 platform: linux/arm64/v8 ``` ### ports 暴露容器端口。端口映射不得與之一起使用，`network_mode: host`否則必將導致運行時錯誤。 #### 短語法簡短語法是用逗號分隔的字符串，用于設置主機IP，主機端口和容器端口，格式如下： `[HOST:]CONTAINER[/PROTOCOL]`在哪里： * `HOST`是`[IP:](port | range)` * `CONTAINER`是`port | range` * `PROTOCOL`將端口限制為指定的協議。`tcp`和`udp`值由規范定義。Compose實現可以為特定于平臺的協議名稱提供支持。主機IP（如果未設置）必須綁定到所有網絡接口。端口可以??是單個值或范圍。主機和容器必須使用等效范圍。要么指定兩個端口（`HOST:CONTAINER`），要么僅指定容器端口。在后一種情況下，Compose實現應自動分配任何未分配的主機端口。 `HOST:CONTAINER`應該始終將其指定為（帶引號的）字符串，以避免與[yaml base-60 float](https://yaml.org/type/float.html)沖突。例子： ```yml 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" ``` > **注意**：平臺上可能不支持主機IP映射，在這種情況下，Compose實現應拒絕Compose文件，并且必須通知用戶它們將忽略指定的主機IP。 #### 長語法長格式語法允許配置其他不能以短格式表示的字段。 * `target`：集裝箱港口 * `published`：公開端口 * `protocol`：端口協議（`tcp`或`udp`），未指定表示任何協議 * `mode`：`host`用于在每個節點上發布主機端口，或`ingress`用于負載平衡的端口。 ```yml ports: - target: 80 published: 8080 protocol: tcp mode: host ``` ### privileged `privileged`配置服務容器以提升的特權運行。支持和實際影響是特定于平臺的。 ### profiles `profiles`定義要在其下啟用的服務的命名配置文件列表。如果未設置，則始終啟用服務。如果存在，`profiles`則應遵循的正則表達式格式`[a-zA-Z0-9][a-zA-Z0-9_.-]+`。 ### pull_policy `pull_policy`定義Compose實現在開始提取圖像時將做出的決定。可能的值為： * `always`：撰寫實現應始終從注冊表中提取圖像。 * `never`：撰寫實現不應從注冊表中提取映像，而應依賴平臺緩存的映像。如果沒有緩存的圖像，則必須報告失敗。 * `missing`：僅當平臺緩存中不存在映像時，撰寫實現才應拉取映像。對于沒有構建支持的Compose實現，這應該是默認選項。`if_not_present`應該考慮該值的別名，以便向后兼容 * `build`：撰寫實現應構建映像。撰寫實現應重新構建映像（如果已存在）。如果`pull_policy`和`build`都出現，則Compose實現應默認構建映像。撰寫實現可以在工具鏈中覆蓋此行為。 ### read_only `read_only`將服務容器配置為使用只讀文件系統創建。 ### restart `restart`定義平臺將在容器終止上應用的策略。 * `no`：默認的重啟策略。在任何情況下都不重啟容器。 * `always`：策略始終重新啟動容器，直到將其移除。 * `on-failure`：如果退出代碼指示錯誤，則策略將重新啟動容器。 * `unless-stopped`：無論退出代碼是什么，該策略都會重新啟動容器，但是在停止或刪除服務后，該策略將停止重新啟動。 ```yml restart: "no" restart: always restart: on-failure restart: unless-stopped ``` ### runtime `runtime`指定用于服務容器的運行時。的值`runtime`特定于實現。例如，`runtime`可以是[OCI Runtime Spec的實現](implementations.md)的名稱，例如“ runc”。 ```yml web: image: busybox:latest command: true runtime: runc ``` ### scale -已棄用：使用[部署/副本](deploy.md)(replicas)_ `scale`指定要為此服務部署的默認容器數。 ### secrets `secrets`授予對每項服務根據[機密](https://github.com/compose-spec/compose-spec/blob/master/secrets)定義的敏感數據的訪問權限。支持兩種不同的語法變體：短語法和長語法。如果機密在平臺上不存在或未在`secrets`此Compose文件的部分中定義，則撰寫實現必須報告錯誤。 #### 短語法簡短的語法變體僅指定秘密名稱。這會授予容器對機密的訪問權限，并將其以只讀方式安裝到`/run/secrets/<secret_name>`容器內。源名稱和目標安裝點都設置為機密名稱。下面的示例使用short語法向`frontend`服務授予對`server-certificate`機密的訪問權限。的值`server-certificate`設置為文件的內容`./server.cert`。 ```yml services: frontend: image: awesome/webapp secrets: - server-certificate secrets: server-certificate: file: ./server.cert ``` #### 長語法長語法提供了在服務的容器中如何創建機密的更多粒度。 * `source`：機密存在于平臺上的名稱。 * `target`：要`/run/secrets/`在服務的任務容器中掛載的文件的名稱。`source`如果未指定，則默認為。 * `uid`和`gid`：`/run/secrets/`在服務的任務容器中擁有文件的數字UID或GID。默認值為USER運行容器。 * `mode`：文件的[權限](http://permissions-calculator.org/)以`/run/secrets/`八進制表示法裝入服務的任務容器中。默認值為世界可讀的權限（模式`0444`）。如果設置了可寫位，則必須將其忽略。可執行位可以設置。以下示例將`server-certificate`秘密文件的名稱設置為`server.crt`容器內的名稱，將模式設置為`0440`（組可讀），并將用戶和組的名稱設置為`103`。`server-certificate`秘密的價值由平臺通過查找和秘密生命周期提供，而不由Compose實現直接管理。 ```yml services: frontend: image: awesome/webapp secrets: - source: server-certificate target: server.cert uid: "103" gid: "103" mode: 0440 secrets: server-certificate: external: true ``` 服務可能被授予訪問多個機密的權限。機密的長短語法可以在同一個Compose文件中使用。在頂級`secrets`MUTS中定義機密并不意味著授予對它的任何服務訪問權限。這樣的授予必須在服務規范中作為`secrets`服務元素是明確的。 ### security_opt `security_opt`覆蓋每個容器的默認標簽方案。 ```yml security_opt: - label:user:USER - label:role:ROLE ``` ### shm_size `shm_size`配置`/dev/shm`服務容器允許的共享內存（Linux上的分區）的大小。指定為[字節值](spec.md)(specifying-byte-values)。 ### stdin_open `stdin_open`將服務容器配置為與分配的標準輸入一起運行。 ### stop_grace_period `stop_grace_period`指定[`stop_signal`](spec.md)在發送SIGKILL之前，如果Compose實現無法處理SIGTERM（或已使用指定的任何停止信號），則在嘗試停止容器時，Compose實現必須等待多長時間。指定為[持續時間](spec.md)(specifying-durations)。 ```yml stop_grace_period: 1s stop_grace_period: 1m30s ``` 容器在發送SIGKILL之前退出的默認值為10秒。 ### stop_signal `stop_signal`定義Compose實現必須用于停止服務容器的信號。如果未設置的容器由Compose Implementation通過發送停止`SIGTERM`。 ```yml stop_signal: SIGUSR1 ``` ### storage_opt `storage_opt`定義服務的存儲驅動程序選項。 ```yml storage_opt: size: '1G' ``` ### sysctls `sysctls`定義要在容器中設置的內核參數。`sysctls`可以使用數組或映射。 ```yml sysctls: net.core.somaxconn: 1024 net.ipv4.tcp_syncookies: 0 ``` ```yml 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)。 ### tmpfs `tmpfs`在容器內安裝一個臨時文件系統。可以是單個值或列表。 ```yml tmpfs: /run ``` ```yml tmpfs: - /run - /tmp ``` ### tty `tty`配置服務容器使其與TTY一起運行。 ### ulimits `ulimits`覆蓋容器的默認ulimit。將單個限制指定為整數，將軟/硬限制指定為映射。 ```yml ulimits: nproc: 65535 nofile: soft: 20000 hard: 40000 ``` ### user `user`覆蓋用于運行容器進程的用戶。默認是由映像設置的值（即Dockerfile`USER`），如果未設置，則為`root`。 ### userns_mode `userns_mode`設置服務的用戶名稱空間。支持的值是特定于平臺的，并且可能取決于平臺配置 ```yml userns_mode: "host" ``` ### volumes `volumes`定義必須由服務容器訪問的裝載主機路徑或命名卷。如果安裝是主機路徑，并且僅由單個服務使用，則可以將其聲明為服務定義的一部分，而不是頂層`volumes`密鑰。要在多個服務之間重用卷，必須在[頂級`volumes`key中](spec.md)聲明一個命名卷。此示例顯示了服務`backend`正在使用的命名卷`db-data`，以及為單個服務定義的綁定安裝 ```yml services: backend: image: awesome/backend volumes: - type: volume source: db-data target: /data volume: nocopy: true - type: bind source: /var/run/postgres/postgres.sock target: /var/run/postgres/postgres.sock volumes: db-data: ``` #### 短語法簡短語法使用帶有逗號分隔值的單個字符串來指定卷裝載（`VOLUME:CONTAINER_PATH`）或訪問模式（`VOLUME:CONTAINER:ACCESS_MODE`）。 `VOLUME`可以是平臺上托管容器（綁定安裝）的主機路徑，也可以是卷名稱。`ACCESS_MODE`可以使用設置為只讀，`ro`或者使用`rw`設置讀寫（默認）。 > **注意**：相對主機路徑必須僅由部署到本地容器運行時的Compose實現支持。這是因為相對路徑是從Compose文件的父目錄解析的，該父目錄僅在本地情況下適用。部署到非本地平臺的撰寫實現必須拒絕使用錯誤的使用相對主機路徑的撰寫文件。為了避免命名卷含糊不清，相對路徑應始終以`.`或開頭`..`。 #### 長語法長格式語法允許配置其他不能以短格式表示的字段。 * `type`：所述安裝型`volume`，`bind`，`tmpfs`或`npipe` * `source`：安裝源，綁定安裝在主機上的路徑或[頂級`volumes`密鑰中](spec.md)定義的卷的名稱。不適用于tmpfs掛載。 * `target`：安裝了卷的容器中的路徑 * `read_only`：將卷設置為只讀的標志 * `bind`：配置其他綁定選項 * `propagation`：用于綁定的傳播模式 * `volume`：配置其他音量選項 * `nocopy`：標志，用于在創建卷時禁用從容器中復制數據 * `tmpfs`：配置其他tmpfs選項 * `size`：tmpfs掛載的大小（以字節為單位） * `consistency`：安裝座的一致性要求。可用值是特定于平臺的 ### volumes_from `volumes_from`從另一個服務或容器安裝所有卷，可以選擇指定只讀訪問（ro）或讀寫（rw）。如果未指定訪問級別，則必須使用讀寫。字符串值在Compose應用程序模型中定義了另一個要從中裝入卷的服務。該`container:`前綴，如果支持的話，允許從不是由撰寫實現管理的容器裝入卷。 ```yaml volumes_from: - service_name - service_name:ro - container:container_name - container:container_name:rw ``` ### working_dir `working_dir`從圖像指定的目錄（即Dockerfile`WORKDIR`）覆蓋容器的工作目錄。 ## Networks top-level element 網絡是允許服務相互通信的層。公開給服務的網絡模型僅限于與目標服務和外部資源的簡單IP連接，而網絡定義允許微調平臺提供的實際實現。可以通過在頂級`networks`區域下指定網絡名稱來創建網絡。服務可以通過在服務[`networks`](https://github.com/compose-spec/compose-spec/blob/master/spec.md#networks)小節下指定網絡名稱來連接到網絡在下面的示例中，將在運行時創建網絡`front-tier`和`back-tier`，并將`frontend`服務連接到`front-tier`網絡和`back-tier`網絡。 ```yml services: frontend: image: awesome/webapp networks: - front-tier - back-tier networks: front-tier: back-tier: ``` ### driver `driver`指定該網絡應使用哪個驅動程序。如果驅動程序在平臺上不可用，則Compose實現必須返回錯誤。 ```yml driver: overlay ``` 默認值和可用值是特定于平臺的。Compose規范必須支持以下特定驅動程序：`none`和`host` * `host`使用主機的網絡堆棧 * `none`禁用網絡 #### host or none 使用內置網絡（例如`host`和`none`）的語法是不同的，因為此類網絡隱式存在于Compose實現的范圍之外。要使用它們，必須使用Compose實現可以使用的名稱`host`或`none`別名定義一個外部網絡（`hostnet`或`nonet`在以下示例中），然后使用其別名向該網絡授予服務訪問權限。 ```yml services: web: networks: hostnet: {} networks: hostnet: external: true name: host ``` ```yml services: web: ... networks: nonet: {} networks: nonet: external: true name: none ``` ### driver_opts `driver_opts`指定選項列表作為鍵值對，以傳遞給該網絡的驅動程序。這些選項取決于驅動程序-有關更多信息，請參考驅動程序的文檔。可選的。 ```yml driver_opts: foo: "bar" baz: 1 ``` ### attachable 如果`attachable`設置為`true`，則除了服務之外，獨立容器還應該能夠連接到該網絡。如果獨立容器連接到網絡，則它可以與也連接到網絡的服務和其他獨立容器進行通信。 ```yml networks: mynet1: driver: overlay attachable: true ``` ### enable_ipv6 `enable_ipv6`在該網絡上啟用IPv6網絡。 ### ipam `ipam`指定自定義IPAM配置。這是一個具有多個屬性的對象，每個屬性都是可選的： * `driver`：自定義IPAM驅動程序，而不是默認驅動程序。 * `config`：具有零個或多個配置元素的列表，每個元素包含： * `subnet`：代表網段的CIDR格式的子網 * `ip_range`：從中分配容器IP的IP范圍 * `gateway`：主子網的IPv4或IPv6網關 * `aux_addresses`：網絡驅動程序使用的輔助IPv4或IPv6地址，作為從主機名到IP的映射 * `options`：特定于驅動程序的選項作為鍵值映射。一個完整的例子： ```yml ipam: driver: default config: - subnet: 172.28.0.0/16 ip_range: 172.28.5.0/24 gateway: 172.28.5.254 aux_addresses: host1: 172.28.1.5 host2: 172.28.1.6 host3: 172.28.1.7 options: foo: bar baz: "0" ``` ### internal 默認情況下，撰寫實現必須提供與網絡的外部連接。`internal`設置為`true`允許創建外部隔離的網絡時。 ### labels 使用標簽將元數據添加到容器。可以使用數組或字典。用戶應使用反向DNS表示法，以防止標簽與其他軟件使用的標簽沖突。 ```yml labels: com.example.description: "Financial transaction network" com.example.department: "Finance" com.example.label-with-empty-value: "" ``` ```yml labels: - "com.example.description=Financial transaction network" - "com.example.department=Finance" - "com.example.label-with-empty-value" ``` Compose實現必須設置`com.docker.compose.project`并`com.docker.compose.network`標記。 ### external 如果設置為`true`，則`external`指定該網絡的生命周期保持在應用程序之外。Compose實現不應嘗試創建這些網絡，如果不存在，則會引發錯誤。在下面的示例中，`proxy`是通往外界的門戶。代替嘗試創建網絡，Compose實現應該詢問簡單調用的現有網絡的平臺`outside`，并將`proxy`服務的容器連接到該平臺。 ```yml services: proxy: image: awesome/proxy networks: - outside - default app: image: awesome/app networks: - default networks: outside: external: true ``` ### name `name`設置此網絡的自定義名稱。名稱字段可用于引用包含特殊字符的網絡。該名稱按原樣使用，**不會**與項目名稱一起作用域。 ```yml networks: network1: name: my-app-net ``` 它也可以與該`external`屬性一起使用，以定義Compose實現應檢索的平臺網絡，通常是通過使用一個參數，這樣Compose文件不需要對運行時特定的值進行硬編碼： ```yml networks: network1: external: true name: "${NETWORK_ID}" ``` ## Volumes top-level element 卷是平臺實現的永久數據存儲。Compose規范為安裝卷的服務和配置參數（在基礎結構上分配它們）提供了中立的抽象。本`volumes`部分允許配置可在多個服務之間重用的命名卷。這是兩種服務設置的示例，其中數據庫的數據目錄作為卷與另一服務共享，以便可以定期備份它： ```yml services: backend: image: awesome/database volumes: - db-data:/etc/data backup: image: backup-service volumes: - db-data:/var/lib/backup/data volumes: db-data: ``` 頂級`volumes`密鑰下的條目可以為空，在這種情況下，它將使用平臺的默認配置來創建卷。（可選）您可以使用以下鍵對其進行配置： ### driver 指定該卷應使用哪個卷驅動程序。默認值和可用值是特定于平臺的。如果驅動程序不可用，則Compose實現必須返回錯誤并停止應用程序部署。 ```yml driver: foobar ``` ### driver_opts `driver_opts`指定選項列表作為鍵值對傳遞給該卷的驅動程序。這些選項取決于驅動程序。 ```yml volumes: example: driver_opts: type: "nfs" o: "addr=10.40.0.199,nolock,soft,rw" device: ":/docker/example" ``` ### external 如果設置為`true`，則`external`指定該卷已在平臺上存在，并且其生命周期在應用程序的生命周期之外進行管理。組合實現不得嘗試創建這些卷，并且如果不存在，則必須返回錯誤。在下面的示例中，Compose不會嘗試創建一個名為`{project_name}_data`的卷，而是查找一個簡單稱為的現有卷`data`并將其裝入`db`服務的容器中。 ```yml services: backend: image: awesome/database volumes: - db-data:/etc/data volumes: db-data: external: true ``` ### labels `labels`用于將元數據添加到卷。您可以使用數組或字典。建議您使用反向DNS表示法，以防止標簽與其他軟件使用的標簽沖突。 ```yml labels: com.example.description: "Database volume" com.example.department: "IT/Ops" com.example.label-with-empty-value: "" ``` ```yml labels: - "com.example.description=Database volume" - "com.example.department=IT/Ops" - "com.example.label-with-empty-value" ``` Compose實現必須設置`com.docker.compose.project`并`com.docker.compose.volume`標記。 ### name `name`為此卷設置一個自定義名稱。名稱字段可用于引用包含特殊字符的卷。該名稱按原樣使用，**不會**與堆棧名稱一起作用域。 ```yml volumes: data: name: "my-app-data" ``` 它也可以與該`external`屬性結合使用。為此，用于在平臺上查找實際卷的卷的名稱與用于在Compose文件中引用該卷的名稱是分開設置的： ```yml volumes: db-data: external: name: actual-name-of-volume ``` 這樣就可以使此查找名稱成為Compose文件的參數，以便對卷的模型ID進行硬編碼，但在部署期間在運行時設置平臺上的實際卷ID： ```yml volumes: db-data: external: name: ${DATABASE_VOLUME} ``` ## Configs top-level element 通過配置，服務無需重新構建Docker映像即可適應其行為。從服務的角度來看，配置可與卷媲美，因為它們被安裝到服務的容器文件系統中。可以從Configuration定義中設置平臺提供的用于獲取配置的實際實現細節。授予對配置的訪問權限后，該配置內容將作為文件安裝在容器中。容器中安裝點的位置默認為`/<config-name>`Linux容器和`C:\<config-name>`Windows容器中的位置。默認情況下，配置必須由運行container命令的用戶所有，但可以被服務配置覆蓋。默認情況下，除非服務被配置為覆蓋此配置，否則該配置必須具有世界可讀的權限（模式0444）。服務僅在由[`configs`](spec.md)小節明確授予時才能訪問配置。頂級`configs`聲明定義或引用可以授予此應用程序中的服務的配置數據。配置的來源是`file`或`external`。 * `file`：使用指定路徑中的文件內容創建配置。 * `external`：如果設置為true，則指定此配置已創建。撰寫實現不會嘗試創建它，如果它不存在，則會發生錯誤。 * `name`：要查找的平臺上的配置對象的名稱。該字段可用于引用包含特殊字符的配置。該名稱按原樣使用，**不會**與項目名稱一起作用域。在此示例中，`http_config`是在`<project_name>_http_config`部署應用程序時創建的（如），并且`my_second_config`必須已存在于Platform上，并且將通過查找獲得價值。在此示例中，通過將as的內容注冊為配置數據來在部署應用程序時`server-http_config`創建。`<project_name>_http_config``httpd.conf` ```yml configs: http_config: file: ./httpd.conf ``` 或者，`http_config`可以聲明為外部，這樣Compose實現將查找`server-certificate`以將配置數據公開給相關服務。 ```yml configs: http_config: external: true ``` 外部配置查找還可以通過指定來使用唯一鍵`name`。以下示例將上一個示例修改為使用parameter來查找config`HTTP_CONFIG_KEY`。這樣做將在部署時通過對變量進行[插值](spec.md)(interpolation)來設置實際的查找關鍵字，但會將其作為硬編碼ID公開給容器`http_config`。 ```yml configs: http_config: external: true name: "${HTTP_CONFIG_KEY}" ``` Compose文件需要向應用程序中的相關服務顯式授予對配置的訪問權限。 ## Secrets top-level element 密鑰是Configs的一種風格，它專注于敏感數據，對此用法有特定的限制。由于平臺的實現可能與Configs明顯不同，因此專用的Secrets部分允許配置相關資源。頂級`secrets`聲明定義或引用可以授予此應用程序中的服務的敏感數據。秘密的來源是`file`或`external`。 * `file`：秘密是使用指定路徑中的文件內容創建的。 * `external`：如果設置為true，則指定此機密已創建。撰寫實現不會嘗試創建它，如果它不存在，則會發生錯誤。 * `name`：Docker中的秘密對象的名稱。此字段可用于引用包含特殊字符的機密。該名稱按原樣使用，**不會**與項目名稱一起作用域。在此示例中，通過將內容注冊為平臺機密，在部署應用程序時`server-certificate`創建。`<project_name>_server-certificate``server.cert` ```yml secrets: server-certificate: file: ./server.cert ``` 或者，`server-certificate`可以聲明為外部，這樣Compose實現將查找`server-certificate`以將秘密公開給相關服務。 ```yml secrets: server-certificate: external: true ``` 外部機密查找還可以通過指定來使用不同的密鑰`name`。以下示例修改了上一個示例，以使用參數查找秘密`CERTIFICATE_KEY`。這樣做將在部署時通過對變量進行[插值](spec.md)(interpolation)來設置實際的查找關鍵字，但會將其作為硬編碼ID公開給容器`server-certificate`。 ```yml secrets: server-certificate: external: true name: "${CERTIFICATE_KEY}" ``` Compose文件需要顯式授予對應用程序中相關服務的機密的訪問權限。 ## Fragments 可以使用[YAML錨點](http://www.yaml.org/spec/1.2/spec.html#id2765878)重用配置片段。 ```yml volumes: db-data: &default-volume driver: default metrics: *default-volume ``` 在先前的示例中，基于體積規范創建了一個*錨點*。以后，它會被*別名*重用以定義卷。相同的邏輯可以應用于Compose文件中的任何元素。錨定解析必須在[變量插值](spec.md)(interpolation)之前進行，因此變量不能用于設置錨定或別名。`default-volume``db-data``*default-volume``metrics` 也可以使用[YAML合并類型](http://yaml.org/type/merge.html)部分覆蓋由錨引用設置的值。在以下示例中，`metrics`卷規范使用別名來避免重復，但會覆蓋`name`屬性： ```yml services: backend: image: awesome/database volumes: - db-data - metrics volumes: db-data: &default-volume driver: default name: "data" metrics: <<: *default-volume name: "metrics" ``` ## Extension 特殊擴展名字段的名稱可以以`x-`字符序列開頭，可以采用任何格式。它們可以在Compose文件的任何結構中使用。這是Compose實現以靜默方式忽略無法識別的字段的唯一例外。 ```yml x-custom: foo: - bar - zot services: webapp: image: awesome/webapp x-foo: bar ``` 此類字段的內容未由Compose規范指定，可用于啟用自定義功能。遇到未知擴展字段的組合實現絕不能失敗，但是可以警告未知字段。對于平臺擴展，強烈建議使用平臺/供應商名稱作為擴展名的前綴，就像瀏覽器添加對[自定義CSS功能的](https://www.w3.org/TR/2011/REC-CSS2-20110607/syndata.html#vendor-keywords)支持一樣 ```yml service: backend: deploy: placement: x-aws-role: "arn:aws:iam::XXXXXXXXXXXX:role/foo" x-aws-region: "eu-west-3" x-azure-region: "france-central" ``` ### Informative Historical Notes 本節內容豐富。在Compose本文時，已知存在以下前綴： | prefix | vendor/organization | | ---------- | ------------------- | | docker | Docker | | kubernetes | Kubernetes | ### Using extensions as fragments 借助對擴展字段的支持，可以如下編寫Compose文件，以提高重用片段的可讀性： ```yml x-logging: &default-logging options: max-size: "12m" max-file: "5" driver: json-file services: frontend: image: awesome/webapp logging: *default-logging backend: image: awesome/database logging: *default-logging ``` ### specifying byte values 值表示一個字節的值作為一個字符串`{amount}{byte unit}`格式：支持的單位是`b`（字節），`k`或`kb`（千字節），`m`或`mb`（兆字節）和`g`或`gb`（千兆字節）。 ``` 2b 1024kb 2048k 300m 1gb ``` ### specifying durations 值以形式將持續時間表示為字符串`{value}{unit}`。支持的單位是`us`（微秒），`ms`（毫秒），`s`（秒），`m`（分鐘）和`h`（小時）。值可以合并多個值，并且可以不帶分隔符地使用。 ``` 10ms 40s 1m30s 1h5m30s20ms ``` ## Interpolation 可以通過變量設置Compose文件中的值，并在運行時進行插值。撰寫文件使用類似Bash的語法`${VARIABLE}` 這兩個`$VARIABLE`和`${VARIABLE}`語法的支持。可以使用典型的Shell語法內聯定義默認值：Latest * `${VARIABLE:-default}`計算環境中`default`是否`VARIABLE`未設置或為空。 * `${VARIABLE-default}``default`僅`VARIABLE`在環境中未設置時評估為。同樣，以下語法允許您指定必需變量： * `${VARIABLE:?err}`退出，并顯示一條錯誤消息，其中包含在環境中`err`是否`VARIABLE`設置為if或為空。 * `${VARIABLE?err}`退出并顯示錯誤消息，其中包含在環境中未設置`err`if的信息`VARIABLE`。 `${VARIABLE/foo/bar}`Compose規范不支持其他擴展的Shell樣式功能，例如。 `$$`當您的配置需要文字美元符號時，可以使用（雙美元符號）。這也可以防止Compose插值，因此a`$$`允許您引用您不想由Compose處理的環境變量。 ```yml web: build: . command: "$$VAR_NOT_INTERPOLATED_BY_COMPOSE" ``` 如果Compose實現無法解析替換變量，并且未定義默認值，則它必須警告用戶并將變量替換為空字符串。由于可以使用變量替換對Compose文件中的任何值進行插值，包括復雜元素的緊湊字符串表示法，因此必須在基于每個文件合并*之前*應用插值。