mirror of
https://github.com/docker/docs.git
synced 2026-11-05 00:14:17 +03:00
Block out initial organization for GA docs
Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony
committed by
Joao Fernandes
Joao Fernandes
parent
31a02d6fd4
commit
e040139d6b
6
certs.md
6
certs.md
@@ -1,11 +1,13 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Manually setting up a CA"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# Manually setting up a CA
|
||||
# Manually set up a Certificate Authority
|
||||
|
||||
A few features of UCP require an external CA (cfssl or equivalent) to sign
|
||||
certs. By default in developer mode, these services aren't created (maybe we'll
|
||||
|
||||
46
deploy-application.md
Normal file
46
deploy-application.md
Normal file
@@ -0,0 +1,46 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Deploy an application thru UCP"
|
||||
description = "Deploy an application thru UCP"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
weight=-80
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# Deploy an application thru UCP
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
## Understand the development workflow
|
||||
Diagram of expected workflow
|
||||
|
||||
## Step 1: Review the Compose file node requirements
|
||||
* images
|
||||
* nodes
|
||||
* volumes
|
||||
* networks
|
||||
|
||||
## Step 2: Add nodes for supporting application
|
||||
|
||||
tbd
|
||||
|
||||
## Step 3: Import Compose file into UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Step 4: Scaling an application
|
||||
* existing load balancer
|
||||
* adding a load balancer
|
||||
|
||||
## Step 4: Verify the deployment
|
||||
* Dashboard
|
||||
* Images
|
||||
|
||||
## Step 5: Review UCP logs
|
||||
|
||||
tbd
|
||||
|
||||
## Troubleshooting section
|
||||
707
evaluation-install.md
Normal file
707
evaluation-install.md
Normal file
@@ -0,0 +1,707 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Evaluation installation"
|
||||
description = "Evaluation installation"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
weight=-100
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# Evaluation installation
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
## Step 1: Learn a little about UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Step 2: Verify you have the prerequisites
|
||||
|
||||
tbd
|
||||
|
||||
## Step 3: Install the CS Engine AMI
|
||||
|
||||
tbd
|
||||
|
||||
## Step 4: Install the UCP controller
|
||||
|
||||
tbd
|
||||
|
||||
## Step 5: Install a License
|
||||
|
||||
tbd
|
||||
|
||||
## Step 6: Add an Engine node to the UCP cluster
|
||||
|
||||
tbd
|
||||
|
||||
## Step 7: Create a container network
|
||||
|
||||
tbd
|
||||
|
||||
## Step 8: Launch an application on your network
|
||||
|
||||
tbd
|
||||
|
||||
## Step 9: Try your application
|
||||
|
||||
tbd
|
||||
|
||||
## Step 11: Work with a client bundle
|
||||
|
||||
tbd
|
||||
|
||||
## Step 12: Challenge yourself
|
||||
|
||||
tbd
|
||||
|
||||
## Upgrade UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Where to Go Next
|
||||
|
||||
|
||||
<!--[metadata]>
|
||||
|
||||
Original Source
|
||||
|
||||
# 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 3: Install Docker CS Engine 1.9](#step-3-install-docker-cs-engine)
|
||||
- [Step 4: (optional) Create user-named volumes](#step-4-optional-create-user-named-volumes)
|
||||
- [Step 5: Install the UCP controller](#step-5-install-the-ucp-controller)
|
||||
- [Step 6: (optional) Add a controller replica to the UCP cluster](#step-6-optional-add-a-controller-replica-to-the-ucp-cluster)
|
||||
- [Step 7: Add an Engine node to the UCP cluster](#step-7-add-an-engine-node-to-the-ucp-cluster)
|
||||
- [Step 8: Set up certs for the Docker CLI](#step-8-set-up-certs-for-the-docker-cli)
|
||||
- [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)
|
||||
|
||||
**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.
|
||||
|
||||
## Plan your installation
|
||||
|
||||
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
|
||||
`join` a node to a UCP controller. The general format of these commands are:
|
||||
|
||||
| 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` | `join --help` |
|
||||
| `docker` | `run --rm -it` | `docker/ucp` | `uninstall --help` |
|
||||
|
||||
You can these two subcommands interactively by passing them the `-i`
|
||||
option or by passing command-line options. This installation guide's steps
|
||||
assume both are run interactively.
|
||||
|
||||
To list all the possible subcommands, 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
|
||||
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
|
||||
|
||||
UCP includes Docker Swarm as part of its installation. So, you don't need to
|
||||
install Docker Swarm. You do need to ensure that the UCP controller and nodes
|
||||
can communicate across your network. Configure your network making sure to open
|
||||
the following ports:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Port</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>443</code> </td>
|
||||
<td>UCP controller port. Open this port to allow inbound access to the UCP interface or CLI.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>2376</code></td>
|
||||
<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>
|
||||
|
||||
|
||||
All the communication among the controller, nodes, and key value store is
|
||||
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.
|
||||
Using a different port is a customization. These instructions assume you are using the default `2376` port.
|
||||
|
||||
## Step 3: Install Docker CS Engine
|
||||
|
||||
The BETA program requires that you install the Docker CS Engine 1.9.0 or above.
|
||||
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)
|
||||
|
||||
### 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)
|
||||
|
||||
|
||||
## Step 4: (optional) Create user-named volumes
|
||||
|
||||
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 |
|
||||
|-------------------------|--------------------------------------------------------------------------------------|
|
||||
| `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. |
|
||||
|
||||
## Step 5: Install the UCP controller
|
||||
|
||||
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
|
||||
docker run --rm -it docker/ucp install --help
|
||||
```
|
||||
|
||||
When you install, the script prompts you for the following information:
|
||||
|
||||
* a password to use for the UCP `admin` account
|
||||
* 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
|
||||
install:
|
||||
|
||||
1. Log into the system where you mean to install the UCP controller.
|
||||
|
||||
If you are installing on a cloud provider such as AWS, make sure the instance has a public IP or hostname.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Your browser may warn you about the connection. The warning appears because
|
||||
the UCP certificate was issued by a built-in certificate authority. Your
|
||||
actions with the install actually created the certificate. If you are
|
||||
concerned, the certificate's fingerprint is displayed during install and you
|
||||
can compare it.
|
||||
|
||||
4. Use the Advanced link to proceed to UCP.
|
||||
|
||||
The login screen displays.
|
||||
|
||||
|
||||
|
||||
5. Enter `admin` for the username along with the password you provided to the `install`.
|
||||
|
||||
If you didn't enter an admin password, the default password is `orca` After
|
||||
you enter the correct credentials, the UCP dashboard displays.
|
||||
|
||||
|
||||
|
||||
The dashboard shows a single node, your controller node.
|
||||
|
||||
## Step 6: (optional) Add a controller replica to the UCP cluster
|
||||
|
||||
In this optional step, you configure support for UCP's high-availability
|
||||
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
|
||||
*replicas* and which nodes are simply for extra capacity. A
|
||||
replica is a node in your cluster that can act as an additional UCP 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.
|
||||
* Configure a minimum of two replicas in addition to the controller.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp join --help
|
||||
```
|
||||
|
||||
The `docker/ucp join` 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 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:
|
||||
|
||||
1. Log into the host where you mean to install the node.
|
||||
|
||||
2. Run the `dokcer/ucp join` command.
|
||||
|
||||
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join --replica -i
|
||||
|
||||
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.
|
||||
|
||||
INFO[0005] Verifying your system is compatible with UCP
|
||||
INFO[0011] Sending add host request to UCP server
|
||||
INFO[0011] Starting local swarm containers
|
||||
|
||||
3. Repeat steps 1 thru 3 on the other replicas.
|
||||
|
||||
You should configure a minimum of 3 controllers configured, a primary and
|
||||
two replicas. Never run a cluster with only the primary controller and a
|
||||
single replica.
|
||||
|
||||
4. Login 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.
|
||||
|
||||
|
||||
|
||||
|
||||
## Step 7: Add an Engine node 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:
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp join --help
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
When you have the information you'll be prompted for, do the following to install:
|
||||
|
||||
1. Log into the system where you mean to install the node.
|
||||
|
||||
2. Run the `docker/ucp join` command.
|
||||
|
||||
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join -i
|
||||
|
||||
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.
|
||||
|
||||
INFO[0005] Verifying your system is compatible with UCP
|
||||
INFO[0011] Sending add host request to UCP server
|
||||
INFO[0011] Starting local swarm containers
|
||||
|
||||
3. Repeat steps 1 thru 2 on the other nodes.
|
||||
|
||||
4. Login 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.
|
||||
|
||||
|
||||
|
||||
## Step 8: Set up certs 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.
|
||||
|
||||
You can download the bundle from the UCP interface or using `curl` command. The
|
||||
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`
|
||||
command an authorization token. Of course, you need to have `curl` installed as well.
|
||||
|
||||
### Download the bundle from the UCP interface
|
||||
|
||||
1. If you haven't already done so, log into UCP.
|
||||
|
||||
2. Choose **ADMIN > Profile** from the right-hand menu.
|
||||
|
||||
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`.
|
||||
|
||||
3. Click **Create Client Bundle**.
|
||||
|
||||
The browser downloads the `ucp-bundle-admin.zip` file.
|
||||
|
||||
### Download the bundle with curl
|
||||
|
||||
1. Log into a machine with network access to the UCP controller.
|
||||
|
||||
You might log into the controller itself. You could also log into any arbitrary machine able to `ping` the controller.
|
||||
|
||||
2. Install the prerequisite `curl`, `zip`, `jq` (JQuery) packages if you haven't already.
|
||||
|
||||
On Ubuntu, the installation looks like this:
|
||||
|
||||
$ sudo apt-get install zip curl jq
|
||||
Reading package lists... Done
|
||||
Building dependency tree
|
||||
Reading state information... Done
|
||||
The following extra packages will be installed:
|
||||
libcurl3
|
||||
The following NEW packages will be installed:
|
||||
jq zip
|
||||
The following packages will be upgraded:
|
||||
curl libcurl3
|
||||
----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.
|
||||
|
||||
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.
|
||||
|
||||
$ curl -k -H "Authorization: Bearer $AUTHTOKEN" https://<ducp-0 IP>/api/clientbundle -o bundle.zip
|
||||
|
||||
The browser downloads a `bundle.zip` file.
|
||||
|
||||
### Install the certificate bundle
|
||||
|
||||
Once you download the bundle, you can unzip and use it.
|
||||
|
||||
1. Make sure you have `zip` installed.
|
||||
|
||||
$ which unzip
|
||||
/usr/bin/unzip
|
||||
|
||||
If you don't, install it before continuing.
|
||||
|
||||
2. Open the folder containing the bundle file.
|
||||
|
||||
4. Unzip the file to reveal its contents.
|
||||
|
||||
ucp-bundle
|
||||
├── ca.pem
|
||||
├── cert.pem
|
||||
├── cert.pub
|
||||
├── env.sh
|
||||
└── key.pem
|
||||
|
||||
5. Set up your environment by sourcing the `env.sh` file.
|
||||
|
||||
$ source env.sh
|
||||
|
||||
6. Use the `docker info` command to get the location of the Swarm managers and engines.
|
||||
|
||||
$ docker info
|
||||
Containers: 9
|
||||
Images: 9
|
||||
Role: primary
|
||||
Strategy: spread
|
||||
Filters: health, port, dependency, affinity, constraint
|
||||
Nodes: 1
|
||||
node1: 192.168.122.7:12376
|
||||
└ Containers: 9
|
||||
└ Reserved CPUs: 0 / 1
|
||||
└ Reserved Memory: 0 B / 2.054 GiB
|
||||
└ Labels: executiondriver=native-0.2, kernelversion=4.0.9-boot2docker, operatingsystem=Boot2Docker 1.8.1 (TCL 6.3); master : eb5571f - Thu Sep 3 22:18:54 UTC 2015, provider=kvm, storagedriver=aufs
|
||||
Cluster Managers: 1
|
||||
192.168.122.7: Healthy
|
||||
└ Orca Controller: https://192.168.122.7
|
||||
└ Swarm Manager: tcp://192.168.122.7:3376
|
||||
└ KV: etcd://192.168.122.7:12379
|
||||
CPUs: 1
|
||||
Total Memory: 2.054 GiB
|
||||
Name: node1
|
||||
ID: PNLT:MFCO:DDWL:MSLF:YVHU:35Z3:66KM:DFZM:OPBK:D4BQ:EKNT:6DXA
|
||||
Labels:
|
||||
com.docker.ucp.license_key=unlicensed
|
||||
com.docker.ucp.license_max_engines=0
|
||||
com.docker.ucp.license_expires=EXPIRED
|
||||
|
||||
### Client Bundles on Externally Managed CA Configuration
|
||||
|
||||
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.
|
||||
|
||||
Generate an 2048-bit RSA private key.
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
```
|
||||
openssl req -new -sha256 -key key.pem -out cert.csr
|
||||
```
|
||||
|
||||
Your CA owner will sign the CSR, and provide `cert.pem` and `ca.pem` files.
|
||||
|
||||
Extract the public key from the signed certificate:
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
export DOCKER_TLS_VERIFY=1
|
||||
export DOCKER_CERT_PATH=$(pwd)
|
||||
export DOCKER_HOST=tcp://<ucp-hostname>:443
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp uninstall --help
|
||||
```
|
||||
|
||||
To uninstall, do the following:
|
||||
|
||||
1. Log into the node you want to remove UCP from.
|
||||
|
||||
2. Enter the following command to uninstall:
|
||||
|
||||
$ 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.
|
||||
|
||||
## 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. When operating in this mode, UCP can
|
||||
not generate regular user certificates, as those must be managed and signed
|
||||
externally, however admin account certs can be generated as they are signed by
|
||||
the internal Swarm Root CA. Normal user accounts should be signed by the same
|
||||
external Root CA (or a trusted intermediary), and the public keys manually added
|
||||
through the UI.
|
||||
|
||||
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
|
||||
|
||||
To learn more you can also investigate:
|
||||
|
||||
* Read more [about the product](https://www.docker.com/universal-control-plane).
|
||||
* Visit the UCP forum to [ask questions and get answers](https://forums.docker.com/c/commercial-products/ucpbeta).
|
||||
* 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]-->
|
||||
25
index.md
25
index.md
@@ -1,20 +1,25 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Docker Universal Control Plane"
|
||||
title ="Universal Control Plane"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
identifier="mn_ucp"
|
||||
weight="-100"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Docker Universal Control Plane
|
||||
|
||||
# Docker Universal Control Plane BETA docs
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
The following are available:
|
||||
## Deploy, manage, and monitor Docker Engine resources
|
||||
|
||||
* [Release Notes](release_notes.md)
|
||||
* [UCP Quickstart Guide](installation.md)
|
||||
* [Key/Value Store Backends](kv_store.md)
|
||||
* [Manually setting up a CA](certs.md)
|
||||
* [Set up container networking with UCP](networking.md)
|
||||
* [Set up high availability](understand_ha.md)
|
||||
* [Work with Docker Support](support.md)
|
||||
tbd
|
||||
|
||||
## Secure communications
|
||||
|
||||
tbd
|
||||
|
||||
## Control user access
|
||||
|
||||
tbd
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="UCP Key/Value Store Backends"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
+++
|
||||
|
||||
<![end-metadata]-->
|
||||
|
||||
# UCP Key/Value Store Backend
|
||||
|
||||
|
||||
20
manage/index.md
Normal file
20
manage/index.md
Normal file
@@ -0,0 +1,20 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Manage and monitor"
|
||||
description = "Manage, monitor, troubleshoot"
|
||||
keywords = ["Manage, monitor, troubleshoot"]
|
||||
[menu.main]
|
||||
identifier="mn_manage_ucp"
|
||||
parent="mn_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# UCP resource management and monitoring
|
||||
|
||||
* [Your UCP installation](monitor-ucp.md)
|
||||
* [Applications](monitor-manage-applications.md)
|
||||
* [Containers](monitor-manage-containers.md)
|
||||
* [Images](monitor-manage-images.md)
|
||||
* [Container networks](monitor-manage-networks.md)
|
||||
* [Users](monitor-manage-users.md)
|
||||
* [volumes](monitor-manage-volumes.md)
|
||||
26
manage/monitor-manage-applications.md
Normal file
26
manage/monitor-manage-applications.md
Normal file
@@ -0,0 +1,26 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Applications"
|
||||
description = "Monitor, manage, troubleshoot applications"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, and troubleshoot applications
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Understand applications and UCP
|
||||
* version matrix
|
||||
* which features are supported
|
||||
* features that aren’t supported
|
||||
* requirements
|
||||
|
||||
## Review applications on UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Troubleshoot applications
|
||||
32
manage/monitor-manage-containers.md
Normal file
32
manage/monitor-manage-containers.md
Normal file
@@ -0,0 +1,32 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Containers"
|
||||
description = "Monitor, manage, troubleshoot containers"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, and troubleshoot containers
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Understand containers and UCP
|
||||
|
||||
* UCP launch
|
||||
* Compose launch
|
||||
* CLI launch
|
||||
|
||||
## Getting container information
|
||||
|
||||
tbd
|
||||
|
||||
## Monitoring container resources
|
||||
Best practices document for monitoring Docker containers (if there is one)
|
||||
|
||||
## Restricting container launch
|
||||
|
||||
* From UCP
|
||||
* From ClI
|
||||
37
manage/monitor-manage-images.md
Normal file
37
manage/monitor-manage-images.md
Normal file
@@ -0,0 +1,37 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Images"
|
||||
description = "Monitor, manage, troubleshoot images"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, and troubleshoot images
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
## Understand images and UCP
|
||||
* Which registries can users pull images from
|
||||
* Image “life cycle” for admins (graphic)
|
||||
|
||||
## Explain how to pull images by example
|
||||
* GUI
|
||||
* Contrast with command-line
|
||||
* Compose for automated pulls
|
||||
|
||||
## Update or review images through UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Ensure containers run the correct image
|
||||
|
||||
tbd
|
||||
|
||||
## Content Trust in UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Troubleshooting image problems
|
||||
if a container is running an old image (how to tell)
|
||||
25
manage/monitor-manage-networks.md
Normal file
25
manage/monitor-manage-networks.md
Normal file
@@ -0,0 +1,25 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Container networks"
|
||||
description = "Monitor, manage, and troubleshoot container networks"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, and troubleshoot networks
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
## Understand container networks and UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Review networks on UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Restricting network launches
|
||||
* From UCP
|
||||
* From CLI
|
||||
28
manage/monitor-manage-users.md
Normal file
28
manage/monitor-manage-users.md
Normal file
@@ -0,0 +1,28 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Users"
|
||||
description = "Manage and troubleshoot UCP Users"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, and troubleshoot Users
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Understand UCP user roles
|
||||
|
||||
tbd
|
||||
|
||||
## Importing users from LDAP
|
||||
|
||||
tbd
|
||||
|
||||
## Manually creating users
|
||||
|
||||
tbd
|
||||
|
||||
## Troubleshoot problems with Users
|
||||
26
manage/monitor-manage-volumes.md
Normal file
26
manage/monitor-manage-volumes.md
Normal file
@@ -0,0 +1,26 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Volumes"
|
||||
description = "Monitor, manage, and troubleshoot volumes"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, and troubleshoot volumes
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Understand volumes and UCP
|
||||
* bind mounted volumes
|
||||
* data volume container
|
||||
|
||||
## Review volumes on UCP
|
||||
|
||||
tbd
|
||||
|
||||
## Troubleshoot volumes
|
||||
|
||||
tbd
|
||||
45
manage/monitor-ucp.md
Normal file
45
manage/monitor-ucp.md
Normal file
@@ -0,0 +1,45 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Your UCP installation"
|
||||
description = "Monitor and Manage UCP"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_manage_ucp"
|
||||
weight=-100
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Monitor, manage, troubleshoot your UCP installation
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Understand UCP process
|
||||
* controller
|
||||
* nodes
|
||||
* images
|
||||
* Swarm
|
||||
* Discovery
|
||||
|
||||
## Configure UCP logging
|
||||
|
||||
|
||||
tbd
|
||||
|
||||
## Getting Status from the command line
|
||||
Using Client Bundle, you can get access to UCP stats, but you can also bypass UCP to get stats directly from Swarm or specific nodes. Admins can use this to troubleshoot UCP if it is not working. Steps below:
|
||||
|
||||
1. Download client bundle on to your desktop and
|
||||
2. run (e.g. “eval $(<env.sh)”)
|
||||
3. Now, running “docker info” or “docker version” provides useful statistics on the UCP cluster and nodes.
|
||||
However, you can also get access directly to Swarm or specific nodes, bypassing UCP.
|
||||
4. To do this, type “docker –H tcp:<Swarm_IP or Node_IP> info”.
|
||||
The “-H” flag allows you to access stats for a specific host
|
||||
5. Can also run “docker –H tcp:<Swarm_IP or Node_IP> version” for version data
|
||||
|
||||
## Review UCP logs
|
||||
|
||||
|
||||
tbd
|
||||
|
||||
## Requesting support
|
||||
@@ -1,9 +1,11 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Set up container networking"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
+++
|
||||
|
||||
<![end-metadata]-->
|
||||
|
||||
# Set up container networking with UCP
|
||||
|
||||
|
||||
36
overview.md
Normal file
36
overview.md
Normal file
@@ -0,0 +1,36 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Docker Universal Control Plane"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
weight="-100"
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
<!--[metadata]>
|
||||
NOTICE:
|
||||
The current doc theme does not allow us to create a split menu: a menu whose label is both a link and a dropdown. Our theme redesign fixes this but it is in RFD, so earliest out is about March 2016. In the mean time
|
||||
|
||||
* the overview.md pages to show up in the menu.
|
||||
* when a user clicks Overview, we will redirect go to https://docs.docker.com/ucp/
|
||||
* Later, after the redesign goes live, we will re-redirect in the unlikely event someone was able to book mark https://docs.docker.com/ucp/overview
|
||||
<![end-metadata]-->
|
||||
|
||||
# UCP overview
|
||||
|
||||
* [Overview](overview.md)
|
||||
* [Evaluation installation](evaluation-install.md)
|
||||
* [Plan a production installation](plan-production-install.md)
|
||||
* [Install UCP for production](production-install.md)
|
||||
* [Upgrade a production installation](production-upgrade.md)
|
||||
* [Manage, monitor, and troubleshoot UCP and its resources](manage/index.md)
|
||||
* [Commands reference](reference/index.md)
|
||||
* [Work with Docker Support](support.md)
|
||||
* [UCP Release Notes](release_notes.md)
|
||||
<!--[metadata]>Older beta docs may change, stay or go tbd<![end-metadata]-->
|
||||
* [UCP Key/Value Store Backend](kv_store.md)
|
||||
* [Set up container networking with UCP](networking.md)
|
||||
* [Set up high availability](understand_ha.md)
|
||||
* [Manually set up a Certificate Authority](certs.md)
|
||||
* [Deploy an application thru UCP](deploy-application.md)
|
||||
781
plan-production-install.md
Normal file
781
plan-production-install.md
Normal file
@@ -0,0 +1,781 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Plan a production installation"
|
||||
description = "Plan a production installation"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
weight=-90
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Plan a production installation
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## What is installed
|
||||
|
||||
tbd
|
||||
|
||||
## About the bootstrapper
|
||||
|
||||
tbd
|
||||
|
||||
### UCP Component architecture
|
||||
|
||||
tbd
|
||||
|
||||
#### controller
|
||||
|
||||
tbd
|
||||
|
||||
#### nodes
|
||||
|
||||
tbd
|
||||
|
||||
#### images
|
||||
|
||||
tbd
|
||||
|
||||
#### containers
|
||||
|
||||
tbd
|
||||
|
||||
### CS Docker Engine
|
||||
|
||||
tbd
|
||||
|
||||
### Docker Swarm
|
||||
|
||||
tbd
|
||||
|
||||
### Key/value Store
|
||||
|
||||
tbd
|
||||
|
||||
## Understand your installation options
|
||||
|
||||
tbd
|
||||
|
||||
### Evaluation install is a good trial to do
|
||||
|
||||
tbd
|
||||
|
||||
### AMI or manual installation
|
||||
|
||||
tbd
|
||||
|
||||
### Default versus the custom installation options
|
||||
|
||||
tbd
|
||||
|
||||
### Mix panel analytics
|
||||
|
||||
tbd
|
||||
|
||||
## Network considerations
|
||||
|
||||
tbd
|
||||
|
||||
### Port numbers
|
||||
|
||||
tbd
|
||||
|
||||
### Swarm Manager
|
||||
|
||||
tbd
|
||||
|
||||
### Data Volumes
|
||||
|
||||
tbd
|
||||
|
||||
### High availability
|
||||
|
||||
tbd
|
||||
|
||||
### Discovery
|
||||
|
||||
tbd
|
||||
|
||||
## Security Considerations
|
||||
|
||||
tbd
|
||||
|
||||
### Certificate authority
|
||||
|
||||
tbd
|
||||
|
||||
### Controlling user access
|
||||
|
||||
tbd
|
||||
|
||||
## Docker Engine Configuration
|
||||
|
||||
tbd
|
||||
|
||||
### Starting the daemon
|
||||
|
||||
tbd
|
||||
|
||||
### Docker CLI and the certificate bundle
|
||||
|
||||
tbd
|
||||
|
||||
## Installation checklist
|
||||
|
||||
tbd
|
||||
|
||||
### Hardware and software requirements
|
||||
|
||||
tbd
|
||||
|
||||
### IP addresses and fully-qualified domain names
|
||||
|
||||
tbd
|
||||
|
||||
### Subject alternative names (SANs)
|
||||
|
||||
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 3: Install Docker CS Engine 1.9](#step-3-install-docker-cs-engine)
|
||||
- [Step 4: (optional) Create user-named volumes](#step-4-optional-create-user-named-volumes)
|
||||
- [Step 5: Install the UCP controller](#step-5-install-the-ucp-controller)
|
||||
- [Step 6: (optional) Add a controller replica to the UCP cluster](#step-6-optional-add-a-controller-replica-to-the-ucp-cluster)
|
||||
- [Step 7: Add an Engine node to the UCP cluster](#step-7-add-an-engine-node-to-the-ucp-cluster)
|
||||
- [Step 8: Set up certs for the Docker CLI](#step-8-set-up-certs-for-the-docker-cli)
|
||||
- [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)
|
||||
|
||||
**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.
|
||||
|
||||
## Plan your installation
|
||||
|
||||
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
|
||||
`join` a node to a UCP controller. The general format of these commands are:
|
||||
|
||||
| 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` | `join --help` |
|
||||
| `docker` | `run --rm -it` | `docker/ucp` | `uninstall --help` |
|
||||
|
||||
You can these two subcommands interactively by passing them the `-i`
|
||||
option or by passing command-line options. This installation guide's steps
|
||||
assume both are run interactively.
|
||||
|
||||
To list all the possible subcommands, 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
|
||||
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
|
||||
|
||||
UCP includes Docker Swarm as part of its installation. So, you don't need to
|
||||
install Docker Swarm. You do need to ensure that the UCP controller and nodes
|
||||
can communicate across your network. Configure your network making sure to open
|
||||
the following ports:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Port</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>443</code> </td>
|
||||
<td>UCP controller port. Open this port to allow inbound access to the UCP interface or CLI.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>2376</code></td>
|
||||
<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>
|
||||
|
||||
|
||||
All the communication among the controller, nodes, and key value store is
|
||||
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.
|
||||
Using a different port is a customization. These instructions assume you are using the default `2376` port.
|
||||
|
||||
## Step 3: Install Docker CS Engine
|
||||
|
||||
The BETA program requires that you install the Docker CS Engine 1.9.0 or above.
|
||||
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)
|
||||
|
||||
### 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)
|
||||
|
||||
|
||||
## Step 4: (optional) Create user-named volumes
|
||||
|
||||
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 |
|
||||
|-------------------------|--------------------------------------------------------------------------------------|
|
||||
| `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. |
|
||||
|
||||
## Step 5: Install the UCP controller
|
||||
|
||||
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
|
||||
docker run --rm -it docker/ucp install --help
|
||||
```
|
||||
|
||||
When you install, the script prompts you for the following information:
|
||||
|
||||
* a password to use for the UCP `admin` account
|
||||
* 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
|
||||
install:
|
||||
|
||||
1. Log into the system where you mean to install the UCP controller.
|
||||
|
||||
If you are installing on a cloud provider such as AWS, make sure the instance has a public IP or hostname.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Your browser may warn you about the connection. The warning appears because
|
||||
the UCP certificate was issued by a built-in certificate authority. Your
|
||||
actions with the install actually created the certificate. If you are
|
||||
concerned, the certificate's fingerprint is displayed during install and you
|
||||
can compare it.
|
||||
|
||||
4. Use the Advanced link to proceed to UCP.
|
||||
|
||||
The login screen displays.
|
||||
|
||||
|
||||
|
||||
5. Enter `admin` for the username along with the password you provided to the `install`.
|
||||
|
||||
If you didn't enter an admin password, the default password is `orca` After
|
||||
you enter the correct credentials, the UCP dashboard displays.
|
||||
|
||||
|
||||
|
||||
The dashboard shows a single node, your controller node.
|
||||
|
||||
## Step 6: (optional) Add a controller replica to the UCP cluster
|
||||
|
||||
In this optional step, you configure support for UCP's high-availability
|
||||
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
|
||||
*replicas* and which nodes are simply for extra capacity. A
|
||||
replica is a node in your cluster that can act as an additional UCP 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.
|
||||
* Configure a minimum of two replicas in addition to the controller.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp join --help
|
||||
```
|
||||
|
||||
The `docker/ucp join` 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 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:
|
||||
|
||||
1. Log into the host where you mean to install the node.
|
||||
|
||||
2. Run the `dokcer/ucp join` command.
|
||||
|
||||
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join --replica -i
|
||||
|
||||
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.
|
||||
|
||||
INFO[0005] Verifying your system is compatible with UCP
|
||||
INFO[0011] Sending add host request to UCP server
|
||||
INFO[0011] Starting local swarm containers
|
||||
|
||||
3. Repeat steps 1 thru 3 on the other replicas.
|
||||
|
||||
You should configure a minimum of 3 controllers configured, a primary and
|
||||
two replicas. Never run a cluster with only the primary controller and a
|
||||
single replica.
|
||||
|
||||
4. Login 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.
|
||||
|
||||
|
||||
|
||||
|
||||
## Step 7: Add an Engine node 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:
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp join --help
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
When you have the information you'll be prompted for, do the following to install:
|
||||
|
||||
1. Log into the system where you mean to install the node.
|
||||
|
||||
2. Run the `docker/ucp join` command.
|
||||
|
||||
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join -i
|
||||
|
||||
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.
|
||||
|
||||
INFO[0005] Verifying your system is compatible with UCP
|
||||
INFO[0011] Sending add host request to UCP server
|
||||
INFO[0011] Starting local swarm containers
|
||||
|
||||
3. Repeat steps 1 thru 2 on the other nodes.
|
||||
|
||||
4. Login 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.
|
||||
|
||||
|
||||
|
||||
## Step 8: Set up certs 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.
|
||||
|
||||
You can download the bundle from the UCP interface or using `curl` command. The
|
||||
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`
|
||||
command an authorization token. Of course, you need to have `curl` installed as well.
|
||||
|
||||
### Download the bundle from the UCP interface
|
||||
|
||||
1. If you haven't already done so, log into UCP.
|
||||
|
||||
2. Choose **ADMIN > Profile** from the right-hand menu.
|
||||
|
||||
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`.
|
||||
|
||||
3. Click **Create Client Bundle**.
|
||||
|
||||
The browser downloads the `ucp-bundle-admin.zip` file.
|
||||
|
||||
### Download the bundle with curl
|
||||
|
||||
1. Log into a machine with network access to the UCP controller.
|
||||
|
||||
You might log into the controller itself. You could also log into any arbitrary machine able to `ping` the controller.
|
||||
|
||||
2. Install the prerequisite `curl`, `zip`, `jq` (JQuery) packages if you haven't already.
|
||||
|
||||
On Ubuntu, the installation looks like this:
|
||||
|
||||
$ sudo apt-get install zip curl jq
|
||||
Reading package lists... Done
|
||||
Building dependency tree
|
||||
Reading state information... Done
|
||||
The following extra packages will be installed:
|
||||
libcurl3
|
||||
The following NEW packages will be installed:
|
||||
jq zip
|
||||
The following packages will be upgraded:
|
||||
curl libcurl3
|
||||
----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.
|
||||
|
||||
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.
|
||||
|
||||
$ curl -k -H "Authorization: Bearer $AUTHTOKEN" https://<ducp-0 IP>/api/clientbundle -o bundle.zip
|
||||
|
||||
The browser downloads a `bundle.zip` file.
|
||||
|
||||
### Install the certificate bundle
|
||||
|
||||
Once you download the bundle, you can unzip and use it.
|
||||
|
||||
1. Make sure you have `zip` installed.
|
||||
|
||||
$ which unzip
|
||||
/usr/bin/unzip
|
||||
|
||||
If you don't, install it before continuing.
|
||||
|
||||
2. Open the folder containing the bundle file.
|
||||
|
||||
4. Unzip the file to reveal its contents.
|
||||
|
||||
ucp-bundle
|
||||
├── ca.pem
|
||||
├── cert.pem
|
||||
├── cert.pub
|
||||
├── env.sh
|
||||
└── key.pem
|
||||
|
||||
5. Set up your environment by sourcing the `env.sh` file.
|
||||
|
||||
$ source env.sh
|
||||
|
||||
6. Use the `docker info` command to get the location of the Swarm managers and engines.
|
||||
|
||||
$ docker info
|
||||
Containers: 9
|
||||
Images: 9
|
||||
Role: primary
|
||||
Strategy: spread
|
||||
Filters: health, port, dependency, affinity, constraint
|
||||
Nodes: 1
|
||||
node1: 192.168.122.7:12376
|
||||
└ Containers: 9
|
||||
└ Reserved CPUs: 0 / 1
|
||||
└ Reserved Memory: 0 B / 2.054 GiB
|
||||
└ Labels: executiondriver=native-0.2, kernelversion=4.0.9-boot2docker, operatingsystem=Boot2Docker 1.8.1 (TCL 6.3); master : eb5571f - Thu Sep 3 22:18:54 UTC 2015, provider=kvm, storagedriver=aufs
|
||||
Cluster Managers: 1
|
||||
192.168.122.7: Healthy
|
||||
└ Orca Controller: https://192.168.122.7
|
||||
└ Swarm Manager: tcp://192.168.122.7:3376
|
||||
└ KV: etcd://192.168.122.7:12379
|
||||
CPUs: 1
|
||||
Total Memory: 2.054 GiB
|
||||
Name: node1
|
||||
ID: PNLT:MFCO:DDWL:MSLF:YVHU:35Z3:66KM:DFZM:OPBK:D4BQ:EKNT:6DXA
|
||||
Labels:
|
||||
com.docker.ucp.license_key=unlicensed
|
||||
com.docker.ucp.license_max_engines=0
|
||||
com.docker.ucp.license_expires=EXPIRED
|
||||
|
||||
### Client Bundles on Externally Managed CA Configuration
|
||||
|
||||
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.
|
||||
|
||||
Generate an 2048-bit RSA private key.
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
```
|
||||
openssl req -new -sha256 -key key.pem -out cert.csr
|
||||
```
|
||||
|
||||
Your CA owner will sign the CSR, and provide `cert.pem` and `ca.pem` files.
|
||||
|
||||
Extract the public key from the signed certificate:
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
export DOCKER_TLS_VERIFY=1
|
||||
export DOCKER_CERT_PATH=$(pwd)
|
||||
export DOCKER_HOST=tcp://<ucp-hostname>:443
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp uninstall --help
|
||||
```
|
||||
|
||||
To uninstall, do the following:
|
||||
|
||||
1. Log into the node you want to remove UCP from.
|
||||
|
||||
2. Enter the following command to uninstall:
|
||||
|
||||
$ 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.
|
||||
|
||||
## 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. When operating in this mode, UCP can
|
||||
not generate regular user certificates, as those must be managed and signed
|
||||
externally, however admin account certs can be generated as they are signed by
|
||||
the internal Swarm Root CA. Normal user accounts should be signed by the same
|
||||
external Root CA (or a trusted intermediary), and the public keys manually added
|
||||
through the UI.
|
||||
|
||||
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
|
||||
|
||||
To learn more you can also investigate:
|
||||
|
||||
* Read more [about the product](https://www.docker.com/universal-control-plane).
|
||||
* Visit the UCP forum to [ask questions and get answers](https://forums.docker.com/c/commercial-products/ucpbeta).
|
||||
* 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]-->
|
||||
700
production-install.md
Normal file
700
production-install.md
Normal file
@@ -0,0 +1,700 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title = "Install UCP for production"
|
||||
description = "Install UCP for production"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
weight=-85
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Install UCP for production
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Step 1: Prepare the properly
|
||||
|
||||
tbd
|
||||
|
||||
## 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 3: Install Docker CS Engine 1.9](#step-3-install-docker-cs-engine)
|
||||
- [Step 4: (optional) Create user-named volumes](#step-4-optional-create-user-named-volumes)
|
||||
- [Step 5: Install the UCP controller](#step-5-install-the-ucp-controller)
|
||||
- [Step 6: (optional) Add a controller replica to the UCP cluster](#step-6-optional-add-a-controller-replica-to-the-ucp-cluster)
|
||||
- [Step 7: Add an Engine node to the UCP cluster](#step-7-add-an-engine-node-to-the-ucp-cluster)
|
||||
- [Step 8: Set up certs for the Docker CLI](#step-8-set-up-certs-for-the-docker-cli)
|
||||
- [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)
|
||||
|
||||
**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.
|
||||
|
||||
## Plan your installation
|
||||
|
||||
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
|
||||
`join` a node to a UCP controller. The general format of these commands are:
|
||||
|
||||
| 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` | `join --help` |
|
||||
| `docker` | `run --rm -it` | `docker/ucp` | `uninstall --help` |
|
||||
|
||||
You can these two subcommands interactively by passing them the `-i`
|
||||
option or by passing command-line options. This installation guide's steps
|
||||
assume both are run interactively.
|
||||
|
||||
To list all the possible subcommands, 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
|
||||
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
|
||||
|
||||
UCP includes Docker Swarm as part of its installation. So, you don't need to
|
||||
install Docker Swarm. You do need to ensure that the UCP controller and nodes
|
||||
can communicate across your network. Configure your network making sure to open
|
||||
the following ports:
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th>Port</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>443</code> </td>
|
||||
<td>UCP controller port. Open this port to allow inbound access to the UCP interface or CLI.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>2376</code></td>
|
||||
<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>
|
||||
|
||||
|
||||
All the communication among the controller, nodes, and key value store is
|
||||
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.
|
||||
Using a different port is a customization. These instructions assume you are using the default `2376` port.
|
||||
|
||||
## Step 3: Install Docker CS Engine
|
||||
|
||||
The BETA program requires that you install the Docker CS Engine 1.9.0 or above.
|
||||
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)
|
||||
|
||||
### 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)
|
||||
|
||||
|
||||
## Step 4: (optional) Create user-named volumes
|
||||
|
||||
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 |
|
||||
|-------------------------|--------------------------------------------------------------------------------------|
|
||||
| `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. |
|
||||
|
||||
## Step 5: Install the UCP controller
|
||||
|
||||
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
|
||||
docker run --rm -it docker/ucp install --help
|
||||
```
|
||||
|
||||
When you install, the script prompts you for the following information:
|
||||
|
||||
* a password to use for the UCP `admin` account
|
||||
* 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
|
||||
install:
|
||||
|
||||
1. Log into the system where you mean to install the UCP controller.
|
||||
|
||||
If you are installing on a cloud provider such as AWS, make sure the instance has a public IP or hostname.
|
||||
|
||||
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
Your browser may warn you about the connection. The warning appears because
|
||||
the UCP certificate was issued by a built-in certificate authority. Your
|
||||
actions with the install actually created the certificate. If you are
|
||||
concerned, the certificate's fingerprint is displayed during install and you
|
||||
can compare it.
|
||||
|
||||
4. Use the Advanced link to proceed to UCP.
|
||||
|
||||
The login screen displays.
|
||||
|
||||
|
||||
|
||||
5. Enter `admin` for the username along with the password you provided to the `install`.
|
||||
|
||||
If you didn't enter an admin password, the default password is `orca` After
|
||||
you enter the correct credentials, the UCP dashboard displays.
|
||||
|
||||
|
||||
|
||||
The dashboard shows a single node, your controller node.
|
||||
|
||||
## Step 6: (optional) Add a controller replica to the UCP cluster
|
||||
|
||||
In this optional step, you configure support for UCP's high-availability
|
||||
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
|
||||
*replicas* and which nodes are simply for extra capacity. A
|
||||
replica is a node in your cluster that can act as an additional UCP 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.
|
||||
* Configure a minimum of two replicas in addition to the controller.
|
||||
|
||||
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:
|
||||
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp join --help
|
||||
```
|
||||
|
||||
The `docker/ucp join` 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 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:
|
||||
|
||||
1. Log into the host where you mean to install the node.
|
||||
|
||||
2. Run the `dokcer/ucp join` command.
|
||||
|
||||
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join --replica -i
|
||||
|
||||
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.
|
||||
|
||||
INFO[0005] Verifying your system is compatible with UCP
|
||||
INFO[0011] Sending add host request to UCP server
|
||||
INFO[0011] Starting local swarm containers
|
||||
|
||||
3. Repeat steps 1 thru 3 on the other replicas.
|
||||
|
||||
You should configure a minimum of 3 controllers configured, a primary and
|
||||
two replicas. Never run a cluster with only the primary controller and a
|
||||
single replica.
|
||||
|
||||
4. Login 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.
|
||||
|
||||
|
||||
|
||||
|
||||
## Step 7: Add an Engine node 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:
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp join --help
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
When you have the information you'll be prompted for, do the following to install:
|
||||
|
||||
1. Log into the system where you mean to install the node.
|
||||
|
||||
2. Run the `docker/ucp join` command.
|
||||
|
||||
$ docker run --rm -it -v /var/run/docker.sock:/var/run/docker.sock --name ucp docker/ucp join -i
|
||||
|
||||
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.
|
||||
|
||||
INFO[0005] Verifying your system is compatible with UCP
|
||||
INFO[0011] Sending add host request to UCP server
|
||||
INFO[0011] Starting local swarm containers
|
||||
|
||||
3. Repeat steps 1 thru 2 on the other nodes.
|
||||
|
||||
4. Login 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.
|
||||
|
||||
|
||||
|
||||
## Step 8: Set up certs 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.
|
||||
|
||||
You can download the bundle from the UCP interface or using `curl` command. The
|
||||
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`
|
||||
command an authorization token. Of course, you need to have `curl` installed as well.
|
||||
|
||||
### Download the bundle from the UCP interface
|
||||
|
||||
1. If you haven't already done so, log into UCP.
|
||||
|
||||
2. Choose **ADMIN > Profile** from the right-hand menu.
|
||||
|
||||
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`.
|
||||
|
||||
3. Click **Create Client Bundle**.
|
||||
|
||||
The browser downloads the `ucp-bundle-admin.zip` file.
|
||||
|
||||
### Download the bundle with curl
|
||||
|
||||
1. Log into a machine with network access to the UCP controller.
|
||||
|
||||
You might log into the controller itself. You could also log into any arbitrary machine able to `ping` the controller.
|
||||
|
||||
2. Install the prerequisite `curl`, `zip`, `jq` (JQuery) packages if you haven't already.
|
||||
|
||||
On Ubuntu, the installation looks like this:
|
||||
|
||||
$ sudo apt-get install zip curl jq
|
||||
Reading package lists... Done
|
||||
Building dependency tree
|
||||
Reading state information... Done
|
||||
The following extra packages will be installed:
|
||||
libcurl3
|
||||
The following NEW packages will be installed:
|
||||
jq zip
|
||||
The following packages will be upgraded:
|
||||
curl libcurl3
|
||||
----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.
|
||||
|
||||
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.
|
||||
|
||||
$ curl -k -H "Authorization: Bearer $AUTHTOKEN" https://<ducp-0 IP>/api/clientbundle -o bundle.zip
|
||||
|
||||
The browser downloads a `bundle.zip` file.
|
||||
|
||||
### Install the certificate bundle
|
||||
|
||||
Once you download the bundle, you can unzip and use it.
|
||||
|
||||
1. Make sure you have `zip` installed.
|
||||
|
||||
$ which unzip
|
||||
/usr/bin/unzip
|
||||
|
||||
If you don't, install it before continuing.
|
||||
|
||||
2. Open the folder containing the bundle file.
|
||||
|
||||
4. Unzip the file to reveal its contents.
|
||||
|
||||
ucp-bundle
|
||||
├── ca.pem
|
||||
├── cert.pem
|
||||
├── cert.pub
|
||||
├── env.sh
|
||||
└── key.pem
|
||||
|
||||
5. Set up your environment by sourcing the `env.sh` file.
|
||||
|
||||
$ source env.sh
|
||||
|
||||
6. Use the `docker info` command to get the location of the Swarm managers and engines.
|
||||
|
||||
$ docker info
|
||||
Containers: 9
|
||||
Images: 9
|
||||
Role: primary
|
||||
Strategy: spread
|
||||
Filters: health, port, dependency, affinity, constraint
|
||||
Nodes: 1
|
||||
node1: 192.168.122.7:12376
|
||||
└ Containers: 9
|
||||
└ Reserved CPUs: 0 / 1
|
||||
└ Reserved Memory: 0 B / 2.054 GiB
|
||||
└ Labels: executiondriver=native-0.2, kernelversion=4.0.9-boot2docker, operatingsystem=Boot2Docker 1.8.1 (TCL 6.3); master : eb5571f - Thu Sep 3 22:18:54 UTC 2015, provider=kvm, storagedriver=aufs
|
||||
Cluster Managers: 1
|
||||
192.168.122.7: Healthy
|
||||
└ Orca Controller: https://192.168.122.7
|
||||
└ Swarm Manager: tcp://192.168.122.7:3376
|
||||
└ KV: etcd://192.168.122.7:12379
|
||||
CPUs: 1
|
||||
Total Memory: 2.054 GiB
|
||||
Name: node1
|
||||
ID: PNLT:MFCO:DDWL:MSLF:YVHU:35Z3:66KM:DFZM:OPBK:D4BQ:EKNT:6DXA
|
||||
Labels:
|
||||
com.docker.ucp.license_key=unlicensed
|
||||
com.docker.ucp.license_max_engines=0
|
||||
com.docker.ucp.license_expires=EXPIRED
|
||||
|
||||
### Client Bundles on Externally Managed CA Configuration
|
||||
|
||||
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.
|
||||
|
||||
Generate an 2048-bit RSA private key.
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
```
|
||||
openssl req -new -sha256 -key key.pem -out cert.csr
|
||||
```
|
||||
|
||||
Your CA owner will sign the CSR, and provide `cert.pem` and `ca.pem` files.
|
||||
|
||||
Extract the public key from the signed certificate:
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
export DOCKER_TLS_VERIFY=1
|
||||
export DOCKER_CERT_PATH=$(pwd)
|
||||
export DOCKER_HOST=tcp://<ucp-hostname>:443
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
docker run --rm -it docker/ucp uninstall --help
|
||||
```
|
||||
|
||||
To uninstall, do the following:
|
||||
|
||||
1. Log into the node you want to remove UCP from.
|
||||
|
||||
2. Enter the following command to uninstall:
|
||||
|
||||
$ 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.
|
||||
|
||||
## 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. When operating in this mode, UCP can
|
||||
not generate regular user certificates, as those must be managed and signed
|
||||
externally, however admin account certs can be generated as they are signed by
|
||||
the internal Swarm Root CA. Normal user accounts should be signed by the same
|
||||
external Root CA (or a trusted intermediary), and the public keys manually added
|
||||
through the UI.
|
||||
|
||||
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
|
||||
|
||||
To learn more you can also investigate:
|
||||
|
||||
* Read more [about the product](https://www.docker.com/universal-control-plane).
|
||||
* Visit the UCP forum to [ask questions and get answers](https://forums.docker.com/c/commercial-products/ucpbeta).
|
||||
* 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]-->
|
||||
@@ -1,10 +1,29 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Quickstart Guide"
|
||||
description="Docker Universal Control Plane"
|
||||
title = "Upgrade production installation"
|
||||
description = "Upgrade production installation"
|
||||
keywords = ["tbd, tbd"]
|
||||
[menu.main]
|
||||
weight="-98"
|
||||
parent="mn_ucp"
|
||||
weight=-80
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Upgrade a production installation
|
||||
|
||||
Intro 1-2 paras, page purpose, intended user, list steps if page is tutorial.
|
||||
|
||||
|
||||
## Plan your upgrade
|
||||
|
||||
tbd
|
||||
|
||||
## Upgrade procedure
|
||||
|
||||
tbd
|
||||
|
||||
|
||||
<!--[metadata]>
|
||||
|
||||
# Docker UCP Quickstart Guide
|
||||
|
||||
@@ -641,3 +660,4 @@ To learn more you can also investigate:
|
||||
* 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]-->
|
||||
@@ -1,12 +1,12 @@
|
||||
+++
|
||||
title = "ucp Tool"
|
||||
title = "ucp tool Reference"
|
||||
description = "Run UCP commands"
|
||||
[menu.main]
|
||||
identifier = "ucp_ref"
|
||||
parent = "mn_ucp"
|
||||
+++
|
||||
|
||||
# ucp Tool
|
||||
# ucp tool Reference
|
||||
|
||||
|
||||
```
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Release Notes"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
weight="-99"
|
||||
parent="mn_ucp"
|
||||
weight="99"
|
||||
+++
|
||||
|
||||
<![end-metadata]-->
|
||||
|
||||
# UCP Release Notes
|
||||
|
||||
|
||||
@@ -1,10 +1,12 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Work with Docker Support"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
weight="2"
|
||||
parent="mn_ucp"
|
||||
weight="89"
|
||||
+++
|
||||
|
||||
<![end-metadata]-->
|
||||
|
||||
# Work with Docker Support
|
||||
|
||||
|
||||
@@ -1,9 +1,11 @@
|
||||
<!--[metadata]>
|
||||
+++
|
||||
title ="Set up high availability"
|
||||
description="Docker Universal Control Plane"
|
||||
[menu.main]
|
||||
parent="mn_ucp"
|
||||
+++
|
||||
|
||||
<![end-metadata]-->
|
||||
|
||||
|
||||
# Set up high availability
|
||||
|
||||
Reference in New Issue
Block a user