Remove "bundle" subcommand and support for DAB files

Deploying stacks using the "Docker Application Bundle" (`.dab`) file
format was introduced as an experimental feature in Docker 1.13 /
17.03, but superseded by support for Docker Compose files in the CLI.

With no development being done on this feature, and no active use of the file
format, support for the DAB file format and the top-level `docker deploy` command
(hidden by default in 19.03), will be removed from the CLI, in favour of
`docker stack deploy` using compose files.

This patch removes documentation for the `docker-compose bundle` subcommand,
which was used to convert compose files into DAB files (and given the above,
will no longer be needed).

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2019-12-07 01:01:38 +01:00
parent 5586e5e0da
commit d4ead1b120
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
11 changed files with 7 additions and 417 deletions

View File

@ -10,7 +10,6 @@ cname:
- docker context
- docker cp
- docker create
- docker deploy
- docker diff
- docker engine
- docker events
@ -70,7 +69,6 @@ clink:
- docker_context.yaml
- docker_cp.yaml
- docker_create.yaml
- docker_deploy.yaml
- docker_diff.yaml
- docker_engine.yaml
- docker_events.yaml

View File

@ -1,134 +0,0 @@
command: docker deploy
short: Deploy a new stack or update an existing stack
long: |-
Create and update a stack from a `compose` or a `dab` file on the swarm. This command
has to be run targeting a manager node.
usage: docker deploy [OPTIONS] STACK
pname: docker
plink: docker.yaml
options:
- option: bundle-file
value_type: string
description: Path to a Distributed Application Bundle file
deprecated: false
experimental: true
experimentalcli: false
kubernetes: false
swarm: true
- option: compose-file
shorthand: c
value_type: stringSlice
default_value: '[]'
description: Path to a Compose file, or "-" to read from stdin
deprecated: false
min_api_version: "1.25"
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: namespace
value_type: string
description: Kubernetes namespace to use
deprecated: false
experimental: false
experimentalcli: false
kubernetes: true
swarm: false
- option: prune
value_type: bool
default_value: "false"
description: Prune services that are no longer referenced
deprecated: false
min_api_version: "1.27"
experimental: false
experimentalcli: false
kubernetes: false
swarm: true
- option: resolve-image
value_type: string
default_value: always
description: |
Query the registry to resolve image digest and supported platforms ("always"|"changed"|"never")
deprecated: false
min_api_version: "1.30"
experimental: false
experimentalcli: false
kubernetes: false
swarm: true
- option: with-registry-auth
value_type: bool
default_value: "false"
description: Send registry authentication details to Swarm agents
deprecated: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: true
examples: |-
### Compose file
The `deploy` command supports compose file version `3.0` and above.
```bash
$ docker stack deploy --compose-file docker-compose.yml vossibility
Ignoring unsupported options: links
Creating network vossibility_vossibility
Creating network vossibility_default
Creating service vossibility_nsqd
Creating service vossibility_logstash
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_ghollector
Creating service vossibility_lookupd
```
You can verify that the services were correctly created
```bash
$ docker service ls
ID NAME MODE REPLICAS IMAGE
29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa
7563uuzr9eys vossibility_kibana replicated 1/1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03
9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe
axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
```
### DAB file
```bash
$ docker stack deploy --bundle-file vossibility-stack.dab vossibility
Loading bundle from vossibility-stack.dab
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_logstash
Creating service vossibility_lookupd
Creating service vossibility_nsqd
Creating service vossibility_vossibility-collector
```
You can verify that the services were correctly created:
```bash
$ docker service ls
ID NAME MODE REPLICAS IMAGE
29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa
7563uuzr9eys vossibility_kibana replicated 1/1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03
9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe
axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
```
deprecated: false
min_api_version: "1.25"
experimental: true
experimentalcli: false
kubernetes: false
swarm: false

View File

