Using a Local Registry with Runtime Fabric

Runtime Fabric uses its own registry to store the necessary Docker images for installing and managing Runtime Fabric and for running applications in Kubernetes. If your security policies require that you pull your Docker images from a registry under your control, you can set up a local registry to pull and store these Docker images.

Limitations on Local Registry Support

You can configure local registry across all Runtime Fabric supported platform vendors to store Mule Docker images (for use when managing application deployments) and Runtime Fabric software images (for use when updating or installing Runtime Fabric software). The following details and limitations apply to both Mule Docker images and Runtime Fabric software images.

You cannot use local registry for installation or management of Runtime Fabric operator on OpenShift.

You can use Runtime Fabric command line utility (rtfctl) version 0.3.150 or later. rtfctl installs Runtime Fabric agent to the latest version by default.
You can use Helm to install Runtime Fabric and configure your local registry.
You can use a local registry only if you create a new Runtime Fabric instance of version 1.12.0 or later.

If you set up a local registry, you can upgrade to a version later than 1.12.0 without reinstalling Runtime Fabric.

To add local registry to an existing Runtime Fabric instance, ensure that the installation is Helm-based Migrating to Helm Managed Runtime Fabric and perform the steps on the following section to add local registry.
If you create a Runtime Fabric instance to use with a local registry, you cannot later reconfigure it to use the rtf-runtime-registry endpoint. To use the rtf-runtime-registry endpoint, you must install a new Runtime Fabric instance using the standard installation procedure.
You are responsible for synchronizing your local registry with required dependencies:
- Synchronize Runtime Fabric core software images or dependencies automatically
- Synchronize Mule runtime images or dependencies manually
- Synchronize third party dependencies required by your application.
  MuleSoft doesn’t provide additional software to synchronize third party dependencies and images. Push all the dependency images for your Mule app to your local registry before you start the deployments.
If you use a local registry that needs authentication, synchronization and propagation of a pull secret between different namespaces is your responsibility. Alternatively, Runtime Fabric can synchronize your pull secret across different namespaces if your secret uses the following label:

  labels:
    rtf.mulesoft.com/synchronized: "true"

If you need to authenticate access to your local registry, ensure that the corresponding credentials are configured as a Kubernetes secret in the rtf namespace. You’ll need the name of the configured secret when you install Runtime Fabric.

Synchronize Mule Runtime Dependencies and Images to Your Local Registry

To synchronize in your registry the Mule runtime versions you intend to use for application deployments, refer to the Mule runtime patch updates for Runtime Fabric Release Notes. The location of the image follows this format: rtf-runtime-registry.kprod.msap.io/mulesoft/.

Synchronize Runtime Fabric Core Software Dependencies and Images to Your Local Registry

To install Runtime Fabric, you must first synchronize the dependencies images to your local registry. You can perform the synchronization by either running a script automatically or executing commands manually.

Synchronize Automatically
Synchronize Manually

To synchronize the dependencies images automatically, run a bash script that uses the docker, curl, and jq tools.

Automated registry synchronization is available from Runtime Fabric version 2.6.0 onwards. Previous dependencies cannot be retrieved using this script.

Ensure that your Access Management permission for Runtime Manager is set to Read Runtime Fabric, which enables you to query Runtime Fabrics in your organization.

In your Unix shell, run the following script, replacing agent-version, authorization-token, mulesoft-docker-server, and any other parameter value where appropriate:

For non-OpenShift environments:

##!/usr/bin/env bash
dependencies=$(curl <platform-url>/runtimefabric/api/agentmanifests/<agent-version>         -H 'Authorization: bearer <authorization-token>' | jq -c '.dependencies |.[] | select(.provider | contains("generic")) | "\(.artifact):\(.version)"' | sed 's/"//g')
for i in $dependencies
do
    echo "Processing $i"
    docker pull <mulesoft-docker-server>/mulesoft/$i
    docker tag  <mulesoft-docker-server>/mulesoft/$i <local-docker-server>/mulesoft/$i
    docker push <local-docker-server>/mulesoft/$i
done

For OpenShift environments:

##!/usr/bin/env bash
dependencies=$(curl <platform-url>/runtimefabric/api/agentmanifests/<agent-version>         -H 'Authorization: bearer <authorization-token>' | jq -c '.dependencies |.[] | select(.provider | contains("openshift")) | "\(.artifact):\(.version)"' | sed 's/"//g')
for i in $dependencies
do
    echo "Processing $i"
    docker pull <mulesoft-docker-server>/mulesoft/$i
    docker tag  <mulesoft-docker-server>/mulesoft/$i <local-docker-server>/mulesoft/$i
    docker push <local-docker-server>/mulesoft/$i
done

