From 5909a90dd563f091a4765d0d16ab863af6dbeb00 Mon Sep 17 00:00:00 2001 From: Joao Fernandes Date: Sun, 1 May 2016 19:32:32 -0700 Subject: [PATCH] Adds docs missing for 1.1.0 * closes #938 * closes #1252 * closes #1318 * closes #448 * closes #1465 * closes #1317 * closes #912 * closes #1473 --- access-ucp/index.md | 7 ++ applications/index.md | 7 ++ configuration/index.md | 8 ++ .../backups-and-disaster-recovery.md | 59 ++++++------ high-availability/index.md | 8 ++ index.md | 12 +++ installation/index.md | 12 +++ installation/install-production.md | 82 ++++++++++------- installation/plan-production-install.md | 91 ++++++++++++++----- installation/system-requirements.md | 30 +++--- installation/uninstall.md | 27 ++++-- monitor/index.md | 8 ++ release_notes.md | 52 +++++++++++ user-management/index.md | 6 ++ 14 files changed, 306 insertions(+), 103 deletions(-) diff --git a/access-ucp/index.md b/access-ucp/index.md index 556ef14f33..0b4ba962c9 100644 --- a/access-ucp/index.md +++ b/access-ucp/index.md @@ -9,3 +9,10 @@ identifier="mn_ucp_access" weight=31 +++ + +# Access UCP + +This section includes the following topics: + +* [Web-based access](web-based-access.md) +* [CLI-based access](cli-based-access.md) diff --git a/applications/index.md b/applications/index.md index 1432e13f92..92e5ab2ce9 100644 --- a/applications/index.md +++ b/applications/index.md @@ -9,3 +9,10 @@ identifier="mn_ucp_applications" weight=80 +++ + +# UCP applications + +This section includes the following topics: + +* [Deploy an app from the UI](deploy-app-ui.md) +* [Deploy an app from the CLI](deploy-app-cli.md) diff --git a/configuration/index.md b/configuration/index.md index 53ac5c916a..9e888cdb6c 100644 --- a/configuration/index.md +++ b/configuration/index.md @@ -9,3 +9,11 @@ identifier="mn_ucp_configuration" weight=50 +++ + +# UCP configuration + +This section includes the following topics: + +* [Set up container networking](multi-host-networking.md) +* [Integrate with Docker Trusted Registry](dtr-integration.md) +* [Configure UCP logging](configure-logs.md) diff --git a/high-availability/backups-and-disaster-recovery.md b/high-availability/backups-and-disaster-recovery.md index 4fe2f8b88a..bdfbc7ad08 100644 --- a/high-availability/backups-and-disaster-recovery.md +++ b/high-availability/backups-and-disaster-recovery.md @@ -20,13 +20,7 @@ The next step is creating a backup policy and disaster recovery plan. ## Backup policy -Docker UCP nodes persist data using [named volumes](../architecture.md): - -* Controller nodes persist cluster configurations, certificates, and keys -used to issue certificates and user bundles. This data is replicated on every -controller node in the cluster. -* Nodes are stateless. They only store certificates for mutual TLS, that -can be regenerated. +Docker UCP nodes persist data using [named volumes](../architecture.md). As part of your backup policy you should regularly create backups of the controller nodes. Since the nodes used for running user containers don't @@ -46,19 +40,7 @@ To have minimal impact on your business, you should: * Configure UCP for high availability. This allows load-balancing user requests across multiple UCP controller nodes. -## Backup UCP data - -To learn about the options available on the `docker/ucp backup` command, you can -check the reference documentation, or run: - -```bash -$ docker run --rm docker/ucp backup --help -``` - -When creating a backup, the resulting tar archive contains sensitive information -like private keys. To ensure this information is kept private you should run -the backup command with the `--passphrase` option. This encrypts -the backup with a passphrase of your choice. +## Backup command The example below shows how to create a backup of a UCP controller node: @@ -68,14 +50,6 @@ $ docker run --rm -i --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ docker/ucp --interactive --passphrase "secret" > /tmp/backup.tar -Do you want proceed with the backup? (y/n): -$ y - -INFO[0000] Temporarily Stopping local UCP containers to ensure a consistent backup -INFO[0000] Beginning backup -INFO[0001] Backup completed successfully -INFO[0002] Resuming stopped UCP containers - # Decrypt the backup and list its contents $ gpg --decrypt /tmp/backup.tar | tar --list @@ -89,6 +63,35 @@ Enter passphrase: secret # output snipped ``` +## Restore command + +The example below shows how to restore a UCP controller node from an existing +backup: + +```bash +$ docker run --rm -i --name ucp \ + -v /var/run/docker.sock:/var/run/docker.sock \ + docker/ucp restore -i < backup.tar +``` + + +## Restore your cluster + +Configuring UCP to have multiple controller nodes allows you tolerate a certain +amount of node failures. If multiple nodes fail at the same time, causing the +cluster to go down, you can use an existing backup to recover. + +As an example, if you have a cluster with three controller nodes, A, B, and C, +and your most recent backup was of node A: + +1. Stop controllers B and C with the `stop` command, +2. Restore controller A, +3. Uninstall UCP from controllers B and C, +4. Join nodes B and C to the cluster. + +You should now have your cluster up and running. + + ## Where to go next * [Set up high availability](set-up-high-availability.md) diff --git a/high-availability/index.md b/high-availability/index.md index 8e9f747c0e..b9768da6f1 100644 --- a/high-availability/index.md +++ b/high-availability/index.md @@ -9,3 +9,11 @@ identifier="mn_ucp_high_availability" weight=60 +++ + +# Configure UCP for high availability + +This section includes the following topics: + +* [Set up high availability](set-up-high-availability.md) +* [Replicate CAs for high availability](replicate-cas.md) +* [Backups and disaster recovery](backups-and-disaster-recovery.md) diff --git a/index.md b/index.md index 0ff021f7fc..78371798e0 100644 --- a/index.md +++ b/index.md @@ -15,3 +15,15 @@ solution from Docker. You install it behind your firewall, and it helps you manage your whole cluster from a single place. The UCP documentation includes the following topics: + +* [Universal Control Plane overview](overview.md) +* [Evaluate UCP in a sandbox](install-sandbox.md) +* [Architecture](architecture.md) +* [Installation](installation/system-requirements.md) +* [Access UCP](access-ucp/web-based-access.md) +* [Configuration](configuration/multi-host-networking.md) +* [Monitor and troubleshoot](monitor/monitor-ucp.md) +* [High availability](high-availability/set-up-high-availability.md) +* [User management](user-management/manage-users.md) +* [Applications](applications/deploy-app-ui.md) +* [Release notes](release_notes.md) diff --git a/installation/index.md b/installation/index.md index 950625a57c..907a7dd630 100644 --- a/installation/index.md +++ b/installation/index.md @@ -9,3 +9,15 @@ identifier="mn_ucp_installation" weight=30 +++ + +# Install UCP + +This section includes the following topics: + +* [System requirements](system-requirements.md) +* [Plan a production installation](plan-production-install.md) +* [Install UCP for production](install-production.md) +* [Install offline](install-offline.md) +* [License UCP](license.md) +* [Upgrade UCP](upgrade.md) +* [Uninstall UCP](uninstall.md) diff --git a/installation/install-production.md b/installation/install-production.md index 669acfdeed..24884f372a 100644 --- a/installation/install-production.md +++ b/installation/install-production.md @@ -16,11 +16,13 @@ weight=20 Docker Universal Control Plane (UCP) is a containerized application that can be installed on-premises or on a cloud infrastructure. +## Step 1: Validate the system requirements + The first step in installing UCP, is ensuring your infrastructure has all the [requirements UCP needs to run](system-requirements). -Once that is done, use these instructions to install UCP. -## Step 1: Install CS Docker on all nodes + +## Step 2: Install CS Docker on all nodes UCP requires you to install Docker CS Engine 1.10 or above on all nodes of your UCP cluster. @@ -28,7 +30,7 @@ your UCP cluster. For each node that you want to add to the UCP cluster, install the CS Docker Engine. -## Step 2: Customize named volumes +## Step 3: Customize named volumes This step is optional. @@ -40,7 +42,9 @@ If the volumes don't exist, when installing UCP they are created with the default volume driver and flags. -## Step 3: Customize the CA used +## Step 4: Customize the CA used + +This step is optional. The UCP cluster uses TLS to secure all communications. Two Certificate Authorities (CA) are used for this: @@ -69,15 +73,11 @@ If you want to use your own certificates: | key.pem | Your UCP controller private key. | -## Step 4: Install the UCP controller +## Step 5: Install the UCP controller To install UCP you use the `docker/ucp` image. This image has commands to install, configure, and backup UCP. To find what commands and options are -available, check the [reference documentation](../reference/install.md), or run: - -```bash -$ docker run --rm -it docker/ucp --help -``` +available, check the [reference documentation](../reference/install.md). To install UCP: @@ -91,47 +91,59 @@ To install UCP: ```bash $ docker run --rm -it --name ucp \ - -v /var/run/docker.sock:/var/run/docker.sock - docker/ucp install -i + -v /var/run/docker.sock:/var/run/docker.sock \ + docker/ucp install -i \ + --host-address <$UCP_PUBLIC_IP> ``` - If you are using server certificates signed by an external CA, include - the `--external-server-cert` option at the end of the command. + Where: + + * i, specify to run the install command interactively, + * host-address, is the public IP where users or a load balancer can access + UCP, + * Also, include the `--external-server-cert` flag if you're using server + certificates signed by an external CA. + +
+ When installing Docker UCP, overlay networking is automatically configured + for you. If you are running Docker CS Engine 1.10, or have custom + configurations on your Docker CS Engine, you need to restart the Docker + daemon at this point. + 3. Check that the UCP web application is running. In your browser, navigate to the address where you've installed UCP. - If you're not using your own certificates, your browser warns that UCP is + If you're not using an external CA, your browser warns that UCP is an unsafe site. ![](../images/login.png) -## Step 5: License your installation +## Step 6: License your installation Now that your UCP controller is installed, you need to license it. [Learn how to license your installation](license.md). -## Step 6: Backup the controller CAs +## Step 7: Backup the controller CAs -Docker UCP has support for high-availability. For an highly available -installation, you add more controller nodes to the UCP cluster. The controller -nodes are replicas of each other. +This step is optional. + +For an highly available installation, you can add more controller nodes to +the UCP cluster. The controller nodes are replicas of each other. [Learn more about high-availability](../high-availability/set-up-high-availability.md). -When configuring UCP for high-availability, you need to ensure the CAs running -on each UCP controller node are interchangeable. This is done by using the same -certificates and keys for every CA on the cluster. +For this, you need to make the CAs on each controller node, use the same +root certificates and keys. [Learn how to replicate the CAs for high availability](../high-availability/replicate-cas.md). -## Step 7: Add controller replicas to the UCP cluster -To add more controller nodes to the cluster, use the -`docker/ucp join --replica` command. To find what commands and options are -available, check the [reference documentation](../reference/join.md), or run: +## Step 8: Add controller replicas to the UCP cluster -```bash -$ docker run --rm -it docker/ucp join --help -``` +This step is optional. + +For an highly available installation, you can add more controller nodes to +the UCP cluster. For that, use the `docker/ucp join --replica` command. +[Learn more about the join command](../reference/join.md). For each node that you want to install as a controller replica: @@ -146,13 +158,13 @@ For each node that you want to install as a controller replica: ```bash $ docker run --rm -it --name ucp \ -v /var/run/docker.sock:/var/run/docker.sock \ - docker/ucp join -i --replica + docker/ucp join -i \ + --replica ``` 3. Repeat steps 1 and 2 on the other nodes you want to set up as replicas. +Make sure you set up 3, 5, or 7 controllers. - For high availability, make sure to set up 3, 5, or 7 controller nodes. - [Learn more about high-availability](../high-availability/set-up-high-availability.md). 4. Check the cluster state. @@ -161,7 +173,7 @@ For each node that you want to install as a controller replica: ![UCP nodes page](../images/replica-nodes.png) -## Step 8: Add more nodes to the UCP cluster +## Step 9: Add more nodes to the UCP cluster Now you can add additional nodes to your UCP cluster. These are the nodes that will be running your containers. @@ -186,7 +198,7 @@ For each node that you want to add to your UCP cluster: ![UCP nodes page](../images/nodes-page.png) -## Step 9. Download an admin user bundle +## Step 10. Download a client certificate bundle To validate that your cluster is correctly configured, you should try accessing the cluster with the Docker CLI client. For this, you'll need to get a client diff --git a/installation/plan-production-install.md b/installation/plan-production-install.md index 3878434162..dce8bca0c0 100644 --- a/installation/plan-production-install.md +++ b/installation/plan-production-install.md @@ -17,38 +17,83 @@ Docker Universal Control Plane can be installed on-premises, or on a virtual private cloud. If you've never used Docker UCP before, you should start by [installing it on a sandbox](../install-sandbox.md). -To secure your data, Docker UCP is automatically set up to use mutual TLS on -all communications. Before you install UCP, make sure you know: +This article explains what you need to consider before deploying +Docker Universal Control Plane. -* The fully qualified domain names (FQDN) of the hosts where you'll install UCP, -* Their Subject Alternative Names (SANs). +## System requirements -## Fully-qualified domain names +Before installing UCP, you should make sure all nodes of your cluster +comply with the [system requirements](system-requirements.md). -When installing Docker UCP, the installer tries to find the fully-qualified -domain names (FQDN) of your hosts. +## Hostname strategy -If the installer can't detect this automatically, or if you want to use a -different FQDN or IP address, use the `--host-address` option when installing. -This option allows you to specify the IP or hostname that UCP is going to use -to reach that host. +Docker UCP requires the Docker CS Engine to run. Before installing Docker CS +Engine on the cluster nodes, you should plan for a common naming strategy. -If you're installing UCP on a cloud provider such as AWS or Digital Ocean, -you might need to create a private network for you UCP installation. In that -case, make sure all nodes of the cluster can communicate using their private -IPs. +Decide if you want to use short hostnames like `engine01` or Fully Qualified +Domain Names (FQDN) likes `engine01.docker.vm`. Independently of your choice, +ensure your naming strategy is consistent across the cluster, since UCP uses +the hostnames. + +As an example, if your cluster has 4 hosts you can name them: + +```bash +engine01.docker.vm +engine02.docker.vm +engine03.docker.vm +engine04.docker.vm +``` + +## Load balancing strategy + +UCP Docker UCP does not include a load-balancer. You can configure your own +load-balancer to balance user requests across all controller nodes. + +If you plan on using a load balancer, you need to decide whether you are going +to add the nodes to the load balancer using their IP address, or their FQDN. +Independently of what you choose, it should be consistent across the nodes. + +After that, you should take note of all IPs or FQDNs before starting the +installation. + +## Load balancing UCP and DTR + +By default, both UCP and DTR use port 443. If you plan on deploying UCP and DTR, +your load balancer needs to distinguish traffic between the two by IP address +or port number. + +* If you want to configure your load balancer to listen on port 443: + * Use one load balancer for UCP, and another for DTR, + * Use the same load balancer with multiple virtual IPs. +* Configure your load balancer to expose UCP or DTR on a port other than 443. -## Subject alternative names (SANs) +## Using external CAs -When joining new nodes to the cluster, UCP creates leaf certificates for that -node. Those certificates are then used by for communicating over mutual TLS -with other members of the cluster. +You can customize UCP to use certificates signed by an external Certificate +Authority. If you decide to use your own CAs take in considerat that: -You can specify the subject alternative names (SANs) to be used in the -certificate. If you are installing UCP interactively you'll be prompted for -this. You can also use the `--san` option when installing and joining nodes -to the cluster. +* During the installation you need to copy the ca.pem, cert.pem, and key.pem +files across all controller hosts, +* The ca.pem is the root CA public certificate +* The cert.pem is the server cert plus any intermediate CA public certificates, +* The cert.pem should have SANs for all addresses used to reach UCP, +* The key.pem is the server private key, + +You can have a certificate for each controller, with a common SAN. As an +example, on a three node cluster you can have: + +* engine01.docker.vm with SAN ducp.docker.vm +* engine02.docker.vm with SAN ducp.docker.vm +* engine03.docker.vm with SAN ducp.docker.vm + +## File transfer across hosts + +Make sure you can transfer file between the hosts on the cluster. You will +need to replicate CAs across controller nodes. + +For this, you can tools like `scp` or `rsync`, or configure the hosts to use +a network file system. ## Where to go next diff --git a/installation/system-requirements.md b/installation/system-requirements.md index 2120e08a65..7b70ad899d 100644 --- a/installation/system-requirements.md +++ b/installation/system-requirements.md @@ -30,22 +30,30 @@ all nodes must have: * Linux kernel version 3.10 or higher * CS Docker Engine version 1.10 or higher +For highly-available installations, you also need a way to transfer files +between hosts. ## Ports used When installing UCP on a host, make sure the following ports are open: -| Hosts | Direction | Port | Purpose | -|:-------------------|:---------:|:--------------------|:------------------------------------------------------------| -| controllers | in | 443 (configurable) | Web app and CLI client access to UCP. | -| controllers | in | 2376 (configurable) | Swarm manager accepts requests from UCP controller. | -| controllers, nodes | in | 2375 | Heartbeat for nodes, to ensure they are running. | -| controllers, nodes | in | 12376 | Proxy for TLS, provides access to UCP, Swarm, and Engine. | -| controller | in | 12379 | Internal node configuration, cluster configuration, and HA. | -| controller | in | 12380 | Internal node configuration, cluster configuration, and HA. | -| controller | in | 12381 | Proxy for TLS, provides access to UCP. | -| controller | in | 12382 | Manages TLS and requests from swarm manager. | -| controller | out | 443 | Send anonymous usage reports to Docker. | +| Hosts | Direction | Port | Purpose | +|:-------------------|:---------:|:--------------------|:---------------------------------------------------------------------------| +| controllers | in | 443 (configurable) | Web app and CLI client access to UCP. | +| controller | out | 443 | Send anonymous usage reports to Docker. | +| controllers, nodes | in | 2375 | Heartbeat for nodes, to ensure they are running. | +| controllers | in | 2376 (configurable) | Swarm manager accepts requests from UCP controller. | +| controllers, nodes | in, out | 4789 | Overlay networking. | +| controllers, nodes | in, out | 7946 | Overlay networking. | +| controllers, nodes | in | 12376 | Proxy for TLS, provides access to UCP, Swarm, and Engine. | +| controller | in | 12379 | Internal node configuration, cluster configuration, and HA. | +| controller | in | 12380 | Internal node configuration, cluster configuration, and HA. | +| controller | in | 12381 | Proxy for TLS, provides access to UCP. | +| controller | in | 12382 | Manages TLS and requests from swarm manager. | +| controller | in | 12383 | Used by the authentication storage backend. | +| controller | in | 12384 | Used by authentication storage backend for replication across controllers. | +| controller | in | 12385 | The port where the authentication API is exposed. | +| controller | in | 12386 | Used by the authentication worker. | UCP collects anonymous usage metrics, to help us improve it. These metrics are entirely anonymous, don’t identify your company, users, applications, diff --git a/installation/uninstall.md b/installation/uninstall.md index 1c7ee45c0c..65ae2d7243 100644 --- a/installation/uninstall.md +++ b/installation/uninstall.md @@ -18,17 +18,18 @@ Plane from a node. This command only removes the UCP containers, and doesn’t affect any other containers. To see what options are available in the uninstall command, check the -[uninstall command reference](../reference/uninstall.md), or run: - -```bash -$ docker run --rm -it docker/ucp uninstall --help -``` +[uninstall command reference](../reference/uninstall.md). To uninstall Docker UCP from a cluster, you should: 1. Uninstall UCP from every node joined in the cluster, 2. Uninstall UCP from every controller node, one at a time. +When you install UCP, your Docker Engine is automatically configured for +multi-host networking. When uninstalling, you need to delete or update the +`/etc/docker/daemon.json` file and restart the Docker daemon on each node. + + ## Example In this example we’ll be running the uninstall command interactively, so that @@ -74,5 +75,19 @@ You can also use flags to pass values to the uninstall command. Deleted: sha256:93743d5df2362466e2fe116a677ec6a4b0091bd09e889abfc9109047fcfcdebf ``` -4. Go to the UCP web application, and confirm the node was removed from the +4. Delete the engine-discovery configuration + + ```bash + $ sudo rm /etc/docker/daemon.json + ``` + +5. Restart the Docker daemon + + As an example, on a Ubuntu host + + ```bash + $ sudo service docker restart + ``` + +6. Go to the UCP web application, and confirm the node was removed from the cluster. diff --git a/monitor/index.md b/monitor/index.md index e1351350ef..b3f1be1d0d 100644 --- a/monitor/index.md +++ b/monitor/index.md @@ -10,3 +10,11 @@ identifier="mn_monitor_ucp" weight=50 +++ + +# Monitor UCP + +This section includes the following topics: + +* [Monitor your cluster](monitor-ucp.md) +* [Troubleshoot your cluster](troubleshoot-ucp.md) +* [Troubleshoot cluster configurations](troubleshoot-configurations.md) diff --git a/release_notes.md b/release_notes.md index 2eae05a436..ffa0b00acc 100644 --- a/release_notes.md +++ b/release_notes.md @@ -12,6 +12,58 @@ weight=110 # UCP Release Notes +## Version 1.1.0 + +**Features** + +* Core + * Added new commands to the docker/ucp image: backup, restore, id, + regen-certs, restart, stop + * UCP and DTR are now using a unified authentication service + * Users and teams created in UCP are displayed in DTR under the 'Datacenter' + organization + * When installing UCP, multi-host networking is Automatically configured + * All controllers joined to the cluster now have replicated CAs + * All UCP components were compiled the Go 1.5.4 and 1.6 to address Go security + vulnerabilities +​ +* UI + * Now you can deploy apps from the UI using a docker-compse.yml file + * There's a new setting to prevent users from deploying containers to the UCP + controller nodes + * Improved usability of LDAP configuration settings + * Images page no longer shows the sha256 id of each image ID + * User profiles now display default permissions + * Improved feedback when creating users and teams with invalid characters + * Added horizontal scrollbar to wide pages + +**Bug Fixes** + +* Improved messages when installing UCP on a host with firewall rules +* Images page no longer shows images generated from intermediate builds +* Images page no longer hangs when pulling an image +* Scaling a container from the UI now preserves parameters like 'net' and 'privileged' +* Fixed `docker ps --filter` to filter containers correctly + + +**Misc** + +* You no longer need to install UCP with --swarm-experimental to use swarm container rescheduling +* All UCP containers now have the 'com.docker.ucp.version' label with their upstream version or UCP version +* When running docker/ucp in interactive mode, the parameters and environment variables passed to the command are displayed +* Renamed 'external-ucp-ca' flag to 'external-server-cert' for clarity. The first is deprecated but still available + +**Component Versions** + +UCP 1.1.0 uses: + +* cfssl 1.2.0 +* Docker Compose 1.7.0 +* Docker Swarm: 1.2.0 +* etcd 2.2.5 +* RethinkDB 2.3.0 +​ + ## Version 1.0.4 **Security update** diff --git a/user-management/index.md b/user-management/index.md index 1101d7c30e..2575520dab 100644 --- a/user-management/index.md +++ b/user-management/index.md @@ -9,3 +9,9 @@ parent="mn_ucp" weight=70 +++ + +# Manage users in UCP + +This section includes the following topics: + +* [Manage users](manage-users.md)