diff --git a/datacenter/dtr/2.1/guides/high-availability/backups-and-disaster-recovery.md b/datacenter/dtr/2.1/guides/high-availability/backups-and-disaster-recovery.md index f85683a090..9746270d9b 100644 --- a/datacenter/dtr/2.1/guides/high-availability/backups-and-disaster-recovery.md +++ b/datacenter/dtr/2.1/guides/high-availability/backups-and-disaster-recovery.md @@ -56,8 +56,7 @@ backup command to learn about all the available flags. As an example, to create a backup of a DTR node, you can use: -```bash -# Create the backup +```none $ docker run -i --rm docker/dtr backup \ --ucp-url \ --ucp-insecure-tls \ @@ -76,7 +75,7 @@ Where: To validate that the backup was correctly performed, you can print the contents of the tar file created: -```bash +```none $ tar -tf /tmp/backup.tar ``` @@ -105,7 +104,7 @@ backup command to learn about all the available flags. As an example, to install DTR on the host and restore its state from an existing backup: -```bash +```none # Install and restore configurations from an existing backup $ docker run -i --rm \ docker/dtr restore \ diff --git a/datacenter/dtr/2.1/guides/install/scale-your-deployment.md b/datacenter/dtr/2.1/guides/install/scale-your-deployment.md index b178c76187..cda1e710c2 100644 --- a/datacenter/dtr/2.1/guides/install/scale-your-deployment.md +++ b/datacenter/dtr/2.1/guides/install/scale-your-deployment.md @@ -20,9 +20,9 @@ you're going to install these replicas also need to be managed by UCP. To add replicas to an existing DTR deployment: -1. Load your UCP user bundle. +1. Use ssh to log into a node that is already part of UCP. -2. Run the join command. +2. Run the DTR join command: ```none docker run -it --rm \ @@ -39,7 +39,10 @@ To add replicas to an existing DTR deployment: ## Remove existing replicas -To remove a DTR replica from a deployment, run: +To remove a DTR replica from your deployment: + +1. Use ssh to log into a node that is already part of UCP. +2. Run the DTR remove command: ```none docker run -it --rm \ diff --git a/datacenter/install/linux.md b/datacenter/install/linux.md index 454d200116..278da26974 100644 --- a/datacenter/install/linux.md +++ b/datacenter/install/linux.md @@ -33,7 +33,7 @@ Also make sure the hosts are running one of these operating systems: Install the commercially supported Docker Engine on all hosts you want to manage with Docker Datacenter. -Log in into each node using ssh, and install CS Docker Engine: +Log in into each host using ssh, and install CS Docker Engine: ```bash curl -SLf https://packages.docker.com/1.12/install.sh | sh @@ -59,6 +59,8 @@ docker run --rm -it --name ucp \ This runs the install command in interactive mode, so that you're prompted for any necessary configuration values. +[Learn more about the UCP installation](../ucp/2.9/guides/installation/index.md) + ### Step 4: License your installation Now that UCP is installed, you need to license it. In your browser, navigate @@ -110,7 +112,5 @@ by UCP. ## Where to go next -* [Create and manage users](../ucp/2.0/guides/user-management/create-and-manage-users.md) * [Deploy an application](../ucp/2.0/guides/applications/index.md) -* [Push an image to DTR](../dtr/2.1/guides/repos-and-images/push-an-image.md) -* [Considerations for a High Availability Deployment](../ucp/2.0/guides/high-availability/index.md) +* [Considerations for high availability](../ucp/2.0/guides/high-availability/index.md) diff --git a/datacenter/ucp/2.0/guides/access-ucp/cli-based-access.md b/datacenter/ucp/2.0/guides/access-ucp/cli-based-access.md index c45ebd48ed..c7b6f8103e 100644 --- a/datacenter/ucp/2.0/guides/access-ucp/cli-based-access.md +++ b/datacenter/ucp/2.0/guides/access-ucp/cli-based-access.md @@ -11,10 +11,10 @@ For this reason, when running docker commands on a UCP node, you need to authenticate your request using client certificates. When trying to run docker commands without a valid certificate, you get an authentication error: -```markdown +```none $ docker ps -An error occurred trying to connect: Get https://ucp:443/v1.22/containers/json: x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" when trying to verify candidate authority certificate "UCP Client Root CA") +x509: certificate signed by unknown authority ``` There are two different types of client certificates: @@ -26,8 +26,8 @@ controller node. ## Download client certificates -To download a client certificate bundle, **log into UCP**, and navigate to your -**profile page**. +To download a client certificate bundle, log into the **UCP web UI**, and +navigate to your user **profile page**. ![](../images/cli-based-access-1.png) @@ -36,66 +36,52 @@ Click the **Create a Client Bundle** button, to download the certificate bundle. ## Use client certificates -Once you've downloaded a client certificate bundle, you can use it to -authenticate your requests. +Once you've downloaded a client certificate bundle to your local computer, you +can use it to authenticate your requests. -Navigate to the directory where you downloaded the bundle, and unzip it. Then -run the `env.sh` script to start using the client certificates. +Navigate to the directory where you downloaded the user bundle, and unzip it. +Then source the `env.sh` script. -```bash +```none $ unzip ucp-bundle-dave.lauper.zip $ cd ucp-bundle-dave.lauper $ eval $(","password":""}' https:///auth/login | jq -r .auth_token) + # Download the client certificate bundle $ curl -k -H "Authorization: Bearer $AUTHTOKEN" https:///api/clientbundle -o bundle.zip ``` ## Where to go next -* [Deploy an app from the UI](../applications/index.md) +* [Access the UCP web UI](index.md) * [Deploy an app from the CLI](../applications/deploy-app-cli.md) diff --git a/datacenter/ucp/2.0/guides/access-ucp/index.md b/datacenter/ucp/2.0/guides/access-ucp/index.md index 43b4d46e95..3a71166a4a 100644 --- a/datacenter/ucp/2.0/guides/access-ucp/index.md +++ b/datacenter/ucp/2.0/guides/access-ucp/index.md @@ -21,3 +21,7 @@ browser, Administrators can: Non-admin users can only see and change the images, networks, volumes, and containers, they are granted access. + +# Where to go next + +* [Access UCP from the CLI](cli-based-access.md) diff --git a/datacenter/ucp/2.0/guides/applications/deploy-app-cli.md b/datacenter/ucp/2.0/guides/applications/deploy-app-cli.md index df1b1f47fb..f4aadcb07e 100644 --- a/datacenter/ucp/2.0/guides/applications/deploy-app-cli.md +++ b/datacenter/ucp/2.0/guides/applications/deploy-app-cli.md @@ -13,8 +13,8 @@ application. Docker UCP secures your Docker swarm with role-based access control, so that only authorized users can deploy applications. To be able to run -Docker commands on a swarm managed by UCP, you need to authenticate your -requests using client certificates. +Docker commands on a swarm managed by UCP, you need to configure your Docker CLI +client to authenticate to UCP using client certificates. [Learn how to set your CLI to use client certificates](../access-ucp/cli-based-access.md). @@ -25,7 +25,7 @@ The WordPress application we're going to deploy is composed of two services: * wordpress: The service that runs Apache, PHP, and WordPress. * db: A MariaDB database used for data persistence. -After setting up your terminal to authenticate using client certificates, +After setting up your Docker CLI client to authenticate using client certificates, create a file named `docker-compose.yml` with the following service definition: ```none @@ -58,14 +58,14 @@ volumes: ``` In your command line, navigate to the place where you've created the -`docker-compose.yml` file and run: +`docker-compose.yml` file and deploy the application to UCP by running: ```bash $ docker-compose --project-name wordpress up -d ``` -Test that the WordPress service is up and running, and find where you can -reach it. +Test that the WordPress service is up and running, and find on which node it +was deployed. ```bash $ docker-compose --project-name wordpress ps @@ -76,7 +76,7 @@ wordpress_db_1 docker-entrypoint.sh mysqld Up 3306/tcp wordpress_wordpress_1 docker-entrypoint.sh apach ... Up 172.31.18.153:8000->80/tcp ``` -In this example, WordPress can be accessed at 172.31.18.153:8000. Navigate to +In this example, WordPress was deployed to 172.31.18.153:8000. Navigate to this address in your browser, to start using the WordPress app you just deployed. diff --git a/datacenter/ucp/2.0/guides/applications/index.md b/datacenter/ucp/2.0/guides/applications/index.md index 8029989546..ac8d1433ed 100644 --- a/datacenter/ucp/2.0/guides/applications/index.md +++ b/datacenter/ucp/2.0/guides/applications/index.md @@ -11,7 +11,7 @@ WordPress application. ## Deploy WordPress -On your browser, **log in** to UCP, and navigate to the **Applications** page. +In your browser, **log in** to UCP, and navigate to the **Applications** page. There, click the **Deploy compose.yml** button, to deploy a new application. ![](../images/deploy-app-ui-1.png) diff --git a/datacenter/ucp/2.0/guides/configuration/index.md b/datacenter/ucp/2.0/guides/configuration/index.md index c8eff1d7a6..6ac29c0bbf 100644 --- a/datacenter/ucp/2.0/guides/configuration/index.md +++ b/datacenter/ucp/2.0/guides/configuration/index.md @@ -5,39 +5,49 @@ keywords: Universal Control Plane, UCP, certificate, authentiation, tls title: Use externally-signed certificates --- -By default the UCP web UI is exposed using HTTPS, to ensure all -communications between clients and UCP are encrypted. Since UCP -controllers use self-signed certificates for this, when a client accesses -UCP their browsers won't trust this certificate, so the browser displays a -warning message. +All UCP services are exposed using HTTPS, to ensure all communications between +clients and UCP are encrypted. By default this is done using self-signed TLS +certificates that are not trusted by client tools like web browsers. So when +you try to access UCP, your browser will warn that it doesn't trust UCP or that +UCP has an invalid certificate. -You can configure UCP to use your own certificates, so that it is automatically -trusted by your users' browser and client tools. +![invalid certificate](../images/use-externally-signed-certs-1.png) + +The same happens with other client tools. + +```none +$ curl https://ucp.example.org + +SSL certificate problem: Invalid certificate chain +``` + +You can configure UCP to use your own TLS certificates, so that it is +automatically trusted by your browser and client tools. To ensure minimal impact to your business, you should plan for this change to -happen outside business peak hours. Your applications will continue -running normally, but UCP will be unresponsive while the controller containers -are restarted. +happen outside business peak hours. Your applications will continue running +normally, but existing UCP client certificates will become invalid, so users +will have to download new ones to [access UCP from the CLI](../access-ucp/cli-based-access.md). -## Replace the server certificates +## Customize the UCP TLS certificates -To configure UCP to use your own certificates and keys, go to the +To configure UCP to use your own TLS certificates and keys, go to the **UCP web UI**, navigate to the **Admin Settings** page, and click **Certificates**. -![](../images/use-externally-signed-certs-1.png) +![](../images/use-externally-signed-certs-2.png) Upload your certificates and keys: * A ca.pem file with the root CA public certificate. -* A cert.pem file with the server certificate and any intermediate CA public +* A cert.pem file with the TLS certificate and any intermediate CA public certificates. This certificate should also have SANs for all addresses used to -reach the UCP controller, including load balancers. -* A key.pem file with server private key. +access UCP, including load balancers. +* A key.pem file with TLS private key. Finally, click **Update** for the changes to take effect. -After replacing the certificates your users won't be able to authenticate +After replacing the TLS certificates your users won't be able to authenticate with their old client certificate bundles. Ask your users to go to the UCP web UI and [get new client certificate bundles](../access-ucp/cli-based-access.md). diff --git a/datacenter/ucp/2.0/guides/configuration/integrate-with-dtr.md b/datacenter/ucp/2.0/guides/configuration/integrate-with-dtr.md index 1dfc381c42..f4c39a1ed8 100644 --- a/datacenter/ucp/2.0/guides/configuration/integrate-with-dtr.md +++ b/datacenter/ucp/2.0/guides/configuration/integrate-with-dtr.md @@ -36,9 +36,9 @@ x509: certificate signed by unknown authority ## 1. Configure your local computer -If you want to use your local computer to interact with DTR, you also need to -configure configure it to trust the DTR TLS certificates. This depends on the -operating system: +If you want to use your local computer to interact with DTR, you need to +configure it to trust the DTR TLS certificates. This depends on the operating +system: * For macOS: @@ -56,7 +56,7 @@ operating system: ```bash # Download the DTR CA certificate - $ sudo curl -k https:///ca -o /usr/local/share/ca-certificates/.crt + $ sudo curl -k https:///ca -o /usr/local/share/ca-certificates/.crt # Refresh the list of certificates to trust $ sudo update-ca-certificates @@ -69,7 +69,7 @@ operating system: ```bash # Download the DTR CA certificate - $ sudo curl -k https:///ca -o /etc/pki/ca-trust/source/anchors/.crt + $ sudo curl -k https:///ca -o /etc/pki/ca-trust/source/anchors/.crt # Refresh the list of certificates to trust $ sudo update-ca-trust @@ -78,12 +78,12 @@ operating system: $ sudo /bin/systemctl restart docker.service ``` -## 2. Test your setup +## 2. Test your local setup The best way to confirm that your computer is correctly configured, is by trying to pull and push images from your local Docker installation to DTR. -1. Create a test repository on DTR. +1. Create a test repository on DTR. Navigate to the **DTR web UI**, and create a new **hello-world** repository so that you can push and pull images. Set it as **private**, and save @@ -91,28 +91,24 @@ trying to pull and push images from your local Docker installation to DTR. ![](../images/dtr-integration-1.png) -2. Use a [UCP client bundle](../access-ucp/cli-based-access.md) to run docker -commands in the UCP cluster. +2. Pull the `hello-world` image from Docker Store, re-tag it, and push it to the +DTR repository you created. -3. Pull an image from Docker Hub: + ```none + # Pull hello-world from Docker Store + docker pull hello-world:latest - ```bash - $ docker pull hello-world + # Re-tag it + docker tag hello-world:latest //hello-world:latest + + # Log into DTR + docker login + + # Push your image to DTR + docker push //hello-world:latest ``` -4. Retag the image: - - ```bash - $ docker tag hello-world:latest //hello-world:1 - ``` - -5. Push the image from the UCP node to your private registry: - - ```bash - $ docker push //hello-world:1 - ``` - -6. Validate that your image is now stored on DTR. +3. Validate that your image is now stored in DTR. When successfully pushing the image you should see a result like: @@ -128,31 +124,19 @@ commands in the UCP cluster. ![](../images/dtr-integration-2.png) +## 3. Configure UCP Docker Engines - - -## 1. Configure UCP Docker Engines +You also need to configure the Docker Engine on every UCP node to trust the +DTR TLS certificates. This allows you do deploy services to UCP using images +that are stored in DTR. For each UCP node: 1. Log into the node as an administrator, using ssh -2. Configure the system to trust the DTR TLS certificates. This depends on -the operating system. +2. Configure the system to trust the DTR TLS certificates, following the same +steps as you used to configure your local computer. -## Troubleshooting - -When one of the components is misconfigured, and doesn't trust the root CA -certificate of the other components, you'll get an error like: - -```none -$ docker push dtr/username/hello-world:1 - -The push refers to a repository [dtr/username/hello-world] -Get https://dtr/v1/_ping: x509: certificate signed by unknown authority -``` ## Where to go next -* [Monitor your cluster](../monitor/index.md) -* [Troubleshoot your cluster](../monitor/troubleshoot.md) -* [Run only signed images](../content-trust/index.md) +* [Use externally-signed certificates](index.md) diff --git a/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-1.png b/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-1.png index 7bd15cacb0..c87bb7bf25 100644 Binary files a/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-1.png and b/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-1.png differ diff --git a/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-2.png b/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-2.png new file mode 100644 index 0000000000..9918180e1a Binary files /dev/null and b/datacenter/ucp/2.0/guides/images/use-externally-signed-certs-2.png differ diff --git a/datacenter/ucp/2.0/guides/index.md b/datacenter/ucp/2.0/guides/index.md index b04696062a..0ce86293d0 100644 --- a/datacenter/ucp/2.0/guides/index.md +++ b/datacenter/ucp/2.0/guides/index.md @@ -6,60 +6,69 @@ title: Universal Control Plane overview --- Docker Universal Control Plane (UCP) is the enterprise-grade cluster management -solution from Docker. You install it behind your firewall, and it helps you -manage your whole cluster from a single place. +solution from Docker. You install it on-premises or in your virtual private +cloud, and it helps you manage your Docker cluster and applications from a +single place. ![](images/overview-1.png) ## Centralized cluster management -Docker UCP can be installed on-premises, or on a virtual private cloud. -And with it, you can manage thousands of nodes as if they were a single one. -You can monitor and manage your cluster using a graphical UI. +With Docker you can join up to thousands of physical or virtual machines +together to create a container cluster, allowing you to deploy your applications +at scale. Docker Universal Control Plane extends the functionality provided +by Docker to make it easier to manage your cluster from a centralized place. + +You can manage and monitor your container cluster using a graphical UI. ![](images/overview-2.png) Since UCP exposes the standard Docker API, you can continue using the tools -you already know, to manage a whole cluster. +you already know, including the Docker CLI client, to deploy and manage your +applications. As an example, you can use the `docker info` command to check the -status of the cluster: +status of a Docker cluster managed by UCP: ```bash $ docker info Containers: 30 Images: 24 -Server Version: swarm/1.1.3 +Server Version: ucp/2.0.1 Role: primary Strategy: spread -Filters: health, port, dependency, affinity, constraint +Filters: health, port, containerslots, dependency, affinity, constraint Nodes: 2 - ucp: 192.168.99.103:12376 + ucp-node-1: 192.168.99.100:12376 └ Status: Healthy └ Containers: 20 - ucp-replica: 192.168.99.102:12376 + ucp-node-2: 192.168.99.101:12376 └ Status: Healthy └ Containers: 10 ``` ## Deploy, manage, and monitor -With Docker UCP you can manage the nodes of your infrastructure. You can also -manage apps, containers, networks, images, and volumes, in a transparent way. +With Docker UCP you can manage from a centralized place all the computing +resources you have available like nodes, volumes, and networks. + +You can also deploy and monitor your applications and services. ## Built-in security and access control -Docker UCP has its own built-in authentication mechanism, and supports LDAP -and Active Directory. It also supports Role Based Access Control (RBAC). -This ensures that only authorized users can access and make changes to cluster. +Docker UCP has its own built-in authentication mechanism and integrates with +LDAP services. It also has Role Based Access Control (RBAC), so that you can +control who can access and make changes to your cluster and applications. ![](images/overview-3.png) -Docker UCP also integrates with Docker Trusted Registry and Docker Content -Trust. This allows you to keep your images stored behind your firewall, -where they are safe. It also allows you to sign those images to ensure that -the images you deploy have not been altered in any way. +Docker UCP integrates with Docker Trusted Registry so that you can keep the +Docker images you use for your applications behind your firewall, where they +are safe and can't be tampered. + +You can also enforce security policies and only allow running applications +that use Docker images you know and trust. ## Where to go next diff --git a/datacenter/ucp/2.0/guides/installation/index.md b/datacenter/ucp/2.0/guides/installation/index.md index 72b673edef..6ed654a45d 100644 --- a/datacenter/ucp/2.0/guides/installation/index.md +++ b/datacenter/ucp/2.0/guides/installation/index.md @@ -7,8 +7,6 @@ title: Install UCP for production Docker Universal Control Plane (UCP) is a containerized application that can be installed on-premise or on a cloud infrastructure. -If you're installing Docker Datacenter on Azure, [follow this guide](https://success.docker.com/?cid=ddc-on-azure). - ## Step 1: Validate the system requirements The first step to installing UCP, is ensuring your @@ -17,9 +15,19 @@ infrastructure has all the [requirements UCP needs to run](system-requirements.m ## Step 2: Install CS Docker on all nodes -UCP is a containerized application that requires CS Docker Engine 1.12.0 or -above to run. Start by installing CS Docker Engine on all hosts that you want to -manage with UCP. +UCP is a containerized application that requires the commercially supported +Docker Engine to run. + +For each host that you plan to manage with UCP: + +1. Log in into that host using ssh. +2. Install CS Docker Engine: + + ```bash + curl -SLf https://packages.docker.com/1.12/install.sh | sh + ``` + + [You can also install CS Docker Engine using a package manager](/cs-engine/install.md) Make sure you install the same CS Docker Engine version on all the nodes. Also, if you're creating virtual machine templates with CS Docker Engine already @@ -79,12 +87,12 @@ If you don't have a license yet, [learn how to get a free trial license](license ## Step 6: Join manager nodes -Skip this step if you don't want your UCP swarm to be highly available. +Skip this step if you don't want UCP to be highly available. -To make your UCP swarm fault-tolerant and highly available, you -can join more manager nodes to your it. Manager nodes are the nodes in the -swarm that perform the orchestration and swarm management tasks, and -dispatch tasks for worker nodes to execute. +To make your Docker swarm and UCP fault-tolerant and highly available, you can +join more manager nodes to your it. Manager nodes are the nodes in the swarm +that perform the orchestration and swarm management tasks, and dispatch tasks +for worker nodes to execute. [Learn more about high-availability](../high-availability/index.md). To join manager nodes to the swarm, go to the **UCP web UI**, navigate to diff --git a/datacenter/ucp/2.0/guides/installation/plan-production-install.md b/datacenter/ucp/2.0/guides/installation/plan-production-install.md index e606ec706e..867d0a597c 100644 --- a/datacenter/ucp/2.0/guides/installation/plan-production-install.md +++ b/datacenter/ucp/2.0/guides/installation/plan-production-install.md @@ -5,16 +5,17 @@ keywords: docker, ucp, install, checklist title: Plan a production installation --- -Docker Universal Control Plane can be installed on-premises, or -on a virtual private cloud. -This article explains what you need to consider before deploying -Docker Universal Control Plane. +Docker Universal Control Plane helps you manage your container cluster from a +centralized place. This article explains what you need to consider before +deploying Docker Universal Control Plane for production. ## System requirements -Before installing UCP, you should make sure all nodes of your cluster -comply with the [system requirements](system-requirements.md). +Before installing UCP you should make sure that all nodes (physical or virtual +machines) that you'll manage with UCP: +* [Comply the the system requirements](system-requirements.md) +* Are running the same version of CS Docker Engine ## Hostname strategy