Compose: spec updates (#22655)

<!--Delete sections as needed -->

## Description

Spec updates on the new attributes released last week (plus some extra -
adds https://github.com/docker/compose/pull/12769 )

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

_vale/config/vocabularies/Docker/accept.txt

@@ -153,6 +153,7 @@ Zsh
 [Ss]warm
 [Ss]yscalls?
 [Ss]ysfs
+[Tt]eardown
 [Tt]oolchains?
 [Uu]narchived?
 [Uu]ngated

content/manuals/compose/how-tos/environment-variables/envvars.md

@@ -26,6 +26,7 @@ This page contains information on how you can set or change the following pre-de
 - `COMPOSE_ENV_FILES`
 - `COMPOSE_MENU`
 - `COMPOSE_EXPERIMENTAL`
+- `COMPOSE_PROGRESS`
 
 ## Methods to override 
 
@@ -192,6 +193,15 @@ This is an opt-out variable. When turned off it deactivates the experimental fea
    - `false` or `0`, to disable
 - Defaults to: `1`
 
+### COMPOSE\_PROGRESS
+
+{{< summary-bar feature_name="Compose progress" >}}
+
+Defines the type of progress output, if `--progress` isn't used. 
+
+Supported values are `auto`, `tty`, `plain`, `json`, and `quiet`.
+Default is `auto`. 
+
 ## Unsupported in Compose V2
 
 The following environment variables have no effect in Compose V2.

content/reference/compose-file/build.md

@@ -466,8 +466,7 @@ The long syntax provides more granularity in how the secret is created within
 the service's containers.
 
 - `source`: The name of the secret as it exists on the platform.
-- `target`: The name of the file to be mounted in `/run/secrets/` in the
-  service's task containers. Defaults to `source` if not specified.
+- `target`: The ID of the secret as declared in the Dockerfile. Defaults to `source` if not specified.
 - `uid` and `gid`: The numeric uid or gid that owns the file within
   `/run/secrets/` in the service's task containers. Default value is `USER`.
 - `mode`: The [permissions](https://wintelguy.com/permissions-calc.pl) for the file to be mounted in `/run/secrets/`
@@ -487,7 +486,7 @@ services:
       context: .
       secrets:
         - source: server-certificate
-          target: server.cert
+          target: cert # secret ID in Dockerfile
           uid: "103"
           gid: "103"
           mode: 0440
@@ -496,6 +495,12 @@ secrets:
     external: true
 ```
 
+```dockerfile
+# Dockerfile
+FROM nginx
+RUN --mount=type=secret,id=cert,required=true,target=/root/cert ...
+```
+
 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 service specification as [secrets](services.md#secrets) service element.

content/reference/compose-file/services.md

@@ -1395,9 +1395,31 @@ services:
           - mysql
 
 networks:
-  front-tier:
-  back-tier:
-  admin:
+  front-tier: {}
+  back-tier: {}
+  admin: {}
+```
+
+### `interface_name`
+
+{{< summary-bar feature_name="Compose interface-name" >}}
+
+`interface_name` lets you specify the name of the network interface used to connect a service to a given network. This ensures consistent and predictable interface naming across services and networks.
+
+```yaml
+services:
+  backend:
+    image: alpine
+    command: ip link show
+    networks:
+      back-tier:
+        interface_name: eth0
+```
+
+Running the example Compose application shows:
+
+```console
+backend-1  | 11: eth0@if64: <BROADCAST,MULTICAST,UP,LOWER_UP,M-DOWN> mtu 1500 qdisc noqueue state UP 
 ```
 
 #### `ipv4_address`, `ipv6_address`
@@ -1693,6 +1715,46 @@ services:
       - debug
 ```
 
+### `provider`
+
+{{< summary-bar feature_name="Compose provider services" >}}
+
+`provider` can be used to define a service that Compose won't manage directly. Compose delegated the service lifecycle to a dedicated or third-party component.
+
+```yaml
+  database:
+    provider:
+      type: awesomecloud
+      options:
+        type: mysql
+        foo: bar  
+  app:
+    image: myapp 
+    depends_on:
+       - database
+```
+
+As Compose runs the application, the `awesomecloud` binary is used to manage the `database` service setup. 
+Dependent service `app` receives additional environment variables prefixed by the service name so it can access the resource. 
+
+For illustration, assuming `awesomecloud` execution produced variables `URL` and `API_KEY`, the `app` service
+runs with environment variables `DATABASE_URL` and `DATABASE_API_KEY`.
+
+As Compose stops the application, the `awesomecloud` binary is used to manage the `database` service tear down.
+
+The mechanism used by Compose to delegate the service lifecycle to an external binary is described [here](https://github.com/docker/compose/tree/main/docs/extension.md).
+
+For more information on using the `provider` attribute, see [Use provider services](/manuals/compose/how-tos/provider-services.md).
+
+### `type`
+
+`type` attribute is required. It defines the external component used by Compose to manage setup and tear down lifecycle
+events.
+
+### `options`
+
+`options` are specific to the selected provider and not validated by the compose specification
+
 ### `pull_policy`
 
 `pull_policy` defines the decisions Compose makes when it starts to pull images. Possible values are:
@@ -2035,6 +2097,11 @@ The short syntax uses a single string with colon-separated values to specify a v
 > platform it rejects Compose files which use relative host paths with an error. To avoid ambiguities
 > with named volumes, relative paths should always begin with `.` or `..`.
 
+> [!NOTE]
+>
+> For bind mounts, the short syntax creates a directory at the source path on the host if it doesn't exist. This is for backward compatibility with `docker-compose` legacy. 
+> It can be prevented by using long syntax and setting `create_host_path` to `false`.
+
 #### Long syntax
 
 The long form syntax lets you configure additional fields that can't be
@@ -2048,9 +2115,7 @@ expressed in the short form.
 - `read_only`: Flag to set the volume as read-only.
 - `bind`: Used to configure additional bind options:
   - `propagation`: The propagation mode used for the bind.
-  - `create_host_path`: Creates a directory at the source path on host if there is nothing present.
-    Compose does nothing if there is something present at the path. This is automatically implied by short syntax
-    for backward compatibility with `docker-compose` legacy.
+  - `create_host_path`: Creates a directory at the source path on host if there is nothing present. Defaults to `true`.
   - `selinux`: The SELinux re-labeling option `z` (shared) or `Z` (private)
 - `volume`: Configures additional volume options:
   - `nocopy`: Flag to disable copying of data from a container when a volume is created.

data/summary.yaml

@@ -97,6 +97,8 @@ Compose gw priority:
   requires: Docker Compose [2.33.1](/manuals/compose/releases/release-notes.md#2331) and later
 Compose include:
   requires: Docker Compose [2.20.3](/manuals/compose/releases/release-notes.md#2203) and later
+Compose interface-name:
+  requires: Docker Compose [2.36.0](/manuals/compose/releases/release-notes.md#2203) and later
 Compose label file:
   requires: Docker Compose [2.32.2](/manuals/compose/releases/release-notes.md#2232) and later
 Compose lifecycle hooks:
@@ -111,6 +113,8 @@ Compose OCI artifact:
   requires: Docker Compose [2.34.0](/manuals/compose/releases/release-notes.md#2340) and later
 Compose provider services:
   requires: Docker Compose [2.36.0](/manuals/compose/releases/release-notes.md) and later
+Compose progress:
+  requires: Docker Compose [2.36.0](/manuals/compose/releases/release-notes.md) and later
 Compose replace file:
   requires: Docker Compose [2.24.4](/manuals/compose/releases/release-notes.md#2244) and later
 Compose required: