Configure a Local Registry for Runtime Fabric

By default, Runtime Fabric pulls the Docker images it needs for installation, management, and application deployments from the MuleSoft-managed registry. If your security policies require that all images come from a registry you control, you can configure Runtime Fabric to use a local registry instead.

Requirements and Considerations

You can configure a local registry across all Runtime Fabric supported platform vendors to store Mule Docker images and Runtime Fabric software images.

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

Supported Configurations

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. Once configured, you can upgrade to later versions without reinstalling Runtime Fabric.

To add a local registry to an existing Runtime Fabric instance, ensure the installation is Helm-based (see Migrating to Helm Managed Runtime Fabric) and follow the steps in this page.

Local registry configuration is a one-way change. After you configure Runtime Fabric to use a local registry, you cannot reconfigure it to use the rtf-runtime-registry endpoint. To revert, you must install a new Runtime Fabric instance using the standard installation procedure.

Synchronization and Authentication

You must keep your local registry synchronized with the images Runtime Fabric requires:

Synchronize Runtime Fabric Core Software Images — synchronize automatically or manually before installation and upgrades.
Synchronize Mule Runtime Images — synchronize manually for each runtime version you deploy.
Third-party dependencies required by your applications — MuleSoft does not provide tooling for this. Push all required images to your local registry before starting deployments.

If your local registry requires authentication, pull secret propagation across namespaces is your responsibility. Alternatively, Runtime Fabric can synchronize your pull secret automatically if you apply this label to the secret:

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

Ensure that the corresponding credentials are configured as a Kubernetes secret in the rtf namespace. You need the name of this secret when you install Runtime Fabric.

Synchronize Images to Your Local Registry

Before you can install or configure Runtime Fabric with a local registry, you must synchronize the required images. These sections cover Runtime Fabric core software images and Mule runtime images separately, as they use different sources and synchronization methods.

Synchronize Runtime Fabric Core Software Images

To install Runtime Fabric, you must first synchronize the core software 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 this 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>/<image-path>/$i
    docker tag  <mulesoft-docker-server>/<image-path>/$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>/<image-path>/$i
    docker tag  <mulesoft-docker-server>/<image-path>/$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. US Cloud: `rtf-runtime-registry.kprod.msap.io` EU Cloud: `rtf-runtime-registry.kprod-eu.msap.io` Canada Cloud: `rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net` Japan Cloud: `rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net` India Cloud: `rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net`
`image-path`	Image namespace path on the registry. US Cloud and EU Cloud: `mulesoft` Canada Cloud, Japan Cloud, and India Cloud: `sfci/mulesoft/ms-docker-image`

For Canada Cloud, Japan Cloud, and India Cloud, images in the SFCI registry use an ms- prefix in the artifact name (for example, ms-rtf-agent instead of rtf-agent). The automated script does not account for this prefix difference, so you must manually prepend ms- to each artifact name when pulling from the SFCI registry for these regions.

To synchronize the dependencies images manually, follow these steps:

Repeat the pull/tag/push pattern shown below for each dependency image listed in the Runtime Fabric release notes for your version, not just rtf-agent.

For the US Cloud:

# 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 Cloud:

# 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>/mulesoft/rtf-agent:v1.12.0

For the Canada Cloud:

# docker pull rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0
# docker tag rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-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 Japan Cloud:

# docker pull rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0
# docker tag rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-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 India Cloud:

# docker pull rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0
# docker tag rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0 <docker-server>/mulesoft/rtf-agent:v1.12.0
# docker push <docker-server>/mulesoft/rtf-agent:v1.12.0

Synchronize Mule Runtime Images

To synchronize the Mule runtime versions you plan to use for application deployments, refer to the Mule runtime patch updates for Runtime Fabric Release Notes for the image names and tags. The source registry depends on your control plane:

Control Plane Image Location Format

Control Plane	Image Location Format
US Cloud	`rtf-runtime-registry.kprod.msap.io/mulesoft/<image>:<tag>`
EU Cloud	`rtf-runtime-registry.kprod-eu.msap.io/mulesoft/<image>:<tag>`
Canada Cloud	`rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/<image>:<tag>`
Japan Cloud	`rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/<image>:<tag>`
India Cloud	`rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/<image>:<tag>`

US Cloud

rtf-runtime-registry.kprod.msap.io/mulesoft/<image>:<tag>

EU Cloud

rtf-runtime-registry.kprod-eu.msap.io/mulesoft/<image>:<tag>

Canada Cloud

rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/<image>:<tag>

Japan Cloud

rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/<image>:<tag>

India Cloud

rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/<image>:<tag>

For Canada Cloud, Japan Cloud, and India Cloud deployments on OpenShift, download these images from the SFCI registry:

Mule runtime: /sfci/mulesoft/ms-docker-image/ms-poseidon-runtime-<version>:<tag>
Anypoint Monitoring sidecar: /sfci/mulesoft/ms-docker-image/ms-dias-anypoint-monitoring-sidecar-ubi:<version>

There is no automated tooling for Mule runtime images. For each runtime version you deploy, manually pull the image from the MuleSoft source registry, retag it for your local registry, and push it, using the same docker pull/docker tag/docker push pattern shown for the core software images.

Log in to both the MuleSoft source registry and your private container registry, then run these commands for your control plane, replacing <image> and <tag> with the values from the Mule runtime release notes and <docker-server> with your local registry server. These examples synchronize a single Mule runtime image; repeat the pattern for each runtime version you deploy.

For the US Cloud:

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

For the EU Cloud:

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

For the Canada Cloud:

# docker pull rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-<image>:<tag>
# docker tag rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-<image>:<tag> <docker-server>/mulesoft/<image>:<tag>
# docker push <docker-server>/mulesoft/<image>:<tag>

For the Japan Cloud:

# docker pull rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-<image>:<tag>
# docker tag rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-<image>:<tag> <docker-server>/mulesoft/<image>:<tag>
# docker push <docker-server>/mulesoft/<image>:<tag>

For the India Cloud:

# docker pull rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-<image>:<tag>
# docker tag rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-<image>:<tag> <docker-server>/mulesoft/<image>:<tag>
# docker push <docker-server>/mulesoft/<image>:<tag>

For Canada Cloud, Japan Cloud, and India Cloud, the source image in the SFCI registry uses an ms- prefix in the artifact name (for example, ms-<image>). When you retag the image for your local registry, drop the ms- prefix so that Runtime Fabric can pull it using the expected name.

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 completed these steps before proceeding:

Set up, configure, and test your private Docker image registry.
Synchronize all required Docker images to your local registry. See the Runtime Fabric release notes for the dependency versions specific to your Runtime Fabric version.

To install Runtime Fabric with your local registry, select your installation method:

RTFCTL
Helm
OpenShift

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 these 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 4 for all other dependency images (such as resourceFetcher and clusterOps) 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 this 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 on-screen instructions.
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 this 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.

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

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

oc 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>

In the OpenShift form view, set the rtfRegistry values to configure the local registry.

Continue with the OpenShift installation.