Updating with commentary

Adding in text fixes
Updating cert material

Signed-off-by: Mary Anthony <mary@docker.com>

dtr-integration.md

@@ -26,32 +26,35 @@ The Universal Control Plane and Trusted Registry are both part of the Docker
 Datacenter solution. This means the license you use for UCP works with DTR or,
 if you have a DTR license, it also works with UCP.
 
-## Step 1: (Optional) Prepare a cert script
+## Step 1. (Optional) Prepare a cert script
 
-If you are using a self-signed or third-party CA, you need to the prepare a
-`cert_create.sh` script. You'll use this script to install the self-signed cert
-on the nodes in your UCP cluster.
+If you are using a self-signed or third-party CA with the Trusted Registry, you
+need to the prepare a `cert_create.sh` script. You'll use this script to install
+the self-signed cert on the nodes in your UCP cluster.
 
 1. Create a file called `cert_create.sh` with your favorite editor.
 
 2. Add the following to content to the file.
 
-        DTR_HOST="<my-dtr-host-dns-name"
-        mkdir -p ~/.docker/tls/${DTR_HOST}
-        openssl s_client -host ${DTR_HOST} -port 443 </dev/null 2>/dev/null | openssl x509 -outform PEM | tee ~/.docker/tls/${DTR_HOST}/ca.crt
+        DTR_HOST="<dtr-fully-qualified-domain-name>"
+        sudo mkdir -p /etc/docker/certs.d/${DTR_HOST}
+        openssl s_client -host ${DTR_HOST} -port 443 </dev/null 2>/dev/null | openssl x509 -CAform PEM | sudo tee /etc/docker/certs.d/${DTR_HOST}/ca.crt
 
-3.  Replace the `<my-dtr-host-dns-name>` value with the fully qualified DNS
+3.  Replace the `<dtr-fully-qualified-domain-name>` value with the fully qualified DNS
     value for your DTR instance.
 
 4. Save and close the `cert_create.sh` file.
 
-4. Set execute permission on the file.
+5. Set execute permission on the file.
 
         $ chmod 755 cert_create.sh
 
-## Step 2: Configure DTR and UCP
 
-In this step, you configure DTR and UCP to communicate. To do this you need an admin level certificate bundle for UCP or terminal access to the UCP controller.  
+## Step 2. Add the UCP cert to the Trusted Registry
+
+In this step, you configure DTR and UCP to communicate. To do this you need an
+admin level certificate bundle for UCP or terminal access to the UCP controller.
+This setup also requires restarting the Docker Trusted Registry server.
 
 1. Log into or connect to the UCP primary controller.
 
@@ -59,15 +62,17 @@ In this step, you configure DTR and UCP to communicate. To do this you need an a
 
     This command generates the certificates for the Swarm cluster.
 
-        $ docker run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp dump-certs  --cluster -ca > /tmp/cluster-root-chain.pem
+        $ docker run --rm -it --name ucp -v /var/run/docker.sock:/var/run/docker.sock docker/ucp dump-certs  --cluster -ca > /tmp/cluster-root-ca.pem
 
-3. Cat or edit the `cluster-root-chain.pem` file.
+3. Cat the `cluster-root-ca.pem` file.
 
-4. Copy the certificate.
+        $ cat /tmp/cluster-root-ca.pem
+
+4. Copy the UCP cluster's root CA.
 
     This example illustrates what you should copy, your installation certificate
     will be different.
-    
+
         -----BEGIN CERTIFICATE-----
         MIIFGDCCAwCgAwIBAgIIIQjwMnZnj2gwDQYJKoZIhvcNAQENBQAwGDEWMBQGA1UE
         AxMNU3dhcm0gUm9vdCBDQTAeFw0xNjAyMTAxNzQzMDBaFw0yMTAyMDgxNzQzMDBa
@@ -86,10 +91,60 @@ In this step, you configure DTR and UCP to communicate. To do this you need an a
 
 7. Locate the **Auth Bypass TLS Root CA** field.
 
-8. Paste certificate you copied into the field.
+8. Paste the UCP root CA you copied in step 4 above into this field.
 
-9. (Optional) If you are using a self-signed or third-party CA, do the following
-on each node in your UCP cluster:     
+9. Scroll to the bottom of the page and press **Save and restart**.
+
+
+## Step 3. Add the Trusted Registry cert to UCP
+
+You must integrate the Trusted Registry with UCP by installing the Trusted
+Registry CA into your UCP.
+
+1. Log into UCP.
+
+2. Choose **Settings > DTR**.
+
+3. Enter the URL of your Trusted Registry in the **URL** field.
+
+4. Do not set the **Insecure** option.
+
+   Regardless of whether you are using self-signed, external third-party, or
+   internal certificates, setting this value means that traffic between the
+   Trusted Registry and UCP is encrypted but unverified. Setting **Insecure** is
+   not recommended as it makes your installation vulnerable to man-in-the-middle
+   attacks.
+
+5. (Optional) Upload the Trusted Registry root CA certificate.
+
+    If your Trusted Registry installation is using an external, 3rd-party root
+    CA you can skip this step. If your registry is using internal, corporate or
+    a self-signed root CA, you *must* follow this step. To create the Trusted
+    Registry root CA file:
+
+    a. Connect to the DTR node via an authorized UCP certificate
+    bundle.
+
+    b. Run the following command:
+
+      openssl s_client -host <dtr-fully-qualified-domain-name> -port 443 </dev/null 2>/dev/null | openssl x509 -CAform PEM | tee /tmp/dtr.pem
+
+      For example:
+
+      $ openssl s_client -host ec2-54-187-154-87.us-west-2.compute.amazonaws.com -port 443 </dev/null 2>/dev/null | openssl x509 -CAform PEM | tee /tmp/dtr.pem
+
+    c. Upload the `dtr.pem` file you just created.
+
+      ![](images/dtr-integrate.png)
+
+6. Press **Update Registry** to save your changes.
+
+7. (Optional) Install the Trusted Registry certificate on every UCP node in your cluster.
+
+    This step ensures that the UCP nodes trust the registry's root CA. If your
+    Trusted Registry installation is using an external, 3rd-party root CA
+    you can skip this step. If your registry is using internal, corporate or a
+    self-signed root CA, you *must* follow this step.
 
     a. Log into a UCP node using an account with `sudo` privileges.
 
