Prepare the cache deployment

To ensure MSR cache functionality, Mirantis highly recommends that you deploy the cache on a dedicated node.

Label the cache node

To target your deployment to the cache node, you must first label that node. To do this, SSH into a manager node of the swarm within which you want to deploy the MSR cache.

docker node update --label-add dtr.cache=true <node-hostname>


If you are using MKE to manage that swarm, use a client bundle to configure your Docker CLI client to connect to the swarm.

Configure the MSR cache

Following cache preparation, you will have the following file structure on your workstation:

├── docker-stack.yaml
├── config.yaml          # The cache configuration file
└── certs
    ├── cache.cert.pem  # The cache public key certificate
    ├── cache.key.pem   # The cache private key
    └── dtr.cert.pem    # MSR CA certificate

With the configuration detailed in this section, the cache fetches image layers from MSR and keeps a local copy for 24 hours. After that, if a user requests that image layer, the cache fetches it again from MSR.

The cache is configured to persist data inside its container. If something goes wrong with the cache service, Docker automatically redeploys a new container, but previously cached data is not persisted. You can customize the storage parameters, if you want to store the image layers using a persistent storage back end.

Also, the cache is configured to use port 443. If you are already using that port in the swarm, update the deployment and configuration files to use another port. Do not forget to create firewall rules for the port you choose.

Edit the docker-stack.yaml file

With the docker-stack.yaml file, which you mount into the container, you deploy the cache using a single command.

You can edit the following MSR cache configuration file to fit your environment:

version: "3.3"
     image: mirantis/dtr-content-cache:2.8.2
         - /
         - "/config.yml"
         - 443:443
         replicas: 1
           constraints: [node.labels.dtr.cache == true]
           condition: on-failure
         - config.yml
         - dtr.cert.pem
         - cache.cert.pem
         - cache.key.pem
    file: ./config.yml
    file: ./certs/dtr.cert.pem
    file: ./certs/cache.cert.pem
    file: ./certs/cache.key.pem

Edit the config.yaml file

The MSR cache takes its configuration from a configuration file that you mount into the container.

You can edit the following MSR cache configuration file for your environment, entering the relevant external MSR cache, worker node, or external loadbalancer FQDN. Once you have configured the cache it fetches image layers from MSR and maintains a local copy for 24 hours. If a user requests the image layer after that period, the cache fetches it again from MSR.

version: 0.1
   level: info
      enabled: true
      rootdirectory: /var/lib/registry
   addr: ''
   secret: generate-random-secret
   host: 'https://<cache-url>''
      certificate: /run/secrets/cache.cert.pem
      key: /run/secrets/cache.key.pem
      - name: downstream
          blobttl: 24h
            - https://<msr-url>:<msr-port>
            - /run/secrets/dtr.cert.pem

Create the MSR cache certificates

To deploy the MSR cache with a TLS endpoint, you must generate a TLS ceritificate and key from a certificate authority.

Be aware that to expose the MSR cache through a node port or a host port you must use a Node FQDN (Fully Qualified Domain Name) as a SAN in your certificate.

Create the MSR cache certficates:

  1. Create a cache certificate:

    ssh-keygen -t rsa -b 4096 -C "" -m PEM
  2. Create a directory called certs.

  3. In the certs directory, place the newly created certificate cache.cert.pem and key cache.key.pem for your MSR cache.

  4. Add content to the cert pem files.

    pem file

    Content to add


    Add the public key certificate for the cache. If the certificate has been signed by an intermediate certificate authority, append its public key certificate at the end of the file.


    Add the unencrypted private key for the cache.


    The cache communicates with MSR using TLS. If you’ve customized MSR to use TLS certificates issued by a globally trusted certificate authority, the cache automatically trusts MSR. If, though, you are using the default MSR configuration, or MSR is using TLS certificates signed by your own certificate authority, you need to configure the cache to trust MSR. To do this, add the MSR CA certificate to the certs/dtr.cert. pem file.

    curl -sk https://<msr-url>/ca > certs/dtr.cert.pem