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

Product/image rename 

This revamps the product and image names.  After merging this change,
the bootstrapper image will be known as "dockerorca/ucp" since it is the
primary image customers interact with.  The controller will be known as
"dockerorca/ucp-controller" and the corresponding container names are
"ucp" and "ucp-controller".  Once we get closer to GA, we'll move the
images under the "docker" org, so the product name will flow nicely from
that "docker/ucp" for the bootstrapping tool, and "docker/ucp-controller"
for the server image.
This commit is contained in:
Daniel Hiltgen 2015-11-25 09:44:21 -08:00 committed by Joao Fernandes
parent 7b1888c219
commit 4a02cc19c8
7 changed files with 170 additions and 170 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
high_availability.md
View File

@ -1,7 +1,7 @@
# Orca High Availability
# UCP High Availability
This document outlines how Orca high availability works, and general
guidelines for deploying a highly available Orca in production.
This document outlines how UCP high availability works, and general
guidelines for deploying a highly available UCP in production.
When adding nodes to your cluster, you decide which nodes you want to
be replicas, and which nodes are simply additional engines for extra
capacity. If you are planning an HA deployment, you should have a
@ -15,34 +15,34 @@ the first replica, if an error occurrs, the cluster will be come unusable.
## Architecture
* **Primary Controller** This is the first node you run the `install` against. It runs the following containers/services:
* **orca-kv** This etcd container runs the replicated KV store
* **orca-swarm-manger** This Swarm Manager uses the replicated KV store for leader election and cluster membership tracking
* **orca-controller** This container runs the Orca server, using the replicated KV store for configuration state
* **orca-swarm-join** Runs the swarm join command to periodically publish this nodes existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster
* **orca-proxy** Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon
* **orca-swarm-ca[-proxy]** These **unreplicated** containers run the Swarm CA used for admin certificate bundles, and adding new nodes
* **orca-ca[-proxy]** These **unreplicated** containers run the (optional) Orca CA used for signing user bundles.
* **ucp-kv** This etcd container runs the replicated KV store
* **ucp-swarm-manger** This Swarm Manager uses the replicated KV store for leader election and cluster membership tracking
* **ucp-controller** This container runs the UCP server, using the replicated KV store for configuration state
* **ucp-swarm-join** Runs the swarm join command to periodically publish this nodes existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster
* **ucp-proxy** Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon
* **ucp-swarm-ca[-proxy]** These **unreplicated** containers run the Swarm CA used for admin certificate bundles, and adding new nodes
* **ucp-ca[-proxy]** These **unreplicated** containers run the (optional) UCP CA used for signing user bundles.
* **Replica Node** This is a node you `join` to the primary using the `--replica` flag and it contributes to the availability of the cluster
* **orca-kv** This etcd container runs the replicated KV store
* **orca-swarm-manger** This Swarm Manager uses the replicated KV store for leader election and cluster membership tracking
* **orca-controller** This container runs the Orca server, using the replicated KV store for configuration state
* **orca-swarm-join** Runs the swarm join command to periodically publish this nodes existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster
* **orca-proxy** Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon
* **Non-Replica Node** These nodes provide additional capacity, but do not enhance the availability of the Orca/Swarm infrastructure
* **orca-swarm-join** Runs the swarm join command to periodically publish this nodes existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster
* **orca-proxy** Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon
* **ucp-kv** This etcd container runs the replicated KV store
* **ucp-swarm-manger** This Swarm Manager uses the replicated KV store for leader election and cluster membership tracking
* **ucp-controller** This container runs the UCP server, using the replicated KV store for configuration state
* **ucp-swarm-join** Runs the swarm join command to periodically publish this nodes existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster
* **ucp-proxy** Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon
* **Non-Replica Node** These nodes provide additional capacity, but do not enhance the availability of the UCP/Swarm infrastructure
* **ucp-swarm-join** Runs the swarm join command to periodically publish this nodes existence to the KV store. If the node goes down, this publishing stops, and the registration times out, and the node is automatically dropped from the cluster
* **ucp-proxy** Runs a local TLS proxy for the docker socket to enable secure access of the local docker daemon
Notes:
* At present, Orca does not include a load-balancer. Users may provide one exernally and load balance between the primary and replica nodes on port 443 for web access to the system via a single IP/hostname if desired. If no external load balancer is used, admins should note the IP/hostname of the primary and all replicas so they can access them when needed.
* At present, UCP does not include a load-balancer. Users may provide one exernally and load balance between the primary and replica nodes on port 443 for web access to the system via a single IP/hostname if desired. If no external load balancer is used, admins should note the IP/hostname of the primary and all replicas so they can access them when needed.
* Backups:
* Users should always back up their volumes (see the other guides for a complete list of named volumes)
* The CAs (swarm and orca) are not currently replicated.
* The CAs (swarm and UCP) are not currently replicated.
* Swarm CA:
* Used for admin cert bundle generation
* Used for adding hosts to the cluster
* During an outage, no new admin cert bundles can be downloaded, but existing ones will still work.
* During an outage, no new nodes can be added to the cluster, but existing nodes will continue to operate
* Orca CA:
* UCP CA:
* Used for user bundle generation
* Used to sign certs for new replica nodes
* During an outage, no new user cert bundles can be downloaded, but existing ones will still work

