Improve image signing docs (#6664)

* Improve image signing docs

ee/dtr/user/access-dtr/configure-your-notary-client.md

@@ -101,7 +101,7 @@ the following content:
 {
   "trust_dir" : "~/.docker/trust",
   "remote_server": {
-    "url": "<dtr-url>",
+    "url": "https://<dtr-url>:<dtr-port>",
     "root_ca": "<dtr-ca.pem>"
   }
 }
@@ -139,4 +139,3 @@ notary key list
 ```
 
 The key you've imported should be listed with the role `delegation`.
-

ee/dtr/user/manage-images/delete-images.md

@@ -14,3 +14,73 @@ You can also delete all image versions, by deleting the repository. For that,
 in the image **repository**, navigate to the **Settings** tab, and click the
 **Delete** button.
 
+## Delete signed images
+
+DTR only allows deleting images if that image hasn't been signed. You first
+need to delete all the trust data associated with the image. Then you'll
+be able to delete it.
+
+![](../../images/delete-images-2.png){: .with-border}
+
+There are three steps to delete a signed image:
+
+1. Find which roles signed the image.
+2. Remove the trust data for each role.
+3. The image is now unsigned, so you can delete it.
+
+### Find which roles signed an image
+
+To find which roles signed an image, you first need to learn which roles
+are trusted to sign the image.
+
+[Set up your Notary client](../../access-dtr/configure-your-notary-client.md),
+and run:
+
+```
+notary delegation list dtr.example.org/library/wordpress
+```
+
+In this example, the repository owner delegated trust to the
+`targets/releases` and `targets/qa` roles:
+
+```
+ROLE                PATHS             KEY IDS                                                             THRESHOLD
+----                -----             -------                                                             ---------
+targets/releases    "" <all paths>    c3470c45cefde5447cf215d8b05832b0d0aceb6846dfa051db249d5a32ea9bc8    1
+targets/qa          "" <all paths>    c3470c45cefde5447cf215d8b05832b0d0aceb6846dfa051db249d5a32ea9bc8    1
+```
+
+Now that you know which roles are allowed to sign images in this repository,
+you can learn which roles actually signed it:
+
+```
+# Check if the image was signed by the "targets" role
+notary list dtr.example.org/library/wordpress
+
+# Check if the image was signed by a specific role
+notary list dtr.example.org/library/wordpress --roles <role-name>
+```
+
+In this example the image was signed by three roles: `targets`,
+`targets/releases`, and `targets/qa`.
+
+### Remove trust data for a role
+
+Once you know which roles signed an image, you'll be able to remove trust data
+for those roles. Only users with private keys that have the roles are able
+to do this operation.
+
+For each role that signed the image, run:
+
+```
+notary remove dtr.example.org/library/wordpress <tag> \
+  --roles <role-name> --publish
+```
+
+Once you've removed trust data for all roles, DTR shows the image as unsigned.
+Then you can delete it.
+
+## Where to go next
+
+* [Pull and push images](pull-and-push-images.md)
+* [Sign an image](sign-images/index.md)

ee/dtr/user/manage-images/override-a-vulnerability.md

@@ -29,3 +29,7 @@ After dismissing a vulnerability, DTR won't re-evaluate the promotion policies
 you have set up for the repository.
 If you want the promotion policy to be re-evaluated for the image after hiding
 a particular vulnerability, click **Promote**.
+
+## Where to go next
+
+* [Scan images for vulnerabilities](scan-images-for-vulnerabilities.md)

ee/dtr/user/manage-images/scan-images-for-vulnerabilities.md

@@ -153,4 +153,8 @@ updated and corrected versions of vulnerable components, or by using a different
 components that provide the same functionality. When you have updated the source
 code, run a build to create a new image, tag the image, and push the updated
 image to your DTR instance. You can then re-scan the image to confirm that you
-have addressed the vulnerabilities.
+have addressed the vulnerabilities.
+
+## Where to go next
+
+* [Override a reported vulnerability](override-a-vulnerability.md)

ee/dtr/user/manage-images/sign-images/delegate-image-signing.md

@@ -39,7 +39,7 @@ The member of the IT ops team then asks the QA team for their public key
 certificate files that are part of their UCP client bundle.
 
 If they don't have a UCP client bundle,
-[they can download a new one](/datacenter/ucp/2.2/guides/user/access-ucp/cli-based-access.md).
+[they can download a new one](/ee/ucp/user-access/cli.md).
 
 ## Delegate image signing
 
@@ -53,20 +53,19 @@ In this example we'll delegate trust to `targets/releases` and `targets/qa`:
 
 ```bash
 # Delegate trust, and add that public key with the role targets/releases
-notary delegation add --publish \
+notary delegation add dtr.example.org/dev/nginx targets/releases \
-  dtr.example.org/dev/nginx targets/releases \
+  <user-1-cert.pem> <user-2-cert.pem> --all-paths --publish
-  --all-paths <user-1-cert.pem> <user-2-cert.pem>
 
 # Delegate trust, and add that public key with the role targets/admin
-notary delegation add --publish \
+notary delegation add dtr.example.org/dev/nginx targets/qa \
-  dtr.example.org/dev/nginx targets/qa \
+  <user-1-cert.pem> <user-2-cert.pem> --all-paths --publish
-  --all-paths <user-1-cert.pem> <user-2-cert.pem>
 ```
 
 Now members from the QA team just have to [configure their Notary CLI client
 with UCP private keys](../../access-dtr/configure-your-notary-client.md)
 to be able to [push and sign images](index.md) into the `dev/nginx` repository.
 
+
 ## Where to go next
 
-- [Manage trusted repositories](manage-trusted-repositories.md)
+- [Manage trusted repositories](manage-trusted-repositories.md)

ee/dtr/user/manage-images/sign-images/index.md

@@ -99,12 +99,14 @@ In this example we'll delegate trust to `targets/releases` and `targets/admin`:
 ```bash
 # Delegate trust, and add that public key with the role targets/releases
 notary delegation add --publish \
-  dtr.example.org/dev/nginx targets/releases \
+  dtr.example.org/dev/nginx \
+  targets/releases \
   --all-paths <ucp-cert.pem>
 
 # Delegate trust, and add that public key with the role targets/admin
 notary delegation add --publish \
-  dtr.example.org/dev/nginx targets/admin \
+  dtr.example.org/dev/nginx \
+  targets/admin \
   --all-paths <ucp-cert.pem>
 ```
 
@@ -168,3 +170,7 @@ signed. For each repository there are four files.
 | `timestamp.json` | Has data about the digest, size, and version number for the snapshot.json file. This data is signed by the timestamp key. |
 
 [Learn more about trust metadata](/notary/service_architecture.md).
+
+## Where to go next
+
+* [Delegate image signing](delegate-image-signing.md)

ee/dtr/user/manage-images/sign-images/manage-trusted-repositories.md

@@ -40,7 +40,7 @@ docker push <dtr_url>/<account>/<repository>
 or
 
 ```
-notary init --publish <dtr_url>/<account>/<repository>
+notary init <dtr_url>/<account>/<repository> --publish
 ```
 
 ## Manage staged changes
@@ -124,14 +124,18 @@ To delegate image signing to other UCP users, get the `cert.pem` file that's
 included in their client bundle and run:
 
 ```bash
-notary delegation add -p <dtr_url>/<account>/<repository> targets/<role> --all-paths user1.pem user2.pem
+notary delegation add \
+  <dtr_url>/<account>/<repository> targets/<role> user1.pem user2.pem \
+  --all-paths --publish
 ```
 
 You can also remove keys from a delegation role:
 
 ```bash
 # Remove the given keys from a delegation role
-notary delegation remove -p <dtr_url>/<account>/<repository> targets/<role> <keyID1> <keyID2>
+notary delegation remove \
+  <dtr_url>/<account>/<repository> targets/<role> <keyID1> <keyID2> \
+  --publish
 
 # Alternatively, you can remove keys from all delegation roles
 notary delegation purge <dtr_url>/<account>/<repository> --key <keyID1> --key <keyID2>
@@ -149,4 +153,4 @@ directory where your private keys are stored, with the `-d` flag.
 ## Where to go next
 
 - [Learn more about Notary](/notary/advanced_usage.md)
-- [Notary architecture](/notary/service_architecture.md)
+- [Notary architecture](/notary/service_architecture.md)