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

Expand the docs for configuring UCP and DTR for content trust

This commit is contained in:
Misty Stanley-Jones 2017-02-20 17:08:45 -08:00 committed by Joao Fernandes
parent 4b9493d276
commit 51d033e640
10 changed files with 714 additions and 183 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
_data/toc.yaml
View File

@ -1202,12 +1202,18 @@ manuals:
title: Restrict services to worker nodes
- path: /datacenter/ucp/2.1/guides/admin/configure/use-domain-names-to-access-services/
title: Use domain names to access services
- path: /datacenter/ucp/2.1/guides/admin/configure/only-allow-running-signed-images/
title: Only allow running signed images
- path: /datacenter/ucp/2.1/guides/admin/configure/use-trusted-images-for-ci/
title: Use trusted images for continuous integration
- path: /datacenter/ucp/2.1/guides/admin/configure/external-auth/
title: Integrate with LDAP
- sectiontitle: Content trust
section:
- path: /datacenter/ucp/2.1/guides/admin/configure/content-trust/
title: Only allow running signed images
- path: /datacenter/ucp/2.1/guides/admin/configure/content-trust/admin_tasks/
title: Configure the UCP and DTR servers for content trust
- path: /datacenter/ucp/2.1/guides/admin/configure/content-trust/client_configuration/
title: Configure the Docker client to sign images
- path: /datacenter/ucp/2.1/guides/admin/configure/use-trusted-images-for-ci/
title: Use trusted images for continuous integration
- sectiontitle: Manage users
section:
- path: /datacenter/ucp/2.1/guides/admin/manage-users/

BIN
datacenter/images/dtr_repo_find_gun.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

BIN
datacenter/images/signed_image_in_dtr.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

BIN
datacenter/images/ucp_content_trust_detail.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
datacenter/images/ucp_content_trust_settings.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 56 KiB

387
datacenter/ucp/2.1/guides/admin/configure/content-trust/admin_tasks.md Normal file
View File

