--- schema_version: "1" id: 19f941ca3533770e693f294948e8cc4ea172ec2175b3071b9c664e022ec7db2a title: Configure a Local Registry for Runtime Fabric collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/runtime-fabric/latest/configure-local-registry.md canonical_url: https://docs.mulesoft.com/runtime-fabric/latest/configure-local-registry source_site: docs.mulesoft.com content_type: documentation content_hash: dc4288601fc2b65859a3edec459520faab1213a79c6a3cb030dcae029fd9927e description: MuleSoft Documentation Site release: "3.0" latest: true --- --- product: Runtime Fabric version: 3.0 is-latest-version: true --- # Configure a Local Registry for Runtime Fabric > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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. > [!IMPORTANT] 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`)](https://docs.mulesoft.com/runtime-fabric/latest/install-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](https://docs.mulesoft.com/runtime-fabric/latest/migrate-helm)) and follow the steps in this page. > [!IMPORTANT] 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](#synch-rtf) — synchronize automatically or manually before installation and upgrades. - [Synchronize Mule Runtime Images](#synch-runtime) — 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](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials). 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. > [!NOTE] 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](https://docs.mulesoft.com/access-management/permissions-by-product#runtime-manager) is set to **Read Runtime Fabric**, which enables you to query Runtime Fabrics in your organization. 1. 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: ```copy ##!/usr/bin/env bash dependencies=$(curl /runtimefabric/api/agentmanifests/ -H 'Authorization: bearer ' | jq -c '.dependencies |.[] | select(.provider | contains("generic")) | "\(.artifact):\(.version)"' | sed 's/"//g') for i in $dependencies do echo "Processing $i" docker pull //$i docker tag //$i /mulesoft/$i docker push /mulesoft/$i done ``` For OpenShift environments: ```copy ##!/usr/bin/env bash dependencies=$(curl /runtimefabric/api/agentmanifests/ -H 'Authorization: bearer ' | jq -c '.dependencies |.[] | select(.provider | contains("openshift")) | "\(.artifact):\(.version)"' | sed 's/"//g') for i in $dependencies do echo "Processing $i" docker pull //$i docker tag //$i /mulesoft/$i docker push /mulesoft/$i done ```
Table 1. Script Parameters
ParametersDescription

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

  • Australia Cloud: rtf-runtime-registry-mulesoft-cp.sfdc-vwfla6.svc.sfdcfc.net

  • United Kingdom Cloud: rtf-runtime-registry-mulesoft-cp.sfdc-5pakla.svc.sfdcfc.net

image-path

Image namespace path on the registry.

  • US Cloud and EU Cloud: mulesoft

  • Canada Cloud, Japan Cloud, India Cloud, Australia Cloud, and United Kingdom Cloud: sfci/mulesoft/ms-docker-image

