diff --git a/images/dashboard.png b/images/dashboard.png index 39544b8cf9d..d4f790362f8 100644 Binary files a/images/dashboard.png and b/images/dashboard.png differ diff --git a/images/docker-hub-license.png b/images/docker-hub-license.png new file mode 100644 index 00000000000..c06d994e857 Binary files /dev/null and b/images/docker-hub-license.png differ diff --git a/images/docker-hub-settings.png b/images/docker-hub-settings.png new file mode 100644 index 00000000000..03d6f83b2df Binary files /dev/null and b/images/docker-hub-settings.png differ diff --git a/images/login.png b/images/login.png index 0505299b8ff..a4deeb34bdb 100644 Binary files a/images/login.png and b/images/login.png differ diff --git a/images/nodes-page.png b/images/nodes-page.png new file mode 100644 index 00000000000..e02c645ebb4 Binary files /dev/null and b/images/nodes-page.png differ diff --git a/images/replica-nodes.png b/images/replica-nodes.png new file mode 100644 index 00000000000..da1def421db Binary files /dev/null and b/images/replica-nodes.png differ diff --git a/images/ucp-architecture.png b/images/ucp-architecture.png index 22bd07d7639..4d38c2e720b 100644 Binary files a/images/ucp-architecture.png and b/images/ucp-architecture.png differ diff --git a/manage/monitor-ucp.md b/manage/monitor-ucp.md index eb5c1d2d38d..de57b363b61 100644 --- a/manage/monitor-ucp.md +++ b/manage/monitor-ucp.md @@ -20,8 +20,7 @@ if something goes wrong. Docker UCP has several components: * UCP controller node: the node that handles user requests, -* UCP replica nodes: replicas of the controller node that can take its place -if it fails, +* UCP replica nodes: replicas of the controller node, for high-availability, * UCP nodes: the nodes that run your own containers. [Learn more about the UCP architecture](../plan-production-install.md#ucp-architecture). @@ -53,8 +52,8 @@ filter dropdown choose **Show all containers** to see all the UCP components. ![UCP container list](../images/container-list.png) -You can see more information about these containers. On the right-hand side of -a container, **click the options knob** to see the container details. +You can see more information about these containers. **Click on the container** +to see its details. ![UCP container details](../images/container-detail-2.png) diff --git a/plan-production-install.md b/plan-production-install.md index 5ba760e52d7..52a2749f1a6 100644 --- a/plan-production-install.md +++ b/plan-production-install.md @@ -20,8 +20,6 @@ The following topics are covered: * [UCP architecture](#ucp-architecture) * [The UCP installation](#the-ucp-installation) * [Understand your installation options](#understand-your-installation-options) -* [Security Considerations](#security-considerations) -* [Docker Engine Configuration](#docker-engine-configuration) * [Installation checklist](#installation-checklist) ## UCP architecture @@ -32,8 +30,8 @@ In this cluster, there are 3 different types of nodes: * [UCP controller node](#UCP-controller-node): the node that handles user requests, -* [UCP replica nodes](#ucp-replica-nodes): replicas of the controller node -that can take its place if it fails, +* [UCP replica nodes](#ucp-replica-nodes): replicas of the controller node, for +high-availability, * [UCP nodes](#ucp-nodes): the nodes that run your own containers. ![](images/ucp-architecture.png) @@ -46,19 +44,24 @@ using a web browser, or a CLI client. Below is a list of the containers that are deployed to the controller node, when running the `ucp install` command: -| Container name | Description | -|:------------------|:------------------------------------------------------------------------------------------| -| ucp-controller | Manages UCP resources, admin configuration, and user commands. | -| ucp-swarm-manager | Accepts requests the from UCP controller. | -| ucp-kv | Internal node discovery, cluster configuration, and support for HA. | -| ucp-ca | Allow external systems to reach UCP. Proxy for TLS. | -| ucp-swarm-ca | Allow external systems to reach UCP, Swarm, and Engine, using credentials. Proxy for TLS. | +| Name | Description | +|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `ucp-kv` | This container runs the key-value store used by UCP. Don't use this key-value store in your applications, since it's for internal use only. | +| `ucp-swarm-manager` | This Swarm manager uses the replicated KV store for leader election and cluster membership tracking. | +| `ucp-controller` | This container runs the UCP server, using the replicated KV store for configuration state. | +| `ucp-swarm-join` | Runs the `swarm join` command to periodically publish this node existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster. | +| `ucp-proxy` | Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon. | +| `ucp-cluster-root-ca` | Run the Swarm CA used for admin certificate bundles, and adding new nodes. | +| `ucp-client-root-ca` | Run the (optional) UCP CA used for signing user bundles. | #### UCP replica nodes Docker UCP has support for high availability. You can configure replica nodes -to stand by, and be ready to take the place of the controller if it fails. +for: + +* Load-balancing user requests across the controller and replica nodes, +* Maintain a copy of the system configuration, in case the controller fails. A cluster with N controller and replica nodes can only tolerate (N-1)/2 node failures. So be sure to set up at least two replicas, when installing UCP for @@ -67,13 +70,13 @@ production. Below is a list of the containers that are deployed to the controller node, when running the `ucp join --replica` command: -| Container name | Description | -|:------------------|:--------------------------------------------------------------------| -| ucp-controller | Manages UCP resources, admin configuration, and user commands. | -| ucp-swarm-manager | Accepts requests from the UCP controller. | -| ucp-kv | Internal node discovery, cluster configuration, and support for HA. | -| ucp-proxy | Manages TLS and requests from swarm manager. | -| ucp-swarm-join | Heartbeat for Swarm nodes to ensure they are running. | +| Name | Description | +|:--------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `ucp-kv` | This container runs the key-value store used by UCP. Don't use this key-value store in your applications, since it's for internal use only. | +| `ucp-swarm-manager` | This Swarm manager uses the replicated KV store for leader election and cluster membership tracking. | +| `ucp-controller` | This container runs the UCP server, using the replicated KV store for configuration state. | +| `ucp-swarm-join` | Runs the `swarm join` command to periodically publish this node existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster. | +| `ucp-proxy` | Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon. | In UCP v1.0 the controller serves as root CA, and no other nodes are able to sign certificates. If the controller fails, it might not be possible to add new @@ -89,10 +92,10 @@ nodes. Below is a list of the containers that are deployed to the controller node, when running the `ucp join` command: -| Container name | Description | -|:---------------|:------------------------------------------------------| -| ucp-proxy | Manages TLS and requests from swarm manager. | -| ucp-swarm-join | Heartbeat for Swarm nodes to ensure they are running. | +| Name | Description | +|:-----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `ucp-swarm-join` | Runs the `swarm join` command to periodically publish this node existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster. | +| `ucp-proxy` | Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon. | ## The UCP installation @@ -174,18 +177,19 @@ The following ports are using on UCP installation: | Hosts | Direction | Port | Purpose | |:----------------------------|:---------:|:--------------------|:------------------------------------------------------------| -| controller, replicas | in | 443 (configurable) | web app and CLI client access to UCP. | -| controller, replicas | in | 2376 (configurable) | swarm manager accepts requests from UCP controller. | -| controller, replicas, nodes | in | 2375 | heartbeat for nodes, to ensure they are running. | -| controller, replicas, nodes | in | 12376 | proxy for TLS, provides access to UCP, Swarm, and Engine. | -| controller, replicas | in | 12379 | internal node configuration, cluster configuration, and HA. | -| controller, replicas | 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, replicas | out | 443 | send anonymous usage reports to Docker. | - -UCP collects anonymous data on the usage of UCP and reports to Docker. -This data is entirely anonymous and does not identify your company or users. +| controller, replicas | in | 443 (configurable) | Web app and CLI client access to UCP. | +| controller, replicas | in | 2376 (configurable) | Swarm manager accepts requests from UCP controller. | +| controller, replicas, nodes | in | 2375 | Heartbeat for nodes, to ensure they are running. | +| controller, replicas, nodes | in | 12376 | Proxy for TLS, provides access to UCP, Swarm, and Engine. | +| controller, replicas | in | 12379 | Internal node configuration, cluster configuration, and HA. | +| controller, replicas | 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, replicas | out | 443 | Send anonymous usage reports to Docker. | + +UCP collects anonymous usage metrics, to help us improve it. +These metrics are entirely anonymous, don't identify your company, users, +applications, or any other sensitive information. You can disable this at any time on the UCP settings screen. @@ -204,19 +208,6 @@ 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. -If the nodes in the cluster cannot communicate using the private IPs, -you'll need to use public IPs or Fully Qualified Domain Names. -[Check the ports used](#ports-used) by UCP. - - -If you are using a cloud provider such as AWS or Digital Ocean, you may need to -create a private network for your UCP installation. You can use this network -as long as the controller and nodes can communicate via -their private IPs. If the private IPs do not support communication among the -UCP cluster, using public IPs or full-qualified domain names are required. For -more information about what ports and protocols are required see -[Step 2: Configure your network for UCP](#step-2-configure-your-network-for-ucp). - ### Subject alternative names (SANs) diff --git a/production-install.md b/production-install.md index c2b7c902998..b3145dd23cd 100644 --- a/production-install.md +++ b/production-install.md @@ -15,7 +15,7 @@ This page explains how to install Docker Universal Control Plane (UCP) on a production environment. A Docker UCP installation, consists of: * A controller node where UCP is running, -* Replica nodes that are ready to take the controller place if it fails, +* Replicas of the controller node, for high-availability, * One or more nodes used to run your containers. The controller node can serve as a controller and also run your containers. @@ -28,10 +28,11 @@ contains the following sections: - [Step 4: Create user-named volumes](#step-4-customize-user-named-volumes-optional) - [Step 5: Customize the CA used](#step-5-customize-the-ca-used-optional) - [Step 6: Install the UCP controller](#step-6-install-the-ucp-controller) -- [Step 7: Add controller replicas to the UCP cluster](#step-7-add-controller-replicas-to-the-ucp-cluster) -- [Step 8: Add more nodes to the UCP cluster](#step-8-add-more-nodes-to-the-ucp-cluster) -- [Step 9: Set up certificates for the Docker CLI](#step-9-set-up-certificates-for-the-docker-cli) -- [Disable usage reporting](#disable-usage-reporting) +- [Step 7: License your installation](#step-7-license-your-installation) +- [Step 8: Add controller replicas to the UCP cluster](#step-8-add-controller-replicas-to-the-ucp-cluster) +- [Step 9: Add more nodes to the UCP cluster](#step-9-add-more-nodes-to-the-ucp-cluster) +- [Step 10: Set up certificates for the Docker CLI](#step-10-set-up-certificates-for-the-docker-cli) +- [Disable collection of usage metrics](#disable-collection-of-usage-metrics) - [Uninstall](#uninstall) - [Where to go next](#where-to-go-next) @@ -102,7 +103,7 @@ your UCP cluster, including the controller node. For each node, follow the Docker CS Engine installation instructions for your particular operating system: -* [Red Hat Linux installation +* [Red Hat Linux and CentOs installation instructions](https://docs.docker.com/docker-trusted-registry/install/install-csengine/#centos-7-1-rhel-7-0-7-1-yum-based-systems) * [Ubuntu installation instructions](https://docs.docker.com/docker-trusted-registry/install/install-csengine/#install-on-ubuntu-14-04-lts) @@ -111,15 +112,15 @@ instructions](https://docs.docker.com/docker-trusted-registry/install/install-cs UCP uses named volumes to persist user data: -| Volume name | Data | -|:---------------------------|:---------------------------------------------------------------------------------------------------------------| -| ucp-root-ca | The certificate and key for the UCP root CA. Do not create this volume if you are using your own certificates. | -| ucp-swarm-root-ca | The certificate and key for the Swarm root CA. | -| ucp-server-certs | The controller certificates for the UCP controllers web server. | -| ucp-swarm-node-certs | The Swarm certificates for the current node (repeated on every node in the cluster). | -| ucp-swarm-kv-certs | The Swarm KV client certificates for the current node (repeated on every node in the cluster). | -| ucp-swarm-controller-certs | The UCP Controller Swarm client certificates for the current node. | -| ucp-kv | Key value store persistence. | +| Volume name | Data | +|:----------------------------|:---------------------------------------------------------------------------------------------------------------| +| ucp-client-root-ca | The certificate and key for the UCP root CA. Do not create this volume if you are using your own certificates. | +| ucp-cluster-root-ca | The certificate and key for the Swarm root CA. | +| ucp-controller-server-certs | The controller certificates for the UCP controllers web server. | +| ucp-node-certs | The Swarm certificates for the current node (repeated on every node in the cluster). | +| ucp-kv-certs | The Swarm KV client certificates for the current node (repeated on every node in the cluster). | +| ucp-controller-client-certs | The UCP Controller Swarm client certificates for the current node. | +| ucp-kv | Key value store persistence. | The `ucp install` command creates these volumes for you with the default volume driver and flags. @@ -194,12 +195,33 @@ On the controller node, install UCP: installation values it needs. When the installation is complete, the command asks you to log into UCP. - INFO[0053] Login to UCP at https://10.0.0.32:443 + INFO[0053] Login to UCP at https://52.70.188.239:443 -3. Enter the address in your browser to navigate to the UCP login screen. +## Step 7: License your installation + +Now that your UCP controller is installed, download and apply the +license to your installation: + +1. Navigate to [Docker Hub](https://hub.docker.com/) to download your license. +On the top-right menu, choose **Settings**. + + ![Docker hub home page](images/docker-hub-settings.png) + +2. Navigate to the **Licenses** tab. + + ![Docker Hub licenses page](images/docker-hub-license.png) + + Download the license by clicking on it. + +3. **Navigate to UCP** to apply the license. + + In your browser, navigate to the IP of the node where you installed the + UCP controller. In this example, it's `https://52.70.188.239`. + + ![UCP login screen](images/login.png) Your browser may warn that the connection to UCP is not secure. The warning - appears because you are accessing UCP using HTTPS, but the certificates used + appears because you are accessing UCP with HTTPS, but the certificates used by UCP were issued during the installation by a built-in certificate authority. @@ -207,19 +229,28 @@ On the controller node, install UCP: You can use the server fingerprint displayed during the installation, and compare it with the certificate displayed on your browser. -4. Accept the security warning to proceed to UCP. +4. **Login** with the admin username and the password you chose during +the installation. - ![UCP Login screenshot](images/login.png) + If you installed non-interactively, the default administrator + credentials are *admin/orca*. -5. Login with the admin username and the password you provided during -the installation. +5. Apply your license file. + + After logging in, you're redirected to the licensing page. Click the + **Upload License** button, and choose your license file. + + ![UCP Login screenshot](images/skip-this.png) - After logging in, you are redirected to the UCP dashboard. It should show - that there's only a single node in your cluster: the controller node. +6. Check the **Dashboard** page. + + After applying the license, you're redirected to the UCP dashboard. It + should show that there's only a single node in your cluster: + the controller node. ![UCP dashboard screenshot](images/dashboard.png) -## Step 7: Add controller replicas to the UCP cluster +## Step 8: Add controller replicas to the UCP cluster Docker UCP has support for high-availability. You set other nodes to be replicas of the UCP controller, that way you can load-balance user requests @@ -279,14 +310,15 @@ For each node that you want to turn into a controller replica: a primary controller and two replicas. Never run a cluster with only the primary controller and a single replica. -4. Log into UCP with your browser and navigate to the **Nodes** page. +4. Log into UCP. - The nodes page should now display your new replica nodes. + The Dashboard page should now display your new replica nodes. In the + bottom of the screen, you can see the health of the controller and replicas. - ![UCP nodes page](images/nodes.png) + ![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. @@ -296,7 +328,7 @@ information: * The URL of the UCP controller, for example `https://52.70.188.239`. * The username/password of an UCP administrator account. -* At least one SAN value which is the actual external, publically-accessible IP +* At least one SAN value which is the actual external, publicly-accessible IP address or fully-qualified domain name for node. So be sure to have this information at hand. If you're installing UCP on a cloud @@ -329,11 +361,11 @@ For each node that you want to add to your UCP cluster: 4. Log into UCP with your browser and navigate to the **Nodes** page. - The nodes page should now display your new replica nodes. + The nodes page should now display all the nodes of your cluster. - ![UCP nodes page](images/nodes.png) + ![UCP nodes page](images/nodes-page.png) -## Step 9: Set up certificates for the Docker CLI +## Step 10: Set up certificates for the Docker CLI After installing UCP, you can run the `docker` command, against UCP cluster nodes. @@ -506,11 +538,11 @@ can use to interact with UCP with the CLI client. export DOCKER_HOST=tcp://:443 ``` -## Disable usage reporting +## Disable collection of usage metrics -Docker UCP uses Mixpanel to collect analytics. This feature collects anonymous -data on your usage of UCP and returns it to Docker. This data is entirely -anonymous and does not identify your company or users. +UCP collects anonymous usage metrics, to help us improve it. +These metrics are entirely anonymous, don't identify your company, users, +applications, or any other sensitive information. To disable usage reporting: @@ -543,7 +575,16 @@ To uninstall UCP from a node: 2. Run the the following command: - $ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp uninstall -i + ``` + $ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp uninstall -i + + INFO[0000] Removing UCP Containers + INFO[0001] Removing UCP images + INFO[0007] Removing UCP volumes + ``` + + After uninstalling UCP, you can remove the `docker/ucp` images that + were pulled from Docker Hub when installing UCP. 3. Repeat steps 1 and 2 on each node of the cluster. Make sure to save the controller for last. @@ -551,6 +592,5 @@ the controller for last. ## Where to go next * Read more [about Docker UCP](https://www.docker.com/universal-control-plane) -* Visit the [UCP forum](https://forums.docker.com/c/commercial-products/ucpbeta) * Read more [about the Docker CLI client](http://docs.docker.com/reference/commandline/cli/) * Learn [about Docker Swarm](http://docs.docker.com/swarm/)