Table 1. Script Parameters
Parameters	Description
`platform-url`	Anypoint Platform URL, such as https://anypoint.mulesoft.com, or https://eu1.anypoint.mulesoft.com.
`agent-version`	Runtime Fabric agent release version required for the synchronization.
`authorization-token`	Authorization token required for using connected apps to perform the synchronization. When you use this token, a link redirects to the connected apps page.
`mulesoft-docker-server`	MuleSoft Docker server required for the synchronization. For the US control plane: `rtf-runtime-registry.kprod.msap.io` For the EU control plane: `rtf-runtime-registry.kprod-eu.msap.io`

To synchronize the dependencies images manually, follow these steps:

For the US control plane:

# docker pull rtf-runtime-registry.kprod.msap.io/mulesoft/rtf-agent:v1.12.0
# docker tag rtf-runtime-registry.kprod.msap.io/mulesoft/rtf-agent:v1.12.0 <docker-server>/mulesoft/rtf-agent:v1.12.0
# docker push <docker-server>/mulesoft/rtf-agent:v1.12.0

For the EU control plane:

# docker pull rtf-runtime-registry.kprod-eu.msap.io/mulesoft/rtf-agent:v1.12.0
# docker tag rtf-runtime-registry.kprod-eu.msap.io/mulesoft/rtf-agent:v1.12.0 <docker-server>/mulesoft/rtf-agent:v1.12.0
# docker push <docker-server>:5000/mulesoft/rtf-agent:v1.12.0

Configure Your Local Registry for Runtime Fabric

To configure a local registry, you must gather and add the necessary credentials to synchronize the registries.

Before You Begin

Ensure that you’ve performed the following tasks:

Set up, configure, and test your private Docker image registry.
Synchronize to your local registry all of the Docker images that you need to install Runtime Fabric:

See the Runtime Fabric release notes for the required dependencies for your Runtime Fabric version.

Dependency versions are specific to the Runtime Fabric version.

To install Runtime Fabric with your local registry using rtfctl or helm, select one of the following options:

RTFCTL
Helm

Download and install the rtfctl command line utility version 0.3.150 or higher.
Obtain rtf-runtime-registry credentials:
```
# rtfctl get registry-credentials <activation-data>
```
This command sets RTF_IMAGE_REGISTRY_ENDPOINT, RTF_IMAGE_REGISTRY_USER, and RTF_IMAGE_REGISTRY_PASSWORD in the current shell environment.

Run the following commands to verify that the Docker login to the rtf-runtime-registry succeeds:

# eval $(rtfctl get registry-credentials <activation-data>)
# docker login $RTF_IMAGE_REGISTRY_ENDPOINT --username $RTF_IMAGE_REGISTRY_USER --password $RTF_IMAGE_REGISTRY_PASSWORD

You should see a message that the login was successful.

Synchronize your container images to your local registry.
Repeat step 3 for all the other dependency images (resourceFetcher, clusterOps etc.) based on the versions published in the Runtime Fabric release notes.

If you use authentication to access your registry, create the required secret in the rtf namespace:

# kubectl create namespace rtf
# kubectl create secret docker-registry regcred --namespace=rtf --docker-server=<docker_server> --docker-username=<docker_username> --docker-email=<docker_email> --docker-password=<docker_password>
# kubectl label secret regcred rtf.mulesoft.com/synchronized=true -n rtf

Finalize the Runtime Fabric installation, and configure it to pull from your local registry:
```
# rtfctl install ‘<activation_data>’ --image-pull-registry <docker-server>
```
Alternatively, if you use authentication to access your registry, use the following command:
```
# rtfctl install ‘<activation_data>’ --image-pull-registry <docker-server> --image-pull-secret <your-local-reg-secret>
```
This command ensures that Runtime Fabric creates the necessary overrides for the local registry URL and image-pull-secret values so Runtime Fabric continues to pull images from the local registry even after an upgrade.
If you use authentication to access your registry, after you complete the installation, you must recreate the pull secret in the RTF namespace and in any other namespaces where you will deploy applications.
Refer to the installation instructions for further steps, such as inserting the Mule license key.

The rtfctl uninstall command deletes any pull secret you specify during installation.

When using rtfctl to perform a backup and restore procedure, the backups point to your local registry URL and pull secret.

Synchronize your container images to your local registry.
Create a Runtime Fabric using Runtime Manager.
In Runtime Manager, select the Helm path, and follow the instructions on the screen platform.
Obtain your private docker-server, docker-username, and docker-password.

Follow the Helm path instructions in Runtime Manager to create a secret with your docker server name, username, and password by running the following command in your Unix shell:

kubectl create secret docker-registry rtf-pull-secret --namespace <rtf-namespace> --docker-server=<docker-servername> --docker-username=<docker-username --docker-password=<docker-password> --docker-email=<docker-email>

Follow the Helm path instructions to download the values.yml file so that you can modify its values. For the private registry configuration, update rtfRegistry with your local docker server, and update the pullSecretName parameter. .
Continue with the Helm path instructions and install Runtime Fabric in your Kubernetes cluster.