From 19131c07c955b3d52d8a128ef2b70227956089bc Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Mon, 18 Jul 2016 11:42:26 -0700 Subject: [PATCH] Adds reference docs for docker/ucp --- reference/images.md | 16 ++++++------ reference/index.md | 1 + reference/install.md | 54 +++++++++++++++++++++-------------------- reference/join.md | 6 ++--- reference/support.md | 26 ++++++++++++++++++++ reference/uninstall.md | 21 ++++++++-------- reference/upgrade.md | 22 ++++++++--------- release_notes.md | 55 +++++++++++++++++++++--------------------- 8 files changed, 115 insertions(+), 86 deletions(-) create mode 100644 reference/support.md diff --git a/reference/images.md b/reference/images.md index 35b8497483..4294248cfc 100644 --- a/reference/images.md +++ b/reference/images.md @@ -30,11 +30,11 @@ to change behavior. ## Options -| Option | Description | -|:----------------------|:-----------------------------------------------------------------------| -| `--debug, -D` | Enable debug | -| `--jsonlog` | Produce json formatted output for easier parsing | -| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] | -| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] | -| `--pull "missing"` | Specify image pull behavior ('always', when 'missing', or 'never') | -| `--list` | Don`t do anything, just list the images used by UCP | +| Option | Description | +|:----------------------|:----------------------------------------------------------------------------------------| +| `--debug, -D` | Enable debug | +| `--jsonlog` | Produce json formatted output for easier parsing | +| `--registry-username` | Specify the username to pull required images with [$REGISTRY_USERNAME] | +| `--registry-password` | Specify the password to pull required images with [$REGISTRY_PASSWORD] | +| `--pull "missing"` | Specify image pull behavior ('always', when 'missing', or 'never') (default: "missing") | +| `--list` | Don`t do anything, just list the images used by UCP | diff --git a/reference/index.md b/reference/index.md index ffdbf86ff4..d94d97a365 100644 --- a/reference/index.md +++ b/reference/index.md @@ -66,6 +66,7 @@ Additional help is available for each command with the '--help' option. | `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 | diff --git a/reference/install.md b/reference/install.md index 8a0b8b6cb4..1cf86b5ee3 100644 --- a/reference/install.md +++ b/reference/install.md @@ -41,29 +41,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. | -| `--controller-port "443"` | Select what port to run the local Controller on. | -| `--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. | -| `--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`). | -| `--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) | +| `--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 | diff --git a/reference/join.md b/reference/join.md index 8c588ae5f1..5d13c3ea21 100644 --- a/reference/join.md +++ b/reference/join.md @@ -51,8 +51,8 @@ will be retrieved from that backup. Add the following volume mount: | `--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. (override automatic detection) [$UCP_HOST_ADDRESS] | -| `--swarm-port "2376"` | Select what port to run the local Swarm manager on. | -| `--controller-port "443"` | Select what port to run the local Controller on. | +| `--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. | @@ -62,6 +62,6 @@ will be retrieved from that backup. Add the following volume mount: | `--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'). | +| `--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/support.md b/reference/support.md new file mode 100644 index 0000000000..4526d2db7d --- /dev/null +++ b/reference/support.md @@ -0,0 +1,26 @@ ++++ +title = "support" +description = "Generate a support dump for this engine." +keywords= ["docker, ucp, support, logs"] +[menu.main] +parent = "ucp_ref" +identifier = "ucp_ref_support" ++++ + +# docker/ucp support + +Generate a support dump for this engine. + +## Usage + +``` +docker run --rm \ + --name ucp \ + -v /var/run/docker.sock:/var/run/docker.sock \ + docker/ucp \ + support > docker-support.tgz +``` + +## Description + +This utility will produce a support dump file on stdout for this local node. diff --git a/reference/uninstall.md b/reference/uninstall.md index 43084d2330..4a5ec2a49f 100644 --- a/reference/uninstall.md +++ b/reference/uninstall.md @@ -28,13 +28,14 @@ engine in your cluster. ## Options -| Option | Description | -|:----------------------|:----------------------------------------------------------------------------| -| `--debug`, `-D` | Enable debug | -| `--jsonlog` | Produce json formatted output for easier parsing | -| `--interactive`, `-i` | Enable interactive mode.,You are prompted to enter all required information | -| `--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 | +| Option | Description | +|:----------------------|:----------------------------------------------------------------------------------------| +| `--debug`, `-D` | Enable debug | +| `--jsonlog` | Produce json formatted output for easier parsing | +| `--interactive`, `-i` | Enable interactive mode.,You are prompted to enter all required information | +| `--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 | diff --git a/reference/upgrade.md b/reference/upgrade.md index 04a05b0252..adff5f80ea 100644 --- a/reference/upgrade.md +++ b/reference/upgrade.md @@ -34,14 +34,14 @@ before proceeding to the next node. ## 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] | -| `--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 upgrade | -| `--pull "always"` | Specify image pull behavior ('always', when 'missing', or 'never') | +| 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] | +| `--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 upgrade | +| `--pull "always"` | Specify image pull behavior ('always', when 'missing', or 'never') (default: "missing") | diff --git a/release_notes.md b/release_notes.md index 21a549027e..b8bd44c15a 100644 --- a/release_notes.md +++ b/release_notes.md @@ -14,55 +14,54 @@ weight=110 Here you can learn about new features, bug fixes, breaking changes and known issues for each UCP version. - You can then use [the upgrade instructions](installation/upgrade.md), to upgrade your installation to the latest release. ## Version 1.1.2 -NOTE: UCP 1.1.2 supports Engine 1.12 but not using the new swarm mode. It will - create a "classic" Swarm 1.2.3 cluster on top of Engine 1.12 based nodes. +Note: UCP 1.1.2 supports Docker Engine 1.12 but doesn't use the new clustering +capabilities provided by the Docker swarm mode. When installing this UCP version +on a Docker Engine 1.12, UCP creates a "classic" Docker Swarm 1.2.3 cluster. **Features** * Core - * Upgraded etcd to version 2.3.6 - * Upgraded rethinkDB to version 2.3.4 - * Support dumps (`dsinfo`) now provide more comprehensive information about the - UCP deployment for technical support sessions + * Upgraded etcd to version 2.3.6. + * Upgraded rethinkDB to version 2.3.4. + * The support dump generated by `dsinfo` now provides more information about + the UCP deployment, that can be used by Docker support. * docker/ucp image - * It's now possible to generate a support dump directly from the CLI using the - `support` command - * It's now possible to tune how often UCP's key-value store takes snapshots using the - `docker/ucp install --kv-snapshot-count` option. This can be used in conjunction - with `--kv-timeout` to tune the key-value store and the resulting performance - of the cluster based on your local environment. + * It's now possible to generate a support dump directly from the CLI using the + `support` command. + * It's now possible to tune how often UCP's key-value store takes snapshots + using the `docker/ucp install --kv-snapshot-count` option. This can be used + with the `--kv-timeout` flag to tune the performance of the key-value store. [Learn more about tuning the key-value store](https://github.com/coreos/etcd/blob/master/Documentation/v2/tuning.md#snapshots) * UI - * The dashboard will now notify admin users when an update for UCP is available. - * It's now possible to see which specific controllers need to have root CAs - inserted in order to achieve full HA. + * The dashboard now notifies admin users when an update for UCP is available. + * It's now possible to see which specific controllers need to have root CAs + inserted in order to achieve high-availability. * It's now possible to filter images on the `Images` tab. **Bug Fixes** -* Fixed an issue in which UCP failed to install in machines where the hostname has -more than 41 characters. -* Fixed an issue in which `ping` requests caused a memory leak in the -`ucp-controller` and `ucp-kv` containers -* When installing in the CLI, UCP now displays the specified `ADMIN_USERNAME` -variable rather than just "admin". -* Fixed an issue where container owner label permissions took priority over access +* Fixed an issue in which UCP failed to install in machines where the hostname +has more than 41 characters. +* Fixed an issue in which `ping` requests caused a memory leak in the +`ucp-controller` and `ucp-kv` containers. +* When installing in the CLI, UCP now displays the specified `ADMIN_USERNAME` +variable rather than just "admin". +* Fixed an issue where container owner label permissions took priority over access label permissions when displaying a list of containers. -* Fixed an issue in which upgrading to UCP caused a user to still see an older +* Fixed an issue in which upgrading to UCP caused a user to still see an older version in the UI. **Known Issues** -* This version of UCP will not install on Engine 1.12 swarm-mode based clusters, -nor is it compatible with swarm-mode based APIs (e.g. `docker service`). +* This version of UCP can't be installed on Engine 1.12 swarm-mode based +clusters, and is not compatible with swarm-mode based APIs, e.g. `docker service`. ## Version 1.1.1 @@ -297,7 +296,7 @@ containers * Use mutual TLS in CFSSL * Improved access control for Docker Engine proxy * Added support for custom server certificates and user bundles - * Users can now launch "private" containers if default permission is + * Users can now launch "private" containers if default permission is Restricted Control or greater * UI @@ -320,7 +319,7 @@ containers * UCP now uses a vendored UCP Swarm image * Removed timestamps from controller logs -* Switched from 'Full Control' to 'Restricted Control' for managing non-container +* Switched from 'Full Control' to 'Restricted Control' for managing non-container resources **Known issues**