docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document how to install UCP in production 

During the UCP beta we had created a quickstart guide
that included installation prerequisites (like ports that
need to be open), and the installation procedure.

Now we're breaking that information in two different documents.
This makes the information more accessible to someone who just
wants to prepare the installation.
This commit is contained in:
Joao Fernandes 2016-02-07 19:30:32 -08:00
parent 6f1c1fc18a
commit 23629a4073
2 changed files with 379 additions and 518 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
images/add-pk.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

799
production-install.md
View File

@ -1,8 +1,8 @@
<!--[metadata]> <!--[metadata]>
+++ +++
title = "Install UCP for production" title = "Install UCP for production"
description = "Install UCP for production" description = "Learn how to install Docker Universal Control Plane on production"
keywords = ["tbd, tbd"] keywords = ["Universal Control Plane, UCP, install"]
[menu.main] [menu.main]
parent="mn_ucp" parent="mn_ucp"
weight=-85 weight=-85
@ -11,471 +11,371 @@ weight=-85
# Install UCP for production # Install UCP for production
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial. 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,
* One or more nodes used to run your containers.
## Step 1: Prepare the properly The controller node can serve as a controller and also run your containers.
These instructions show you how to install both a controller and a node. It
contains the following sections:
tbd - [Step 1: Prepare your installation](#step-1-prepare-your-installation)
## Step 2: Configure your network for UCP
tbd
## Step 3: Install Docker CS Engine 1.9 on each node
tbd
## Step 4: Create user-named volumes
tbd
## Step 5: Configure user-supplied certificates
tbd
## Step 5: Install the UCP controller
tbd
## Step 6: Add a controller replica to the UCP cluster
tbd
## Step 7: Add an Engine node to the UCP cluster
tbd
## Step 8: Set up certs for the Docker CLI
tbd
## Block Mixpanel analytics
tbd
## Uninstall
tbd
## Where to go next
<!--[metadata]>
# Docker UCP Quickstart Guide
These instructions explain how to install Docker Universal Control Plane (UCP). A UCP installation consists of an UCP controller and one or more nodes. The same machine can serve as both the controller and the node. These instructions show you how to install both a host and a node. It contains the following sections:
- [Plan your installation](#plan-your-installation)
- [Step 1: Verify you have the prerequisites](#step-1-verify-you-have-the-prerequisites)
- [Step 2: Configure your network for UCP](#step-2-configure-your-network-for-ucp) - [Step 2: Configure your network for UCP](#step-2-configure-your-network-for-ucp)
- [Step 3: Install Docker CS Engine 1.9](#step-3-install-docker-cs-engine) - [Step 3: Install Docker CS Engine on each node](#step-3-install-docker-cs-engine-on-each-node)
- [Step 4: (optional) Create user-named volumes](#step-4-optional-create-user-named-volumes) - [Step 4: Create user-named volumes](#step-4-customize-user-named-volumes-optional)
- [Step 5: Install the UCP controller](#step-5-install-the-ucp-controller) - [Step 5: Customize the CA used](#step-5-customize-the-ca-used-optional)
- [Step 6: (optional) Add a controller replica to the UCP cluster](#step-6-optional-add-a-controller-replica-to-the-ucp-cluster) - [Step 6: Install the UCP controller](#step-6-install-the-ucp-controller)
- [Step 7: Add an Engine node to the UCP cluster](#step-7-add-an-engine-node-to-the-ucp-cluster) - [Step 7: Add controller replicas to the UCP cluster](#step-7-add-controller-replicas-to-the-ucp-cluster)
- [Step 8: Set up certs for the Docker CLI](#step-8-set-up-certs-for-the-docker-cli) - [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)
- [Uninstall](#uninstall) - [Uninstall](#uninstall)
- [Block Mixpanel analytics](#block-mixpanel-analytics)
- [Installing with your own certificates](#installing-with-your-own-certificates)
- [Where to go next](#where-to-go-next) - [Where to go next](#where-to-go-next)
**Upgrade Note**: If you have installed UCP 0.6.0 or higher, you can upgrade to UCP 0.7.0 using the [upgrade](reference/upgrade.md) command. ## About these installation instructions
These installation instructions were written using Ubuntu 14.0.3 running on
Amazon AWS, with Elastic IPs configured for all the hosts.
If you're installing UCP on another operating system, the paths and commands
might differ.
## Step 1: Prepare your installation
Before installing UCP, read the
[Plan a production installation](plan-production-install.md) guide.
If you haven't read the planning guide stop here, and go read it first.
There you'll find more information about the architecture of UCP, and the
requirements to install UCP for production.
## Plan your installation
The UCP installation consists of using the Docker Engine CLI to run the `ucp` The UCP installation consists of using the Docker Engine CLI to run the `ucp`
tool. The `ucp` tool is an image with subcommands to `install` a controller or tool. The `ucp` tool is a Docker image that can run subcommands like `install`
`join` a node to a UCP controller. The general format of these commands are: to install UCP on a node, or `join` to join a node to a UCP cluster.
The general format of these commands is:
| Docker client | `run` command with options | `ucp` image | Subcommand with options | | Docker client | run command with options | ucp image | Subcommand with options |
|---------------|----------------------------|--------------|-------------------------| |:--------------|:-------------------------|:-------------|:------------------------|
| `docker` | `run --rm -it` | `docker/ucp` | `install --help` | | `docker` | `run --rm -it` | `docker/ucp` | `install --help` |
| `docker` | `run --rm -it` | `docker/ucp` | `join --help` | | `docker` | `run --rm -it` | `docker/ucp` | `join --help` |
| `docker` | `run --rm -it` | `docker/ucp` | `uninstall --help` | | `docker` | `run --rm -it` | `docker/ucp` | `uninstall --help` |
You can these two subcommands interactively by passing them the `-i` You can use the `ucp` tool interactively, by passing them the `-i` option, or
option or by passing command-line options. This installation guide's steps non-interactively, by passing command-line options. This guide uses the
assume both are run interactively. interactive version.
To list all the possible subcommands, use: To list all the possible subcommands for the `ucp` tool, use:
```
$ docker run --rm -it docker/ucp --help
```
### Default versus the custom installation options
This installation guide walks you through
* configures data volumes on the controller
* generates a certificate chain on the controller
* creates a Swarm cluster
* loads and launches the appropriate images
Regardless of how you use the `docker/ucp install` command, the installer $ docker run --rm -it docker/ucp --help
supplies some quick default options for both data volumes and the certificate
authority (CA).
The first time you install, you should build a sandbox environment using
`ucp` defaults. After installing and using this sandbox environment,
you can uninstall it and try a custom installation. In a custom installation you
can:
* use the high availability feature
* customize the port used by the UCP web application
* customize the port used by the Swarm manager
* create your own data volumes
* use your own certs
This install documentation describes the default installation and the
customization steps. Customize steps are identified with the keyword
(optional). Make sure you skip these steps when doing the default installation
in your sandbox.
### IP addresses and fully-qualified domain names
The `docker/ucp install` subcommand works to do as much network discovery as it
can. If your network configuration defines fully-qualified domain names (FQDN)
on each host, the installer uses this information to obtain accurate host
addresses. If you haven't set up your network with FQDNs and the installer
discovery fails, you must supply the installer an accessible host address either
interactively or using the `--host-address` option.
If you are using a cloud provider such as AWS or Digital Ocean, you may need to
allocate 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)
Further, UCP requires that all clients, including the Docker Engine, use a Swarm
TLS certificate chain signed by the UCP Swarm Root CA. You provide the
certificate system with subject alternative names or SANs. The SANs are used to
set up individual "leaf certificates."
For the controller and each node, you must specify at least one SAN; you can
specify more. You can pass the `--san` values to the boostrapper's `install` or
`join`. A SAN value can be the pubic IP address and/or fully-qualified domain
name.
If you are using a cloud provider and specified private IPs for the host address
values, consider whether you need to access your cluster through a public
network as well as the private network space. If the answer is yes, your SAN
values should contain both the public IPs or full-qualified domain names (FQDN) and the private network IPs.
### Mixpanel analytics
The UCP BETA program makes use of Mixpanel to collect analytics. This feature
collects data on your usage of UCP and returns it to Docker. The information is
entirely anonymous and does not identify your Company or users. Currently, you
cannot turn the collection off but you can block the outgoing messaging. Later
in this documentation [Block Mixpanel analytics](#block-mixpanel-analytics)
explains how.
### About these installation instructions
These installation instructions were written using the Ubuntu 14.0.3 operating
system. The file paths and commands used in the instructions are specific to
Ubuntu 14.0.3. If you are installing on another operating system, the steps are
the same but your commands and paths may differ.
The Ubuntu system used to write these instructions was an AWS EC2 instance. The
instance was running in a in an AWS virtual private network. Elastic IPs were
configured for all the hosts.
## Step 1: Verify you have the prerequisites
You can install UCP on your network or on a cloud provider such AWS or Digital
Ocean. To install, the controller and the nodes require a minimum of 1.50 GB of memory. You can run any of these supported operating systems:
* RHEL 7.0, 7.1
* Ubuntu 14.04 LTS
* CentOS 7.1
Your system must have a 3.16.0 kernel or higher. If you don't have the proper kernel installed, the `docker/ucp install` command returns this error.
```
INFO[0000] Verifying your system is compatible with UCP
FATA[0000] Your kernel version 3.13.0 is too old. UCP requires at least version 3.16.0 for all features to work. To proceed with an old kernel use the '--old-kernel' flag
```
If you proceed with the '--old-kernel' flag, you cannot use the Docker custom networking features.
Installing Docker UCP requires that you first install the CS Docker Engine v1.9
on both the controller and the nodes. The CS Engine can be installed manually or
from an image if your cloud provider support its. These instructions assume you
are installing both UCP and Engine manually.
## Step 2: Configure your network for UCP ## Step 2: Configure your network for UCP
UCP includes Docker Swarm as part of its installation. So, you don't need to Before installing UCP, you need to make sure all nodes in the cluster can
install Docker Swarm. You do need to ensure that the UCP controller and nodes communicate. Configure your network to make sure these ports are open:
can communicate across your network. Configure your network making sure to open
the following ports:
<table> | Hosts | Direction | Port | Purpose |
<tr> |:----------------------------|:---------:|:--------------------|:------------------------------------------------------------|
<th>Port</th> | controller, replicas | in | 443 (configurable) | web app and CLI client access to UCP. |
<th>Description</th> | controller, replicas | in | 2376 (configurable) | swarm manager accepts requests from UCP controller. |
</tr> | controller, replicas, nodes | in | 2375 | heartbeat for nodes, to ensure they are running. |
<tr> | controller, replicas, nodes | in | 12376 | proxy for TLS, provides access to UCP, Swarm, and Engine. |
<td><code>443</code> </td> | controller, replicas | in | 12379 | internal node configuration, cluster configuration, and HA. |
<td>UCP controller port. Open this port to allow inbound access to the UCP interface or CLI.</td> | controller, replicas | in | 12380 | internal node configuration, cluster configuration, and HA. |
</tr> | controller | in | 12381 | proxy for TLS, provides access to UCP. |
<tr> | controller | in | 12382 | manages TLS and requests from swarm manager. |
<td><code>2376</code></td> | controller, replicas | out | 80 | send anonymous usage reports to Docker. |
<td>Allows inbound access from the nodes to the Swarm manager.</td>
</tr>
<tr>
<td><code>12376</code></td>
<td>Open this on secondary nodes to allow the Engine proxy to access the Orca server node.</td>
</tr>
<tr>
<td><code>12379</code>, <code>12380</code></td>
<td>Key Value store </td>
</tr>
<tr>
<td><code>12381</code></td>
<td>Swarm CA service</td>
</tr>
<tr>
<td><code>12382` </td>
<td>UCP CA service</td>
</tr>
</table>
Some of the ports used, are customizable. Check the
[UCP install command reference](reference/install.md) for more
information on this. This guide uses the default ports.
All the communication among the controller, nodes, and key value store is ## Step 3: Install Docker CS Engine on each node
protected by mutual TLS. The UCP installation of Swarm provides and configures
TLS for you automatically.
Finally, you can specify a different port for the Swarm manager if you need to. UCP requires you to install Docker CS Engine 1.10 or above on all nodes of
Using a different port is a customization. These instructions assume you are using the default `2376` port. your UCP cluster, including the controller node.
## Step 3: Install Docker CS Engine For each node, follow the Docker CS Engine installation instructions for your
particular operating system:
The BETA program requires that you install the Docker CS Engine 1.9.0 or above. * [Red Hat Linux installation
Follow the instructions for your particular operating system and ensure
you are pointing at the proper repo.
Install the Docker CS Engine on both the controller node and each member node.
### RHEL 7.0, 7.1 and CentOS 7.1
Use the detailed [Red Hat Linux installation
instructions](https://docs.docker.com/docker-trusted-registry/install/install-csengine/#centos-7-1-rhel-7-0-7-1-yum-based-systems) instructions](https://docs.docker.com/docker-trusted-registry/install/install-csengine/#centos-7-1-rhel-7-0-7-1-yum-based-systems)
* [Ubuntu installation
### Ubuntu 14.04 LTS
Use the [detailed Ubuntu installation
instructions](https://docs.docker.com/docker-trusted-registry/install/install-csengine/#install-on-ubuntu-14-04-lts) instructions](https://docs.docker.com/docker-trusted-registry/install/install-csengine/#install-on-ubuntu-14-04-lts)
## Step 4: Customize user-named volumes (optional)
## Step 4: (optional) Create user-named volumes UCP uses named volumes to persist user data:
UCP uses named volumes for persistence of user data. By default, the `ucp
install` command creates for you. It uses the default volume driver and flags.
The first time you install, you should skip this step and try it later. Later,
try an install where your take the option to use custom volume driver and create
your own volumes.
If you choose this option, create your volumes prior to installing UCP. The
volumes UCP requires are:
| Volume name | 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-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-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-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-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-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-swarm-controller-certs | The UCP Controller Swarm client certificates for the current node. |
| `ucp-kv` | Key value store persistence. | | ucp-kv | Key value store persistence. |
## Step 5: Install the UCP controller The `ucp install` command creates these volumes for you with the default
volume driver and flags.
If you want to use custom volume drivers, create these named-volumes before
installing UCP.
In this step you install the UCP controller. The controller includes a running
Swarm manager and node as well. Use the following command to pull the
`docker/ucp` image and review the `install` options:
```bash ## Step 5: Customize the CA used (optional)
docker run --rm -it docker/ucp install --help
```
When you install, the script prompts you for the following information: To protect your UCP cluster against unauthorized access, all components of
the cluster use mutual TLS. That way, for two components to talk, both need
to identify using certificates.
* a password to use for the UCP `admin` account For this, UCP uses two different root Certificate Authorities:
* at lease one SAN value which is the accessible IP address or fully-qualified domain name for the controller node
When you have the information you'll be prompted for, do the following to * One CA is used to secure and authenticate the communications between
install: users and UCP,
* Another CA is used to secure the communications between all nodes that are
part of your UCP cluster.
1. Log into the system where you mean to install the UCP controller. All this is done automatically when installing UCP.
If you are installing on a cloud provider such as AWS, make sure the instance has a public IP or hostname. You can also customize UCP to use certificates signed by an external
Certificate Authority, for the UCP controller. That way you can
use a certificate from a CA that your browsers and client tools already trust.
![Open certs](images/ip_cloud_provider.png) To install UCP with your own external root CA:
1. Log into the machine where you intend to install UCP.
2. Make sure you have created a named volume called `ucp-server-certs`.
3. Add the following files to the volume's top-level directory:
| File | Description |
|:---------|:---------------------------------------------------------------|
| ca.pem | Your Root CA Certificate chain (including any intermediaries). |
| cert.pem | Your signed UCP controller certificate. |
| key.pem | Your UCP controller private key. |
## Step 6: Install the UCP controller
During UCP installation, you will be prompted for the following information:
* A password to use for the UCP `admin` account.
* At least one Subject Alternative Name (SAN). This is the IP address or
fully-qualified domain name where you can reach this controller.
Be sure to have this information at hand before starting the installation.
If you're installing UCP on a cloud provider such as AWS, make sure your
instance has a public IP or hostname, as displayed below.
![Controller public IP on AWS](images/ip_cloud_provider.png)
On the controller node, install UCP:
1. Review the options available on the `ucp install` command.
$ docker run --rm -it docker/ucp install --help
You can also find the documentation for these option on
the [UCP install command reference](reference/install.md).
2. Run the `ucp` command interactively. 2. Run the `ucp` command interactively.
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp install -i $ docker run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp install -i
The command pulls several images and prompts you for the installation values it needs. When it completes, the command prompts you to login into the UCP GUI. If you are using an external CA, include the `--external-ucp-ca` option at
the end of the command.
The command pulls several images from Docker Hub, and prompts you for the
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://10.0.0.32:443
3. Enter the address into your browser to view the UCP login screen. 3. Enter the address in your browser to navigate to the UCP login screen.
Your browser may warn you about the connection. The warning appears because Your browser may warn that the connection to UCP is not secure. The warning
the UCP certificate was issued by a built-in certificate authority. Your appears because you are accessing UCP using HTTPS, but the certificates used
actions with the install actually created the certificate. If you are by UCP were issued during the installation by a built-in certificate
concerned, the certificate's fingerprint is displayed during install and you authority.
can compare it.
4. Use the Advanced link to proceed to UCP. If you're concerned about security, check the installation messages.
You can use the server fingerprint displayed during the installation,
and compare it with the certificate displayed on your browser.
The login screen displays. 4. Accept the security warning to proceed to UCP.
![](images/login.png) ![UCP Login screenshot](images/login.png)
5. Enter `admin` for the username along with the password you provided to the `install`. 5. Login with the admin username and the password you provided during
the installation.
If you didn't enter an admin password, the default password is `orca` After After logging in, you are redirected to the UCP dashboard. It should show
you enter the correct credentials, the UCP dashboard displays. that there's only a single node in your cluster: the controller node.
![](images/dashboard.png) ![UCP dashboard screenshot](images/dashboard.png)
The dashboard shows a single node, your controller node. ## Step 7: Add controller replicas to the UCP cluster
## Step 6: (optional) Add a controller replica 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
across the controller and replica nodes.
In this optional step, you configure support for UCP's high-availability For High Availability (HA) installations:
feature. You do this by adding one or more UCP *replicas* using the `docker/ucp
join` subcommand. The first time you install, you should skip this optional
step and try it later. Later, try an install where you configure
high-availability.
When adding nodes to your cluster, you decide which nodes you to use as * Configure the controller and replicas before adding additional nodes
*replicas* and which nodes are simply for extra capacity. A to the cluster.
replica is a node in your cluster that can act as an additional UCP controller. * Configure at least two replicas in addition to the controller.
Should the primary controller fail, a replica can take over the controller role
for the cluster. If you are trying out the optional HA deployment:
* Configure the controller and replicas before adding additional Engine nodes. Keep in mind that with N controller and replicas, a cluster can only
* Configure a minimum of two replicas in addition to the controller. tolerate up to (N-1)/2 node failures.
Repeat the install for each node you want to add. Use the following command to pull the `docker/ucp` image and review the `join` options: Also, in UCP v1.0 the controller serves as root CA. During a controller
failure, it might not be possible to add more nodes to the cluster.
[Learn more about high availability](understand_ha.md).
```bash When adding replica nodes to your installation, you will be prompted for
docker run --rm -it docker/ucp join --help the following information:
```
The `docker/ucp join` prompts you for the following information: * The URL of the UCP controller node, for example `https://52.70.188.239`.
* The username/password of an UCP administrator account.
* At least one SAN value which is an accessible IP address or
fully-qualified domain name for the node.
* the URL of the UCP controller, for example `https://52.70.188.239` Be sure to have this information at hand before using the `ucp join`
* the username/password of an UCP administrator account command to join the replica nodes to the cluster.
* at least one SAN value which is an accessible IP address or fully-qualified domain name for node
When you have the information you'll be prompted for, do the following to install: Review the options available on the `ucp join` command.
1. Log into the host where you mean to install the node. $ docker run --rm -it docker/ucp join --help
2. Run the `dokcer/ucp join` command. You can also find the documentation for the `ucp join` command at
the [UCP join command reference](reference/join.md) page.
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join --replica -i For each node that you want to turn into a controller replica:
The `join` pulls several images and prompts you for the installation values 1. Log into that node.
it needs. When it completes, the command notifies you that it is starting
swarm. 2. Run the `ucp join` command:
$ docker run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp join --replica -i
The `join` command pulls several images and prompts you for the
installation values it needs. When it completes, the command notifies
you that it is starting Docker Swarm.
INFO[0005] Verifying your system is compatible with UCP INFO[0005] Verifying your system is compatible with UCP
INFO[0011] Sending add host request to UCP server INFO[0011] Sending add host request to UCP server
INFO[0011] Starting local swarm containers INFO[0011] Starting local swarm containers
3. Repeat steps 1 thru 3 on the other replicas. 3. Repeat steps 1 through 3 on the other nodes you want to set up as replicas.
You should configure a minimum of 3 controllers configured, a primary and For high availability, make sure to configure a minimum of 3 controllers:
two replicas. Never run a cluster with only the primary controller and a a primary controller and two replicas. Never run a cluster with only
single replica. the primary controller and a single replica.
4. Login into UCP with your browser and navigate to the **NODES** page. 4. Log into UCP with your browser and navigate to the **Nodes** page.
Simply clicking on the nodes from the Dashboard takes you to the page. The page should display your new nodes. The nodes page should now display your new replica nodes.
![](images/nodes.png) ![UCP nodes page](images/nodes.png)
## Step 7: Add an Engine node to the UCP cluster ## Step 8: Add more nodes to the UCP cluster
In this step, you install one or more UCP nodes using the `ucp join` subcommand. Repeat the install for each node you want to add. Use the following command to pull the `docker/ucp` image and review the `join` options: Now you can add additional nodes to your UCP cluster. These are the nodes that
will be running your containers.
```bash When adding nodes to your cluster, you will be prompted for the following
docker run --rm -it docker/ucp join --help information:
```
The `docker/ucp join` command prompts you for the following 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
address or fully-qualified domain name for node.
* the URL of the UCP controller, for example `https://52.70.188.239` So be sure to have this information at hand. If you're installing UCP on a cloud
* the username/password of an UCP administrator account provider such as AWS, make sure your instance has a public IP or hostname.
* at least one SAN value which is the actual external, publically-accessible IP address or fully-qualified domain name for node
When you have the information you'll be prompted for, do the following to install: Review the options available on the `ucp join` command:
1. Log into the system where you mean to install the node. $ docker run --rm -it docker/ucp join --help
2. Run the `docker/ucp join` command. You can also find the documentation for the `ucp join` command on
the [UCP join command reference](reference/join.md) page.
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join -i For each node that you want to add to your UCP cluster:
The `join` pulls several images and prompts you for the installation values it needs. When it completes, the command notifies you that it is starting Swarm. 1. Log into that node.
2. Run the `ucp join` command.
$ docker run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp join -i
The `join` command pulls several images and prompts you for the
installation values it needs. When it completes, the command notifies
you that it is starting Docker Swarm.
INFO[0005] Verifying your system is compatible with UCP INFO[0005] Verifying your system is compatible with UCP
INFO[0011] Sending add host request to UCP server INFO[0011] Sending add host request to UCP server
INFO[0011] Starting local swarm containers INFO[0011] Starting local swarm containers
3. Repeat steps 1 thru 2 on the other nodes. 3. Repeat steps 1 and 2 on the other nodes you want to add to your UCP cluster.
4. Login into UCP with your browser and navigate to the **NODES** page. 4. Log into UCP with your browser and navigate to the **Nodes** page.
Simply clicking on the nodes from the Dashboard takes you to the page. The page should display your new nodes. The nodes page should now display your new replica nodes.
![](images/nodes.png) ![UCP nodes page](images/nodes.png)
## Step 8: Set up certs for the Docker CLI ## Step 9: Set up certificates for the Docker CLI
Once you install UCP on a machine, it is a good idea to download a client bundle. The bundle contains the certificates a user needs to run the Docker Engine command line client (`docker`) against the UCP controller and nodes. After installing UCP, you can run the `docker` command, against UCP
cluster nodes.
Since all traffic between users and UCP nodes is secure and authenticated,
when using the Docker CLI client, you'll need to provide client certificates.
You can download the bundle from the UCP interface or using `curl` command. The You have two ways of downloading a bundle that contains the client certificates
bundle is in a `.zip` package. You need `zip` or similar to unzip the file. If you plan to use `curl` you also need JQuery. This is used to pass the `curl` for a user:
command an authorization token. Of course, you need to have `curl` installed as well.
### Download the bundle from the UCP interface - Download them from the UCP web app, or
- Download them from the REST API, using the `curl` command.
### Download the client bundle from the UCP web app
1. If you haven't already done so, log into UCP. 1. If you haven't already done so, log into UCP.
2. Choose **ADMIN > Profile** from the right-hand menu. 2. Navigate to your profile.
Any user can download their certificates. So, if you were logged in under a user name such as `davey` the path to download bundle is **davey > Profile**. Since you are logged ins as `ADMIN`, the path is `ADMIN`. As an example, if you're logged in as the `Admin` user,
on the right-hand menu, navigate to **Admin > Profile**.
3. Click **Create Client Bundle**. 3. Click the **Create Client Bundle** button.
The browser downloads the `ucp-bundle-admin.zip` file. The browser downloads the `ucp-bundle-admin.zip` file.
### Download the bundle with curl ### Download the client bundle using the REST API
1. Log into a machine with network access to the UCP controller. You can download the client certificate bundle, using the UCP REST API. In
this example we'll be using `curl` for making the web requests to the API, and
`jq` to parse the responses from the API.
You might log into the controller itself. You could also log into any arbitrary machine able to `ping` the controller. 1. In the command line, log into a machine with network access to
the UCP controller.
2. Install the prerequisite `curl`, `zip`, `jq` (JQuery) packages if you haven't already. You might log into the controller node itself, or any machine that
can `ping` it.
2. Install the `curl`, `zip`, `jq` packages if you don't have them.
On Ubuntu, the installation looks like this: On Ubuntu, the installation looks like this:
```
$ sudo apt-get install zip curl jq $ sudo apt-get install zip curl jq
Reading package lists... Done Reading package lists... Done
Building dependency tree Building dependency tree
@ -487,18 +387,20 @@ command an authorization token. Of course, you need to have `curl` installed as
The following packages will be upgraded: The following packages will be upgraded:
curl libcurl3 curl libcurl3
----output snipped---- ----output snipped----
```
To curl the bundle, you must export your user security token from the UCP controller. You do this in the next step.
3. Create an environment variable to hold your user security token. 3. Create an environment variable to hold your user security token.
AUTHTOKEN=$(curl -sk -d '{"username":"admin","password":"<password>"}' https://<ducp-0 IP>/auth/login | jq -r .auth_token) To connect to the UCP controller with `curl`, you must export your user
security token from the UCP controller.
$ AUTHTOKEN=$(curl -sk -d '{"username":"admin","password":"<password>"}' https://<ducp-0 IP>/auth/login | jq -r .auth_token)
4. Curl the client bundle down to your node. 4. Curl the client bundle down to your node.
$ curl -k -H "Authorization: Bearer $AUTHTOKEN" https://<ducp-0 IP>/api/clientbundle -o bundle.zip $ curl -k -H "Authorization: Bearer $AUTHTOKEN" https://<ducp-0 IP>/api/clientbundle -o bundle.zip
The browser downloads a `bundle.zip` file. Curl downloads a `bundle.zip` file to your working directory.
### Install the certificate bundle ### Install the certificate bundle
@ -515,19 +417,23 @@ Once you download the bundle, you can unzip and use it.
4. Unzip the file to reveal its contents. 4. Unzip the file to reveal its contents.
```bash
ucp-bundle ucp-bundle
├── ca.pem ├── ca.pem
├── cert.pem ├── cert.pem
├── cert.pub ├── cert.pub
├── env.sh ├── env.sh
└── key.pem └── key.pem
```
5. Set up your environment by sourcing the `env.sh` file. 5. Set up your environment by running the `env.sh` file.
$ source env.sh $ source env.sh
6. Use the `docker info` command to get the location of the Swarm managers and engines. 6. Use the `docker info` command to get the location of the Swarm
managers and engines.
```
$ docker info $ docker info
Containers: 9 Containers: 9
Images: 9 Images: 9
@ -553,143 +459,98 @@ Once you download the bundle, you can unzip and use it.
com.docker.ucp.license_key=unlicensed com.docker.ucp.license_key=unlicensed
com.docker.ucp.license_max_engines=0 com.docker.ucp.license_max_engines=0
com.docker.ucp.license_expires=EXPIRED com.docker.ucp.license_expires=EXPIRED
```
### Client Bundles on Externally Managed CA Configuration ### Client bundles with an externally managed CA
If UCP is configured with an external CA, it will be unable to sign client bundles for non-admin users automatically. It is still possible to manually issue certificates signed by the CA that UCP users can use to interact with UCP via the CLI. When using UCP with an external Certificate Authority, client bundles
for non-admin users won't be signed automatically. It is still possible to
manually issue certificates signed by the Certificate Authority, that UCP users
can use to interact with UCP with the CLI client.
Generate an 2048-bit RSA private key. 1. Generate a 2048-bit RSA private key.
``` $ openssl genrsa -out key.pem 2048
openssl genrsa -out key.pem 2048
```
Generate a Certificate Signing Request (CSR). The output `cert.csr` should be provided to your organization's CA owner to be signed, with a minimum of client authentication usage. 2. Generate a Certificate Signing Request (CSR).
``` The output `cert.csr` should be provided to your organization's CA
openssl req -new -sha256 -key key.pem -out cert.csr owner to be signed, with a minimum of client authentication usage.
```
Your CA owner will sign the CSR, and provide `cert.pem` and `ca.pem` files. $ openssl req -new -sha256 -key key.pem -out cert.csr
Extract the public key from the signed certificate:
``` 3. Your CA owner signs the CSR, and provides the `cert.pem` and `ca.pem` files.
openssl x509 -pubkey -noout -in cert.pem > cert.pub
```
The contents of cert.pub will then need to be added to your profile. You can add this in the UI by clicking the User Menu in the top right corner, and select profile. 4. Extract the public key from the signed certificate:
Once you are on the User Profile screen, click the "Add an Existing Public Key" button and provide the contents of cert.pub, along with a memorable label for this bundle. $ openssl x509 -pubkey -noout -in cert.pem > cert.pub
Now that you have linked the public key to you account, the next step is to configure your CLI. To configure your CLI to use the certificate bundle that you have generated, you will need to export the following environment variables: 5. Add the content of the `cert.pub` to your UCP profile.
``` In the UCP web app, navigate to your **profile**, and click the **Add an
export DOCKER_TLS_VERIFY=1 Existing Public Key** button.
export DOCKER_CERT_PATH=$(pwd)
export DOCKER_HOST=tcp://<ucp-hostname>:443 ![Add public key](images/add-pk.png)
```
Set a name, and the contents of the `cert.pub` file.
6. Set the necessary environment variables.
Now that you have linked the public key to you account, you need to
configure your CLI client. Set the following environment variables:
```
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=$(pwd)
export DOCKER_HOST=tcp://<ucp-hostname>:443
```
## Disable usage reporting
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.
To disable usage reporting:
1. Log into Docker UCP
2. Navigate to the **Settings** screen
3. In the **Anonymous Usage Reporting** section, toggle:
* Enable hourly usage reporting, to send sending usage reports.
* Enable API tracking, to send sending metrics on each API call.
4. Click the **Update Usage Reporting** button, to save your changes.
## Uninstall ## Uninstall
The `docker/ucp uninstall` command removes UCP from the controller and the nodes. The uninstall process does not remove any other containers that are running, except those recognized to be part of UCP. To see the `uninstall` options before you uninstall, use the following: To uninstall Docker UCP, use the `ucp uninstall` command. This command only
removes the UCP containers, and doesn't affect any other containers.
When uninstalling UCP from a cluster, leave the UCP controller node for last.
```bash Review the options available on the `ucp uninstall` command.
docker run --rm -it docker/ucp uninstall --help
```
To uninstall, do the following: $ docker run --rm -it docker/ucp uninstall --help
1. Log into the node you want to remove UCP from. You can also find the documentation for the `ucp uninstall` command at
the [UCP uninstall command reference](reference/uninstall.md) page.
2. Enter the following command to uninstall: To uninstall UCP from a node:
1. Login into the node you want to remove UCP from
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
3. Repeat the uninstall on each node making sure to save the controller till last. 3. Repeat steps 1 and 2 on each node of the cluster. Make sure to save
the controller for last.
## Block Mixpanel analytics
To block the outflow of Mixpanel analytic data to Docker, do the following:
1. Log into the system running the UCP controller.
2. Add a rule to drop the forward to port 80.
$ iptables -I FORWARD -p tcp --dport 80 -j DROP
Reboots unset this iptables chain, so it is a good idea to add this command to the controller's startup script.
## Installing with your own certificates
UCP uses two separate root CAs for access control - one for Swarm, and one for
the UCP controller itself. The dual root certificates supply differentiation
between the Docker remote API access to UCP vs. Swarm. Unlike Docker Engine or
Docker Swarm, UCP implements ACL and audit logging on a per-user basis. Swarm
and the Engine proxies trust only the Swarm Root CA, while the UCP controller
trusts both Root CAs. Admins can access UCP, Swarm and the engines while
normal users are only granted access to UCP.
UCP v1.0 supports user provided externally signed certificates
for the UCP controller. This cert is used by UCP's main management web UI
and the Docker remote API. The remote API is visible to the Docker CLI. In this release, the Swarm Root CA is always managed by UCP.
The external UCP Root CA model supports customers managing their own CA, or
purchasing certs from a commercial CA.
The first time you install, we recommend you skip user-supplied certs and use
the default certificates instead. The default TLS certificate files are placed
on the host filesystem of each Docker Engine in
`/var/lib/docker/discovery_certs/`. Later, do a second install and try the
option to use your own certs.
### Configure user-supplied Certificates
To install UCP with your own external root CA, you create a named volume called
**ucp-server-certs** on the same system where you plan to install the UCP
controller.
1. Log into the machine where you intend to install UCP.
2. If you haven't already done so, create a named volume called **ucp-server-certs**.
3. Ensure the volume's top-level directory contains these files:
<table>
<tr>
<th>File</th>
<th>Description</th>
</tr>
<tr>
<td><code>ca.pem</code></td>
<td>Your Root CA Certificate chain (including any intermediaries).</td>
</tr>
<tr>
<td><code>cert.pem</code></td>
<td>Your signed UCP controller cert.</td>
</tr>
<tr>
<td><code>key.pem</code></td>
<td>Your UCP controller private key.</td>
</tr>
</table>
4. Follow "Step 5" above to install UCP but pass in an additional `--external-ucp-ca` option to the `docker/run install`, for example:
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
...snip...
install -i --external-ucp-ca
## Where to go next ## Where to go next
To learn more you can also investigate: * 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 product](https://www.docker.com/universal-control-plane). * Read more [about the Docker CLI client](http://docs.docker.com/reference/commandline/cli/)
* Visit the UCP forum to [ask questions and get answers](https://forums.docker.com/c/commercial-products/ucpbeta). * Learn [about Docker Swarm](http://docs.docker.com/swarm/)
* Try the [UCP hands-on lab](https://github.com/docker/ucp_lab).
* [How to use the Docker Client](http://docs.docker.com/reference/commandline/cli/)
* [An overview of Docker Swarm](http://docs.docker.com/swarm/)
<![end-metadata]-->