Prepare the cache deployment

Important

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>

Note

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.yml
├── config.yml          # 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 herein, 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 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 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. 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"
services:
  cache:
    image: mirantis/dtr-content-cache:2.8.2
    entrypoint:
      - "/start.sh"
      - "/config.yml"
    ports:
      - 443:443
    deploy:
      replicas: 1
      placement:
        constraints: [node.labels.dtr.cache == true]
      restart_policy:
        condition: on-failure
    configs:
      - config.yml
    secrets:
      - dtr.cert.pem
      - cache.cert.pem
      - cache.key.pem
configs:
  config.yml:
    file: ./config.yml
secrets:
  dtr.cert.pem:
    file: ./certs/dtr.cert.pem
  cache.cert.pem:
    file: ./certs/cache.cert.pem
  cache.key.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
log:
  level: info
storage:
  delete:
    enabled: true
  filesystem:
    rootdirectory: /var/lib/registry
http:
  addr: '0.0.0.0:443'
  secret: generate-random-secret
  host: 'https://<cache-url>'
  tls:
    certificate: /run/secrets/cache.cert.pem
    key: /run/secrets/cache.key.pem
middleware:
  registry:
    - name: downstream
      options:
        blobttl: 24h
        upstreams:
          - https://<msr-url>:<msr-port>
        cas:
          - /run/secrets/dtr.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 "your_email@example.com" -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	Content to add
   cache.cert.pem	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.
   cache.key.pem	Add the unencrypted private key for the cache.
   dtr.cert.pem	The cache communicates with MSR using TLS. If you have 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, and edit the daemon.json file to allow for insecure registries. Add the MSR CA certificate to the certs/dtr.cert. pem file: curl -sk https://<msr-url>/ca > certs/dtr.cert.pem Modify the daemon.json file to include: "insecure-registries" : "<msraddress:portnumber>"