@ -2,20 +2,12 @@ command: docker stack deploy
aliases: up
short: Deploy a new stack or update an existing stack
long: |-
Create and update a stack from a `compose` or a `dab` file on the swarm. This command
has to be run targeting a manager node.
Create and update a stack from a `compose` file on the swarm. This command has to
be run targeting a manager node.
usage: docker stack deploy [OPTIONS] STACK
pname: docker stack
plink: docker_stack.yaml
options:
- option: bundle-file
value_type: string
description: Path to a Distributed Application Bundle file
deprecated: false
experimental: true
experimentalcli: false
kubernetes: false
swarm: true
- option: compose-file
shorthand: c
value_type: stringSlice
@ -151,34 +143,6 @@ examples: |-
9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe
axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
```
### DAB file
```bash
$ docker stack deploy --bundle-file vossibility-stack.dab vossibility
Loading bundle from vossibility-stack.dab
Creating service vossibility_elasticsearch
Creating service vossibility_kibana
Creating service vossibility_logstash
Creating service vossibility_lookupd
Creating service vossibility_nsqd
Creating service vossibility_vossibility-collector
```
You can verify that the services were correctly created:
```bash
$ docker service ls
ID NAME MODE REPLICAS IMAGE
29bv0vnlm903 vossibility_lookupd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4awt47624qwh vossibility_nsqd replicated 1/1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662
4tjx9biia6fs vossibility_elasticsearch replicated 1/1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa
7563uuzr9eys vossibility_kibana replicated 1/1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03
9gc5m4met4he vossibility_logstash replicated 1/1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe
axqh55ipl40h vossibility_vossibility-collector replicated 1/1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba
```
deprecated: false
min_api_version: "1.25"
experimental: false

View File

@ -913,8 +913,6 @@ reference:
title: Command-line completion
- path: /compose/reference/build/
title: build
- path: /compose/reference/bundle/
title: bundle
- path: /compose/reference/config/
title: config
- path: /compose/reference/create/
@ -1145,8 +1143,6 @@ manuals:
title: Install Compose
- path: /compose/gettingstarted/
title: Getting started
- path: /compose/bundles/
title: Docker stacks and distributed application bundles
- path: /compose/swarm/
title: Using Compose with Swarm
- path: /compose/env-file/

View File

@ -1,211 +0,0 @@
---
advisory: experimental
description: Description of Docker and Compose's experimental support for application bundles
keywords: documentation, docs, docker, compose, bundles, stacks
title: Docker stacks and distributed application bundles (experimental)
---
> **Note**: This is a modified copy of the [Docker Stacks and Distributed Application
> Bundles](https://github.com/moby/moby/blob/v1.12.0-rc4/experimental/docker-stacks-and-bundles.md)
> document in the [docker/docker-ce repo](https://github.com/docker/docker-ce). It's been updated to accurately reflect newer releases.
## Overview
A Dockerfile can be built into an image, and containers can be created from
that image. Similarly, a `docker-compose.yml` can be built into a **distributed
application bundle**, and **stacks** can be created from that bundle. In that
sense, the bundle is a multi-services distributable image format.
Docker Stacks and Distributed Application Bundles started as experimental
features introduced in Docker 1.12 and Docker Compose 1.8, alongside the concept
of swarm mode, and nodes and services in the Engine API. Neither Docker Engine
nor the Docker Registry support distribution of bundles, and the concept of a
`bundle` is not the emphasis for new releases going forward.
However, [swarm mode](/engine/swarm/index.md), multi-service applications, and
stack files now are fully supported. A stack file is a particular type of
[version 3 Compose file](/compose/compose-file/index.md).
## Produce a bundle
The easiest way to produce a bundle is to generate it using `docker-compose`
from an existing `docker-compose.yml`. Of course, that's just *one* possible way
to proceed, in the same way that `docker build` isn't the only way to produce a
Docker image.
From `docker-compose`:
```bash
$ docker-compose bundle
WARNING: Unsupported key 'network_mode' in services.nsqd - ignoring
WARNING: Unsupported key 'links' in services.nsqd - ignoring
WARNING: Unsupported key 'volumes' in services.nsqd - ignoring
[...]
Wrote bundle to vossibility-stack.dab
```
## Create a stack from a bundle
> **Note**: Because support for stacks and bundles is in the experimental stage,
> you need to install an experimental build of Docker Engine to use it.
>
> If you're on Mac or Windows, download the “Beta channel” version of
> [Docker Desktop for Mac](/docker-for-mac/) or
> [Docker Desktop for Windows](/docker-for-windows/) to install
> it. If you're on Linux, follow the instructions in the
> [experimental build README](https://github.com/docker/cli/blob/master/experimental/README.md).
A stack is created using the `docker deploy` command:
```bash
# docker deploy --help
Usage: docker deploy [OPTIONS] STACK
Create and update a stack
Options:
--file string Path to a Distributed Application Bundle file (Default: STACK.dab)
--help Print usage
--with-registry-auth Send registry authentication details to Swarm agents
```
Let's deploy the stack created before:
```bash
# docker deploy vossibility-stack
Loading bundle from vossibility-stack.dab
Creating service vossibility-stack_elasticsearch
Creating service vossibility-stack_kibana
Creating service vossibility-stack_logstash
Creating service vossibility-stack_lookupd
Creating service vossibility-stack_nsqd
Creating service vossibility-stack_vossibility-collector
```
We can verify that services were correctly created:
```bash
# docker service ls
ID NAME REPLICAS IMAGE
COMMAND
29bv0vnlm903 vossibility-stack_lookupd 1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 /nsqlookupd
4awt47624qwh vossibility-stack_nsqd 1 nsqio/nsq@sha256:eeba05599f31eba418e96e71e0984c3dc96963ceb66924dd37a47bf7ce18a662 /nsqd --data-path=/data --lookupd-tcp-address=lookupd:4160
4tjx9biia6fs vossibility-stack_elasticsearch 1 elasticsearch@sha256:12ac7c6af55d001f71800b83ba91a04f716e58d82e748fa6e5a7359eed2301aa
7563uuzr9eys vossibility-stack_kibana 1 kibana@sha256:6995a2d25709a62694a937b8a529ff36da92ebee74bafd7bf00e6caf6db2eb03
9gc5m4met4he vossibility-stack_logstash 1 logstash@sha256:2dc8bddd1bb4a5a34e8ebaf73749f6413c101b2edef6617f2f7713926d2141fe logstash -f /etc/logstash/conf.d/logstash.conf
axqh55ipl40h vossibility-stack_vossibility-collector 1 icecrime/vossibility-collector@sha256:f03f2977203ba6253988c18d04061c5ec7aab46bca9dfd89a9a1fa4500989fba --config /config/config.toml --debug
```
## Manage stacks
Stacks are managed using the `docker stack` command:
```bash
# docker stack --help
Usage: docker stack COMMAND
Manage Docker stacks
Options:
--help Print usage
Commands:
config Print the stack configuration
deploy Create and update a stack
rm Remove the stack
services List the services in the stack
tasks List the tasks in the stack
Run 'docker stack COMMAND --help' for more information on a command.
```
## Bundle file format
Distributed application bundles are described in a JSON format. When bundles
are persisted as files, the file extension is `.dab`.
A bundle has two top-level fields: `version` and `services`. The version used
by Docker 1.12 tools is `0.1`.
`services` in the bundle are the services that comprise the app. They
correspond to the new `Service` object introduced in the 1.12 Docker Engine API.
A service has the following fields:
<dl>
<dt>
Image (required) <code>string</code>
</dt>
<dd>
The image that the service runs. Docker images should be referenced
with full content hash to fully specify the deployment artifact for the
service. Example:
<code>postgres@sha256:e0a230a9f5b4e1b8b03bb3e8cf7322b0e42b7838c5c87f4545edb48f5eb8f077</code>
</dd>
<dt>
Command <code>[]string</code>
</dt>
<dd>
Command to run in service containers.
</dd>
<dt>
Args <code>[]string</code>
</dt>
<dd>
Arguments passed to the service containers.
</dd>
<dt>
Env <code>[]string</code>
</dt>
<dd>
Environment variables.
</dd>
<dt>
Labels <code>map[string]string</code>
</dt>
<dd>
Labels used for setting meta data on services.
</dd>
<dt>
Ports <code>[]Port</code>
</dt>
<dd>
Service ports (composed of <code>Port</code> (<code>int</code>) and
<code>Protocol</code> (<code>string</code>). A service description can
only specify the container port to be exposed. These ports can be
mapped on runtime hosts at the operator's discretion.
</dd>
<dt>
WorkingDir <code>string</code>
</dt>
<dd>
Working directory inside the service containers.
</dd>
<dt>
User <code>string</code>
</dt>
<dd>
Username or UID (format: <code>&lt;name|uid&gt;[:&lt;group|gid&gt;]</code>).
</dd>
<dt>
Networks <code>[]string</code>
</dt>
<dd>
Networks that the service containers should be connected to. An entity
deploying a bundle should create networks as needed.
</dd>
</dl>
> **Note**: Some configuration options are not yet supported in the DAB format,
> including volume mounts.
## Related topics
* [docker stack deploy](/engine/reference/commandline/stack_deploy/) command
* [deploy](/compose/compose-file/index.md#deploy) option in [Compose files](/compose/compose-file/index.md)

View File

@ -1,25 +0,0 @@
---
description: Create a distributed application bundle from the Compose file.
keywords: fig, composition, compose, docker, orchestration, cli, bundle
title: docker-compose bundle
notoc: true
---
```
Usage: bundle [options]
Options:
--push-images Automatically push images for any services
which have a `build` option specified.
-o, --output PATH Path to write the bundle file to.
Defaults to "<project name>.dab".
```
Generate a Distributed Application Bundle (DAB) from the Compose file.
Images must have digests stored, which requires interaction with a
Docker registry. If digests aren't stored for all images, you can fetch
them with `docker-compose pull` or `docker-compose push`. To push images
automatically when bundling, pass `--push-images`. Only services with
a `build` option specified have their images pushed.

View File

@ -3,6 +3,8 @@ description: Config validates and view the compose file.
keywords: fig, composition, compose, docker, orchestration, cli, config
title: docker-compose config
notoc: true
redirect_from:
- /compose/reference/bundle/
---
```

