mirror of https://github.com/docker/docs.git
Initial edits
This commit is contained in:
Maria Bermudez
GitHub
parent
f3563e9ee6
commit
30778f3e9f
|
|
@ -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.
|
||||
|
||||
|
||||
|
||||
> 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.
|
||||
|
||||
{: .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.
|
||||
|
||||
{: .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.
|
||||
|
||||
|
||||
{: .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)
|
||||
- [Notary architecture](/notary/service_architecture.md)
|
||||
|
|
|
|||
Loading…
Reference in New Issue