@ -0,0 +1,387 @@
---
title: Configure the UCP and DTR servers for content trust
description: Configuration tasks for using content trust on UCP and DTR servers
---
These tasks allow an administrator to set up the UCP and DTR servers to require
content trust and to delegate the ability to sign images to UCP users. For an
overview of content trust in UCP, see [Run only the images you trust](index.md).
After completing these steps, continue to
[Client configuration for content trust in UCP](client_configuration.md).
## Prerequisites
Before completing these tasks, set up the teams for signing and add users to
them. For instance, if your business requirement is that images need to be
signed by `engineering`, `security`, and `quality` teams, set up those teams and
add the appropriate users to them. See
[Set up teams](/datacenter/ucp/2.1/guides/admin/manage-users/create-and-manage-teams.md)
and
[Create and manage users](/ucp/2.1/guides/admin/manage-users/create-and-manage-users.md).
## Overview
The administrator needs to complete the following tasks to configure UCP and DTR
for image signing.
2. [Configure UCP](#configure-ucp) to only allow signed images to be used.
3. [Set up the Docker Notary CLI client](#set-up-the-docker-notary-client)
locally so that the administrator can initialize the trusted image
repository.
4. [Initialize the trusted image repository](#initialize-the-trusted-image-repository)
which will store trusted images.
5. [Delegate image signing](#delegate-image-signing) so that the appropriate
users are able to sign images. This step is optional, and assumes that the
UCP administrator will not be the only one signing images.
## Configure UCP
This step configures UCP to only allow deployment of signed images, as well as
the teams that must sign an image before it can be trusted. Set up the users
and groups before starting this step.
1. Go to the **UCP web UI**, navigate to the **Admin Settings** page, and click
the **Content Trust** menu item.
![Content Trust settings](/datacenter/images/ucp_content_trust_settings.png)
2. Select the **Only run signed images** option.
Click the **REQUIRE SIGNATURE FROM ALL OF THESE TEAMS** field and choose
one or more teams. DDC will consider an image to be trustworthy only if it
is signed by a member of _every team_ you select. The requirement can be
fulfilled by a single user who is a member of all the teams, or by a signer
in each team.
> **Note**: If you don't specify any team (by leaving the field blank), an
> image will be trusted as long as it is signed by any UCP user whose keys
> are [configured in the Notary client](#set-up-the-docker-notary-client).
The following screenshot shows a configuration that requires images to be
signed by a member of the `engineering` team.
![Content Trust settings detail](/datacenter/images/ucp_content_trust_detail.png)
3. Click **Update** to apply the changes.
UCP is now configured to only allow use of signed images, but you don't have the
ability to sign images yet. Next,
[set up the Docker Notary CLI client](#set-up-the-docker-notary-client).
## Set up the Docker Notary CLI client
After [configuring UCP](#configure-ucp), you need to specify which Docker images
can be trusted, using the Docker Notary server that is built into Docker Trusted
Registry (DTR). The following procedure configures the Notary server to store
signed metadata about the Docker images you trust. This set-up step only needs
to be done on the client of an administrator responsible for setting up
repositories and delegating the ability to sign images.
1. **If you are on a Linux client**, install the Notary binary. If you use Docker
for Mac or Docker for Windows, the Notary client is included in your
installation.
- [Download the latest client archive](https://github.com/docker/notary/releases).
- Extract the archive.
- Rename the binary to `notary` and set it to executable. Either move it to
a location in your path or modify the examples below to include the full
path to the binary.
2. Configure the Notary client to communicate with the DTR server and store
its metadata in the correct location. You can either use a
[Notary configuration file](/notary/reference/client-config.md) or manually
specify the following flags when you run the `notary` command.
|Flag |Purpose |
|-------------------|------------------------------------------------------|
| `-s <dtr_url>` | The hostname or IP address of the DTR server |
| `-d <trust_directory>` | The path to the local directory where trust metadata will be stored |
| `--tlscacert <dtr_ca.pem>` | The path to the trust certificate for DTR. Only required if your DTR registry is not using certificates signed by a globally trusted certificate authority, such as self-signed certificates. Download the trust certificate from `https://<dtr_url>/ca` either from your browser or using `curl` or `wget`.|
> **Tip**: If you don't want to provide the `-s`, `-d`, and `--tlscacert`
> parameters each time you run a Nptary command, you can set up an alias in
> Bash (Linux or macOS) or PowerShell (Windows) to save some typing. The
> following examples do not include the `--tlscacert` flag, but you can add
> it if necessary. All of the `notary` commands in the rest of this topic
> assume that you have set up the alias.
>
> - **Bash**: Type the following, or add it to your `~/.profile` file to make
> it permanent. Replace `<dtr_url>` with the hostname or IP address of your
> DTR instance.
>
> alias notary="notary -s https://<dtr_url> -d ~/.docker/trust"
>
> - **PowerShell**: Type the following, or add it to your `profile.ps1` to
> make it permanent.
>
> PS C:\> set-alias notary "notary -s https://<dtr_url> -d ~/.docker/trust"
>
>
> After setting up the alias, you only need to type `notary` and the server
> and destination directory will be included in the command automatically.
{: id="notary_alias_config_note" }
3. Find the _globally unique name (GUN)_ for your repository. The GUN
is the `<registry/<account>/<repository>` string, such as
`dtr-example.com/engineering/my-repo`. You can find the GUN for a repository
by browsing to it in the DTR web UI and copying the part of the
**Pull command** after `docker pull`.
Next, [initialize a trusted image repository](#set-up-a-trusted-image-repository).
## Initialize the trusted image repository
> **Tip - Yubikey integration**: Notary supports integration with Yubikey. If
> you have a Yubikey plugged in when you initialize a repository with Notary,
> the root key is stored on the Yubikey instead of in the trust directory. When
> you run any command that needs the `root` key, Notary looks on the Yubikey
> first, and uses the trust directory as a fallback.
This procedure needs to be done on the client of an administrator responsible for
setting up repositories. It needs to be done once per signing repository.
In these examples, add the `-s`, `-d`, and `--tlscacert` parameters you need
before `<GUN>` if you decided not to configure Notary using a
[configuration file](/notary/reference/client-config.md){: target="_blank" class="_" }
or a [terminal alias](#notary_alias_config_note").
1. In the DTR web UI, create a new repository or browse to an existing
repository that you want to reconfigure as a trusted image repository.
Make a note of the GUN for the repository by copying the contents of the
**Pull command** field after `docker pull`.
![Finding the GUN in the DTR UI](/datacenter/images/dtr_repo_find_gun.png)
2. At the command line on your client, check whether Notary has information
about the repository. Most likely if you are performing this task for the
first time, the repository is not initialized.
```bash
$ notary list <GUN>
```
The response may be one of the following:
- `fatal: client is offline`: Either the repository server can't be reached,
or DTR is using certificates which are not signed by a globally trusted
certificate authority, such as self-signed certificates. Run `notary list`
again, adding the `--tlscacert` flag, with the path to the certificate
authority for DTR. To get the certificate, download `https://<dtr_url>/ca`
from your browser or using `curl` or `wget`. This certificate is
different from the UCP trust certificate in the UCP client bundle.
- `fatal: <dtr_url> does not have trust data for ddc-staging-dtr.qa.aws.dckr.io/engineering/redis`:
The repository has not yet been initialized and you need to run
`notary init`. Continue to step 2.
- `No targets present in this repository.`: The repository has been
initialized, but contains no signed images. You do not need to do step 2.
- A list of signed image tags, their digests, and the role of the private
key used to sign the metadata. This indicates that the repository is configured
correctly and images have been signed and uploaded. You do not need to do
step 2.
2. To initialize the repository, run `notary init`, setting the `-p` flag to
the GUN of the repository. You will be prompted to set passphrases for
three different keys:
- The `root` key is used to sign the `targets` and `snapshot` keys.
- The `targets` key will be used to sign the keys of users authorized to sign
images and designate them as trusted.
- The `snapshot` key is used for snapshotting the repository, which is an
optimization for updating the trust data.
```bash
$ notary init <GUN>
No root keys found. Generating a new root key...
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 717fa4b:
Repeat passphrase for new root key with ID 717fa4b:
Enter passphrase for new targets key with ID 776d924 (<GUN>):
Repeat passphrase for new targets key with ID 776d924 (<GUN>):
Enter passphrase for new snapshot key with ID d3cc399 (<GUN>):
Repeat passphrase for new snapshot key with ID d3cc399 (<GUN>):
Enter username: admin
Enter password:
```
As the help text in the command says, it's important to choose good
passphrases and to save them in a secure location such as a password
manager. The final username and password prompt are for the DTR login.
Several important files are saved in the trust directory (the location you
specified as the value of the `-d` flag. The following is an example listing
of the trust directory:
```none
├── private
│   ├── root_keys
│   │   └── 92c11d487023de4447ef57747e84e7364cd7c62a4be28d8714ec05afe2f130f8.key
│   └── tuf_keys
│   └── dtr-example.com
│   └── engineering
│   └── testrepo
│   ├── 87a129ea47a4112fec6b989bde35f6ddea8325638450d41b3f44fabaf49dbe3d.key
│   └── aa4b236c610e3d951c930bf2a503861c41808ac28369bfbaf5c075b62cb3dd41.key
└── tuf
└── dtr-example.com
└── engineering
└── testrepo
├── changelist
└── metadata
├── root.json
├── snapshot.json
└── targets.json
```
The `tuf` directory contains metadata needed by Notary. The `private`
directory contains the root key, target key, and snapshots key. It is
important to protect these keys, especially the root key. If you are using
the Yubikey integration feature, the root key is already stored on your
Yubikey. You should back up the entire `private` subdirectory to secure
offline storage and remove the `root_keys` subdirectory from the trust
directory. If you do not use a Yubikey, back up the entire trust
directory to secure offline storage, and bring it online only when you need
to perform Notary operations.
3. The metadata has been created but only exists on your client. To publish
it to DTR, use `notary publish`.
```bash
$ notary publish <GUN>
Pushing changes to <GUN>
Enter username: admin
Enter password:
Enter passphrase for targets key with ID 63c2d66:
Enter passphrase for snapshot key with ID 6ac388d:
Successfully published changes for repository <GUN>
```
You will be prompted for the DTR login, the passphrase for the `targets` key,
and the passphrase for the `snapshot` key.
Typically, the administrator is not part of the group which is authorized to
sign images. If you do attempt to sign images and you are not part of one of the
correct groups, the image will not be available to UCP.
Continue to [delegate image signing](#delegate-image-signing) to give the
appropriate users the ability to sign images.
You can also
[learn more about the keys used by Notary](/engine/security/trust/trust_key_mng.md).
## Delegate image signing
The administrator who manages Docker Trusted Registry is often not part of the
group which is allowed to sign images. This is where
[Notary delegation roles](/notary/advanced_usage.md) come in. Delegation roles
provide:
- Simple collaboration workflows
- Fine-grained permissions within a collection's contents across delegations
- Ability to dynamically add or remove keys from delegation roles when
collaborators join or leave trusted repositories
When you [initialized the trusted repository](#nitialize-the-trusted-image-repository),
three keys were created:
- The `root` key signs the `targets` and `snapshot` keys.
- The `targets` key is used by Notary for delegation roles, which act as signers.
- Each change in the repository needs to be signed by the `snapshot` key.
To avoid the need to distribute the `snapshot` key to each person who will sign
images, you can configure the Notary server to manage it. In order to do this,
you need to also rotate the `snapshots` key, so that private keys do not need
to be transferred between the client and server.
1. Rotate the key and configure the Notary server to manage it. This operation
only needs to be done once for each trusted repository.
```bash
$ notary key rotate <GUN> snapshot --server-managed
```
You are prompted for the DTR credentials followed by the passphrase for the
`root` key.
2. For each user who should be able to sign images, ask that user to create a
client bundle. They should:
1. Go to the UCP web UI.
2. Click your username at the top right. Click **Profile**.
3. Click **Create a Client Bundle**. A file is downloaded called
`ucp-bundle-<username>.zip`.
4. Extract the zip file. The important file within the archive is the
`cert.pem`, which is the user certificate.
5. Send you the `cert.pem` **through a secure, trusted channel**. If you
plan to create more than one delegation, rename the `cert.pem` with the
username or other identifying information.
3. Run the following command to add the `targets/releases` delegation role for
each user, using the `cert.pem` files. You can specify multiple `cert.pem`
files at once.
```bash
$ notary delegation add -p <GUN> targets/releases --all-paths user1.pem user2.pem
```
You will be prompted for your DTR credentials and the passphrase for the
`targets` key.
> **Note**: You can also add arbitrary delegations, but `targets/releases`
> is a special delegation, and is treated as an actual release branch for
> Docker Content Trust. If a Docker client has content trust enabled, and
> the client runs `docker pull`, this delegation is what signals that the
> content is trusted.
Each user who can release images should be added to the `targets/releases`
role.
4. Create at least one more delegation and add users to it, or UCP will not
honor the signed content. This delegation indicates the team that is signing
the release.
Docker recommends adding one delegation per team. For instance, if you have
an `engineering` team and a `qa` team, add a delegation for each of these.
If a user is a member of both teams, that user will be able to indicate
which team they are signing on behalf of. Notary has no limit on how many
delegation roles can exist.
Valid delegation roles take the form of `targets/<delegation>`. Do not include
a trailing slash.
The following command adds `user1` to the `targets/engineering` delegation:
```bash
$ notary delegation add -p <GUN> targets/engineering --all-paths user1.pem
```
You will be prompted for your DTR credentials followed by the passphrase
for the `targets` key.
5. Securely remove the `.pem` files of the users you added delegations to. If
these keys are compromised, they could be used to sign images which should
not be trusted.
## Next steps
The Notary server is now configured to allow users to sign images. Next, each
user needs to [configure their client](client_configuration.md)
and [sign some images](client_configuration.md#sign-and-push-images).
[Learn more about the targets/releases role](/engine/security/trust/trust_delegation.md).

255
datacenter/ucp/2.1/guides/admin/configure/content-trust/client_configuration.md Normal file
View File

@ -0,0 +1,255 @@
---
title: Configure the Docker client to sign images
description:
---
After an administrator
[configures the UCP and DTR servers for content trust](admin_tasks.md) and
[delegates users to be able to sign images](admin_tasks.md#delegate-image-signing),
each of those users needs to configure their system for image signing. This
topic covers the required configuration steps, as well as how to sign and
push images.
Each user who will sign images needs to follow these steps.
## Import the user's signing key
Users who need to sign images should import the `key.pem` file from their UCP
client bundle into Docker. The user probably downloaded the client bundle when
they sent the administrator their `cert.pem` so the administrator could
[delegate signing to them](#delegate-image-signing).
Import the private key associated with the user certificate. You must specify
the trust directory `~/.docker/private`. If the `~/.docker/private` directory
does not yet exist, Notary will create it.
- **Linux or macOS**:
```bash
$ notary -d ~/.docker/trust key import /path/to/key.pem
```
- **Windows**:
```powershell
PS C:\> notary -d ~/.docker/trust key import /path/to/key.pem
```
You are prompted for a passphrase. Save it in a secure location such as a
password manager. You will need to provide the passphrase each time you sign an
image.
## Configure the Docker client
These steps may need to be performed for each Docker user who will push images
to the trusted repository, and also on each Docker client which should only be
allowed to pull and use trusted images.
### Linux or MacOS
1. **Required**: Set the `DOCKER_CONTENT_TRUST` environment variable to `1`.
You can do this temporarily or permanently.
- To set the environment variable for the current command-line session, type
the following into the terminal where you will be running `docker` commands:
```bash
$ export DOCKER_CONTENT_TRUST=1
```
This environment variable will be effective until you close the command
prompt.
- To set the environmment variable for just a single command, add it before
the command:
```bash
$ DOCKER_CONTENT_TRUST=1 docker pull...
```
- To set the environment variable permanently, edit the `~/.profile` file
and add the following line:
```bash
export DOCKER_CONTENT_TRUST=1
```
2. **If your DTR instance uses certificates not signed by a public certificate authority (CA)**:
Configure the local Docker daemon and client to trust the DTR server's
certificate. You need to do this step if you see an error like the following
when you try to [sign and push an image](#sign-and-push-an-image).
```none
x509: certificate signed by unknown authority
```
This procedure is different if you are on a Linux or macOS client:
- **Linux**:
1. Download the certificate add it to a subdirectory of the
`/etc/docker/certs.d/` directory.
```bash
$ sudo mkdir -p /etc/docker/certs.d/<dtr-domain-name>
$ curl -k https://<host_or_ip_of_dtr_host>/ca -o <dtr-domain-name>.crt
$ sudo mv <dtr-domain-name>.crt /etc/docker/certs.d/<dtr-domain-name>/ca.crt
```
2. Configure the Docker client to use certificates available to the
Docker daemon by creating a symbolic link from `/etc/docker/certs.d/`
to `~/.docker/tls/`
```bash
$ ln -s /etc/docker/certs.d ~/.docker/tls
```
3. Restart Docker using one of the following commands:
- `sudo systemctl restart docker`
- `sudo service docker restart`
- **macOS**:
1. Download the certificate and name the output file
`<dtr-domain-name>.crt`.
```bash
$ curl -k https://<host_or_ip_of_dtr_host>/ca -o <dtr-domain-name>.crt
```
2. Import the certificate into the macOS keychain. This example uses the
command line, but you can use the **Keychain Access** application
instead.
```bash
$ sudo security add-trusted-cert -d \
-r trustRoot \
-k /Library/Keychains/System.keychain \
<dtr-domain-name>.crt
```
3. Restart Docker for Mac. Click the Docker icon in the toolbar and click
**restart**.
The Docker daemon and client now trust the DTR server. Continue to
[Sign and push an image](#sign-and-push-an-image).
### Windows
1. Set the `DOCKER_CONTENT_TRUST` environment variable to `1`. You can do this
temporarily or permanently.
- To set the environment variable for the current PowerShell session, type the
following into the PowerShell terminal where you will be running `docker` commands:
```powershell
PS C:\> $env:DOCKER_CONTENT_TRUST = "1"
```
This environment variable will be effective until you close the PowerShell
session.
- To set the environment variable permanently for the logged-in user, use the
following command:
```powershell
PS C:\> [Environment]::SetEnvironmentVariable("DOCKER_CONTENT_TRUST", "1", "User")
```
The variable is set immediately.
Whichever method you use, you can verify that the environment variable is set
by typing `$Env:DOCKER_CONTENT_TRUST` at the command line.
2. **If your DTR instance uses certificates not signed by a public certificate authority (CA)**:
Configure the local Docker daemon and client to trust the DTR server's
certificate. You need to do this step if you see an error like the following
when you try to [sign and push an image](#sign-and-push-an-image).
1. Download the certificate by browsing to the URL
`https://<dtr-domain-name>/ca`. The certificate is shown in the browser
as a text file. Choose **File** / **Save As** and save the file as
`<dtr-domain-name>.crt`.
2. Open Windows Explorer and go to the directory where you saved the file.
Right-click `<dtr-domain-name>.crt` and choose **Install certificate**.
- Select **Local machine** for the store location.
- Select **Place all certificates in the following store**.
- Click **Browse** and select **Trusted Root Certificate Authorities**.
- Click **Finish**.
3. Restart Docker for Windows. Click the Docker icon in the Notifications
area and click **Settings**. Click **Reset** and choose
**Restart Docker**.
The Docker daemon and client now trust the DTR server. Continue to
[Sign and push an image](#sign-and-push-an-image).
## Sign and push an image
After [Configuring the signer's Notary and Docker clients](#onfigure-the-signers-otary-and-ocker-clients),
the user can sign and push images to Docker Trusted Registry. These steps are
the same on Linux, macOS, or Windows.
1. Log into DTR.
```bash
$ docker login <dtr_url>
```
You are prompted for your DTR credentials.
2. Tag the image with a tag in the format `<GUN>:imagename`. The following
example tags the `ubuntu:16.04` image as `ubuntu` in your trusted
repository. This will signal to the `docker push` command that the image tag
contains a repository.
```bash
$ docker tag ubuntu:16.04 dtr-example.com/engineering/testrepo:ubuntu
```
3. Sign and push the tagged image, so that your deployments can use it. The
following example signs and pushes the image created in the previous step.
You are prompted for the delegation key passphrase.
```bash
$ docker push dtr-example.com/engineering/testrepo:ubuntu
The push refers to a repository [dtr-example.com/engineering/testrepo]
5eb5bd4c5014: Pushed
d195a7a18c70: Pushed
af605e724c5a: Pushed
59f161c3069d: Pushed
4f03495a4d7d: Pushed
ubuntu: digest: sha256:4c0b138bdaaefa6a1c290ba8d8a97a568f43c0f8f25c733af54d3999da12dfd4 size: 1357
Signing and pushing trust metadata
Enter passphrase for delegation key with ID ff97e18:
Successfully signed "dtr-example.com/engineering/testrepo":ubuntu
```
4. To test pulling the image, remove it locally, then pull it.
```bash
$ docker image remove dtr-example.com/engineering/testrepo:ubuntu
$ docker pull dtr-example.com/engineering/testrepo:ubuntu
```
5. You can verify that the image exists in the repository using the DTR web UI.
Go to the DTR web UI and click **Repositories**. Choose the repository and
go to **Images**.
![Trusted image in DTR repository](/datacenter/images/signed_image_in_dtr.png)
The signed, trusted image is available in your trusted repository.
## Where to go next
* [Restrict services to worker nodes](restrict-services-to-worker-nodes.md)

61
datacenter/ucp/2.1/guides/admin/configure/content-trust/index.md Normal file
View File

@ -0,0 +1,61 @@
---
description: Configure a Docker UCP cluster to only allow running applications that use images you trust.
keywords: docker, ucp, backup, restore, recovery
title: Run only the images you trust
redirect_from:
- /datacenter/ucp/2.1/guides/admin/configure/only-allow-running-signed-images/
---
## About trusted images
When transferring data among networked systems, _trust_ is a central concern. In
particular, when communicating over an untrusted medium such as the internet, it
is critical to ensure the integrity and the publisher of all the data a system
operates on. Docker allows you to push images to, and pull images from, public
and private registries.
Docker provides a mechanism called
[content trust](/engine/security/trust/content_trust.md), which you can use to
verify that the contents of the image have been approved by people you trust,
and to prevent untrusted images from being used in your UCP instance.
### Example workflow for using trusted images
An example workflow that takes advantage of content trust might look like this:
1. Developers push code into source control.
2. A CI system performs automated tests. If the tests pass, the CI system
builds and cryptographically signs an image containing the code.
3. A quality engineering team pulls the image signed by the CI system and
performs quality tests on it. When the image is approved for production,
part of the approval process is to cryptographically sign the image again.
4. If any image is not signed both by the CI group and the QA group, UCP
refuses to deploy it.
## Configuration overview
First, an administrator performs the following configuration tasks, which are
detailed in [Server-side tasks for content trust in UCP](admin_tasks.md).
1. Configure UCP.
2. Configure the Notary client on the administrator's system.
3. Initialize the trusted repository in DTR.
4. Delegate image signing to users in the correct groups.
Afterward, members of approved teams perform the following tasks, which are
detailed in [Configure the Docker client to sign images](client_configuration.md):
1. Set up the Docker CLI to use the signing certificates from the UCP client
bundle and to require images to be signed when pulling them from
repositories.
2. Sign and push an image to a repository.
## Next steps
- [Server-side tasks for content trust in UCP](admin_tasks.md)
- [Configure the Docker client to sign images](client_configuration.md)

178
datacenter/ucp/2.1/guides/admin/configure/only-allow-running-signed-images.md
View File

@ -1,178 +0,0 @@
---
description: Configure a Docker Universal Plane cluster to only allow running applications
that use images you trust.
keywords: docker, ucp, backup, restore, recovery
title: Run only the images you trust
---
With Docker Universal Control Plane you can enforce applications to only use
Docker images signed by UCP users you trust. When a user tries to deploy an
application to the cluster, UCP checks if the application uses a Docker image
that is not trusted, and won't continue with the deployment if that's the case.
By signing and verifying the Docker images, you ensure that the images being
used in your cluster are the ones you trust and haven't been altered either
in the image registry or on their way from the image registry to your UCP
cluster.
## Configure UCP
To configure UCP to only allow running applications that use Docker images you
trust, go to the **UCP web UI**, navigate to the **Settings** page, and click
the **Content Trust** tab.
<!-- todo: add screenshot -->
Select the **Run only signed images** option to only allow deploying
applications if they use images you trust.
Then, in the **Require signature from** field, you can specify all the teams
that need sign the image, before it is trusted to run in the UCP cluster. If
you specify multiple teams, the image needs to be signed by a member of each
team, or someone that is a member of all those teams.
If you don't specify any team, the image will be trusted as long as it is signed
by any UCP user whose keys are trusted in a Notary delegation role.
## Set up the Docker Notary CLI client
Once you've configured UCP to only run applications that use Docker images you
trust, you'll need to specify which Docker images can be trusted. This is done
by using the Docker Notary server that is built into Docker Trusted Registry.
You'll configure the Notary server to store signed metadata about the Docker
images you trust.
To interact with the Notary server, you need to
[install the Notary CLI client](https://github.com/docker/notary/releases).
Once you've installed the Notary client, you need to configure it to talk to
the Notary server that is built into Docker Trusted Registry. This can be done
using a [Notary configuration file](/notary/reference/client-config.md)
or by running:
```bash
# Create an alias to always have the notary client talking to the right server
$ alias notary="notary -s https://<dtr_url> -d ~/.docker/trust"
```
Where `-s` specifies the notary server to talk to, and `-d` specifies the
directory to store private keys and cache data.
If your Docker Trusted Registry is not using certificates signed by a globally
trusted certificate authority, you'll also need to configure notary to use the
certificate of the DTR CA:
```bash
$ alias notary="notary -s https://<dtr_url> -d ~/.docker/trust --tlscacert <dtr_ca.pem>"
```
## Set up a trusted image repository
Once your Docker Notary CLI client is configured, you can check if Notary has
information about a specific repository:
```bash
# <dtr_url>/<account>/<repository> is also known as a Globally Unique Name (GUN)
$ notary list <dtr_url>/<account>/<repository>
```
If notary has information about the repository it returns the list of
image tags it knows about, their expected digests, and the role of the private
key used to sign the metadata.
If Notary doesn't know yet about an image repository, run:
```bash
$ notary init -p <dtr_url>/<account>/<repository>
```
The Notary CLI client generates public and private key pairs, prompts you for
a passphrase to encrypt the private key, and stores the key pair in the
directory you've specified with the `notary -d` flag.
You should ensure you create backups for these keys, and that they are kept
securely and offline.
[Learn more about the keys used by Docker Notary.](/engine/security/trust/trust_key_mng.md)
## Sign and push an image
Now you can sign your images before pushing them to Docker Trusted Registry:
```bash
# Setting Docker content trust makes the Docker CLI client sign images before pushing them
$ export DOCKER_CONTENT_TRUST=1
# Push the image
$ docker push <dtr_url>/<account>/<repository>:<tag>
```
The Docker CLI client will prompt you for the passphrase you used to encrypt the
private keys, sign the image, and push it to the registry.
## Delegate image signing
Instead of signing the Docker images yourself, you can delegate that task
to other users.
Delegation roles simplify collaborator workflows in Notary trusted collections,
and also allow for fine-grained permissions within a collection's contents
across delegations.
Delegation roles act as signers in Notary that are managed by the targets key
and can be configured to use external signing keys. Keys can be dynamically
added to or removed from delegation roles as collaborators join and leave
trusted repositories.
[Learn more about Notary delegation roles.](/notary/advanced_usage.md)
Every change to the repository now needs to be signed by the snapshot key that
was generated with the `notary init` command.
To avoid having to distribute this key to other members so that they can also
sign images with this key, you can rotate the key and make it be managed by
the Notary server.
This operation only needs to be done once for the repository.
```bash
# This only needs to be done once for the repository
$ notary key rotate <dtr_url>/<account>/<repository> snapshot --server-managed
```
Then ask the users you want to delegate the image signing to share with you
the `cert.pem` files that are included in their client bundles. These files
should be shared using a trusted channel.
Then run the following command to create a new Notary delegation role, using the
user certificates:
```bash
$ notary delegation add -p <dtr_url>/<account>/<repository> targets/releases --all-paths user1.pem user2.pem
```
The above command adds the the `targets/releases` delegation role to a trusted
repository.
This role is treated as an actual release branch for Docker Content Trust,
since `docker pull` commands with trust enabled will pull directly from this
role, if data exists.
All users that can release images should be added to this role.
[Learn more about the targets/releases role](/engine/security/trust/trust_delegation.md).
Notary has no limit on how many delegation roles can exist, so you can add more
delegation roles such as `targets/qa_team` or `targets/security_team` to the
trusted repository.
Valid delegation roles take the form of `targets/<delegation>`, where
`<delegation>` does not include further slashes.
You will need to add the key to at least one delegation in addition to the `targets/releases` delegation in order for UCP to honor the signed content:
```bash
$ notary delegation add -p <dtr_url>/<account>/<repository> targets/devops --all-paths user1.pem user2.pem
```
Before delegation role users can publish signed content with Notary or
Docker Content Trust, they must import the private key associated with the user certificate:
```bash
$ notary key import key.pem
```
## Where to go next
* [Restrict services to worker nodes](restrict-services-to-worker-nodes.md)

2
datacenter/ucp/2.1/guides/admin/configure/store-logs-in-an-external-system.md
View File

@ -55,4 +55,4 @@ options that can accomplish this (e.g. Shield plug-in for Kibana)
## Where to go next
* [Only allow running signed images](only-allow-running-signed-images.md)
* [Require all images to be signed](content-trust.md)