@@ -101,14 +156,38 @@ on each node in your UCP cluster:
 
     d. Verify the cert was created.
 
-        $ sudo cat ~/.docker/tls/${DTR_HOST}/ca.crt
+        $ sudo cat /etc/docker/certs.d/<dtr-fully-qualified-domain-name>/ca.crt
 
 
-## Step 2: Confirm the integration
+## Step 4. Create a test repository
 
-The best way to confirm the integration is to push and pull an image from a UCP node.
+Before you can confirm you integration, you need to make sure you have a test
+repository on the Trusted Registry.
 
-1. Open a terminal session on a UCP node.
+1. Log into the Trusted Registry.
+
+2. Choose **Repositories**.
+
+3. Choose **New repository**.
+
+4. Create a private repository called `hello_world` under your username.
+
+    ![](images/dtr-integrate.png)
+
+5. Press **Save**.
+
+6. Go to the **Settings** page and look for the **Domain name**.
+
+    You'll use name value in the next section, write it down or remember it.
+
+## Step 5. Confirm the integration
+
+The best way to confirm the integration is to push and pull an image from a UCP
+node to your test repository. In this procedure, you must use a username and
+password combination that exists on both the Trusted Registry and UCP.
+
+1. Connect to the terminal on a UCP node via an authorized UCP certificate
+bundle.
 
 2. Pull Docker's `hello-world` image.
 
@@ -120,38 +199,72 @@ The best way to confirm the integration is to push and pull an image from a UCP
         Digest: sha256:8be990ef2aeb16dbcb9271ddfe2610fa6658d13f6dfb8bc72074cc1ca36966a7
         Status: Downloaded newer image for hello-world:latest
 
-3. Get the `IMAGE ID` of the `hello-world` image.
+3. List the `hello-world` image.
 
         $ docker images
-        REPOSITORY          TAG                        IMAGE ID            CREATED             SIZE
-        hello-world         latest                     690ed74de00f        4 months ago        960 B
+        REPOSITORY              TAG                 IMAGE ID            CREATED             SIZE
+        ...<output snipped>...
+        hello-world             latest              690ed74de00f        4 months ago        960 B
 
-5. Retag the `hello-world` image with a new tag.
+4. Retag the `hello-world` image with a new tag.
 
     The syntax for tagging an image is:
 
-        docker tag <ID> <username>/<image-name>:<tag>
+        docker tag <image-name> <dtr-domain-name>/<username>/<image-name>:<tag>
 
     Make sure to replace `<username>` with your actual username and the <ID>
     with the ID of the `hello-world` image you pulled.
 
-        $ docker tag 690ed74de00f username/hello-world:test
+        $ docker tag hello-world mydtr.company.com/moxiegirl/hello_world:test
 
-4. Login into the DTR instance from the command line.
+5. List the new image.
+
+
+        $ docker images
+        REPOSITORY                        TAG                 IMAGE ID            CREATED             SIZE
+        ...<output snipped>...
+        hello-world                       latest              690ed74de00f        4 months ago        960 B
+        mydtr.company.com/admin/hello_world   test                690ed74de00f        4 months ago        960 B
+
+6. Login into the DTR instance from the command line.
 
     The example below uses `mydtr.company.com` as the URL for the DTR instance.
     Your's will be different.  
 
         $  docker login mydtr.company.com
 
-    Provide your username password when prompted.
+    Provide your username, password, and email when prompted.
 
-5. Push your newly tagged image to the DTR instance.
+7. Push your newly tagged image to the DTR instance.
 
     The following is an example only, substitute your DTR URL and username when
     you run this command.            
 
-        $ docker push  mydtr.company.com/username/hello-world:test
+        $ docker push mydtr.company.com/moxiegirl/hello_world:test
+        The push refers to a repository [mydtr.company.com/moxiegirl/hello_world]
+        5f70bf18a086: Pushed
+        b652ec3a27e7: Pushed
+        test: digest: sha256:6febc57b05c1a791edd184fd3480a33aaa63949573daa5d1bd17bb5f75477b82 size: 1941
+
+8. Log into the Trusted Registry and confirm your repository contains the image your pushed.
+
+    ![](images/dtr_tag.png)
+
+9. Log into UCP.
+
+10. Choose **Images** and search for `hello`.
+
+    ![](images/dtr_hello.png)
+
+11. Delete any `hello-world` or `hello_world` image.
+
+    This step ensures the next step goes to the Trusted Registry. Once you are sure you no longer have any of your test images in UCP, go onto the next step.
+
+12. While still on **Images**, choose **Pull Image**
+
+13. Enter the name of your test image and press **Pull**.
+
+    ![](images/dtr_pull.png)
 
 
 ## Troubleshooting section
@@ -159,6 +272,11 @@ The best way to confirm the integration is to push and pull an image from a UCP
 This section details common problems you can encounter when working with the DTR /
 UCP integration.
 
+### Pull completes but no image is pulled
+
+Currently, UCP does not return pull errors in the UI. If you do not get an image
+with the **Pull Images** operation, check the UCP controller logs.
+
 ### Unknown authority error on push
 
 Example: