diff --git a/_data/toc.yaml b/_data/toc.yaml index 037f961e60..bfb6b84b0a 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1257,6 +1257,8 @@ toc: title: Configure your Docker Engine with DTR - path: /datacenter/dtr/2.2/guides/work-images-dtr/ title: Work with images in DTR + - path: /datacenter/dtr/2.2/guides/cache-docker-images/ + title: Cache Docker images - path: /datacenter/dtr/2.2/guides/security-scan-dtr/ title: Docker Security Scanning in DTR - sectiontitle: API and CLI reference diff --git a/datacenter/dtr/2.2/guides/cache-docker-images.md b/datacenter/dtr/2.2/guides/cache-docker-images.md new file mode 100644 index 0000000000..4a39417f74 --- /dev/null +++ b/datacenter/dtr/2.2/guides/cache-docker-images.md @@ -0,0 +1,235 @@ +--- +title: Cache Docker images +description: Learn how to configure DTR to have caching and making pulls faster. +keywords: docker, registry, dtr, cache +--- + +You can configure DTR to have multiple caches. Users can then configure their +DTR user accounts to specify which cache to pull from. This way users can +pull Docker images from a cache that is geographically closer to them or +that allows them faster downloads. + +## How DTR caches works + +You start by deploying one or more DTR caches. + +![](images/cache-docker-images-1.svg) + +Since caches have to contact DTR for authorizing user requests, and requests +are chained from one cache to the next until the request reaches DTR, you +should avoid creating cache trees that have more than two levels. This can +make the image pull slower than having no cache at all. + +After you've deployed the caches, users can configure which cache to +pull from on their DTR user profile page. This allows users to choose which +cache to use for faster image pulls. + +In this example, users can go to their DTR profile page, and configure their +user account to use the US cache. Then, when using the +`docker pull //` command to pull an image, the +following happens: + +1. The Docker client makes a request to DTR which in turn authenticates the +request +2. The Docker client requests the image manifest to DTR. This ensures that +users will always pull the correct image, and not an outdated version +3. The Docker client requests the layer blobs to DTR, which redirects the +request to the cache configured by the user +4. If the blob exists on the cache it is sent to the user. Otherwise, the cache +pulls it from DTR and sends it to the user + +When a user pushes an image, that image is only available in DTR. A cache +will only store the image when a user tries to pull the image using that cache. + + +## Deploy a DTR cache + +You can deploy a DTR cache on any host that has Docker installed. The only +requirements are that: + +* Users need to have access to both DTR and the cache +* The cache needs access to DTR + +Log into the host using ssh, and create a `config.yml` file with the following +content: + +``` +version: 0.1 +storage: + delete: + enabled: true + filesystem: + rootdirectory: /var/lib/registry +http: + addr: :5000 +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - originhost: https:// + cas: + - /certs/dtr-ca.pem +``` + +This configures the cache to store the images in the directory +`/var/lib/registry`, exposes the cache service on port 5000, and configures the +cache to delete images that are not pulled in the last 24 hours. It also +defines where DTR can be reached, and which CA certificates should be trusted. + +Now we need to download the CA certificate used by DTR. For this, run: + +``` +curl -k https:///ca > dtr-ca.pem +``` + +Now that we've got the cache configuration file and DTR CA certificate, we can +deploy the cache by running: + +```none +docker run --detach --restart always \ + --name content-cache \ + --publish 5000:5000 \ + --volume $(pwd)/dtr-ca.pem:/certs/dtr-ca.pem \ + --volume $(pwd)/config.yml:/config.yml \ + docker/dtr-content-cache: /config.yml +``` + +You can also run the command in interactive mode instead of detatched by +replacing `--detached` with `--interactive`. This allows you to +see the logs generated by the container and troubleshoot misconfigurations. + +Now that you've deployed a cache, you need to configure DTR to know about it. +This is done using the `POST /api/v0/content_caches` API. You can use the +DTR interactive API documentation to use this API. + +In the DTR web UI, click the top-right menu, and choose **API docs**. + +![](images/cache-docker-images-2.png){: .with-border} + +Navigate to the `POST /api/v0/content_caches` line and click it to expand. +In the **body** field include: + +``` +{ + "name": "region-us", + "host": "http://:5000" +} +``` + +Click the **Try it out!** button to make the API call. + +![](images/cache-docker-images-3.png){: .with-border} + +DTR knows about the cache we've created, so we just need to configure our DTR +user settings to start using that cache. + +In the DTR web UI, navigate to your **user profile**, click the **Settings** +tab, and change the **Content cache** settings to use the **region-us** cache. + +![](images/cache-docker-images-4.png){: .with-border} + +Now when you pull images, you'll be using the cache. To test this, try pulling +an image from DTR. You can inspect the logs of the cache service, to validate +that the cache is being used, and troubleshoot problems. + +In the host where you've deployed the `region-us` cache, run: + +``` +docker logs content-cache +``` + + +## Configure the cache + +The DTR cache is based on Docker Registry, and uses the same configuration +file format. +[Learn more about the configuration options](/registry/configuration.md). + +The DTR cache extends the Docker Registry configuration file format by +introducing a new middleware called `downstream` that has three configuration +options: `blobttl`, `upstreams`, and `cas`: + +```none +# Settings that you would include in a +# Docker Registry configuration file followed by + +middleware: + registry: + - name: downstream + options: + blobttl: 24h + upstreams: + - originhost: + upstreamhosts: + - + - + cas: + - + - +``` + +Below you can find the description for each DTR cache-specific parameter. + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequiredDescription
+ blobttl + + no + +The TTL for blobs in the cache. This field takes a positive integer and an optional suffix indicating the unit of time. If +this field is configured, "storage.delete.enabled" must be configured to true. Possible units are: +
    +
  • ns (nanoseconds)
    • +
  • us (microseconds)
    • +
  • ms (milliseconds)
    • +
  • s (seconds)
    • +
  • m (minutes)
    • +
  • h (hours)
    • +
