Skip to content

Commit 2b252a8

Browse files
dvdksndvdksn
committed
fixup! docs: minor editorial improvements, typo fixes
Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
1 parent 08f3aff commit 2b252a8

File tree

5 files changed

+115
-118
lines changed

5 files changed

+115
-118
lines changed

‎docs/reference/commandline/swarm_init.md‎

Lines changed: 98 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -5,30 +5,30 @@ Initialize a swarm
55

66
### Options
77

8-
| Name | Type | Default | Description |
9-
|:----------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------|
10-
| `--advertise-addr` | `string` | | Advertised address (format: `<ip\|interface>[:port]`) |
11-
| `--autolock` | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) |
12-
| `--availability` | `string` | `active` | Availability of the node (`active`, `pause`, `drain`) |
13-
| `--cert-expiry` | `duration` | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h) |
14-
| `--data-path-addr` | `string` | | Address or interface to use for data path traffic (format: `<ip\|interface>`) |
15-
| `--data-path-port` | `uint32` | `0` | Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. |
16-
| `--default-addr-pool` | `ipNetSlice` | | default address pool in CIDR format |
17-
| `--default-addr-pool-mask-length` | `uint32` | `24` | default address pool subnet mask length |
18-
| `--dispatcher-heartbeat` | `duration` | `5s` | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h) |
19-
| `--external-ca` | `external-ca` | | Specifications of one or more certificate signing endpoints |
20-
| `--force-new-cluster` | | | Force create a new cluster from current state |
21-
| `--listen-addr` | `node-addr` | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`) |
22-
| `--max-snapshots` | `uint64` | `0` | Number of additional Raft snapshots to retain |
23-
| `--snapshot-interval` | `uint64` | `10000` | Number of log entries between Raft snapshots |
24-
| `--task-history-limit` | `int64` | `5` | Task history retention limit |
8+
| Name | Type | Default | Description |
9+
|:--------------------------------------------|:--------------|:---------------|:-----------------------------------------------------------------------------------------------------------------------------|
10+
| [`--advertise-addr`](#advertise-addr) | `string` | | Advertised address (format: `<ip\|interface>[:port]`) |
11+
| [`--autolock`](#autolock) | | | Enable manager autolocking (requiring an unlock key to start a stopped manager) |
12+
| [`--availability`](#availability) | `string` | `active` | Availability of the node (`active`, `pause`, `drain`) |
13+
| `--cert-expiry` | `duration` | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h) |
14+
| [`--data-path-addr`](#data-path-addr) | `string` | | Address or interface to use for data path traffic (format: `<ip\|interface>`) |
15+
| [`--data-path-port`](#data-path-port) | `uint32` | `0` | Port number to use for data path traffic (1024 - 49151). If no value is set or is set to 0, the default port (4789) is used. |
16+
| [`--default-addr-pool`](#default-addr-pool) | `ipNetSlice` | | default address pool in CIDR format |
17+
| `--default-addr-pool-mask-length` | `uint32` | `24` | default address pool subnet mask length |
18+
| `--dispatcher-heartbeat` | `duration` | `5s` | Dispatcher heartbeat period (ns\|us\|ms\|s\|m\|h) |
19+
| [`--external-ca`](#external-ca) | `external-ca` | | Specifications of one or more certificate signing endpoints |
20+
| [`--force-new-cluster`](#force-new-cluster) | | | Force create a new cluster from current state |
21+
| [`--listen-addr`](#listen-addr) | `node-addr` | `0.0.0.0:2377` | Listen address (format: `<ip\|interface>[:port]`) |
22+
| [`--max-snapshots`](#max-snapshots) | `uint64` | `0` | Number of additional Raft snapshots to retain |
23+
| [`--snapshot-interval`](#snapshot-interval) | `uint64` | `10000` | Number of log entries between Raft snapshots |
24+
| `--task-history-limit` | `int64` | `5` | Task history retention limit |
2525

2626

2727
<!---MARKER_GEN_END-->
2828

2929
## Description
3030

31-
Initialize a swarm. The docker engine targeted by this command becomes a manager
31+
Initialize a swarm. The Docker Engine targeted by this command becomes a manager
3232
in the newly created single-node swarm.
3333

3434
## Examples
@@ -40,94 +40,91 @@ Swarm initialized: current node (bvz81updecsj6wjz393c09vti) is now a manager.
4040

4141
To add a worker to this swarm, run the following command:
4242

43-
docker swarm join \
44-
--token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx \
45-
172.17.0.2:2377
43+
docker swarm join --token SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx 172.17.0.2:2377
4644

4745
To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
4846
```
4947

50-
`docker swarm init` generates two random tokens, a worker token and a manager token. When you join
51-
a new node to the swarm, the node joins as a worker or manager node based upon the token you pass
52-
to [swarm join](swarm_join.md).
48+
The `docker swarm init` command generates two random tokens: a worker token and
49+
a manager token. When you join a new node to the swarm, the node joins as a
50+
worker or manager node based upon the token you pass to [swarm
51+
join](swarm_join.md).
5352

