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

Initial edits

This commit is contained in:
Maria Bermudez 2019-02-19 12:17:28 -08:00 committed by GitHub
parent f3563e9ee6
commit 30778f3e9f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 70 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
ee/dtr/user/manage-images/sign-images/trust-with-remote-ucp.md
View File

@ -6,84 +6,78 @@ keywords: registry, sign, trust, notary
For more advanced deployments, you may want to share one Docker Trusted Registry For more advanced deployments, you may want to share one Docker Trusted Registry
across multiple Universal Control Planes. However, customers wanting to adopt across multiple Universal Control Planes. However, customers wanting to adopt
this model, alongside the [Only Run Signed this model alongside the [Only Run Signed
Images](../.../../ucp/admin/configure/run-only-the-images-you-trust.md) feature 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.
of UCP, run into problems as each Universal Control Plane operates an
independent set of users.
Docker Content Trust with a Remote UCP gets around this problem, as User's from 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 a remote UCP are able to sign images in the central DTR and still apply runtime
enforcement. enforcement.
In the following example we will connect DTR to 1 remote UCP cluster, sign the 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 that remote UCP cluster, and provide runtime enforcement image with a user from UCP cluster 2, and provide runtime enforcement
within the remote UCP cluster. This process could be repeated over and over, within UCP cluster 2. This process could be repeated over and over,
integrating DTR with multiple remote UCP clusters, signing the image with Users integrating DTR with multiple remote UCP clusters, signing the image with users
from each environment, and then providing runtime enforcement in each remote UCP from each environment, and then providing runtime enforcement in each remote UCP
cluster seperately. cluster separately.
![](../../../images/remoteucp-graphic.png) ![](../../../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) > Trust](engine/security/trust/content_trust/#signing-images-with-docker-content-trust)
> and [Only Run Signed > and [Only Run Signed
> Images](../.../../ucp/admin/configure/run-only-the-images-you-trust.md) on a > 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. > background.
## Prerequisites ## Prerequisites
- Cluster 1, running UCP 3.0.x or higher, with a DTR 2.5.x or higher deployed - Cluster 1, running UCP 3.0.x or higher, with a DTR 2.5.x or higher deployed
within the cluster. within the cluster.
- Cluster 2, running UCP 3.0.x or higher, it is expected that - Cluster 2, running UCP 3.0.x or higher, with no DTR node.
there is no DTR installed on this environment. - Nodes on Cluster 2 need to trust the Certificate Authority which signed DTR's
- 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
TLS Certificate. This can be tested by logging on to a Cluster 2 virtual
machine and running `curl https://dtr.example.com`. machine and running `curl https://dtr.example.com`.
- The DTR TLS Certificate needs be properly configured, ensuring that the - The DTR TLS Certificate needs be properly configured, ensuring that the
**Loadbalancer/Public Address** field has been configured, with this address **Loadbalancer/Public Address** field has been configured, with this address
included [within the included [within the
certificate](../../../admin/configure/use-your-own-tls-certificates/). 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` EE 1803 or newer) installed, as this contains the relevant `$ docker trust`
commands. commands.
## Registering DTR with a remote Universal Control Plane ## 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 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 register DTR within the remote UCP in cluster 2. When you normally
install Docker Trusted Registry, this registration process happens by default to install DTR, this registration process happens by default to
a local UCP. a local UCP, or cluster 1.
> The registration process allows the remote UCP to get signature data from DTR, > 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 > however this will not provide Single Sign On (SSO). Users on cluster 2 will not be
> synced with Cluster 1's Universal Control Plane or Docker Trusted Registry. > synced with cluster 1's UCP or DTR. Therefore when pulling images, registry
> Therefore when pulling images, if the repository is private, registry
> authentication will still need to be passed as part of the service definition > 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) > [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 > 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 To add a new registry, retrieve the Certificate
Authority used to sign the DTR TLS Certificate. This can be done through DTR's Authority (CA) used to sign the DTR TLS Certificate through the DTR URL's
`/ca` endpoint. `/ca` endpoint.
```bash ```bash
$ curl -ks https://dtr.example.com/ca > dtr.crt $ curl -ks https://dtr.example.com/ca > dtr.crt
``` ```
Next we need to convert this DTR certificate into a JSON configuration file, Next, convert the DTR certificate into a JSON configuration file
this can then be used to register DTR within the 2nd Clusters Universal Control for registration within the UCP for cluster 2.
Plane.
A template of the json file called `dtr-bundle.json` is found below. Please 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`.
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`.
> Note within the json file, ensure there are no line breaks between each line > ### JSON Formatting
> of the DTR CA certificate. > 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 ```bash
$ cat dtr-bundle.json $ 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 Now upload the configuration file to cluster 2's UCP
Plane using the UCP API endpoint `/api/config/trustedregistry_`. To authenticate via the UCP API endpoint, `/api/config/trustedregistry_`. To authenticate
against the API of Cluster 2's UCP, we have downloaded a [UCP client 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 bundle](/ee/ucp/user-access/cli/#download-client-certificates/), extracted it in
the current directory, and will reference the keys for authentication. 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_ https://cluster2.example.com/api/config/trustedregistry_
``` ```
To check this has been imported successfully, as the UCP endpoint will not Navigate to the UCP web interface to verify that the JSON file was imported successfully, as the UCP endpoint will not
output anything, we can check within Cluster 2's UCP UI. Select **Admin** in the output anything. Select **Admin > Admin Settings > Docker
top left hand corner, select **Admin Settings** and the finally select **Docker Trusted Registry**. If the registry has been added successfully, you should see
Trusted Registry**. If the registry has been added successfully we should see
the DTR listed. the DTR listed.
![](../../../images/remoteucp-addregistry.png){: .with-border} ![](../../../images/remoteucp-addregistry.png){: .with-border}
You could also check the full [configuration Additionally, you can check the full [configuration
file](/ee/ucp/admin/configure/ucp-configuration-file/) within Cluster 2's UCP. 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 Once downloaded, the `ucp-config.toml` file should now contain a section called
`[registries]` `[registries]`
```bash ```bash
$ curl --cacert ca.pem --cert cert.pem --key key.pem https://cluster2.example.com/api/ucp/config-toml > ucp-config.toml $ 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 If the new registry isn't shown in the list, check the `ucp-controller` container logs on cluster 2.
`ucp-controller` container running on Cluster 2.
## Signing an image in DTR ## Signing an image in DTR
We will now sign an image and push this to DTR, to sign images we need a User's 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. Key pairs can be found in a client bundle, with the 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 within a x509 `key.pem` being a private key and `cert.pem` being the public key on an **X.509**
certificate. 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 `(~/.docker/trust)`. The name used here is purely metadata to help keep track of
which keys you have imported. which keys you have imported.
@ -148,11 +140,10 @@ Repeat passphrase for new cluster2admin key with ID a453196:
Successfully imported key from key.pem 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. 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 Keep note of these passphrases, and see [Docker Content Trust documentation]
head to the Docker Content Trust documentation (/engine/security/trust/trust_delegation/#managing-delegations-in-a-notary-server) to learn more about managing keys.
[here](/engine/security/trust/trust_delegation/#managing-delegations-in-a-notary-server).
``` ```
@ -166,8 +157,8 @@ Successfully initialized "dtr.example.com/admin/trustdemo"
Successfully added signer: cluster2admin to 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 Finally, sign the image tag. This pushes the image up to DTR, as well as
signing the tag with the User from Cluster 2's keys. signs the tag with the user from cluster 2's keys.
``` ```
$ docker trust sign dtr.example.com/admin/trustdemo:1 $ 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 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} ![](../../../images/remoteucp-signedimage.png){: .with-border}
We could sign this image multiple times if required, whether there were multiple You could sign this image multiple times if required, whether it's multiple
teams from the same Cluster that wanted to sign the image, or you wanted to teams from the same cluster wanting to sign the image, or you integrating DTR with more remote UCPs so users from clusters 1,
integrate DTR with more remote UCP's, and therefore a User from Cluster 1, 2, 3, or more can all sign the same image.
Cluster 2, Cluster 3...etc can all to sign the same image.
## Enforce Signed Image Tags on the Remote UCP ## Enforce Signed Image Tags on the Remote UCP
We can now enable **Only Run Signed Images** on the Remote UCP. To do this, 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 login to cluster 2's UCP web interface as an admin. Select **Admin > Admin Settings > Docker Content
hand corner, select **Admin Settings** and then go down to **Docker Content
Trust**. Trust**.
For more information on **Only Run Signed Images** in UCP, refer to the [UCP 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.
Documentation](/ee/ucp/admin/configure/run-only-the-images-you-trust/).
![](../../../images/remoteucp-enablesigning.png){: .with-border} ![](../../../images/remoteucp-enablesigning.png){: .with-border}
Finally we are in a position to deploy a workload on Cluster 2, using a signed Finally we can now deploy a workload on cluster 2, using a signed
image from a DTR running Cluster 1. This workload could be a simple `$ docker 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 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. client bundle, and try running one of your signed images.
``` ```
$ source env.sh $ source env.sh
@ -228,15 +216,13 @@ nqsph0n6lv9u laughing_lamarr replicated 1/1
## Troubleshooting ## Troubleshooting
1) If the image is stored in a Private Repository within DTR, as there is no If the image is stored in a private repository within DTR, you need to pass credentials to the
Single Sign On between Cluster 2 and DTR, you need to pass credentials to the Orchestrator as there is no SSO between cluster 2 and DTR. See the relevant
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
[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)
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 image or trust data does not exist for dtr.example.com/admin/trustdemo:1
@ -245,17 +231,15 @@ 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 This means something went wrong when initiating the repository or signing the
image, as the tag contains no signing data. image, as the tag contains no signing data.
3) If you see:
``` ```
Error response from daemon: image did not meet required signing policy Error response from daemon: image did not meet required signing policy
dtr.example.com/admin/trustdemo:1: 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 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 image does not mean the signing policy in cluster 2. This could be because you
signed the Image with the wrong Users Keys. signed the image with the wrong user keys.
## Where to go next ## Where to go next