docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1876 from moxiegirl/carry-and-close-1836 

Add commands reference to the Swarm documentation
This commit is contained in:
moxiegirl 2016-02-24 09:21:07 -08:00
parent a839ebdd06 e8fad3d657
commit 638709a2d7
7 changed files with 523 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
docs/reference/create.md Normal file
View File

@ -0,0 +1,25 @@
<!--[metadata]>
+++
title = "create"
description = "Create a Swarm manager."
keywords = ["swarm, create"]
[menu.main]
identifier="swarm.create"
parent="smn_swarm_subcmds"
+++
<![end-metadata]-->
# create — Create a discovery token
The `create` command uses Docker Hub's hosted discovery backend to create a unique *discovery token* for your cluster. For example:
$ docker run --rm swarm create
86222732d62b6868d441d430aee4f055
Later, when you use [`manage`](manage.md) or [`join`](join.md) to create Swarm managers and nodes, you use the discovery token in the `<discovery>` argument (e.g., `token://86222732d62b6868d441d430aee4f055`). The discovery backend registers each new Swarm manager and node that uses the token as a member of your cluster.
Some documentation also refers to the discovery token as a *cluster_id*.
> Warning: Docker Hub's hosted discovery backend is not recommended for production use. It’s intended only for testing/development.
For more information and examples about this and other discovery backends, see the [Docker Swarm Discovery](../discovery.md) topic.

42
docs/reference/help.md Normal file
View File

