From 79f2bdb5e4f7b49752ed65eb3230f0cda87dca31 Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Tue, 16 Aug 2016 13:44:21 -0700 Subject: [PATCH] Update CLI reference docs --- reference/backup.md | 18 +++++------ reference/engine-discovery.md | 35 ++++---------------- reference/index.md | 38 +++++++++------------- reference/install.md | 61 ++++++++++++++++++----------------- reference/join.md | 32 ++++-------------- reference/restore.md | 47 +++++++++++++++------------ reference/uninstall.md | 10 +++--- 7 files changed, 101 insertions(+), 140 deletions(-) diff --git a/reference/backup.md b/reference/backup.md index c228e72df4..0a9e0fa31a 100644 --- a/reference/backup.md +++ b/reference/backup.md @@ -9,7 +9,7 @@ parent = "ucp_ref" # docker/ucp id -Stream a tar file to stdout containing all UCP data volumes. +Stream a tar file to stdout containing all UCP data volumes ## Usage @@ -42,11 +42,11 @@ built-in PGP compatible encryption. ## Options -| Option | Description | -|:-----------------|:------------------------------------------------------------------------| -| `--debug, -D` | Enable debug mode | -| `--jsonlog` | Produce json formatted output for easier parsing | -| `--id` | The ID of the UCP instance to backup | -| `--root-ca-only` | Backup only the root CA certificates and keys from this controller node | -| `--passphrase` | Encrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] | -| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. | \ No newline at end of file +| Option | Description | +|:--------------------|:---------------------------------------------------------------------------------| +| `--debug, -D` | Enable debug mode | +| `--jsonlog` | Produce json formatted output for easier parsing | +| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. | +| `--id` | The ID of the UCP instance to backup | +| `--root-ca-only` | Backup only the root CA certificates and keys from this controller node | +| `--passphrase` | Encrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] | diff --git a/reference/engine-discovery.md b/reference/engine-discovery.md index b9aa44c457..e90f5c6e8e 100644 --- a/reference/engine-discovery.md +++ b/reference/engine-discovery.md @@ -9,7 +9,7 @@ identifier="ucp_ref_engine_discovery" # docker/ucp engine-discovery -Manage the Engine discovery configuration. +The engine-discovery command is no longer used. ## Usage @@ -23,33 +23,12 @@ docker run --rm -it \ ## Description -This command will display and update the local Docker engine discovery -configuration. This is used by the engine for cluster membership and multi-host -networking. - -By default, this command will check if the configuration is up to date. Use -'--update' to update the configuration. Use '--debug' to show more information -including current and proposed configuration. - -UCP controllers in this cluster are auto-detected if possible. Alternately you -may use one or more '--controller' arguments to manually specify ALL of the UCP -controllers. - -The '--host-address' argument specifies the public advertise address for THIS -node (how other nodes in the system talk to this node.) You may specify an IP -address, and the port number will be automatically filled in. If omitted, the -tool will attempt to discover the address of this node. - -This command uses the exit status of 0 for success. An exit status of 1 is used -when run without the '--update' flag and when the configuration needs updating, -and 2 is used for any failures. +The engine-discovery command is no longer used. Overlay networking is enabled +automatically via swarm-mode. ## Options -| Option | Description | -|:-----------------------------------------------------------|:----------------------------------------------------------------------------------------------| -| `--debug, -D` | Enable debug | -| `--jsonlog` | Produce json formatted output for easier parsing | -| `--update` | Apply engine discovery configuration changes | -| `--controller` `[--controller option --controller option]` | Update discovery with the external IP address or hostname of the controller(s) | -| `--host-address` | Update the external IP address or hostname this node advertises itself as [$UCP_HOST_ADDRESS] | +| Option | Description | +|:--------------|:-------------------------------------------------| +| `--debug, -D` | Enable debug | +| `--jsonlog` | Produce json formatted output for easier parsing | diff --git a/reference/index.md b/reference/index.md index d94d97a365..3d6b515271 100644 --- a/reference/index.md +++ b/reference/index.md @@ -26,10 +26,7 @@ $ docker run --rm -it \ ## Description -Docker Universal Control Plane Tool - -This tool has commands to 'install' the UCP initial controller and -'join' nodes to that controller. The tool can also 'uninstall' the product. +This tool has commands to 'install' and 'uninstall' UCP. This tool must run as a container with a well-known name and with the docker.sock volume mounted, which you can cut-and-paste from the usage example below. @@ -39,8 +36,8 @@ your hostname and primary IP addresses. This may be overridden with the '--host-address' option. The tool may not be able to discover your externally visible fully qualified hostname. For proper certificate verification, you should pass one or more Subject Alternative Names with -'--san' during 'install' and 'join' that matches the fully qualified -hostname you intend to use to access the given system. +'--san' during 'install' that matches the fully qualified hostname you +intend to use to access the given system. Many settings can be passed as flags or environment variables. When passing as an environment variable, use the 'docker run -e VARIABLE_NAME ...' syntax to @@ -58,19 +55,16 @@ Additional help is available for each command with the '--help' option. ## Commands -| Command | Description | -|:-------------------|:---------------------------------------------------------------------------| -| `install` | Install UCP on this engine | -| `join` | Join this engine to an existing UCP | -| `upgrade` | Upgrade the UCP components on this engine | -| `images` | Verify the UCP images on this engine | -| `uninstall` | Uninstall UCP components from this engine | -| `dump-certs` | Dump out the public certs for this UCP controller | -| `support` | Generate a support dump for this engine | -| `fingerprint` | Dump out the TLS fingerprint for the UCP controller running on this engine | -| `id` | Dump out the ID of the UCP components running on this engine | -| `engine-discovery` | Manage the engine discovery configuration | -| `backup` | Stream a tar file to stdout containing all UCP data volumes | -| `restore` | Stream a tar file on stdin containing all local UCP data volumes | -| `regen-certs` | Regenerate keys and certificates for a UCP controller | -| `help` | Shows a list of commands or help for one command | +| Command | Description | +|:--------------|:---------------------------------------------------------------------------| +| `install` | Install UCP on this engine | +| `upgrade` | Upgrade the UCP components on this engine | +| `images` | Verify the UCP images on this engine | +| `dump-certs` | Dump out the public certs for this UCP controller | +| `support` | Generate a support dump for this engine | +| `fingerprint` | Dump out the TLS fingerprint for the UCP controller running on this engine | +| `id` | Dump out the ID of the UCP components running on this engine | +| `backup` | Stream a tar file to stdout containing all UCP data volumes | +| `restore` | Stream a tar file on stdin containing all local UCP data volumes | +| `regen-certs` | Regenerate keys and certificates for a UCP controller | +| `help` | Shows a list of commands or help for one command | diff --git a/reference/install.md b/reference/install.md index 1cf86b5ee3..4722bdac77 100644 --- a/reference/install.md +++ b/reference/install.md @@ -28,7 +28,10 @@ local engine. If you intend to install a multi-node cluster, you must open firewall ports between the engines for the following ports: -Ports: 443, 12376, 12379, 12380, 12381, 12382 and 2376 or the '--swarm-port' +* 443 or the '--controller-port' +* 2376 or the '--swarm-port' +* 12376, 4789, 12379, 12380, 12381, 12382, 12383, 12384, 12385, 12386 +* 4789(udp) and 7946(tcp/udp) for overlay networking You can optionally use an externally generated and signed certificate for the UCP controller by specifying '--external-server-cert'. Create a storage @@ -41,31 +44,31 @@ mounting the file at '/docker_subscription.lic' in the tool. E.g. ## Options -| Option | Description | -|:-----------------------------------------------------------|:--------------------------------------------------------------------------------------------------------| -| `--debug`, `-D` | Enable debug. | -| `--jsonlog` | Produce json formatted output for easier parsing. | -| `--interactive`, `-i` | Enable interactive mode.,You will be prompted to enter all required information. | -| `--admin-username` | Specify the UCP admin username [$UCP_ADMIN_USER] | -| `--admin-password` | Specify the UCP admin password [$UCP_ADMIN_PASSWORD] | -| `--fresh-install` | Destroy any existing state and start fresh. | -| `--san` `[--san option --san option]` | Additional Subject Alternative Names for certs (e.g. `--san foo1.bar.com --san foo2.bar.com`). | -| `--host-address` | Specify the visible IP/hostname for this node. | -| `--swarm-port "2376"` | Select what port to run the local Swarm manager on (default: 2376) | -| `--controller-port "443"` | Select what port to run the local Controller on (default: 443) | -| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. | -| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. | -| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. | -| `--kv-timeout` | Timeout in milliseconds for the KV store (set higher for a multi-datacenter cluster) | -| `--kv-snapshot-count` | Number of changes between KV store snapshots (all controllers must use the same value) (default: 10000) | -| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] | -| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] | -| `--swarm-experimental` | Enable experimental Swarm features. Note: Use only for install, not join). | -| `--disable-tracking` | Disable anonymous tracking and analytics. | -| `--disable-usage` | Disable anonymous usage reporting. | -| `--external-server-cert` | Set up UCP with an external CA. | -| `--preserve-certs` | Don't (re)generate certs on the host if existing ones are found. | -| `--binpack` | Set Swarm scheduler to binpack mode (default spread). | -| `--random` | Set Swarm scheduler to random mode (default spread). | -| `--pull "missing"` | Specify image pull behavior (`always`, when `missing`, or `never`) (default: "missing") | -| `--skip-engine-discovery` | Do not configure engine for clustering | +| Option | Description | +|:-----------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--debug`, `-D` | Enable debug. | +| `--jsonlog` | Produce json formatted output for easier parsing. | +| `--interactive`, `-i` | Enable interactive mode.,You will be prompted to enter all required information. | +| `--admin-username` | Specify the UCP admin username [$UCP_ADMIN_USER] | +| `--admin-password` | Specify the UCP admin password [$UCP_ADMIN_PASSWORD] | +| `--fresh-install` | Destroy any existing state and start fresh. | +| `--san` `[--san option --san option]` | Additional Subject Alternative Names for certs (e.g. `--san foo1.bar.com --san foo2.bar.com`). | +| `--host-address` | Specify the visible IP/hostname for this node. | +| `--swarm-port "2376"` | Select what port to run the local Swarm manager on (default: 2376) | +| `--controller-port "443"` | Select what port to run the local Controller on (default: 443) | +| `--swarm-grpc-port` | Select what port to run Swarm GRPC on (default: 2377) | +| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. [$DNS] | +| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. [$DNS_OPT] | +| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. [$DNS_SEARCH] | +| `--pull "missing"` | Specify image pull behavior (`always`, when `missing`, or `never`) (default: "missing") | +| `--kv-timeout` | Timeout in milliseconds for the KV store (set higher for a multi-datacenter cluster, all controllers must use the same value) (default: 5000) [$KV_TIMEOUT] | +| `--kv-snapshot-count` | Number of changes between KV store snapshots (all controllers must use the same value) (default: 20000) [$KV_SNAPSHOT_COUNT] | +| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] | +| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] | +| `--swarm-experimental` | Enable experimental Swarm features. Note: Use only for install, not join). | +| `--disable-tracking` | Disable anonymous tracking and analytics. | +| `--disable-usage` | Disable anonymous usage reporting. | +| `--external-server-cert` | Set up UCP with an external CA. | +| `--preserve-certs` | Don't (re)generate certs on the host if existing ones are found. | +| `--binpack` | Set Swarm scheduler to binpack mode (default spread). | +| `--random` | Set Swarm scheduler to random mode (default spread). | | diff --git a/reference/join.md b/reference/join.md index 5d13c3ea21..02d6f1c74c 100644 --- a/reference/join.md +++ b/reference/join.md @@ -9,7 +9,7 @@ identifier = "ucp_ref_join" # docker/ucp join -Join this engine to an existing UCP. +The join command is no longer used. ## Usage @@ -23,21 +23,7 @@ docker run --rm -it \ ## Description -When running the 'join' command, you must run this tool -on the engine you wish to join to an existing UCP. The UCP controller -must be running on a different engine. Both engines must have network -visibility to eachother and have the required ports open on their firewall -settings. If your system has multiple IP addresses, you may need to -specify the '--host-address' option to ensure the correct address is used. - -Ports: 443, 12376, 12379, 12380, 12381, 12382 and 2376 or the '--swarm-port' from 'install' - -To enable high-availability, you must join at least one node with the -'replica' flag. When joining a replica, you may optionally provide -a backup tar file containing the Root CA material from the initial -controller saved via the 'backup' command. Only the Root CA material -will be retrieved from that backup. Add the following volume mount: -`-v /path/to/my/backup.tar:/backup.tar` +To join a node to UCP, simply run `docker swarm join` ## Options @@ -53,15 +39,9 @@ will be retrieved from that backup. Add the following volume mount: | `--host-address` | Specify the visible IP/hostname for this node. (override automatic detection) [$UCP_HOST_ADDRESS] | | `--swarm-port "2376"` | Select what port to run the local Swarm manager on (default: 2376) | | `--controller-port "443"` | Select what port to run the local Controller on (default: 443) | -| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. | -| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. | -| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. | +| `--swarm-grpc-port value` | Select what port to run Swarm GRPC on (default: 2377) | +| `--dns` `[--dns option --dns option]` | Set custom DNS servers for the UCP infrastructure containers. [$DNS] | +| `--dns-opt` `[--dns-opt option --dns-opt option]` | Set DNS options for the UCP infrastructure containers. [$DNS_OPT] | +| `--dns-search` `[--dns-search option --dns-search option]` | Set custom DNS search domains for the UCP infrastructure containers. [$DNS_SEARCH] | | `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] | | `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] | -| `--url` | The connection URL for the remote UCP controller [$UCP_URL] | -| `--fingerprint` | The fingerprint of the UCP controller you trust [$UCP_FINGERPRINT] | -| `--replica` | Configure this node to be a UCP controller replica. | -| `--external-server-cert` | (Replica only) Use externally signed certificates for the controller. | -| `--pull "missing"` | Specify image pull behavior ('always', when 'missing', or 'never') (default: "missing") | -| `--passphrase` | Decrypt the Root CA tar file with the provided passphrase [$UCP_PASSPHRASE] | -| `--skip-engine-discovery` | Do not configure engine for clustering | diff --git a/reference/restore.md b/reference/restore.md index e358acf2b4..68ae6f11e8 100644 --- a/reference/restore.md +++ b/reference/restore.md @@ -10,7 +10,7 @@ identifier = "ucp_ref_restore" # docker/ucp id -Stream a tar file on stdin containing all local UCP data volumes. +Restore a UCP cluster from a backup tar file. ## Usage @@ -24,27 +24,34 @@ docker run --rm -i \ ## Description -This utility will restore all the contents in all the volumes on this -controller based on a tar file generated by the 'backup' command. Any UCP -containers that are running will be stopped prior to restoring the data. -After the data is replaced, the containers will be restarted. +This utility will restore the state of this controller based on a tar file +generated by the 'backup' command. Any UCP containers that are running on this +host will be stopped prior to restoring the data. After the data is replaced, +the containers will be restarted. -When restoring multiple controllers in an HA cluster, you must manually -stop all controller nodes you plan to restore first, then begin the -restore with the most recent controller backup first. The cluster will -resume operation once 1/2+1 of the controllers have been restored. +The full restore operation can be only performed on the same node where a backup +was taken. Other controllers of the cluster need to be stopped before attempting +a restore operation. -WARNING: Any existing state on this node will be lost and replaced by -the contents of the backup. To prevent accidental use, the "-id" flag -must be provided. +The restore operation can be also used to replicate Root CA material across +controllers in the same cluster, by using the --root-ca-only flag. In this case, +no controllers need to be stopped and the same backup file can be used to +replicate Root CA material across multiple controllers of the same cluster. + +WARNING: Existing state on this node will be lost and replaced by the +contents of the backup. + +When the restore operation is run using --interactive mode, the backup file +needs to be mounted under /backup.tar within this container. If the +--interactive flag is not set, the backup file will be read from stdin. ## Options -| Option | Description | -|:-----------------|:-------------------------------------------------------------------------------------------------------| -| `--debug, -D` | Enable debug mode | -| `--jsonlog` | Produce json formatted output for easier parsing | -| `--id` | The ID of the UCP instance to backup | -| `--root-ca-only` | Restore only the root CA certificates and keys on this controller node (leaving all other data intact) | -| `--passphrase` | Decrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] | -| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. | +| Option | Description | +|:--------------------|:-------------------------------------------------------------------------------------------------------| +| `--debug, -D` | Enable debug mode | +| `--jsonlog` | Produce json formatted output for easier parsing | +| `--interactive, -i` | Enable interactive mode. You will be prompted to enter all required information. | +| `--id` | The ID of the UCP instance to backup | +| `--root-ca-only` | Restore only the root CA certificates and keys on this controller node (leaving all other data intact) | +| `--passphrase` | Decrypt the tar file with the provided passphrase [$UCP_PASSPHRASE] | diff --git a/reference/uninstall.md b/reference/uninstall.md index 4a5ec2a49f..2a8d4d7a2b 100644 --- a/reference/uninstall.md +++ b/reference/uninstall.md @@ -9,7 +9,7 @@ identifier = "ucp_ref_uninstall" # docker/ucp uninstall -Uninstall UCP components from this Docker Engine. +The uninstall command is no longer used. ## Usage @@ -23,8 +23,9 @@ docker run --rm -it \ ## Description -When uninstalling UCP, you must run the 'uninstall' command against every -engine in your cluster. +The uninstall command is no longer used. To remove a node from the UCP cluster, +run the 'docker swarm leave' and 'docker node rm' commands. To remove the UCP +components but preserve the swarm cluster, use the 'uninstall-cluster' command. ## Options @@ -36,6 +37,3 @@ engine in your cluster. | `--pull` | Specify image pull behavior ('always', when 'missing', or 'never') (default: "missing") | | `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] | | `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] | -| `--id` | The ID of the UCP instance to uninstall | -| `--preserve-certs` | Don't delete the certs on the host | -| `--preserve-images` | Don't delete images on the host |