Add documentation for application management in DTR 2.7 (docker#1186)

* Add documentation for application management in DTR 2.7

* Incorporate feedback

* Remove unknown type warning

* Incorporate feedback

- s/UCP/DTR
- Add link to client certificate authentication page

* Incorporate feedback

- Rephrase scanning results
- Rephrase instructions

_data/toc.yaml

@@ -2545,6 +2545,8 @@ manuals:
             path: /ee/dtr/user/audit-repository-events/
           - title: Auto-delete repository events
             path: /ee/dtr/admin/configure/auto-delete-repo-events/
+      - title: Manage applications
+        path: /ee/dtr/user/manage-applications/
       - title: Manage access tokens
         path: /ee/dtr/user/access-tokens/
       - title: Tag pruning

app/working-with-app.md

@@ -35,7 +35,7 @@ We'll complete the following steps:
 1. Populate the project
 1. Validate the app
 1. Deploy the app
-1. Push the app to Docker Hub
+1. Push the app to Docker Hub or Docker Trusted Registry
 1. Install the app directly from Docker Hub
 
 ### Prerequisites
@@ -337,7 +337,22 @@ hashicorp/http-echo
 
 The app is now stored in the container registry.
 
-### Install the app directly from Docker Hub
+### Push the app to DTR
+
+Pushing an app to Docker Trusted Registry (DTR) involves the same procedure as [pushing an app to Docker Hub](#push-the-app-to-docker-hub) except that you need your DTR user credentials and [your DTR repository information](/ee/dtr/user/manage-images/review-repository-info/). To use client certificates for DTR authentication, see [Enable Client Certificate Authentication](/ee/enable-client-certificate-authentication/).
+
+```bash
+$ docker app push my-app --tag <dtr-fqdn>/nigelpoulton/app-test:0.1.0
+<dtr-fqdn>/nigelpoulton/app-test:0.1.0-invoc
+hashicorp/http-echo
+ application/vnd.docker.distribution.manifest.v2+json [2/2] (sha256:bd1a813b...)
+Successfully pushed bundle to <dtr-fqdn>/nigelpoulton/app-test:0.1.0. 
+Digest is sha256:bd1a813b6301939fa46e617f96711e0cca1e4065d2d724eb86abde6ef7b18e23.
+```
+
+The app is now stored in your DTR.
+
+### Install the app directly from Docker Hub or DTR
 
 Now that the app is pushed to the registry, try an `inspect` and `install` command against it. The location of your app will be different to the one shown in the examples.
 
@@ -355,7 +370,7 @@ hello.port     8080
 hello.text     Hello world!
 ```
 
-This action was performed directly against the app in the registry.
+This action was performed directly against the app in the registry. Note that for DTR, the application will be prefixed with the Fully Qualified Domain Name (FQDN) of your trusted registry.
 
 Now install it as a native Docker App by referencing the app in the registry, with a different port.
 
@@ -386,6 +401,3 @@ Application "hello-world" uninstalled on context "default"
 
 You can see the name of your Docker App with the `docker stack ls` command.
 
-## Convert an existing Compose app into a Docker App project
-
-Content TBA

ee/dtr/user/manage-applications.md

@@ -0,0 +1,61 @@
+---
+title: Manage applications
+description: Learn how to manage applications in Docker Trusted Registry.
+keywords: DTR, trusted registry, Docker apps
+---
+
+With the introduction of [the experimental `app` plugin](/engine/reference/commandline/app/) to the Docker CLI, DTR has been enhanced to include application management. In DTR 2.7, you can push an app to your DTR repository and have an application be clearly distinguished from [individual and multi-architecture container images](/ee/dtr/user/manage-images/pull-and-push-images/#push-an-image/), as well as [plugins](/engine/reference/commandline/plugin_push/). When you push an application to DTR, you see two image tags:
+
+| Image | Tag | Type | Under the hood |
+|-------|-----|------|----------------|
+| Invocation | `<app_tag>-invoc` | Container image represented by OS and architecture (e.g. `linux amd64`) | Uses Docker Engine. The Docker daemon is responsible for building and pushing the image. |
+| Application with bundled components | `<app_tag>` | Application | Uses the app client to build and push the image. `docker app` is experimental on the Docker client. | 
+
+Notice the app-specific tags, `app` and `app-invoc`, with scan results for the bundled components in the former and the invocation image in the latter. To view the scanning results for the bundled components, click "View Details" next to the `app` tag.
+
+![](/ee/dtr/images/manage-applications-1.png){: .with-border}
+
+Click on the image name or digest to see the vulnerabilities for that specific image.
+
+![](/ee/dtr/images/manage-applications-2.png){: .with-border}
+
+## Parity with existing repository and image features
+
+The following repository and image management events also apply to applications:
+
+- [Creation](/app/working-with-app/#initialize-and-deploy-a-new-docker-app-project-from-scratch/)
+- [DTR pushes](/app/working-with-app/#push-the-app-to-dtr) 
+- [Vulnerability scans](/ee/dtr/user/manage-images/scan-images-for-vulnerabilities/)
+- [Vulnerability overrides](/ee/dtr/user/manage-images/override-a-vulnerability/) 
+- [Deletion](/ee/dtr/user/manage-images/delete-images/)
+- [Immutable tags](/ee/dtr/user/manage-images/prevent-tags-from-being-overwritten/)
+- [Promotion policies](/ee/dtr/user/promotion-policies/)
+
+### Limitations
+
+- You cannot sign an application since the Notary signer cannot sign [OCI (Open Container Initiative)](https://github.com/opencontainers/image-spec/blob/master/spec.md) indices.
+- Scanning-based policies do not take effect until after all images bundled in the application have been scanned. 
+- Docker Content Trust (DCT) does not work for applications and multi-arch images, which are the same under the hood.
+
+## Troubleshooting tips
+
+### x509 certificate errors
+
+```bash
+fixing up "35.165.223.150/admin/lab-words:0.1.0" for push: failed to resolve "35.165.223.150/admin/lab-words:0.1.0-invoc", push the image to the registry before pushing the bundle: failed to do request: Head https://35.165.223.150/v2/admin/lab-words/manifests/0.1.0-invoc: x509: certificate signed by unknown authority
+```
+
+#### Workaround
+
+Check that your DTR has been configured with your TLS certificate's Fully Qualified Domain Name (FQDN). See [Configure DTR](/ee/dtr/admin/install/#step-5-configure-dtr) for more details. For `docker app` testing purposes, you can pass the `--insecure-registries` option for pushing an application`.
+
+```bash
+docker app push hello-world --tag 35.165.223.150/admin/lab-words:0.1.0 --insecure-registries 35.165.223.150
+35.165.223.150/admin/lab-words:0.1.0-invoc
+Successfully pushed bundle to 35.165.223.150/admin/lab-words:0.1.0. Digest is sha256:bd1a813b6301939fa46e617f96711e0cca1e4065d2d724eb86abde6ef7b18e23.
+```
+
+## Known Issues
+
+See [DTR 2.7 Release Notes - Known Issues](/ee/dtr/release-notes/#270) for known issues related to applications in DTR.
+

ee/dtr/user/promotion-policies/index.md

@@ -6,12 +6,15 @@ keywords: registry, promotion, mirror
 ---
 
 Docker Trusted Registry allows you to automatically promote and mirror images
-based on a policy. This way you can create a Docker-centric development pipeline.
+based on a policy. In DTR 2.7, you have the option to promote applications with [the experimental `docker app` CLI addition](/ee/dtr/user/manage-applications/).
+Note that scanning-based promotion policies do not take effect until all application-bundled images have been scanned.
+This way you can create a Docker-centric development pipeline.
 
 You can mix and match promotion policies, mirroring policies, and webhooks to
 create flexible development pipelines that integrate with your existing
 CI/CD systems.
 
+
 ## Promote an image using policies
 
 One way to create a promotion pipeline is to automatically promote images