@ -0,0 +1,42 @@
<!--[metadata]>
+++
title = "help"
description = "Get help for Swarm commands."
keywords = ["swarm, help"]
[menu.main]
identifier="swarm.help"
parent="smn_swarm_subcmds"
+++
<![end-metadata]-->
# help - Display information about a command
The `help` command displays information about how to use a command.
For example, to see a list of Swarm options and commands, enter:
$ docker run swarm --help
To see a list of arguments and options for a specific Swarm command, enter:
$ docker run swarm <command> --help
For example:
$ docker run swarm list --help
Usage: swarm list [OPTIONS] <discovery>
List nodes in a cluster
Arguments:
<discovery> discovery service to use [$SWARM_DISCOVERY]
* token://<token>
* consul://<ip>/<path>
* etcd://<ip1>,<ip2>/<path>
* file://path/to/file
* zk://<ip1>,<ip2>/<path>
* [nodes://]<ip1>,<ip2>
Options:
--timeout "10s" timeout period
--discovery-opt [--discovery-opt option --discovery-opt option] discovery options

20
docs/reference/index.md Normal file
View File

@ -0,0 +1,20 @@
<!--[metadata]>
+++
title = "Command line reference"
description = "Docker Swarm Commands Overview"
keywords = ["Swarm, cluster, commands"]
[menu.main]
identifier="smn_swarm_subcmds"
parent="workw_swarm"
weight=80
+++
<![end-metadata]-->
# Docker Swarm command line reference
- [swarm](swarm.md) — Run a Swarm container on Docker Engine
- [create](create.md) — Create a discovery token
- [list](list.md) — List the nodes in a Docker cluster
- [manage](manage.md) — Create a Swarm manager
- [join](join.md) — Create a Swarm node
- [help](help.md) — See a list of Swarm commands, or help for one command

96
docs/reference/join.md Normal file
View File

@ -0,0 +1,96 @@
<!--[metadata]>
+++
title = "join"
description = "Create a Swarm node."
keywords = ["swarm, create, join"]
[menu.main]
identifier="swarm.join"
parent="smn_swarm_subcmds"
+++
<![end-metadata]-->
# join — Create a Swarm node
Prerequisite: Before using `join`, establish a discovery backend as described in [this discovery topic](../discovery.md).
The `join` command creates a Swarm node whose purpose is to run containers on behalf of the cluster. A typical cluster has multiple Swarm nodes.
To create a Swarm node, use the following syntax:
$ docker run swarm join [OPTIONS] <discovery>
For example, to create a Swarm node in a high-availability cluster with other managers, enter:
$ docker run -d swarm join --advertise=172.30.0.69:2375 consul://172.30.0.161:8500
Or, for example, to create a Swarm node that uses Transport Layer Security (TLS) to authenticate the Docker Swarm nodes, enter:
$ sudo docker run -d swarm join --addr=node1:2376 token://86222732d62b6868d441d430aee4f055
## Arguments
The `join` command has only one argument:
### `<discovery>` — Discovery backend
Before you create a Swarm node, [create a discovery token](create.md) or [set up a discovery backend](../discovery.md) for your cluster.
When you create the swarm node, use the `<discovery>` argument to specify one of the following discovery backends:
* `token://<token>`
* `consul://<ip1>/<path>`
* `etcd://<ip1>,<ip2>,<ip2>/<path>`
* `file://<path/to/file>`
* `zk://<ip1>,<ip2>/<path>`
* `[nodes://]<iprange>,<iprange>`
Where:
* `<token>` is a discovery token generated by Docker Hub's hosted discovery service. To generate this discovery token, use the [`create`](create.md) command.
> Warning: Docker Hub's hosted discovery backend is not recommended for production use. It’s intended only for testing/development.
* `ip1`, `ip2`, `ip3` are each the IP address and port numbers of a discovery backend node.
* `path` (optional) is a path to a key-value store on the discovery backend. When you use a single backend to service multiple clusters, you use paths to maintain separate key-value stores for each cluster.
* `path/to/file` is the path to a file that contains a static list of the Swarm managers and nodes that are members the cluster. <!--tbd - can the file contain ipranges?-->
* `iprange` is an IP address or a range of IP addresses followed by a port number.
For example:
* A discovery token: `token://0ac50ef75c9739f5bfeeaf00503d4e6e`
* A Consul node: `consul://172.30.0.165:8500`
The environment variable for `<discovery>` is `$SWARM_DISCOVERY`.
For more information and examples, see the [Docker Swarm Discovery](../discovery.md) topic.
## Options
The `join` command has the following options:
### `--advertise` or `--addr` — Advertise the Docker Engine's IP and port number
Use `--advertise <ip>:<port>` or `--addr <ip>:<port>` to advertise the IP address and port number of the Docker Engine. For example, `--advertise 172.30.0.161:4000`. Swarm managers MUST be able to reach this Swarm node at this address.
The environment variable for `--advertise` is `$SWARM_ADVERTISE`.
### `--heartbeat` — Period between each heartbeat
Use `--heartbeat "<interval>s"` to specify the interval, in seconds, between heartbeats the node sends to the primary manager. These heartbeats indicate that the node is healthy and reachable. By default, the interval is 60 seconds.
### `--ttl` — Sets the expiration of an ephemeral node
Use `--ttl "<interval>s"` to specify the time-to-live (TTL) interval, in seconds, of an ephemeral node. The default interval is `180s`. <!-- tbd - Define ephemeral node. Explain what triggers the ttl countdown. -->
### `--delay` — Add a random delay in [0s,delay] to avoid synchronized registration
Use `--delay "<interval>s"` to specify the maximum interval for a random delay, in seconds, before the node registers with the discovery backend. If you deploy a large number of nodes simultaneously, the random delay spreads registrations out over the interval and avoids saturating the discovery backend.
### `--discovery-opt` — Discovery options
Use `--discovery-opt <value>` to discovery options, such as paths to the TLS files; the CA's public key certificate, the certificate, and the private key of the distributed K/V store on a Consul or etcd discovery backend. You can enter multiple discovery options. For example:
--discovery-opt kv.cacertfile=/path/to/mycacert.pem \
--discovery-opt kv.certfile=/path/to/mycert.pem \
--discovery-opt kv.keyfile=/path/to/mykey.pem \
For more information, see [Use TLS with distributed key/value discovery](../discovery.md)

86
docs/reference/list.md Normal file
View File

@ -0,0 +1,86 @@
<!--[metadata]>
+++
title = "list"
description = "List the nodes in a cluster."
keywords = ["swarm, list"]
[menu.main]
identifier="swarm.list"
parent="smn_swarm_subcmds"
+++
<![end-metadata]-->
# list — List the nodes in a cluster
Use `list` to display a list of the nodes in a cluster.
To list the nodes in a cluster, use the following syntax:
docker run swarm list [OPTIONS] <discovery>
The following examples show a few different syntaxes for the `<discovery>` argument:
etcd:
swarm list etcd://<etcd_addr1>,<etcd_addr2>/<optional path prefix> <node_ip:port>
Consul:
swarm list consul://<consul_addr>/<optional path prefix> <node_ip:port>
ZooKeeper:
swarm list zk://<zookeeper_addr1>,<zookeeper_addr2>/<optional path prefix> <node_ip:port>
<!--tbd - show and explain the output from a real example-->
## Arguments
The `list` command has only one argument:
### `<discovery>` — Discovery backend
When you use the `list` command, use the `<discovery>` argument to specify one of the following discovery backends:
* `token://<token>`
* `consul://<ip1>/<path>`
* `etcd://<ip1>,<ip2>,<ip2>/<path>`
* `file://<path/to/file>`
* `zk://<ip1>,<ip2>/<path>`
* `[nodes://]<iprange>,<iprange>`
Where:
* `<token>` is a discovery token generated by Docker Hub's hosted discovery service. To generate this discovery token, use the [`create`](create.md) command.
> Warning: Docker Hub's hosted discovery backend is not recommended for production use. It’s intended only for testing/development.
* `ip1`, `ip2`, `ip3` are each the IP address and port numbers of a discovery backend node.
* `path` (optional) is a path to a key-value store on the discovery backend. When you use a single backend to service multiple clusters, you use paths to maintain separate key-value stores for each cluster.
* `path/to/file` is the path to a file that contains a static list of the Swarm managers and nodes that are members the cluster. <!--tbd - can the file contain ipranges?-->
* `iprange` is an IP address or a range of IP addresses followed by a port number.
For example:
* A discovery token: `token://0ac50ef75c9739f5bfeeaf00503d4e6e`
* A Consul node: `consul://172.30.0.165:8500`
The environment variable for `<discovery>` is `$SWARM_DISCOVERY`.
For more information and examples, see the [Docker Swarm Discovery](../discovery.md) topic.
## Options
The `list` command has the following options:
### `--timeout` — Timeout period
Use `--timeout "<interval>s"` to specify the timeout period, in seconds, to wait for the discovery backend to return the list. The default interval is `10s`.
### `--discovery-opt` — Discovery options
Use `--discovery-opt <value>` to discovery options, such as paths to the TLS files; the CA's public key certificate, the certificate, and the private key of the distributed K/V store on a Consul or etcd discovery backend. You can enter multiple discovery options. For example:
--discovery-opt kv.cacertfile=/path/to/mycacert.pem \
--discovery-opt kv.certfile=/path/to/mycert.pem \
--discovery-opt kv.keyfile=/path/to/mykey.pem \
For more information, see [Use TLS with distributed key/value discovery](../discovery.md)

208
docs/reference/manage.md Normal file
View File

@ -0,0 +1,208 @@
<!--[metadata]>
+++
title = "manage"
description = "Create a Swarm manager."
keywords = ["swarm, create, manage"]
[menu.main]
identifier="swarm.manage"
parent="smn_swarm_subcmds"
+++
<![end-metadata]-->
# manage — Create a Swarm manager
Prerequisite: Before using `manage` to create a Swarm manager, establish a discovery backend as described in [this discovery topic](../discovery.md).
The `manage` command creates a Swarm manager whose purpose is to receive commands on behalf of the cluster and assign containers to Swarm nodes. You can create multiple Swarm managers as part of a high-availability cluster.
To create a Swarm manager, use the following syntax:
$ docker run swarm manage [OPTIONS] <discovery>
For example, you can use `manage` to create a Swarm manager in a high-availability cluster with other managers:
$ docker run -d -p 4000:4000 swarm manage -H :4000 --replication --advertise 172.30.0.161:4000 consul://172.30.0.165:8500
Or, for example, you can use it to create a Swarm manager that uses Transport Layer Security (TLS) to authenticate the Docker Client and Swarm nodes:
$ docker run -d -p 3376:3376 -v /home/ubuntu/.certs:/certs:ro swarm manage --tlsverify --tlscacert=/certs/ca.pem --tlscert=/certs/cert.pem --tlskey=/certs/key.pem --host=0.0.0.0:3376 token://$TOKEN
## Argument
The `manage` command has only one argument:
### `<discovery>` — Discovery backend
Before you create a Swarm manager, [create a discovery token](create.md) or [set up a discovery backend](../discovery.md) for your cluster.
When you create the swarm node, use the `<discovery>` argument to specify one of the following discovery backends:
* `token://<token>`
* `consul://<ip1>/<path>`
* `etcd://<ip1>,<ip2>,<ip2>/<path>`
* `file://<path/to/file>`
* `zk://<ip1>,<ip2>/<path>`
* `[nodes://]<iprange>,<iprange>`
Where:
* `<token>` is a discovery token generated by Docker Hub's hosted discovery service. To generate this discovery token, use the [`create`](create.md) command.
> Warning: Docker Hub's hosted discovery backend is not recommended for production use. It’s intended only for testing/development.
* `ip1`, `ip2`, `ip3` are each the IP address and port numbers of a discovery backend node.
* `path` (optional) is a path to a key-value store on the discovery backend. When you use a single backend to service multiple clusters, you use paths to maintain separate key-value stores for each cluster.
* `path/to/file` is the path to a file that contains a static list of the Swarm managers and nodes that are members the cluster. <!--tbd - can the file contain ipranges?-->
* `iprange` is an IP address or a range of IP addresses followed by a port number.
Here are a pair of `<discovery>` argument examples:
* A discovery token: `token://0ac50ef75c9739f5bfeeaf00503d4e6e`
* A Consul node: `consul://172.30.0.165:8500`
The environment variable for `<discovery>` is `$SWARM_DISCOVERY`.
For more information and examples, see the [Docker Swarm Discovery](../discovery.md) topic.
## Options
The `manage` command has the following options:
### `--strategy` — Scheduler placement strategy
Use `--strategy "<value>"` to tell the Docker Swarm scheduler which placement strategy to use.
Where `<value>` is:
* `spread` — Assign each container to the Swarm node with the most available resources.
* `binpack` - Assign containers to one Swarm node until it is full before assigning them to another one.
* `random` - Assign each container to a random Swarm node.
By default, the scheduler applies the `spread` strategy.
For more information and examples, see [Docker Swarm strategies](../scheduler/strategy.md).
### `--filter`, `-f` — Scheduler filter
Use `--filter <value>` or `-f <value>` to tell the Docker Swarm scheduler which nodes to use when creating and running a container.
Where `<value>` is:
* `health` — Use nodes that are running and communicating with the discovery backend.
* `port` — For containers that have a static port mapping, use nodes whose corresponding port number is available (i.e., not occupied by another container or process).
* `dependency` — For containers that have a declared dependency, use nodes that already have a container with the same dependency.
* `affinity` — For containers that have a declared affinity, use nodes that already have a container with the same affinity.
* `constraint` — For containers that have a declared constraint, use nodes that already have a container with the same constraint.
You can use multiple scheduler filters, like this:
`--filter <value> --filter <value>`
For more information and examples, see [Swarm filters](../scheduler/filter.md).
### `--host`, `-H` — Listen to IP/port
Use `--host <ip>:<port>` or `-H <ip>:<port>` to specify the IP address and port number to which the manager listens for incoming messages. If you replace `<ip>` with zeros or omit it altogether, the manager uses the default host IP. For example, `--host=0.0.0.0:3376` or `-H :4000`.
The environment variable for `--host` is `$SWARM_HOST`.
<!--tbd - Provide more information and examples of using environment variables.-->
<!--tbd - What happens if you omit the port number?-->
### `--replication` — Enable Swarm manager replication
Enable Swarm manager replication between the *primary* and *secondary* managers in a high-availability cluster. Replication mirrors cluster information from the primary to the secondary managers so that, if the primary manager fails, a secondary can become the primary manager.
### `--replication-ttl` — Leader lock release time on failure
Use `--replication-ttl "<delay>s"` to specify the delay, in seconds, before notifying secondary managers that the primary manager is down or unreachable. This notification triggers an election in which one of the secondary managers becomes the primary manager. By default, the delay is 15 seconds.
### `--advertise`, `--addr` — Advertise Docker Engine's IP and port number
Use `--advertise <ip>:<port>` or `--addr <ip>:<port>` to advertise the IP address and port number of the Docker Engine. For example, `--advertise 172.30.0.161:4000`. Other swarm managers MUST be able to reach this swarm manager at this address.
The environment variable for `--advertise` is `$SWARM_ADVERTISE`.
### `--tls` — Enable transport layer security (TLS)
Use `--tls` to enable transport layer security (TLS). If you use `--tlsverify`, you do not need to use `--tls`.
### `--tlscacert` — Path to a CA's public key file
Use `--tlscacert=<path/file>` to specify the path and filename of the public key (certificate) from a Certificate Authority (CA). For example, `--tlscacert=/certs/ca.pem`. When specified, the manager trusts only remotes that provide a certificate signed by the same CA.
### `--tlscert` — Path to the node's TLS certificate file
Use `--tlscert` to specify the path and filename of the manager's certificate (signed by the CA). For example, `--tlscert=/certs/cert.pem`.
### `--tlskey` — Path to the node's TLS key file
Use `--tlskey` to specify the path and filename of the manager's private key (signed by the CA). For example, `--tlskey=/certs/key.pem`.
### `--tlsverify` — Use TLS and verify the remote
Use `--tlsverify` to enable transport layer security (TLS) and accept connections from only those managers, nodes, and clients that have a certificate signed by the same CA. If you use `--tlsverify`, you do not need to use `--tls`.
### `--engine-refresh-min-interval` — Set engine refresh minimum interval
Use `--engine-refresh-min-interval "<interval>s"` to specify the minimum interval, in seconds, between Engine refreshes. By default, the interval is 30 seconds.
> When the primary manager in performs an *Engine refresh*, it gets updated information about an Engine in the cluster. The manager uses this information to, among other things, determine whether the Engine is *healthy*. If there is a connection failure, the manager determines that the node is *unhealthy*. The manager *retries* an Engine refresh a specified number of times. If the Engine responds to one of the retries, the manager determines that the Engine is healthy again. Otherwise, the manager stops retrying and ignores the Engine. <!--TBD - Use this note as the basis for a new topic called something like "Node Lifecycle". Then replace this note with a link to that topic.-->
### `--engine-refresh-max-interval` — Set engine refresh maximum interval
Use `--engine-refresh-max-interval "<interval>s"` to specify the minimum interval, in seconds, between Engine refresh. By default, the interval is 60 seconds.
### `--engine-failure-retry` — Set engine failure retry count
Use `--engine-failure-retry "<number>"` to specify the number of retries to attempt if the engine fails. By default, the number is 3 retries.
### `--engine-refresh-retry` — Deprecated
Deprecated; Use `--engine-failure-retry` instead of `--engine-refresh-retry "<number>"`. The default number is 3 retries.
### `--heartbeat` — Period between each heartbeat
Use `--heartbeat "<interval>s"` to specify the interval, in seconds, between heartbeats the manager sends to the primary manager. These heartbeats indicate that the manager is healthy and reachable. By default, the interval is 60 seconds.
### `--api-enable-cors`, `--cors` — Enable CORS headers in the remote API
Use `--api-enable-cors` or `--cors` to enable cross-origin resource sharing (CORS) headers in the remote API.
### `--cluster-driver`, `-c` — Cluster driver to use
Use `--cluster-driver "<driver>"`, `-c "<driver>"` to specify a cluster driver to use. Where `<driver>` is one of the following:
* `swarm` is the Docker Swarm driver.
* `mesos-experimental` is the Mesos cluster driver.
By default, the driver is `swarm`.
For more information about using Mesos driver, see [Using Docker Swarm and Mesos](https://github.com/docker/swarm/blob/master/cluster/mesos/README.md).
### `--cluster-opt` — Cluster driver options
You can enter multiple cluster driver options, like this:
`--cluster-opt <value> --cluster-opt <value>`
Where `<value>` is one of the following:
* `swarm.overcommit=0.05` — Set the fractional percentage by which to overcommit resources. The default value is `0.05`, or 5 percent.
* `swarm.createretry=0` — Specify the number of retries to attempt when creating a container fails. The default value is `0` retries.
* `mesos.address=` — Specify the Mesos address to bind on. The environment variable for this option is `$SWARM_MESOS_ADDRESS`.
* `mesos.checkpointfailover=false` — Enable Mesos checkpointing, which allows a restarted slave to reconnect with old executors and recover status updates, at the cost of disk I/O. The environment variable for this option is `$SWARM_MESOS_CHECKPOINT_FAILOVER`. The default value is `false` (disabled).
* `mesos.port=` — Specify the Mesos port to bind on. The environment variable for this option is `$SWARM_MESOS_PORT`.
* `mesos.offertimeout=30s` — Specify the Mesos timeout for offers, in seconds. The environment variable for this option is `$SWARM_MESOS_OFFER_TIMEOUT`. The default value is `30s`.
* `mesos.offerrefusetimeout=5s` — Specify timeout for Mesos to consider unused resources refused, in seconds. The environment variable for this option is `$SWARM_MESOS_OFFER_REFUSE_TIMEOUT`. The default value is `5s`.
* `mesos.tasktimeout=5s` — Specify the timeout for Mesos task creation, in seconds. The environment variable for this option is `$SWARM_MESOS_TASK_TIMEOUT`. The default value is `5s`.
* `mesos.user=` — Specify the Mesos framework user name. The environment variable for this option is `$SWARM_MESOS_USER`.
### `--discovery-opt` — Discovery options
Use `--discovery-opt <value>` to discovery options, such as paths to the TLS files; the CA's public key certificate, the certificate, and the private key of the distributed K/V store on a Consul or etcd discovery backend. You can enter multiple discovery options. For example:
--discovery-opt kv.cacertfile=/path/to/mycacert.pem \
--discovery-opt kv.certfile=/path/to/mycert.pem \
--discovery-opt kv.keyfile=/path/to/mykey.pem \
For more information, see [Use TLS with distributed key/value discovery](../discovery.md)

46
docs/reference/swarm.md Normal file
View File

@ -0,0 +1,46 @@
<!--[metadata]>
+++
title = "swarm"
description = "swarm command overview"
keywords = ["Swarm, cluster, commands"]
[menu.main]
identifier="swarm.swarm"
parent="smn_swarm_subcmds"
+++
<![end-metadata]-->
# Swarm — A Docker-native clustering system
The `swarm` command runs a Swarm container on a Docker Engine host and performs the task specified by the required subcommand, `COMMAND`.
Use `swarm` with the following syntax:
$ docker run swarm [OPTIONS] COMMAND [arg...]
For example, you use `swarm` with the `manage` subcommand to create a Swarm manager in a high-availability cluster with other managers:
$ docker run -d -p 4000:4000 swarm manage -H :4000 --replication --advertise 172.30.0.161:4000 consul://172.30.0.165:8500
## Options
The `swarm` command has the following options:
* `--debug` — Enable debug mode. Display messages that you can use to debug a Swarm node. For example:
time="2016-02-17T17:57:40Z" level=fatal msg="discovery required to join a cluster. See 'swarm join --help'."
The environment variable for this option is `[$DEBUG]`.
* `--log-level "<value>"` or `-l "<value>"` — Set the log level. Where `<value>` is: `debug`, `info`, `warn`, `error`, `fatal`, or `panic`. The default value is `info`.
* `--experimental` — Enable experimental features.
* `--help` or `-h` — Display help.
* `--version` or `-v` — Display the version. For example:
$ docker run swarm --version
swarm version 1.1.0 (a0fd82b)
## Commands
The `swarm` command has the following subcommands:
- [create, c](create.md) - Create a discovery token
- [list, l](list.md) - List the nodes in a Docker cluster
- [manage, m](manage.md) - Create a Swarm manager
- [join, j](join.md) - Create a Swarm node
- [help](help.md) - Display a list of Swarm commands, or help for one command