Add a custom TLS certificate

By default, Mirantis Secure Registry (MSR) services are exposed using HTTPS. This ensures encrypted communications between clients and your trusted registry. If you do not pass a PEM-encoded TLS certificate during installation, MSR will generate a self-signed certificate, which leads to an insecure site warning when accessing MSR through a browser. In addition, MSR includes an HTTP Strict Transport Security (HSTS) header in all API responses, which can cause your browser not to load the MSR web UI.

You can configure MSR to use your own TLS certificates, to ensure that MSR automatically trusts browsers and client tools. You can also enable user authentication through client certificates that your organization Public Key Infrastructure (PKI) provides.

Kubernetes deployments

To upload your own TLS certificates and keys, you can use the Helm CLI options to either install or reconfigure your MSR instance.

You can customize the WebTLS certificate using either the MSR Operator or the Helm chart:

  1. Obtain your TLS certificate and key files.

    Note

    You can use a previously created CA signed SSL certificate, or create a new one. 1

  2. Add the secret to the cluster:

    kubectl create secret tls <secret-name> \
  --key <keyfile>.pem \
  --cert <certfile>.pem

  3. Update your custom resource manifest:

    spec:
  nginx:
    webtls:
      secretName: '<secret-name>'
      create: false

  4. Apply the changes to the custom resource:

    kubectl apply -f cr-sample-manifest.yaml

  5. Verify completion of the reconciliation process for the custom resource:

    kubectl get msrs.msr.mirantis.com
kubectl get rethinkdbs.rethinkdb.com

  6. Enable port forwarding:

    kubectl port-forward service/msr 8080 8443:443

  7. Go to https://localhost:8443/login and log in as an administrator.

  8. Verify the presence of a valid certificate by matching the information with that of the generated certificate.

  1. Acquire your TLS certificate and key files.

    Note

    You can use a previously created CA signed SSL certificate, or you can create a new one. 1

  2. Add the secret to the cluster:

    kubectl create secret tls <secret-name> \
  --key <keyfile>.pem \
  --cert <certfile>.pem

  3. Install the helm chart with the custom certificate:

    helm install msr msr \
  --repo https://registry.mirantis.com/charts/msr/msr \
  --version 1.0.0 \
  --set-file license=path/to/file/license.lic \
  --set nginx.webtls.secretName="<secret-name>"

  4. Enable port forwarding:

    kubectl port-forward service/msr 8080 8443:443

  5. Log in as an administrator at https://localhost:8443/login.

  6. Verify the presence of a valid certificate by matching the information with that of the generated certificate.

Swarm deployments

Add a custom TLS certificate to an existing Swarm deployment, using the Docker CLI:

  1. Acquire your PEM-encoded x509 certificate.

    Note

    You can use a previously created CA signed SSL certificate, or you can create a new one. 1

  2. Verify that your certificate is split into the following three files:

    cert.pem

    This is the public key and includes everything between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

    key.pem

    This is the private key and includes everything between -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY-----.

    ca.pem

    This is the public certificate of the Certificate Authority and includes everything between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

    Note

    If the certificate is not already split, you can split it yourself by copy-pasting each of the three sections into its own separate file.

  3. Create a Docker secret for each of the three certificate files:

    docker secret create msr-web-cert cert.pem
docker secret create msr-web-key key.pem
docker secret create msr-web-ca ca.pem

  4. Update the NGINX service with the custom certificate:

    docker service update msr_msr-nginx \
  --secret-add msr-web-ca \
  --secret-add msr-web-cert \
  --secret-add msr-web-key \
  --env-rm MSR_WEB_TLS_CERT_FILE \
  --env-rm MSR_WEB_TLS_KEY_FILE \
  --env-rm MSR_WEB_TLS_CA_FILE \
  --env-add MSR_WEB_TLS_CERT_FILE=/var/run/secrets/msr-web-cert \
  --env-add MSR_WEB_TLS_KEY_FILE=/var/run/secrets/msr-web-key \
  --env-add MSR_WEB_TLS_CA_FILE=/var/run/secrets/msr-api-ca
1(1,2,3)

Users who want to create a new self-signed certificate that is valid for the host name can do so using mkcert or openssl.

See also