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

Note

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

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: registry.mirantis.com/msr/msr-content-cache:3.0.7
    entrypoint:
      - "/start.sh"
      - "/config.yml"
    ports:
      - 443:443
    deploy:
      replicas: 1
      placement:
        constraints: [node.labels.msr.cache == true]
      restart_policy:
        condition: on-failure
    configs:
      - source: config.yml
        target: /config.yml
    secrets:
      - msr.cert.pem
      - cache.cert.pem
      - cache.key.pem
configs:
  config.yml:
    file: ./config.yml
secrets:
  msr.cert.pem:
    file: ./certs/msr.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 load balancer 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/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:

Create a cache certificate:

ssh-keygen -t rsa -b 4096 -C "your_email@example.com" -m PEM

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.

Configure the cert pem files, as detailed below:

pem file	Information 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.
`msr.cert.pem`	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

pem file

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

msr.cert.pem

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