Introduction to WSO2 Registry Mounting

This post is based on the common questions raised about registry mounting and how it works etc. Below are the main questions people ask:

1). How mounting works?
2). What is the difference between Config Registry and Governance Registry?
3). Can I use databases other than H2 for Local Registry?
4). What is meant by mount path and target path?
5). Do I need to configure “remoteInstance” URL?
6). What should I use as the cacheId?

So let's start with how to configure a registry mount. When you are configuring the registry mount, you have to add the relevant data source to the master-datasources.xml file. In addition to that, you have to add mounting related configuration into the registry.xml file as well.

In the master-datasources.xml file you have to just configure a JDBC data source by providing JDBC URL, username, password, validation queries, connection optimization parameters, etc. An example data source entry will look like below. Note: You need to add below configuration in addition to the existing 'WSO2CarbonDB' data source. 

            <description>The datasource used for registry- config/governance</description>
            <definition type="RDBMS">
                    <validationQuery>SELECT 1</validationQuery>
In the registry.xml file, there are many vexed areas available. So let’s see an example mounting configuration first.

<dbConfig name="mounted_registry">

<remoteInstance url="https://localhost:9443/registry">

<mount path="/_system/config" overwrite="true">
<mount path="/_system/governance" overwrite="true">

You can see that when defining a mounting configuration, I have added four sections of configurations. They are ‘dbConfig’, ‘remoteInstance’ and two sections of the ‘mount’ entry.

I think it's easy to explain from the mount entry first, then remoteInstance and dbConfig. In the mount entry, you can configure path, overwrite, targetPath, and instanceId.


path - Path is a location in the registry which is similar to a file system path. Resources stored inside this path will be store in relevant configured DB.
overwrite- (Virtual, True, False)Whether an existing collection/resource at the given path would be overwritten or not. Virtual means changes are only stored in the memory and will not be written into the DB.
instanceId - Reference to the ‘remoteInstance’.
targetPath - The path which is stored in the database.

In nutshell, any registry paths which are starting with the value in the path section will be stored in the DB against targetPath(path will be replaced with targetPath and stored in the DB). When retrieving registry path it will do the reverse replacement as well.  So this target path will not be visible to you at all. If you are too curious to know about that, you can verify it by querying REG_PATH table.


'remoteInstance' is the mapping between 'dbConfig' and Mounts. This mapping is handled via 'id' and 'dbConfig' elements. The 'id' value referred in the each mounting configurations and value of dbConfig element should be same as dbConfig name. In addition to that 'cacheId' is one of the most important configurations in this section.

url - Registry URL of the local registry instance. This is only used in the WSO2 Governance Registry product. So you can use any value for the other products.
readOnly - Whether the instance is read-only.
registryRoot - The root of the registry instance.
enableCache - Whether caching is enabled or not.
cacheId - This is an unique identification of the remote instance used in distributed caching layer.  Here we are recommending to use the cache id as registry DBUsername@DBUrl.


This dbConfig is a reference to the data source added in the master-datasources.xml file. Note that you should not remove or modify default dbConfig available in the registry.xml file. Instead of that, you need to add a new dbConfig element. Further, as the name of the newly adding dbConfig, you should use a name other than 'wso2registry', since it has been used as the default dbConfig name.

So, let me answer to other questions. Any WSO2 product(released before 2018) internally consist three registry spaces. they are local, config and governance.

Local Registry(repository) is used to store instance specific information such as last index time', etc.
Config Registry(repository) is the place to store information that can only be shared with same products and if multinode product cluster, this section will be shared.
Governance Registry(repository) is the place to store configurations and data that are shared across the whole WSO2 platform.

We are recommending to store config and governance sections in an external database system. Since the Local Registry(repository) section is instance specific, we are recommending to store it with default H2 database. Information which are stored in the local registry are fail-safe and can be recovered. Please note that if you are willing to store Local section in an external RDBMS, you have to create a separate database(schema) for each instance.

So let’s  move on to validating my mounting configuration. In your 'remoteInstance' configuration you have to correctly refer the dbConfig name. This DB config name should not be the same one which we used for Local Registry. In addition that, you have to properly map each 'mount' section to the 'remoteInstance' using the instanceId.

If you have any questions which are related to registry mounting, you can comment here. I am happy to help you.


Popular posts from this blog

XSLT - Modify Date and DateTime value

Integrate With Mutual Certificate Authentication based Service

Yield Price Sri Lanka - Android Application