View File

@ -9,7 +9,6 @@ The following pages describe the usage information for the [docker-compose](over
* [docker-compose](overview.md)
* [build](build.md)
* [bundle](bundle.md)
* [config](config.md)
* [create](create.md)
* [down](down.md)

View File

@ -172,7 +172,7 @@ the docker command is automatically executed.
### Docker Stack deployment
To deploy complex multi-container apps, you can use the `docker stack deploy` command. You can either deploy a bundle on your machine over an SSH tunnel, or copy the `docker-compose.yml` file to a manager node via `scp` for example. You can then SSH into the manager node and run `docker stack deploy` with the `--compose-file` or `-c` option. See [docker stack deploy options](/engine/reference/commandline/stack_deploy/#options) for the list of different options. If you have multiple manager nodes, make sure you are logged in to the one with the stack file copy.
To deploy complex multi-container apps, you can use the `docker stack deploy` command. You can either deploy a docker compose file on your machine over an SSH tunnel, or copy the `docker-compose.yml` file to a manager node via `scp` for example. You can then SSH into the manager node and run `docker stack deploy` with the `--compose-file` or `-c` option. See [docker stack deploy options](/engine/reference/commandline/stack_deploy/#options) for the list of different options. If you have multiple manager nodes, make sure you are logged in to the one with the stack file copy.
For example:

View File

@ -149,7 +149,7 @@ This tool internally makes use of docker global-mode service that runs a task on
### Docker Stack deployment
To deploy complex multi-container apps, you can use the docker stack deploy command. You can either deploy a bundle on your machine over an SSH tunnel, or copy the docker-compose.yml file to a manager node via scp for example. You can then SSH into the manager node and run docker stack deploy with the --compose-file or -c option. See docker stack deploy options for the list of different options. If you have multiple manager nodes, make sure you are logged in to the one with the stack file copy.
To deploy complex multi-container apps, you can use the docker stack deploy command. You can either deploy a compose file on your machine over an SSH tunnel, or copy the docker-compose.yml file to a manager node via scp for example. You can then SSH into the manager node and run docker stack deploy with the --compose-file or -c option. See docker stack deploy options for the list of different options. If you have multiple manager nodes, make sure you are logged in to the one with the stack file copy.
For example:

View File

@ -3,6 +3,7 @@ datafolder: engine-cli
datafile: docker_stack_deploy
title: docker stack deploy
redirect_from:
- /compose/bundles/
- /edge/engine/reference/commandline/stack_deploy/
skip_read_time: true
---