> [!NOTE] For Canada Cloud, Japan Cloud, India Cloud, Australia Cloud, and United Kingdom 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: > [!NOTE] Repeat the pull/tag/push pattern shown below for each dependency image listed in the > [Runtime Fabric release notes](https://docs.mulesoft.com/release-notes/runtime-fabric/runtime-fabric-release-notes-2.x.x) > for your version, not just `rtf-agent`. 1. Log in to your private container registry and run this command, replacing `docker-server` where appropriate: For the US Cloud: ```copy # 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 /mulesoft/rtf-agent:v1.12.0 # docker push /mulesoft/rtf-agent:v1.12.0 ``` For the EU Cloud: ```copy # 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 /mulesoft/rtf-agent:v1.12.0 # docker push /mulesoft/rtf-agent:v1.12.0 ``` For the Canada Cloud: ```copy # 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 /mulesoft/rtf-agent:v1.12.0 # docker push /mulesoft/rtf-agent:v1.12.0 ``` For the Japan Cloud: ```copy # 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 /mulesoft/rtf-agent:v1.12.0 # docker push /mulesoft/rtf-agent:v1.12.0 ``` For the India Cloud: ```copy # 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 /mulesoft/rtf-agent:v1.12.0 # docker push /mulesoft/rtf-agent:v1.12.0 ``` For the Australia Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-vwfla6.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0 # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-vwfla6.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0 /mulesoft/rtf-agent:v1.12.0 # docker push /mulesoft/rtf-agent:v1.12.0 ``` For the United Kingdom Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-5pakla.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0 # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-5pakla.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-rtf-agent:v1.12.0 /mulesoft/rtf-agent:v1.12.0 # docker push /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](https://docs.mulesoft.com/release-notes/runtime-fabric/runtime-fabric-runtimes-release-notes) for the image names and tags. The source registry depends on your control plane:
Control PlaneImage 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/v2/sfci/mulesoft/ms-docker-image/<image>:<tag>

Japan Cloud

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

India Cloud

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

Australia Cloud

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

United Kingdom Cloud

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

> [!NOTE] For Canada Cloud, Japan Cloud, India Cloud, Australia Cloud, and United Kingdom Cloud > deployments on OpenShift, download these images from the SFCI registry: > > - Mule runtime: `/sfci/mulesoft/ms-docker-image/ms-poseidon-runtime-:` > > - Anypoint Monitoring sidecar: > `/sfci/mulesoft/ms-docker-image/ms-dias-anypoint-monitoring-sidecar-ubi:` 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 `` and `` with the values from the [Mule runtime release notes](https://docs.mulesoft.com/release-notes/runtime-fabric/runtime-fabric-runtimes-release-notes) and `` 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: ```copy # docker pull rtf-runtime-registry.kprod.msap.io/mulesoft/: # docker tag rtf-runtime-registry.kprod.msap.io/mulesoft/: /mulesoft/: # docker push /mulesoft/: ``` For the EU Cloud: ```copy # docker pull rtf-runtime-registry.kprod-eu.msap.io/mulesoft/: # docker tag rtf-runtime-registry.kprod-eu.msap.io/mulesoft/: /mulesoft/: # docker push /mulesoft/: ``` For the Canada Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-58ktaz.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: /mulesoft/: # docker push /mulesoft/: ``` For the Japan Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-mchho0.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: /mulesoft/: # docker push /mulesoft/: ``` For the India Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-y37hzm.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: /mulesoft/: # docker push /mulesoft/: ``` For the Australia Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-vwfla6.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-vwfla6.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: /mulesoft/: # docker push /mulesoft/: ``` For the United Kingdom Cloud: ```copy # docker pull rtf-runtime-registry-mulesoft-cp.sfdc-5pakla.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: # docker tag rtf-runtime-registry-mulesoft-cp.sfdc-5pakla.svc.sfdcfc.net/sfci/mulesoft/ms-docker-image/ms-: /mulesoft/: # docker push /mulesoft/: ``` > [!NOTE] For Canada Cloud, Japan Cloud, India Cloud, Australia Cloud, and United Kingdom Cloud, the > source image in the SFCI registry uses an `ms-` prefix in the artifact name (for example, > `ms-`). 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: 1. Set up, configure, and test your private Docker image registry. 2. [Synchronize](#synchronize-images-to-your-local-registry) all required Docker images to your local registry. See the [Runtime Fabric release notes](https://docs.mulesoft.com/release-notes/runtime-fabric/runtime-fabric-release-notes-2.x.x) 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 1. [Download and install the `rtfctl` command line utility](https://docs.mulesoft.com/runtime-fabric/latest/install-self-managed#step-3-download-the-rtfctl-utility) version 0.3.150 or higher. 2. Obtain `rtf-runtime-registry` credentials: ```copy # rtfctl get registry-credentials ``` This command sets `RTF_IMAGE_REGISTRY_ENDPOINT`, `RTF_IMAGE_REGISTRY_USER`, and `RTF_IMAGE_REGISTRY_PASSWORD` in the current shell environment. 3. Run these commands to verify that the Docker login to the `rtf-runtime-registry` succeeds: ```copy # eval $(rtfctl get registry-credentials ) # 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. 4. [Synchronize your container images](#synch-rtf) to your local registry. 5. Repeat step 4 for all other dependency images (such as `resourceFetcher` and `clusterOps`) based on the versions published in the Runtime Fabric release notes. 6. If you use authentication to access your registry, create the required secret in the rtf namespace: ```copy # kubectl create namespace rtf # kubectl create secret docker-registry regcred --namespace=rtf --docker-server= --docker-username= --docker-email= --docker-password= # kubectl label secret regcred rtf.mulesoft.com/synchronized=true -n rtf ``` 7. Finalize the Runtime Fabric installation, and configure it to pull from your local registry: ```copy # rtfctl install ‘’ --image-pull-registry ``` Alternatively, if you use authentication to access your registry, use this command: ```copy # rtfctl install ‘’ --image-pull-registry --image-pull-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. 8. 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. 9. Refer to the [installation instructions](https://docs.mulesoft.com/runtime-fabric/latest/install-self-managed) 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. 1. [Synchronize your container images](#synch-rtf) to your local registry. 2. [Create a Runtime Fabric using Runtime Manager](https://docs.mulesoft.com/runtime-fabric/latest/install-helm#create-a-runtime-fabric-using-runtime-manager). 3. In Runtime Manager, select the **Helm** path, and follow the on-screen instructions. 4. Obtain your private `docker-server`, `docker-username`, and `docker-password`. 5. 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: ```copy kubectl create secret docker-registry rtf-pull-secret --namespace --docker-server= --docker-username= --docker-email= ``` 6. 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. 7. Continue with the **Helm** path instructions and install Runtime Fabric in your Kubernetes cluster. 8. [Synchronize your container images](#synch-rtf) to your local registry. 9. [Create a Runtime Fabric using Runtime Manager](https://docs.mulesoft.com/runtime-fabric/latest/install-helm#create-a-runtime-fabric-using-runtime-manager). 10. In Runtime Manager, follow the on-screen instructions. 11. Obtain your private `docker-server`, `docker-username`, and `docker-password`. 12. 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: ```copy oc create secret docker-registry rtf-pull-secret --namespace --docker-server= --docker-username= --docker-email= ``` 13. In the OpenShift form view, set the rtfRegistry values to configure the local registry. ![OpenShift form view to add values for rtfRegistry](/mulesoft/current/en-us/runtime-fabric/latest/_images/ocp-local-registry.png) 14. Continue with the OpenShift installation. ## See Also - [Configure values.yml Reference](https://docs.mulesoft.com/runtime-fabric/latest/install-helm#values-yml-reference)