Merge pull request docker#7834 from bermudezmt/dtr-deploy-caches

Add note around deploying DTR caches to avoid synchronicity issues

_data/toc.yaml

@@ -2657,10 +2657,14 @@ manuals:
               section:
               - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/
                 title: Overview
-              - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/tls/
-                title: Deploy caches with TLS
-              - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/chaining/
-                title: Chain multiple caches
+              - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/strategy/
+                title: Cache deployment strategy
+              - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/simple/
+                title: Deploy a DTR cache
+              - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/high-availability/
+                title: Configure caches for high availability
+              - path: /datacenter/dtr/2.5/guides/admin/configure/deploy-caches/configuration-reference/
+                title: Cache configuration reference
             - path: /datacenter/dtr/2.5/guides/admin/configure/garbage-collection/
               title: Garbage collection
             - path: /datacenter/dtr/2.5/guides/admin/configure/use-a-web-proxy/

datacenter/dtr/2.5/guides/admin/configure/deploy-caches/configuration-reference.md

@@ -0,0 +1,80 @@
+---
+title: DTR cache configuration reference
+description: Learn about the different configuration options for DTR caches.
+keywords: DTR, cache
+---
+
+DTR caches are based on Docker Registry, and use 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:
+            - <Externally-reachable address for upstream registry or content cache in format scheme://host:port>
+          cas:
+            - <Absolute path to next-hop upstream registry or content cache CA certificate in the container's filesystem>
+```
+
+Below you can find the description for each parameter, specific to DTR caches.
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Required</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td>
+      <code>blobttl</code>
+    </td>
+    <td>
+      no
+    </td>
+    <td>
+A positive integer and an optional unit of time suffix to determine the TTL (Time to Live) value for blobs in the cache. If <code>blobttl</code> is configured, <code>storage.delete.enabled</code> must be set to <code>true</code>. Acceptable units of time are:
+      <ul>
+        <li><code>ns</code> (nanoseconds)</li>
+        <li><code>us</code> (microseconds)</li>
+        <li><code>ms</code> (milliseconds)</li>
+        <li><code>s</code> (seconds)</li>
+        <li><code>m</code> (minutes)</li>
+        <li><code>h</code> (hours)</li>
+      </ul>
+    If you omit the suffix, the system interprets the value as nanoseconds.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>cas</code>
+    </td>
+    <td>
+      no
+    </td>
+    <td>
+      An optional list of absolute paths to PEM-encoded CA certificates of upstream registries or content caches.
+    </td>
+  </tr>
+<tr>
+  <td>
+    <code>upstreams</code>
+  </td>
+  <td>
+    yes
+  </td>
+  <td>
+      A list of externally-reachable addresses for upstream registries of content caches. If more than one host is specified, it will pull from registries in round-robin order.
+  </td>
+</tr>
+</table>

datacenter/dtr/2.5/guides/admin/configure/deploy-caches/high-availability.md

@@ -0,0 +1,76 @@
+---
+title: Configure caches for high availability
+description: Learn how to deploy a DTR cache with fault tolerance and high
+  availability.
+keywords: DTR, cache
+---
+
+If you're deploying a DTR cache in a zone with few users and with no uptime
+SLAs, a [single cache service is enough for you](simple.md).
+
+But if you want to make sure your DTR cache is always available to users
+and is highly performant, you should configure your cache deployment for
+high availability.
+
+![Highly-available cache](../../../images/deploy-caches-ha-1.svg)
+
+## System requirements
+
+* Multiple nodes, one for each cache replica.
+* A load balancer.
+* Shared storage system that has read-after-write consistency.
+
+The way you deploy a DTR cache is the same, whether you're deploying a single
+replica or multiple ones. The difference is that you should configure the
+replicas to store data using a shared storage system.
+
+When using a shared storage system, once an image layer is cached, any replica
+is able to serve it to users without having to fetch a new copy from DTR.
+
+DTR caches support the following storage systems:
+* Alibaba Cloud Object Storage Service
+* Amazon S3
+* Azure Blob Storage
+* Google Cloud Storage
+* NFS
+* Openstack Swift
+
+If you're using NFS as a shared storage system, make sure the shared
+directory is configured with:
+
+```
+/dtr-cache *(rw,root_squash,no_wdelay)
+```
+
+This ensures read-after-write consistency for NFS.
+
+You should also mount the NFS directory on each node where you'll deploy a
+DTR cache replica.
+
+## Label the DTR cache nodes
+
+Use SSH to log in to a manager node of the swarm where you want to deploy
+the DTR cache.
+
+If you're using UCP to manage that swarm you can also use a client bundle to
+configure your Docker CLI client to connect to that swarm.
+
+Label each node that is going to run the cache replica, by running:
+
+```
+docker node update --label-add dtr.cache=true <node-hostname>
+```
+
+## Configure and deploy the cache
+
+Create the cache configuration files by following the
+[instructions for deploying a single cache replica](simple.md#prepare-the-cache-deployment).
+
+Make sure you adapt the `storage` object, using the
+[configuration options for the shared storage](/registry/configuration.md#storage)
+of your choice.
+
+## Configure your load balancer
+
+The last step is to deploy a load balancer of your choice to load-balance
+requests across the multiple replicas you deployed.