+ If you omit the suffix, the system interprets the value as nanoseconds. +
+ cas + + no + + A list of absolute paths to PEM-encoded CA certificates of upstream registries. +
+ originhost + + yes + + An externally-reachable address for the origin registry, as a fully qualified URL. +
+ upstreamhosts + + no + + A list of externally-reachable addresses for upstream registries for cache chaining. If more than one host is specified, pulls from upstream content caches will be done in round-robin order. +
diff --git a/datacenter/dtr/2.2/guides/images/cache-docker-images-1.svg b/datacenter/dtr/2.2/guides/images/cache-docker-images-1.svg new file mode 100644 index 0000000000..338dcdcd53 --- /dev/null +++ b/datacenter/dtr/2.2/guides/images/cache-docker-images-1.svg @@ -0,0 +1,53 @@ + + + + content-cache-1 + Created with Sketch. + + + + + + + + + + + + + + + cache CH + + + + + + + + cache AS + + + + + + cache EU + + + + + + cache US + + + + + + + DTR + + + + + + \ No newline at end of file diff --git a/datacenter/dtr/2.2/guides/images/cache-docker-images-2.png b/datacenter/dtr/2.2/guides/images/cache-docker-images-2.png new file mode 100644 index 0000000000..dd60832b44 Binary files /dev/null and b/datacenter/dtr/2.2/guides/images/cache-docker-images-2.png differ diff --git a/datacenter/dtr/2.2/guides/images/cache-docker-images-3.png b/datacenter/dtr/2.2/guides/images/cache-docker-images-3.png new file mode 100644 index 0000000000..085ac31f86 Binary files /dev/null and b/datacenter/dtr/2.2/guides/images/cache-docker-images-3.png differ diff --git a/datacenter/dtr/2.2/guides/images/cache-docker-images-4.png b/datacenter/dtr/2.2/guides/images/cache-docker-images-4.png new file mode 100644 index 0000000000..93f76f1a78 Binary files /dev/null and b/datacenter/dtr/2.2/guides/images/cache-docker-images-4.png differ