164
install-beta.md
View File

@ -1,15 +1,15 @@
# Docker Orca Quickstart Guide
# Docker UCP Quickstart Guide
These instructions explain how to install Orca. An Orca installation consists of an Orca server and one or more nodes. The same machine can serve as both the server and the node. These instructions show you how to install both a host and a node. It contains the following sections:
These instructions explain how to install UCP. A UCP installation consists of an UCP server and one or more nodes. The same machine can serve as both the server 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 Orca](#step-2-configure-your-network-for-orca)
- [Step 2: Configure your network for UCP](#step-2-configure-your-network-for-ucp)
- [Step 3: Install Docker Engine v1.9](#step-3-install-docker-engine-v19)
- [Step 4: (optional) Create user-named volumes](#step-4-optional-create-user-named-volumes)
- [Step 5: Install the Orca server](#step-5-install-the-orca-server)
- [Step 5: Install the UCP server](#step-5-install-the-ucp-server)
- [Step 6: Set up certs for the Docker CLI](#step-6-set-up-certs-for-the-docker-cli)
- [Step 7: Add a Node to the Orca cluster](#step-7-add-a-node-to-the-orca-cluster)
- [Step 7: Add a Node to the UCP cluster](#step-7-add-a-node-to-the-ucp-cluster)
- [Uninstall](#uninstall)
- [Block Mixpanel analytics](#block-mixpanel-analytics)
- [Installing with your own certificates](#installing-with-your-own-certificates)
@ -17,9 +17,9 @@ These instructions explain how to install Orca. An Orca installation consists of
## Plan your installation
The Orca installation consists of running the `orca-bootstrap` image using the
The UCP installation consists of running the `ucp` image using the
Docker Engine CLI. The image launches an interactive script that automates the
Orca setup using a default configurations for both data volumes and certificate
UCP setup using a default configurations for both data volumes and certificate
authority (CA).
The first time you install, you should install in a sandbox environment where
@ -36,35 +36,35 @@ customization steps. Customize steps are identified with the keyword
(optional). Make sure you skip these steps when doing the default installation
in your sandbox.
The Orca BETA program makes use of Mixpanel to collect analytics. This feature collects data on your usage of Orca 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.
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.
## Step 1: Verify you have the prerequisites
You can install Orca on your network or on a cloud provider such AWS or Digital Ocean. To install, the server and the nodes can run any of these supported operating systems:
You can install UCP on your network or on a cloud provider such AWS or Digital Ocean. To install, the server and the nodes can run any of these supported operating systems:
* RHEL 7.0, 7.1
* Ubuntu 14.04 LTS
* CentOS 7.1
Installing Docker Orca requires that you first install the testing Docker Engine v1.9 on both the server and the nodes. The Docker Engine can be local or remote. These instructions assume you are installing both Orca and Docker Engine locally.
Installing Docker UCP requires that you first install the testing Docker Engine v1.9 on both the server and the nodes. The Docker Engine can be local or remote. These instructions assume you are installing both UCP and Docker Engine locally.
Finally, installing Orca requires you to pull an image from the Docker Hub. If you don't already have a Docker Hub account, make sure you [create an account](https://hub.docker.com/). Once you have a Hub account, send an email to <mailto:support@docker.com> with your account name and request access to the Orca BETA image.
Finally, installing UCP requires you to pull an image from the Docker Hub. If you don't already have a Docker Hub account, make sure you [create an account](https://hub.docker.com/). Once you have a Hub account, send an email to <mailto:support@docker.com> with your account name and request access to the UCP BETA image.
## Step 2: Configure your network for Orca
## Step 2: Configure your network for UCP
Orca includes Docker Swarm as part of its installation. So, you don't need to install Docker Swarm. You do need to ensure that the Orca server and nodes can communicate across your network. Configure your network making sure to open the following ports:
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 server and nodes can communicate across your network. Configure your network making sure to open the following ports:
| Port | Description |
|------------------|-----------------|
| `443` | Orca server |
| `443` | UCP server |
| `2376` | Swarm manager |
| `12376` | Engine proxy |
| `12379`, `12380` | Key Value store |
| `12381` | Swarm CA service|
| `12382` | Orca CA service |
| `12382` | UCP CA service |
The communication between the server, nodes, and key value store is all protected by mutual TLS. The Orca installation of Swarm provides TLS for you automatically.
The communication between the server, nodes, and key value store is all protected by mutual TLS. The UCP installation of Swarm provides TLS for you automatically.
Finally, you can specify a different port for the Swarm manager if you need to. These instructions assume you are using the default `2376` port.
@ -120,43 +120,43 @@ EOF
## Step 4: (optional) Create user-named volumes
Orca uses named volumes for persistence of user data. By default, the
`orca-bootstrap` installer creates for you. It uses the default volume driver and flags. The first time you install, we recommend you skip this step and try it later, on another install. Later, try an install where your try the option to use custom volume driver and create your own volumes.
UCP uses named volumes for persistence of user data. By default, the
`ucp` installer creates for you. It uses the default volume driver and flags. The first time you install, we recommend you skip this step and try it later, on another install. Later, try an install where your try the option to use custom volume driver and create your own volumes.
If you choose this option, create your volumes prior to installing Orca. The volumes Oraca requires are:
If you choose this option, create your volumes prior to installing UCP. The volumes Oraca requires are:
| Volume name | Data |
|-------------------------|--------------------------------------------------------------------------------------|
| `orca-root-ca` | The certificate and key for the Orca root CA. Do not create this volume if you are using your own certificates. |
| `orca-swarm-root-ca` | The certificate and key for the Swarm root CA. |
| `orca-server-certs` | The server certificates for the Orca web server. |
| `orca-swarm-node-certs` | The Swarm certificates for the current node (repeated on every node in the cluster). |
| `orca-swarm-kv-certs` | The Swarm KV client certificates for the current node (repeated on every node in the cluster). |
| `orca-swarm-controller-certs` | The Orca Controller Swarm client certificates for the current node. |
| `orca-kv` | Key value store persistence. |
| `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 server certificates for the UCP 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 Orca server
## Step 5: Install the UCP server
In this step you install the Orca server. The server includes a running Swarm manager and node as well. To review the installation options before you install, use the following command:
In this step you install the UCP server. The server includes a running Swarm manager and node as well. To review the installation options before you install, use the following command:
```bash
docker run --rm -it dockerorca/orca-bootstrap install --help
docker run --rm -it dockerorca/ucp install --help
```
When you install, the script prompts you for the following information:
* a password to use for the Orca `admin` account
* a password to use for the UCP `admin` account
* your Docker Hub username/password/email
* an alias which is the actual external, publically-accessible IP address or name for the Orca server
* an alias which is the actual external, publically-accessible IP address or name for the UCP server
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 Orca server.
1. Log into the system where you mean to install the UCP server.
2. Use the CLI to log into Docker Hub .
Make sure you use the account which has permissions to the Orca images.
Make sure you use the account which has permissions to the UCP images.
$ sudo docker login
Username: moxiegirl
@ -165,19 +165,19 @@ When you have the information you'll be prompted for, do the following to instal
WARNING: login credentials saved in /home/ubuntu/.docker/config.json
Login Succeeded
3. Run the `orca-bootstrap` installer.
3. Run the `ucp` installer.
$ docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
--name orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
install -i
The installer pulls several images and prompts you for the installation values it needs. When it completes, the installer prompts you to login into the Orca GUI.
The installer pulls several images and prompts you for the installation values it needs. When it completes, the installer prompts you to login into the UCP GUI.
INFO[0053] Login to Orca at https://10.0.0.32:443
INFO[0053] Login to UCP at https://10.0.0.32:443
4. Enter the address into your browser to view the Orca login screen.
4. Enter the address into your browser to view the UCP login screen.
The login screen displays.
@ -186,26 +186,26 @@ When you have the information you'll be prompted for, do the following to instal
5. Enter `admin` for the username along with the password you provided to the installer.
If you didn't enter an admin password, the default password is `orca`
After you enter the correct credentials, the Orca dashboard displays.
After you enter the correct credentials, the UCP dashboard displays.
![](dashboard.png)
## Step 6: Set up certs for the Docker CLI
The first thing you probably want to do is download a client bundle. The bundle contains the certificates user needs to run the `docker` clients against the Orca server and nodes.
The first thing you probably want to do is download a client bundle. The bundle contains the certificates user needs to run the `docker` clients against the UCP server and nodes.
1. If you haven't already done so, log into Orca.
1. If you haven't already done so, log into UCP.
2. Choose **ADMIN > Client bundle** from the menu.
The browser downloads the `orca-bundle.zip` file.
The browser downloads the `ucp-bundle.zip` file.
3. Open the folder containing the download file.
4. Unzip the file to reveal its contents.
orca-bundle
ucp-bundle
├── ca.pem
├── cert.pem
├── cert.pub
@ -239,20 +239,20 @@ The first thing you probably want to do is download a client bundle. The bundle
swarm_master=tcp://10.0.0.32:2376
## Step 7: Add a Node to the Orca cluster
## Step 7: Add a Node to the UCP cluster
In this step you install an Orca nodes using the `orca-bootstrap join` subcommand. Repeat the instal for each node you want to add. To review join options before installing the node use the following:
In this step you install an UCP nodes using the `ucp join` subcommand. Repeat the instal for each node you want to add. To review join options before installing the node use the following:
```bash
docker run --rm -it dockerorca/orca-bootstrap join --help
docker run --rm -it dockerorca/ucp join --help
```
The installer prompts you for the following information:
* the URL of the Orca server
* the username/password of an Orca administrator account
* the URL of the UCP server
* the username/password of an UCP administrator account
* your Docker Hub username/password/email
* an alias which is the actual external, publically-accessible IP address or name for the Orca node
* an alias which is the actual external, publically-accessible IP address or name for the UCP node
When you have the information you'll be prompted for, do the following to install:
@ -269,21 +269,21 @@ When you have the information you'll be prompted for, do the following to instal
WARNING: login credentials saved in /home/ubuntu/.docker/config.json
Login Succeeded
3. Run the `orca-bootstrap` installer.
3. Run the `ucp` installer.
$ docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
--name orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
join -i
The installer pulls several images and prompts you for the installation values it needs. When it completes, the installer notifies you that it is starting swarm.
INFO[0005] Verifying your system is compatible with Orca
INFO[0011] Sending add host request to Orca server
INFO[0005] Verifying your system is compatible with UCP
INFO[0011] Sending add host request to UCP server
INFO[0011] Starting local swarm containers
4. Login into Orca with your browser and go to the **NODES** page.
4. Login into UCP with your browser and go to the **NODES** page.
The display should include your new node.
@ -292,22 +292,22 @@ When you have the information you'll be prompted for, do the following to instal
## Uninstall
The installer can also uninstall Orca from the server and the nodes. To see the uninstall options before you uninstall, use the following:
The installer can also uninstall UCP from the server and the nodes. To see the uninstall options before you uninstall, use the following:
```bash
docker run --rm -it dockerorca/orca-bootstrap uninstall --help
docker run --rm -it dockerorca/ucp uninstall --help
```
To uninstall, do the following:
1. Log into the node you want to remove Orca from.
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 orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
uninstall
3. Repeat the uninstall on each node making sure to save the server till last.
@ -316,7 +316,7 @@ To uninstall, do the following:
To block the outflow of Mixplanel analytic data to Docker, do the following:
1. Log into the system running the Orca server.
1. Log into the system running the UCP server.
2. Add a rule to drop the forward to port 80.
@ -326,20 +326,20 @@ Reboots unset this iptables chain, so it is a good idea to add this command to t
## Installing with your own certificates
Orca uses two separate root CAs for access control - one for Swarm, and one for
the Orca server itself. The dual root certificates supply differentiation
between the Docker remote API access to Orca vs. Swarm. Unlike Docker Engine or
Docker Swarm, Orca implements ACL and audit logging on a per-user basis. Swarm
and the Engine proxies trust only the Swarm Root CA, while the Orca server
trusts both Root CAs. Admins can access Orca, Swarm and the engines while
normal users are only granted access to Orca.
UCP uses two separate root CAs for access control - one for Swarm, and one for
the UCP server 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 server
trusts both Root CAs. Admins can access UCP, Swarm and the engines while
normal users are only granted access to UCP.
Orca v1.0 supports user provided externally signed certificates
for the Orca server. This cert is used by Orca'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 Orca.
UCP v1.0 supports user provided externally signed certificates
for the UCP server. 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 Orca Root CA model supports customers managing their own CA, or
purchasing certs from a commercial CA. When operating in this mode, Orca can
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
@ -350,13 +350,13 @@ The first time you install, we recommend you skip user-supplied certs and use th
### Configure user-supplied Certificates
To install Orca with your own external root CA, you create a named volume called
**orca-server-certs** on the same system where you plan to install the Orca
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
server.
1. Log into the machine where you intend to install Orca.
1. Log into the machine where you intend to install UCP.
2. If you haven't already done so, create a named volume called **orca-server-certs**.
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:
@ -371,20 +371,20 @@ server.
</tr>
<tr>
<td><code>cert.pem</code></td>
<td>Your signed Orca server cert.</td>
<td>Your signed UCP server cert.</td>
</tr>
<tr>
<td><code>key.pem</code></td>
<td>Your Orca server private key.</td>
<td>Your UCP server private key.</td>
</tr>
</table>
4. Follow "Step 5" above to install Orca but pass in an additional `--external-orca-ca` option to the installer, for example:
4. Follow "Step 5" above to install UCP but pass in an additional `--external-ucp-ca` option to the installer, for example:
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
...snip...
install -i --external-orca-ca
install -i --external-ucp-ca
## Where to go next

6
kv_store.md
View File

@ -1,6 +1,6 @@
# Key/Value Store
In this release, Orca leverages the
In this release, UCP leverages the
[etcd](https://github.com/coreos/etcd/) KV store.
Under normal circumstances, you should not have to access the KV store
@ -9,7 +9,7 @@ you may be required by Docker support or your SE to change configuration
values or data in the store.
The following example demonstrates basic `curl` usage assuming you
have set up your environment with the downloaded orca bundle.
have set up your environment with the downloaded ucp bundle.
The example below uses the [jq](https://stedolan.github.io/jq/) tool to
pretty print the resulting json. This can be omitted for raw json output.
@ -26,7 +26,7 @@ curl -s \
```
You can browse the Orca keys under `/v2/keys/orca/` and swarm under
You can browse the UCP keys under `/v2/keys/ucp/` and swarm under
`/v2/keys/swarm` as well as modify by `POST`ing updated values to
workaround problems. Further documentation for the etcd API is available
at https://github.com/coreos/etcd/blob/master/Documentation/api.md

24
networking.md
View File

@ -1,7 +1,7 @@
# Cross-Host Networking
For the Orca beta, enabling cross-host networking requires a manual step.
This document explains how to enable this feature after Orca has been
For the UCP beta, enabling cross-host networking requires a manual step.
This document explains how to enable this feature after UCP has been
installed.
@ -13,33 +13,33 @@ officially supported as of Docker 1.9 (it is no longer an
feature). However, in 1.9, enabling this feature requires modifying
command line arguments for the Docker daemon.
The Key/Value store used by Orca, Swarm, and libnetwork is protected
by the Swarm TLS certificate chain managed by Orca. This will prevent
The Key/Value store used by UCP, Swarm, and libnetwork is protected
by the Swarm TLS certificate chain managed by UCP. This will prevent
unathorized access to the clusters configuration, and requires all
clients use a certificate signed by the Orca Swarm Root CA. Admin users
clients use a certificate signed by the UCP Swarm Root CA. Admin users
certificate bundles, and the internal systems are signed by this CA.
During the install of Orca, TLS certificate files are placed on the
During the install of UCP, TLS certificate files are placed on the
host filesystem of each engine in `/var/lib/docker/discovery_certs/`
to aid in the manual setup steps outlined below.
## Instructions
### 0) Install Orca
### 0) Install UCP
Install your controller, and join additional nodes as desired.
You can add additional nodes after enbabling cross-host networking,
however the manual steps described below must be performed **after**
the orca-bootstrap container has run `install` or `join` on the node.
the bootstrap container has run `install` or `join` on the node.
The steps below must be performed on **every** node in your cluster.
### 1) Determine Orca IP
### 1) Determine UCP IP
Before configuring each engine, determine the public facing IP address
(or hostname) of the primary orca system. One example approach to
(or hostname) of the primary ucp system. One example approach to
determine this address is by running the following on the host system
where the Orca controller is running:
where the UCP controller is running:
```bash
ORCA_PUBLIC_IP=$(ip -o -4 route get 8.8.8.8 | cut -f8 -d' ')
@ -62,7 +62,7 @@ for configuring the Docker daemon. The following lists a few examples:
### 3) Add cluster flags to Docker Daemon
For each docker engine in your Orca/Swarm cluster **including the system running orca-controller**, you will have to update the docker daemon command line flags.
For each docker engine in your UCP/Swarm cluster **including the system running ucp-controller**, you will have to update the docker daemon command line flags.
First determine the local engine's public IP:

8
profiling.md
View File

@ -1,6 +1,6 @@
# Profiling Orca
# Profiling UCP
If you run the Orca server with the debug flag set, not only will you get more logging output, but we enable
If you run the UCP server with the debug flag set, not only will you get more logging output, but we enable
remote pprof access.
Links:
@ -14,9 +14,9 @@ Links:
* If you're using TLS (e.g., with bootstrap install) you'll need to add the certs to the local system's trusted certs (unfortunately pprof doesn't have an "--insecure" flag)
```bash
sudo bash -c "docker run --rm -it \
--name orca-bootstrap \
--name ucp \
-v /var/run/docker.sock:/var/run/docker.sock \
dockerorca/orca-bootstrap \
dockerorca/ucp \
dump-certs > /usr/local/share/ca-certificates/orca.crt"
sudo update-ca-certificates
```

76
quickstart.md
View File

@ -1,4 +1,4 @@
# Orca Quick Start Guide
# UCP Quick Start Guide
For all the gory details about how our installer works, check out
[install spec](install_upgrade_spec.md) but you came here to get up and
@ -10,9 +10,9 @@ running quickly, so lets dive right in!
* [https://hub.docker.com/r/dockerorca/orca-bootstrap/](https://hub.docker.com/r/dockerorca/orca-bootstrap/)
* You'll need at leasts one docker engine (local or remote should work)
* If you want to build a multi-node deployment, **all** the nodes must be able to see eachother, so make sure if you're using remote engines, they're all on the same remote network.
* Orca installs its own Swarm, so don't set up Swarm first, just install Orca directly on your engine(s)
* UCP installs its own Swarm, so don't set up Swarm first, just install UCP directly on your engine(s)
* Ports - If you have firewalls configured, please make sure each node can access the following ports on the other nodes in the cluster.
* Orca Server: 443
* UCP Server: 443
* Swarm Manager: 2376 (user configurable) - Protected via mutual TLS
* Engine Proxy: 12376 - Protected via mutual TLS
* KV Store: 12379, 12380 - Protected by mutual TLS
@ -24,12 +24,12 @@ running quickly, so lets dive right in!
```bash
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
--name orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
install --swarm-port 3376 -i
```
The above command will prompt you for some basic information to get Orca
The above command will prompt you for some basic information to get UCP
stood up. You can use "install --help" as the last line above to get
information about various options to the installer.
@ -38,80 +38,80 @@ Important notes for first time users:
* The last line of the installer output tells you where to go log in.
* If you didn't enter an admin password, the default login is "admin/orca"
* The first thing you probably want to do is download a cert bundle (upper right corner of UI, but subject to change)
* With this, you can run docker CLI commands against Orca (and/or the swarm/engines if you're account is an admin account)
* With this, you can run docker CLI commands against UCP (and/or the swarm/engines if you're account is an admin account)
* Take a look at the env.sh within the zip file for instructions (should be familiar if you've used machine)
## Data Persistence
Orca uses named volumes for persistence of user data. By default,
UCP uses named volumes for persistence of user data. By default,
the bootstrapper will create these using the default volume driver and
flags if they are not detected. If you use a custom volume driver, you
can pre-create volumes prior to installing Orca.
can pre-create volumes prior to installing UCP.
* **orca-root-ca** - The certificate and key for the Orca Root CA
* **orca-root-ca** - The certificate and key for the UCP Root CA
* **orca-swarm-root-ca** - The certificate and key for the Swarm Root CA
* **orca-server-certs** - The server certificates for the Orca web server
* **orca-server-certs** - The server certificates for the UCP web server
* **orca-swarm-node-certs** - The swarm certificates for the current node (repeated on every node in the cluster)
* **orca-swarm-kv-certs** The Swarm KV client certificates for the current node (repeated on every node in the cluster)
* **orca-swarm-controller-certs** The Orca Controller Swarm client certificates for the current node
* **orca-swarm-controller-certs** The UCP Controller Swarm client certificates for the current node
* **orca-kv** - KV store persistence
## User Supplied Certificates
Orca uses two separate root CAs for access control - one for Swarm,
and one for the Orca server itself. The motivation for the dual root
certificates is to differentiate Docker remote API access to Orca
vs. Swarm. Orca implements ACL and audit logging on a per-users basis
UCP uses two separate root CAs for access control - one for Swarm,
and one for the UCP server itself. The motivation for the dual root
certificates is to differentiate Docker remote API access to UCP
vs. Swarm. UCP implements ACL and audit logging on a per-users basis
which are not offered in Swarm or the engines. Swarm and the engine
proxies trust only the Swarm Root CA, while the Orca server trusts both
Root CAs. Admins can access Orca, Swarm and the engines while normal
users are only granted access to Orca.
proxies trust only the Swarm Root CA, while the UCP server trusts both
Root CAs. Admins can access UCP, Swarm and the engines while normal
users are only granted access to UCP.
In Orca v1.0 we support user provided externally signed certificates
for the Orca server. This cert is used by the main management web UI
In UCP v1.0 we support user provided externally signed certificates
for the UCP server. This cert is used by the main management web UI
(visible to your browser when you connect) as well as the Docker remote
API (visible to the Docker CLI and friends.) The Swarm Root CA is
always manged by Orca itself in this release. This external Orca Root
always manged by UCP itself in this release. This external UCP Root
CA model supports customers managing their own CA, or purchasing certs
from a commercial CA. When operating in this mode, Orca can not generate
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.
To install Orca with an external Root CA, create a named volume called **orca-server-certs**
on the engine host where you will install Orca **before** running the install, and ensure the following
To install UCP with an external Root CA, create a named volume called **orca-server-certs**
on the engine host where you will install UCP **before** running the install, and ensure the following
files are present in the top-level directory of this volume:
* **ca.pem** - Your Root CA Certificate chain (including any intermediaries)
* **cert.pem** - Your signed Orca server cert
* **key.pem** - Your Orca server private key
* **cert.pem** - Your signed UCP server cert
* **key.pem** - Your UCP server private key
After setting up these files on the host, you can install with the "--external-orca-ca" flag.
If you are creating your own storage volumes (for example, to take
advantage of a 3rd party storage driver) you can omit the **orca-root-ca**
volume as it will not be used when using an external Orca Root CA.
volume as it will not be used when using an external UCP Root CA.
```bash
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
--name orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
install --swarm-port 3376 -i --external-orca-ca
```
# Adding Nodes to the Cluster
To add capacity to your cluster, run the following on the engine you want to add (**not** the engine where you installed Orca above)
To add capacity to your cluster, run the following on the engine you want to add (**not** the engine where you installed UCP above)
```bash
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
--name orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
join -i
```
@ -124,15 +124,15 @@ See [networking.md](networking.md) for more details on the steps required
to enable cross-host networking
# Uninstalling
The installer can also uninstall the Orca software on either the primary
Orca node, as well as the secondary Orca nodes. Run the following directly
against the engine you want to uninstall (**not** against Orca itself)
The installer can also uninstall the UCP software on either the primary
UCP node, as well as the secondary UCP nodes. Run the following directly
against the engine you want to uninstall (**not** against UCP itself)
```bash
docker run --rm -it \
-v /var/run/docker.sock:/var/run/docker.sock \
--name orca-bootstrap \
dockerorca/orca-bootstrap \
--name ucp \
dockerorca/ucp \
uninstall
```

20
support.md
View File

@ -1,11 +1,11 @@
# Orca Support Dumps
# UCP Support Dumps
Orca supports generating support dumps across the entire swarm cluster, leveraging the
UCP supports generating support dumps across the entire swarm cluster, leveraging the
dsinfo container developed by Docker Support.
In this version of Orca, support dumps are only exposed via API, but this can be fairly
In this version of UCP, support dumps are only exposed via API, but this can be fairly
easily accessed with curl. The following example shows how to download a support bundle from your
Orca server.
UCP server.
This example leverages curl, which most customers should have, as well
as a handy utility called [jq](https://stedolan.github.io/jq/). If the
@ -14,7 +14,7 @@ cut-and-paste the token output from the login command below.
```bash
# Replace with your Orca server IP or hostname
# Replace with your UCP server IP or hostname
ORCA=https://192.68.1.2
echo -n "Please enter your admin password"
read -s PASSWORD
@ -26,20 +26,20 @@ curl --insecure -s -H "X-Access-Token:admin:${TOKEN}" -X POST "${ORCA}/api/suppo
Hints:
* The orca server doesn't like extra slashes at the beginning, so if you set your ORCA variable with a trailing slash, then you'll get a 301 (redirect)
* The token often has special characters in it, so if the user cuts and pastes, they may run into problems with the shell interpreting things like $
* If you want to avoid the --insecure, you'll have to install the Orca server's cert locally. See below...
* If you want to avoid the --insecure, you'll have to install the UCP server's cert locally. See below...
## Trusting the Orca server
## Trusting the UCP server
If you want to trust the orca servers certificates on the local system, you can use the following technique. Note that the paths are somewhat system specific and may vary from linux distro to distro.
Run the following when pointed at the machine the Orca server is running on (either locally, or via DOCKER\_HOST
Run the following when pointed at the machine the UCP server is running on (either locally, or via DOCKER\_HOST
```bash
sudo bash -c "docker run --rm -it \
--name orca-bootstrap \
--name ucp \
-v /var/run/docker.sock:/var/run/docker.sock \
dockerorca/orca-bootstrap \
dockerorca/ucp \
dump-certs > /usr/local/share/ca-certificates/orca.crt"
sudo update-ca-certificates
```