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 msr.cache=true <node-hostname>


If you are using MKE to manage the 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.yml
├── config.yml          # The cache configuration file
└── certs
    ├── cache.cert.pem  # The cache public key certificate
    ├── cache.key.pem   # The cache private key
    └── msr.cert.pem    # MSR CA certificate

With the configuration detailed herein, the cache fetches image layers from MSR and retains a local copy for 24 hours. After that, if a user requests that image layer, the cache re-fetches it 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 the previously cached data does not persist. 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. Remember to create firewall rules for the port you choose.

Edit the docker-stack.yml file

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

Edit the sample MSR cache configuration file that follows to fit your environment:

version: "3.3"
      - "/"
      - "/config.yml"
      - 443:443
      replicas: 1
        constraints: [node.labels.msr.cache == true]
        condition: on-failure
      - source: config.yml
        target: /config.yml
      - msr.cert.pem
      - cache.cert.pem
      - cache.key.pem
    file: ./config.yml
    file: ./certs/msr.cert.pem
    file: ./certs/cache.cert.pem
    file: ./certs/cache.key.pem

Edit the config.yml file

You configure the MSR cache using a configuration file that you mount into the container.

Edit the sample MSR cache configuration file that follows to fit your environment, entering the relevant external MSR cache, worker node, or external loadbalancer FQDN. Once configured, the cache 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 re-fetches it 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/msr.cert.pem

Create the MSR cache certificates

To deploy the MSR cache with a TLS endpoint, you must generate a TLS certificate 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 certificates:

  1. Create a cache certificate:

    ssh-keygen -t rsa -b 4096 -C "" -m PEM
  2. Create a directory called certs and place in it the newly created certificate cache.cert.pem and key cache.key.pem for your MSR cache.

  3. Configure the cert pem files, as detailed below:

    pem file

    Information 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.


    Configure the cache to trust MSR.

    Add the MSR CA certificate to the certs/msr.cert. pem file, if you are using the default MSR configuration, or if MSR is using TLS certificates signed by your own certificate authority. Note that configuring msr.cert.pem is not necessary if you have customized MSR to use TLS certificates issued by a globally trusted certificate authority, as in this case the cache will automatically trust MSR.

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