Install MSR online¶

Mirantis Secure Registry (MSR) is a containerized application that runs on a swarm managed by the Mirantis Kubernetes Engine (MKE). It can be installed on-premises or on a cloud infrastructure.

Step 1. Validate the system requirements¶

Before installing MSR, make sure your infrastructure meets the MSR system requirements.

Step 2. Install MKE¶

MSR requires Mirantis Kubernetes Engine (MKE) to run.

Note

Prior to installing MSR:

When upgrading, upgrade MKE before MSR for each major version. For example, if you are upgrading four major versions, upgrade one major version at a time, first MKE, then MSR, and then repeat for the remaining three versions. - MKE upgraded to the most recent version before an initial install of MSR.
Mirantis Container Runtime should be updated to the most recent version before installing or updating MKE.

MKE and MSR must not be installed on the same node, due to the potential for resource and port conflicts. Instead, install MSR on worker nodes that will be managed by MKE. Note also that MSR cannot be installed on a standalone Mirantis Container Runtime.

Step 3. Install MSR¶

Once MKE is installed, navigate to the MKE web interface as an admin. Expand your profile on the left-side navigation panel, and Select Admin Settings > Mirantis Secure Registry.
After you configure all the options, you should see a Docker CLI command that you can use to install MSR. Before you run the command, take note of the --dtr-external-url parameter:
```
$ docker run -it --rm \
  mirantis/dtr:2.8.13 install \
  --dtr-external-url <msr.example.com> \
  --ucp-node <mke-node-name> \
  --ucp-username admin \
  --ucp-url <mke-url>
```
If you want to point this parameter to a load balancer that uses HTTP for health probes over port 80 or 443, temporarily reconfigure the load balancer to use TCP over a known open port. Once MSR is installed, you can configure the load balancer however you need to.
Run the MSR install command on any node connected to the MKE cluster, and with Mirantis Container Runtime installed. MSR will not be installed on the node you run the install command on. MSR will be installed on the MKE worker defined by the --ucp-node flag.

For example, you could SSH into a MKE node and run the MSR install command from there. Running the installation command in interactive TTY or -it mode means you will be prompted for any required additional information.

Here are some useful options you can set during installation:
- To install a different version of MSR, replace 2.8.13 with your desired version in the installation command above.
- MSR is deployed with self-signed certificates by default, so MKE might not be able to pull images from MSR. Use the --dtr-external-url <msr-domain>:<port> optional flag during installation, or during a reconfiguration, so that MKE is automatically reconfigured to trust MSR.
- Starting with MSR 2.7, you can enable browser authentication via client certificates at install time. This bypasses the MSR login page and hides the logout button, thereby skipping the need for entering your username and password.
Verify that MSR is installed. Either:
- See https://<mke-fqdn>/manage/settings/dtr, or;
- Navigate to Admin Settings > Mirantis Secure Registry from the MKE web UI. Under the hood, MKE modifies /etc/docker/certs.d for each host and adds MSR’s CA certificate. MKE can then pull images from MSR because the Mirantis Container Runtime for each node in the MKE swarm has been configured to trust MSR.
Reconfigure your load balancer back to your desired protocol and port.

Step 4. Check that MSR is running¶

In your browser, navigate to the MKE web interface.
Select Shared Resources > Stacks from the left-side navigation panel. You should see MSR listed as a stack.
To verify that MSR is accessible from the browser, enter your MSR IP address or FQDN on the address bar. Since HSTS (HTTP Strict-Transport-Security) header is included in all API responses, make sure to specify the FQDN (Fully Qualified Domain Name) of your MSR prefixed with https://, or your browser may refuse to load the web interface.

Step 5. Configure MSR¶

After installing MSR, you should configure:

The certificates used for TLS communication
The storage back end to store the Docker images

Web interface¶

To update your TLS certificates, access MSR from the browser and navigate to System > General.
To configure your storage back end, navigate to System > Storage.

Command line interface¶

To reconfigure MSR using the CLI, refer to MSR Operations Guide: CLI reference.

Step 6. Test pushing and pulling¶

Now that you have a working installation of MSR, you should test that you can push and pull images:

Configure your local Mirantis Container Runtime
Create a repository
Push and pull images

Step 7. Join replicas to the cluster¶

This step is optional.

To set up MSR for high availability, you can add more replicas to your MSR cluster. Adding more replicas allows you to load-balance requests across all replicas, and keep MSR working if a replica fails.

For high-availability, you should set 3 or 5 MSR replicas. The replica nodes also need to be managed by the same MKE.

To add replicas to a MSR cluster, use the join command:

Load your MKE user bundle.
Run the join command.
```
docker run -it --rm \
  mirantis/dtr:2.8.13 join \
  --ucp-node <mke-node-name> \
  --ucp-insecure-tls
```
Important

The <mke-node-name> following the --ucp-node flag is the target node to install the MSR replica. This is NOT the MKE Manager URL.

When you join a replica to a MSR cluster, you need to specify the ID of a replica that is already part of the cluster. You can find an existing replica ID by going to the Shared Resources > Stacks page in the MKE web UI.
Check that all replicas are running.
1. In your browser, navigate to the MKE web UI.
2. Select Shared Resources > Stacks. All replicas should be displayed.