From 30778f3e9f552cf0a83d9ae696960982a03f0883 Mon Sep 17 00:00:00 2001 From: Maria Bermudez Date: Tue, 19 Feb 2019 12:17:28 -0800 Subject: [PATCH] Initial edits --- .../sign-images/trust-with-remote-ucp.md | 156 ++++++++---------- 1 file changed, 70 insertions(+), 86 deletions(-) diff --git a/ee/dtr/user/manage-images/sign-images/trust-with-remote-ucp.md b/ee/dtr/user/manage-images/sign-images/trust-with-remote-ucp.md index d4d84e08ed..ecd81a46a1 100644 --- a/ee/dtr/user/manage-images/sign-images/trust-with-remote-ucp.md +++ b/ee/dtr/user/manage-images/sign-images/trust-with-remote-ucp.md @@ -6,84 +6,78 @@ keywords: registry, sign, trust, notary For more advanced deployments, you may want to share one Docker Trusted Registry across multiple Universal Control Planes. However, customers wanting to adopt -this model, alongside the [Only Run Signed -Images](../.../../ucp/admin/configure/run-only-the-images-you-trust.md) feature -of UCP, run into problems as each Universal Control Plane operates an -independent set of users. +this model alongside the [Only Run Signed +Images](../.../../ucp/admin/configure/run-only-the-images-you-trust.md) UCP feature, run into problems as each UCP operates an independent set of users. -Docker Content Trust with a Remote UCP gets around this problem, as User's from -a remote UCP are able to sign images in the central DTR, and still apply runtime +Docker Content Trust (DCT) gets around this problem, since users from +a remote UCP are able to sign images in the central DTR and still apply runtime enforcement. -In the following example we will connect DTR to 1 remote UCP cluster, sign the -image with a User from that remote UCP cluster, and provide runtime enforcement -within the remote UCP cluster. This process could be repeated over and over, -integrating DTR with multiple remote UCP clusters, signing the image with Users +In the following example, we will connect DTR managed by UCP cluster 1 with a remote UCP cluster which we are calling UCP cluster 2, sign the +image with a user from UCP cluster 2, and provide runtime enforcement +within UCP cluster 2. This process could be repeated over and over, +integrating DTR with multiple remote UCP clusters, signing the image with users from each environment, and then providing runtime enforcement in each remote UCP -cluster seperately. +cluster separately. ![](../../../images/remoteucp-graphic.png) -> Before attempting this guide, please familiarize yourself with [Docker Content +> Before attempting this guide, familiarize yourself with [Docker Content > Trust](engine/security/trust/content_trust/#signing-images-with-docker-content-trust) > and [Only Run Signed > Images](../.../../ucp/admin/configure/run-only-the-images-you-trust.md) on a -> single UCP. A lot of the concepts within this guide may be new without that +> single UCP. Many of the concepts within this guide may be new without that > background. ## Prerequisites - Cluster 1, running UCP 3.0.x or higher, with a DTR 2.5.x or higher deployed within the cluster. -- Cluster 2, running UCP 3.0.x or higher, it is expected that - there is no DTR installed on this environment. -- Nodes on Cluster 2 need to trust the Certificate Authority that signed DTR's - TLS Certificate. This can be tested by logging on to a Cluster 2 virtual +- Cluster 2, running UCP 3.0.x or higher, with no DTR node. +- Nodes on Cluster 2 need to trust the Certificate Authority which signed DTR's + TLS Certificate. This can be tested by logging on to a cluster 2 virtual machine and running `curl https://dtr.example.com`. - The DTR TLS Certificate needs be properly configured, ensuring that the **Loadbalancer/Public Address** field has been configured, with this address included [within the certificate](../../../admin/configure/use-your-own-tls-certificates/). -- A workstation with the [Docker Client](/ee/ucp/user-access/cli/) (CE 17.12 / +- A machine with the [Docker Client](/ee/ucp/user-access/cli/) (CE 17.12 / EE 1803 or newer) installed, as this contains the relevant `$ docker trust` commands. ## Registering DTR with a remote Universal Control Plane -As there is no registry running within Cluster 2, by default UCP will not know +As there is no registry running within cluster 2, by default UCP will not know where to check for trust data. Therefore, the first thing we need to do is -register DTR within the Universal Control Plane of Cluster 2. When you normally -install Docker Trusted Registry, this registration process happens by default to -a local UCP. +register DTR within the remote UCP in cluster 2. When you normally +install DTR, this registration process happens by default to +a local UCP, or cluster 1. > The registration process allows the remote UCP to get signature data from DTR, -> however this will not provide Single Sign On, Users on Cluster 2 will not be -> synced with Cluster 1's Universal Control Plane or Docker Trusted Registry. -> Therefore when pulling images, if the repository is private, registry +> however this will not provide Single Sign On (SSO). Users on cluster 2 will not be +> synced with cluster 1's UCP or DTR. Therefore when pulling images, registry > authentication will still need to be passed as part of the service definition -> (For example in +> if the repository is private. See > [Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-in-the-cluster-that-holds-your-authorization-token) > or [Docker -> Swarm](https://docs.docker.com/engine/swarm/services/#create-a-service-using-an-image-on-a-private-registry). +> Swarm](https://docs.docker.com/engine/swarm/services/#create-a-service-using-an-image-on-a-private-registry) examples. -To add a new registry, the first thing we need to retrieve is the Certificate -Authority used to sign the DTR TLS Certificate. This can be done through DTR's +To add a new registry, retrieve the Certificate +Authority (CA) used to sign the DTR TLS Certificate through the DTR URL's `/ca` endpoint. ```bash $ curl -ks https://dtr.example.com/ca > dtr.crt ``` -Next we need to convert this DTR certificate into a JSON configuration file, -this can then be used to register DTR within the 2nd Clusters Universal Control -Plane. +Next, convert the DTR certificate into a JSON configuration file +for registration within the UCP for cluster 2. -A template of the json file called `dtr-bundle.json` is found below. Please -replace the host address with the relevant URL, and enter the contents of the -DTR CA certificate between the new line commands `\n and \n`. +You can find a template of the `dtr-bundle.json` below. Replace the host address with your DTR URL, and enter the contents of the DTR CA certificate between the new line commands `\n and \n`. -> Note within the json file, ensure there are no line breaks between each line -> of the DTR CA certificate. +> ### JSON Formatting +> Ensure there are no line breaks between each line +> of the DTR CA certificate within the JSON file. Use your favorite JSON formatter for validation. ```bash $ cat dtr-bundle.json @@ -93,9 +87,9 @@ $ cat dtr-bundle.json } ``` -Now we will upload this configuration file to Cluster 2's Universal Control -Plane using the UCP API endpoint `/api/config/trustedregistry_`. To authenticate -against the API of Cluster 2's UCP, we have downloaded a [UCP client +Now upload the configuration file to cluster 2's UCP +via the UCP API endpoint, `/api/config/trustedregistry_`. To authenticate +against the API of cluster 2's UCP, we have downloaded a [UCP client bundle](/ee/ucp/user-access/cli/#download-client-certificates/), extracted it in the current directory, and will reference the keys for authentication. @@ -108,35 +102,33 @@ $ curl --cacert ca.pem --cert cert.pem --key key.pem \ https://cluster2.example.com/api/config/trustedregistry_ ``` -To check this has been imported successfully, as the UCP endpoint will not -output anything, we can check within Cluster 2's UCP UI. Select **Admin** in the -top left hand corner, select **Admin Settings** and the finally select **Docker -Trusted Registry**. If the registry has been added successfully we should see +Navigate to the UCP web interface to verify that the JSON file was imported successfully, as the UCP endpoint will not +output anything. Select **Admin > Admin Settings > Docker +Trusted Registry**. If the registry has been added successfully, you should see the DTR listed. ![](../../../images/remoteucp-addregistry.png){: .with-border} -You could also check the full [configuration -file](/ee/ucp/admin/configure/ucp-configuration-file/) within Cluster 2's UCP. -Once downloaded the `ucp-config.toml` file should now contain a section called +Additionally, you can check the full [configuration +file](/ee/ucp/admin/configure/ucp-configuration-file/) within cluster 2's UCP. +Once downloaded, the `ucp-config.toml` file should now contain a section called `[registries]` ```bash $ curl --cacert ca.pem --cert cert.pem --key key.pem https://cluster2.example.com/api/ucp/config-toml > ucp-config.toml ``` -If the new registry isn't shown in the list, please check the logs of the -`ucp-controller` container running on Cluster 2. +If the new registry isn't shown in the list, check the `ucp-controller` container logs on cluster 2. ## Signing an image in DTR -We will now sign an image and push this to DTR, to sign images we need a User's -key pair from Cluster 2. Key pairs can be found in a client bundle, with the -`key.pem` being a private key, and `cert.pem` being the public key within a x509 +We will now sign an image and push this to DTR. To sign images we need a user's public private +key pair from cluster 2. It can be found in a client bundle, with +`key.pem` being a private key and `cert.pem` being the public key on an **X.509** certificate. -First we load the Private key into the local Docker trust store +First, load the private key into the local Docker trust store `(~/.docker/trust)`. The name used here is purely metadata to help keep track of which keys you have imported. @@ -148,11 +140,10 @@ Repeat passphrase for new cluster2admin key with ID a453196: Successfully imported key from key.pem ``` -Next we will initiate the repository, and add the public key of Cluster 2's User +Next initiate the repository, and add the public key of cluster 2's user as a signer. You will be asked for a number of passphrases to protect the keys. -Please keep note of these passphrases, and to learn more about managing Keys -head to the Docker Content Trust documentation -[here](/engine/security/trust/trust_delegation/#managing-delegations-in-a-notary-server). +Keep note of these passphrases, and see [Docker Content Trust documentation] +(/engine/security/trust/trust_delegation/#managing-delegations-in-a-notary-server) to learn more about managing keys. ``` @@ -166,8 +157,8 @@ Successfully initialized "dtr.example.com/admin/trustdemo" Successfully added signer: cluster2admin to dtr.example.com/admin/trustdemo ``` -Finally we will sign an image tag. This pushes the image up to DTR, as well as -signing the tag with the User from Cluster 2's keys. +Finally, sign the image tag. This pushes the image up to DTR, as well as +signs the tag with the user from cluster 2's keys. ``` $ docker trust sign dtr.example.com/admin/trustdemo:1 @@ -183,34 +174,31 @@ Enter passphrase for cluster2admin key with ID a453196: Successfully signed dtr.example.com/admin/trustdemo:1 ``` -Within the DTR UI, you should now be able to see a new tag has been pushed, as well as the **Signed** text next to the size. +Within the DTR web interface, you should now be able to see your newly pushed tag with the **Signed** text next to the size. ![](../../../images/remoteucp-signedimage.png){: .with-border} -We could sign this image multiple times if required, whether there were multiple -teams from the same Cluster that wanted to sign the image, or you wanted to -integrate DTR with more remote UCP's, and therefore a User from Cluster 1, -Cluster 2, Cluster 3...etc can all to sign the same image. +You could sign this image multiple times if required, whether it's multiple +teams from the same cluster wanting to sign the image, or you integrating DTR with more remote UCPs so users from clusters 1, +2, 3, or more can all sign the same image. ## Enforce Signed Image Tags on the Remote UCP -We can now enable **Only Run Signed Images** on the Remote UCP. To do this, -login to Cluster 2's UCP UI as an Admin user, select **Admin** in the top left -hand corner, select **Admin Settings** and then go down to **Docker Content +We can now enable **Only Run Signed Images** on the remote UCP. To do this, +login to cluster 2's UCP web interface as an admin. Select **Admin > Admin Settings > Docker Content Trust**. -For more information on **Only Run Signed Images** in UCP, refer to the [UCP -Documentation](/ee/ucp/admin/configure/run-only-the-images-you-trust/). +See [Run only the images you trust](/ee/ucp/admin/configure/run-only-the-images-you-trust/) for more information on only running signed images in UCP. ![](../../../images/remoteucp-enablesigning.png){: .with-border} -Finally we are in a position to deploy a workload on Cluster 2, using a signed -image from a DTR running Cluster 1. This workload could be a simple `$ docker -run`, a Swarm Service or a Kubernetes workload. As a simple test, source a -client bundle, and try and run one of your signed images. +Finally we can now deploy a workload on cluster 2, using a signed +image from a DTR running on cluster 1. This workload could be a simple `$ docker +run`, a Swarm Service, or a Kubernetes workload. As a simple test, source a +client bundle, and try running one of your signed images. ``` $ source env.sh @@ -228,15 +216,13 @@ nqsph0n6lv9u laughing_lamarr replicated 1/1 ## Troubleshooting -1) If the image is stored in a Private Repository within DTR, as there is no - Single Sign On between Cluster 2 and DTR, you need to pass credentials to the - Orchestrator. Please see the relevant - [Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-in-the-cluster-that-holds-your-authorization-token) - or [Docker +If the image is stored in a private repository within DTR, you need to pass credentials to the +Orchestrator as there is no SSO between cluster 2 and DTR. See the relevant +[Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#create-a-secret-in-the-cluster-that-holds-your-authorization-token) or [Docker Swarm](https://docs.docker.com/engine/swarm/services/#create-a-service-using-an-image-on-a-private-registry) - documentation. + documentation for more details. -2) If you see: +### Example Errors ``` image or trust data does not exist for dtr.example.com/admin/trustdemo:1 @@ -245,19 +231,17 @@ image or trust data does not exist for dtr.example.com/admin/trustdemo:1 This means something went wrong when initiating the repository or signing the image, as the tag contains no signing data. -3) If you see: - ``` Error response from daemon: image did not meet required signing policy dtr.example.com/admin/trustdemo:1: image did not meet required signing policy ``` -This means that the image was signed correctly, however the User that signed the -image does not mean the signing policy in Cluster 2. This could be because you -signed the Image with the wrong Users Keys. +This means that the image was signed correctly, however the user who signed the +image does not mean the signing policy in cluster 2. This could be because you +signed the image with the wrong user keys. ## Where to go next - [Learn more about Notary](/notary/advanced_usage.md) -- [Notary architecture](/notary/service_architecture.md) \ No newline at end of file +- [Notary architecture](/notary/service_architecture.md)