5453
After you create the swarm, you can display or rotate the token using
5554
[swarm join-token](swarm_join-token.md).
5655

57-
### `--autolock`
56+
### <a name="autolock"></a> Protect manager keys and data (--autolock)
5857

59-
This flag enables automatic locking of managers with an encryption key. The
60-
private keys and data stored by all managers will be protected by the
61-
encryption key printed in the output, and will not be accessible without it.
62-
Thus, it is very important to store this key in order to activate a manager
63-
after it restarts. The key can be passed to `docker swarm unlock` to reactivate
64-
the manager. Autolock can be disabled by running
65-
`docker swarm update --autolock=false`. After disabling it, the encryption key
66-
is no longer required to start the manager, and it will start up on its own
67-
without user intervention.
58+
The `--autolock` flag enables automatic locking of managers with an encryption
59+
key. The private keys and data stored by all managers are protected by the
60+
encryption key printed in the output, and is inaccessible without it. Make sure
61+
to store this key securely, in order to reactivate a manager after it restarts.
62+
Pass the key to the `docker swarm unlock` command to reactivate the manager.
63+
You can disable autolock by running `docker swarm update --autolock=false`.
64+
After disabling it, the encryption key is no longer required to start the
65+
manager, and it will start up on its own without user intervention.
6866

69-
### `--cert-expiry`
67+
### <a name=""></a> Configure node healthcheck frequency (--dispatcher-heartbeat)
7068

71-
This flag sets the validity period for node certificates.
69+
The `--dispatcher-heartbeat` flag sets the frequency at which nodes are told to
70+
report their health.
7271

73-
### `--dispatcher-heartbeat`
72+
### <a name="external-ca"></a> Use an external certificate authority (--external-ca)
7473

75-
This flag sets the frequency with which nodes are told to use as a
76-
period to report their health.
74+
This flag sets up the swarm to use an external CA to issue node certificates.
75+
The value takes the form `protocol=X,url=Y`. The value for `protocol` specifies
76+
what protocol should be used to send signing requests to the external CA.
77+
Currently, the only supported value is `cfssl`. The URL specifies the endpoint
78+
where signing requests should be submitted.
7779

78-
### `--external-ca`
80+
### <a name="force-new-cluster"></a> Force-restart node as a single-mode manager (--force-new-cluster)
7981

80-
This flag sets up the swarm to use an external CA to issue node certificates. The value takes
81-
the form `protocol=X,url=Y`. The value for `protocol` specifies what protocol should be used
82-
to send signing requests to the external CA. Currently, the only supported value is `cfssl`.
83-
The URL specifies the endpoint where signing requests should be submitted.
82+
This flag forces an existing node that was part of a quorum that was lost to
83+
restart as a single-node Manager without losing its data.
8484

85-
### `--force-new-cluster`
85+
### <a name="listen-addr"></a> Specify interface for inbound control plane traffic (--listen-addr)
8686

