Spec split (#16740)

* split spec

* spec split

* trial branch

* fix

* branch update

* landing page

* add description

* add description

* update file path

* tweak

* fix build

* split spec

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* spec split

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* trial branch

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* fix

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* branch update

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* landing page

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* add description

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* add description

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* update file path

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* tweak

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* fix build

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* missing new line

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>

* first batch of fix links

* second batch of link fix

* update toc

---------

Signed-off-by: CrazyMax <crazy-max@users.noreply.github.com>
Co-authored-by: CrazyMax <crazy-max@users.noreply.github.com>
This commit is contained in:
Allie Sadler 2023-03-22 12:00:04 +00:00 committed by GitHub
parent e04f063645
commit 855cda4011
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
25 changed files with 281 additions and 2545 deletions

View File

@ -215,3 +215,44 @@ fetch-remote:
- dest: "build/attestations/attestation-storage.md"
src:
- "docs/attestations/attestation-storage.md"
- repo: "https://github.com/compose-spec/compose-spec"
default_branch: "master"
ref: "master"
paths:
- dest: "compose/compose-file/status.md"
src:
- "01-status.md"
- dest: "compose/compose-file/model.md"
src:
- "02-model.md"
- dest: "compose/compose-file/compose-file.md"
src:
- "03-compose-file.md"
- dest: "compose/compose-file/version-and-name.md"
src:
- "04-version-and-name.md"
- dest: "compose/compose-file/services.md"
src:
- "05-services.md"
- dest: "compose/compose-file/networks.md"
src:
- "06-networks.md"
- dest: "compose/compose-file/volumes.md"
src:
- "07-volumes.md"
- dest: "compose/compose-file/configs.md"
src:
- "08-configs.md"
- dest: "compose/compose-file/secrets.md"
src:
- "09-secrets.md"
- dest: "compose/compose-file/fragments.md"
src:
- "10-fragments.md"
- dest: "compose/compose-file/extension.md"
src:
- "11-extension.md"
- dest: "compose/compose-file/interpolation.md"
src:
- "12-interpolation.md"

View File

@ -884,8 +884,34 @@ reference:
path: /engine/reference/builder/
- sectiontitle: Compose file reference
section:
- path: /compose/compose-file/
title: Compose Specification
- sectiontitle: Compose specification
section:
- path: /compose/compose-file/
title: Overview
- path: /compose/compose-file/01-status/
title: Status of the specification
- path: /compose/compose-file/02-model/
title: Compose application model
- path: /compose/compose-file/03-compose-file/
title: The Compose file
- path: /compose/compose-file/build/04-version-and-name/
title: Version and name top-level element
- path: /compose/compose-file/05-services/
title: Services top-level element
- path: /compose/compose-file/06-networks/
title: Network top-level element
- path: /compose/compose-file/07-volumes/
title: Volumes top-level element
- path: /compose/compose-file/08-configs/
title: Configs top-level element
- path: /compose/compose-file/09-secrets/
title: Secrets top-level element
- path: /compose/compose-file/10-fragments/
title: Fragments
- path: /compose/compose-file/11-extensions/
title: Extensions
- path: /compose/compose-file/12-interpolation/
title: Interpolation
- path: /compose/compose-file/build/
title: Compose file build
- path: /compose/compose-file/deploy/

View File

@ -98,7 +98,7 @@ Unlike the [HCL format](file-definition.md#hcl-definition), there are some
limitations with the compose format:
* Specifying variables or global scope attributes is not yet supported
* `inherits` service field is not supported, but you can use [YAML anchors](https://docs.docker.com/compose/compose-file/#fragments){:target="blank" rel="noopener" class=""}
* `inherits` service field is not supported, but you can use [YAML anchors](../../compose/compose-file/10-fragments.md){:target="blank" rel="noopener" class=""}
to reference other services like the example above
## `.env` file
@ -155,7 +155,7 @@ $ docker buildx bake --print
## Extension field with `x-bake`
Even if some fields are not (yet) available in the compose specification, you
can use the [special extension](../../compose/compose-file/index.md#extension)
can use the [special extension](../../compose/compose-file/11-extension.md)
field `x-bake` in your compose file to evaluate extra fields:
```yaml

View File

@ -0,0 +1,7 @@
---
title: Status of the specification
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Compose application model
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: The Compose file
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Version and name top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Services top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Networks top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Volumes top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Configs top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Secrets top-level element
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Fragments
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Extensions
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -0,0 +1,7 @@
---
title: Interpolation
keywords: compose, compose specification
fetch_remote:
line_start: 2
line_end: -1
---

View File

@ -229,7 +229,7 @@ Unsupported cache target MUST be ignored and not prevent user from building imag
### extra_hosts
`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](index.md#extra_hosts).
`extra_hosts` adds hostname mappings at build-time. Use the same syntax as [extra_hosts](05-services.md#extra_hosts).
```yml
extra_hosts:
@ -247,7 +247,7 @@ configuration, which means for Linux `/etc/hosts` will get extra lines:
### isolation
`isolation` specifies a builds container isolation technology. Like [isolation](index.md#isolation) supported values
`isolation` specifies a builds container isolation technology. Like [isolation](05-services.md#isolation) supported values
are platform-specific.
### labels
@ -288,7 +288,7 @@ available in the local image store.
### shm_size
`shm_size` set the size of the shared memory (`/dev/shm` partition on Linux) allocated for building Docker image. Specify
as an integer value representing the number of bytes or as a string expressing a [byte value](index.md#specifying-byte-values).
as an integer value representing the number of bytes or as a string expressing a [byte value](11-extension.md#specifying-byte-values).
```yml
build:
@ -313,11 +313,11 @@ build:
```
### secrets
`secrets` grants access to sensitive data defined by [secrets](index.md#secrets) on a per-service build basis. Two
`secrets` grants access to sensitive data defined by [secrets](05-services.md#secrets) on a per-service build basis. Two
different syntax variants are supported: the short syntax and the long syntax.
Compose implementations MUST report an error if the secret isn't defined in the
[`secrets`](index.md#secrets-top-level-element) section of the Compose file.
[`secrets`](09-secrets.md) section of the Compose file.
#### Short syntax
@ -380,12 +380,12 @@ secrets:
Service builds MAY be granted access to multiple secrets. Long and short syntax for secrets MAY be used in the
same Compose file. Defining a secret in the top-level `secrets` MUST NOT imply granting any service build access to it.
Such grant must be explicit within the service specification as a [secrets](index.md#secrets) service element.
Such grant must be explicit within the service specification as a [secrets](05-services.md#secrets) service element.
### tags
`tags` defines a list of tag mappings that MUST be associated to the build image. This list comes in addition of
the `image` [property defined in the service section](index.md#image)
the `image` [property defined in the service section](05-services.md#image)
```yml
tags:
@ -395,7 +395,7 @@ tags:
### platforms
`platforms` defines a list of target [platforms](index.md#platform).
`platforms` defines a list of target [platforms](05-services.md#platform).
```yml
build:

View File

@ -155,7 +155,7 @@ services:
`memory` configures a limit or reservation on the amount of memory a container
can allocate, set as a string expressing a
[byte value](index.md#specifying-byte-values).
[byte value](11-extension.md#specifying-byte-values).
#### pids
@ -249,11 +249,11 @@ deploy:
`restart_policy` configures if and how to restart containers when they exit. If `restart_policy` is not set, Compose implementations MUST consider `restart` field set by service configuration.
- `condition`: One of `none`, `on-failure` or `any` (default: `any`).
- `delay`: How long to wait between restart attempts, specified as a [duration](index.md#specifying-durations) (default: 0).
- `delay`: How long to wait between restart attempts, specified as a [duration](11-extension.md#specifying-durations) (default: 0).
- `max_attempts`: How many times to attempt to restart a container before giving up (default: never give up). If the restart does not
succeed within the configured `window`, this attempt doesn't count toward the configured `max_attempts` value.
For example, if `max_attempts` is set to '2', and the restart fails on the first attempt, more than two restarts MUST be attempted.
- `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](index.md#specifying-durations) (default:
- `window`: How long to wait before deciding if a restart has succeeded, specified as a [duration](11-extension.md#specifying-durations) (default:
decide immediately).
```yml

File diff suppressed because it is too large Load Diff

View File

@ -43,7 +43,7 @@ services:
The `.env` file should be placed at the root of the project directory next to your `docker-compose.yml` file. You can use an alternative path with one of the following methods:
- The [`--file` option in the CLI](../reference/index.md#use--f-to-specify-name-and-path-of-one-or-more-compose-files)
- The [`--env-file` option in the CLI](#substitute-with---env-file)
- Using the [`env_file` attribute in the Compose file](../compose-file/index.md#env_file)
- Using the [`env_file` attribute in the Compose file](../compose-file/05-services.md#env_file)
For more information on formatting an environment file, see [Use an environment file](env-file.md).
@ -56,7 +56,7 @@ For more information on formatting an environment file, see [Use an environment
### Use the `environment` attribute
You can set environment variables in a service's containers with the
[`environment` attribute](../compose-file/index.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...`
[`environment` attribute](../compose-file/05-services.md#environment) in your Compose file. It works in the same way as `docker run -e VARIABLE=VALUE ...`
```yaml
web:
@ -75,12 +75,12 @@ web:
The value of the `DEBUG` variable in the container is taken from the value for the same variable in the shell in which Compose is run.
See [`environment` attribute](../compose-file/index.md#environment) for more information.
See [`environment` attribute](../compose-file/05-services.md#environment) for more information.
### Use the `env_file` attribute
You can pass multiple environment variables from an external file through to
a service's containers with the [`env_file` option](../compose-file/index.md#env_file). This works in the same way as `docker run --env-file=FILE ...`:
a service's containers with the [`env_file` option](../compose-file/05-services.md#env_file). This works in the same way as `docker run --env-file=FILE ...`:
```yaml
web:
@ -94,7 +94,7 @@ If multiple files are specified, they are evaluated in order and can override va
>
>With this option, environment variables declared in the file cannot then be referenced again separately in the Compose file or used to configure Compose.
See [`env_file` attribute](../compose-file/index.md#env_file) for more information.
See [`env_file` attribute](../compose-file/05-services.md#env_file) for more information.
### Substitute from the shell

View File

@ -446,4 +446,4 @@ services:
## Reference information
[`extends`](compose-file/index.md#extends)
[`extends`](compose-file/05-services.md#extends)

View File

@ -82,14 +82,14 @@ services:
image: postgres
```
See the [links reference](compose-file/index.md#links) for more information.
See the [links reference](compose-file/05-services.md#links) for more information.
## Multi-host networking
When deploying a Compose application on a Docker Engine with [Swarm mode enabled](../engine/swarm/index.md),
you can make use of the built-in `overlay` driver to enable multi-host communication.
Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/index.md#attachable) property to `false`.
Overlay networks are always created as `attachable`. You can optionally set the [`attachable`](compose-file/06-networks.md#attachable) property to `false`.
Consult the [Swarm mode section](../engine/swarm/index.md), to see how to set up
a Swarm cluster, and the [Getting started with multi-host networking](../network/network-tutorial-overlay.md)
@ -131,9 +131,9 @@ networks:
bar: "2"
```
Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/index.md#ipv4_address-ipv6_address) for each attached network.
Networks can be configured with static IP addresses by setting the [ipv4_address and/or ipv6_address](compose-file/05-services.md#ipv4_address-ipv6_address) for each attached network.
Networks can also be given a [custom name](compose-file/index.md#name):
Networks can also be given a [custom name](compose-file/06-networks.md#name):
```yaml
services:
@ -165,7 +165,7 @@ networks:
## Use a pre-existing network
If you want your containers to join a pre-existing network, use the [`external` option](compose-file/index.md#external)
If you want your containers to join a pre-existing network, use the [`external` option](compose-file/06-networks.md#external)
```yaml
services:
# ...
@ -181,5 +181,5 @@ Instead of attempting to create a network called `[projectname]_default`, Compos
For full details of the network configuration options available, see the following references:
- [Top-level `networks` key](compose-file/index.md#networks-top-level-element)
- [Service-level `networks` key](compose-file/index.md#networks)
- [Top-level `networks` key](compose-file/06-networks)
- [Service-level `networks` key](compose-file/05-services.md#networks)

View File

@ -23,7 +23,7 @@ production. These changes might include:
- Binding to different ports on the host
- Setting environment variables differently, such as reducing the verbosity of
logging, or to specify settings for external services such as an email server
- Specifying a restart policy like [`restart: always`](compose-file/index.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime
- Specifying a restart policy like [`restart: always`](compose-file/05-services.md#restart){: target="_blank" rel="noopener" class="_" } to avoid downtime
- Adding extra services such as a log aggregator
For this reason, consider defining an additional Compose file, say

View File

@ -18,7 +18,7 @@ development tasks.
## Assigning profiles to services
Services are associated with profiles through the
[`profiles` attribute](compose-file/index.md#profiles) which takes an
[`profiles` attribute](compose-file/05-services.md#profiles) which takes an
array of profile names:
```yaml
@ -183,4 +183,4 @@ $ COMPOSE_PROFILES=dev docker compose up phpmyadmin
## Reference information
[`profiles`](compose-file/index.md#profiles)
[`profiles`](compose-file/05-services.md#profiles)

View File

@ -7,7 +7,7 @@ notoc: true
{% include compose-eol.md %}
You can control the order of service startup and shutdown with the
[depends_on](compose-file/index.md#depends_on) option. Compose always starts and stops
[depends_on](compose-file/05-services.md#depends_on) option. Compose always starts and stops
containers in dependency order, where dependencies are determined by
`depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`.
@ -25,6 +25,6 @@ The solution for detecting the ready state of a service is to use the `conditio
## Reference information
- [`depends_on`](compose-file/index.md#depends_on)
- [`healthcheck`](compose-file/index.md#healthcheck)
- [`depends_on`](compose-file/05-services.md#depends_on)
- [`healthcheck`](compose-file/05-services.md#depends_on)

View File

@ -245,7 +245,7 @@ volumes:
```
For more information about using volumes with Compose, refer to the
[Volumes](../compose/compose-file/index.md#volumes)
[Volumes](../compose/compose-file/07-volumes.md)
section in the Compose specification.
### Start a service with volumes