87-
This flag forces an existing node that was part of a quorum that was lost to restart as a single node Manager without losing its data.
88-
89-
### `--listen-addr`
90-
91-
The node listens for inbound swarm manager traffic on this address. The default is to listen on
92-
0.0.0.0:2377. It is also possible to specify a network interface to listen on that interface's
93-
address; for example `--listen-addr eth0:2377`.
87+
The node listens for inbound swarm manager traffic on this address. The default
88+
is to listen on `0.0.0.0:2377`. It is also possible to specify a network
89+
interface to listen on that interface's address; for example `--listen-addr
90+
eth0:2377`.
9491

9592
Specifying a port is optional. If the value is a bare IP address or interface
96-
name, the default port 2377 will be used.
93+
name, the default port 2377 is used.
9794

98-
### `--advertise-addr`
95+
### <a name="advertise-addr"></a> Specify interface for outbound control plane traffic (--advertise-addr)
9996

100-
This flag specifies the address that will be advertised to other members of the
101-
swarm for API access and overlay networking. If unspecified, Docker will check
102-
if the system has a single IP address, and use that IP address with the
103-
listening port (see `--listen-addr`). If the system has multiple IP addresses,
104-
`--advertise-addr` must be specified so that the correct address is chosen for
105-
inter-manager communication and overlay networking.
97+
The `--advertise-addr` flag specifies the address that will be advertised to
98+
other members of the swarm for API access and overlay networking. If
99+
unspecified, Docker will check if the system has a single IP address, and use
100+
that IP address with the listening port (see `--listen-addr`). If the system
101+
has multiple IP addresses, `--advertise-addr` must be specified so that the
102+
correct address is chosen for inter-manager communication and overlay
103+
networking.
106104

107-
It is also possible to specify a network interface to advertise that interface's address;
108-
for example `--advertise-addr eth0:2377`.
105+
It is also possible to specify a network interface to advertise that
106+
interface's address; for example `--advertise-addr eth0:2377`.
109107

110108
Specifying a port is optional. If the value is a bare IP address or interface
111-
name, the default port 2377 will be used.
109+
name, the default port 2377 is used.
110+
111+
### <a name="data-path-addr"></a> Specify interface for data traffic (--data-path-addr)
112112

113-
### `--data-path-addr`
113+
The `--data-path-addr` flag specifies the address that global scope network
114+
drivers will publish towards other nodes in order to reach the containers
115+
running on this node. Using this parameter you can separate the container's
116+
data traffic from the management traffic of the cluster.
114117

115-
This flag specifies the address that global scope network drivers will publish towards
116-
other nodes in order to reach the containers running on this node.
117-
Using this parameter it is then possible to separate the container's data traffic from the
118-
management traffic of the cluster.
119-
If unspecified, Docker will use the same IP address or interface that is used for the
120-
advertise address.
118+
If unspecified, the IP address or interface of the advertise address is used.
121119

122-
### `--data-path-port`
120+
### <a name="data-path-port"></a> Configure port number for data traffic (--data-path-port)
123121

124-
This flag allows you to configure the UDP port number to use for data path
125-
traffic. The provided port number must be within the 1024 - 49151 range. If
126-
this flag is not set or is set to 0, the default port number 4789 is used.
127-
The data path port can only be configured when initializing the swarm, and
128-
applies to all nodes that join the swarm.
129-
The following example initializes a new Swarm, and configures the data path
130-
port to UDP port 7777;
122+
The `--data-path-port` flag allows you to configure the UDP port number to use
123+
for data path traffic. The provided port number must be within the 1024 - 49151
124+
range. If this flag isn't set, or if it's set to 0, the default port number
125+
4789 is used. The data path port can only be configured when initializing the
126+
swarm, and applies to all nodes that join the swarm. The following example
127+
initializes a new Swarm, and configures the data path port to UDP port 7777;
131128

132129
```console
133130
$ docker swarm init --data-path-port=7777
@@ -146,43 +143,45 @@ Data Path Port: 7777
146143
<...>
147144
```
148145

149-
### `--default-addr-pool`
150-
This flag specifies default subnet pools for global scope networks.
151-
Format example is `--default-addr-pool 30.30.0.0/16 --default-addr-pool 40.40.0.0/16`
146+
### <a name="default-addr-pool"></a> Specify default subnet pools (--default-addr-pool)
152147

153-
### `--default-addr-pool-mask-length`
154-
This flag specifies default subnet pools mask length for default-addr-pool.
155-
Format example is `--default-addr-pool-mask-length 24`
148+
The `--default-addr-pool` flag specifies default subnet pools for global scope
149+
networks. For example, to specify two address pools:
156150

157-
### `--task-history-limit`
151+
```console
152+
$ docker swarm init \
153+
--default-addr-pool 30.30.0.0/16 \
154+
--default-addr-pool 40.40.0.0/16
155+
```
158156

159-
This flag sets up task history retention limit.
157+
Use the `--default-addr-pool-mask-length` flag to specify the default subnet
158+
pools mask length for the subnet pools.
160159

161-
### `--max-snapshots`
160+
### <a name="max-snapshots"></a> Set limit for number of snapshots to keep (--max-snapshots)
162161

163162
This flag sets the number of old Raft snapshots to retain in addition to the
164163
current Raft snapshots. By default, no old snapshots are retained. This option
165164
may be used for debugging, or to store old snapshots of the swarm state for
166165
disaster recovery purposes.
167166

168-
### `--snapshot-interval`
167+
### <a name="snapshot-interval"></a> Configure Raft snapshot log interval (--snapshot-interval)
169168

170-
This flag specifies how many log entries to allow in between Raft snapshots.
171-
Setting this to a higher number will trigger snapshots less frequently.
172-
Snapshots compact the Raft log and allow for more efficient transfer of the
173-
state to new managers. However, there is a performance cost to taking snapshots
174-
frequently.
169+
The `--snapshot-interval` flag specifies how many log entries to allow in
170+
between Raft snapshots. Setting this to a high number will trigger snapshots
171+
less frequently. Snapshots compact the Raft log and allow for more efficient
172+
transfer of the state to new managers. However, there is a performance cost to
173+
taking snapshots frequently.
175174

176-
### `--availability`
175+
### <a name="availability"></a> Configure the availability of a manager (--availability)
177176

178-
This flag specifies the availability of the node at the time the node joins a master.
179-
Possible availability values are `active`, `pause`, or `drain`.
177+
The `--availability` flag specifies the availability of the node at the time
178+
the node joins a master. Possible availability values are `active`, `pause`, or
179+
`drain`.
180180

181-
This flag is useful in certain situations. For example, a cluster may want to have
182-
dedicated manager nodes that are not served as worker nodes. This could be achieved
181+
This flag is useful in certain situations. For example, a cluster may want to
182+
have dedicated manager nodes that don't serve as worker nodes. You can do this
183183
by passing `--availability=drain` to `docker swarm init`.
184184

185-
186185
## Related commands
187186

188187
* [swarm ca](swarm_ca.md)

0 commit comments

Comments
 (0)