Governance Partition in a Remote Registry

In this deployment strategy, only the governance partition is shared among instances of a group/cluster. For example, a WSO2 Application Server instance and a WSO2 ESB instance that have been configured to operate in a clustered environment can have a single governance registry which is shared across each node of the cluster. A separate instance of the WSO2 Governance Registry (G-Reg) is used to provide the space used in common.

Figure 3: Governance partition in the remote Governance Registry instance.

Configuration steps are given in the following sections.

Creating the database

In a production setup, it is recommended to use an Oracle or MySQL database for the governance registry. As an example, we use MySQL database named ‘registrydb’. Instructions are as follows:

Access MySQL using the command:
```
mysql -u root -p
```
Enter the password when prompted.
Create 'registrydb' database.
```
create database registrydb;
```

The MySQL database for G-Reg is now created.

Configuring the Governance Registry instance

Database configurations are stored in $PRODUCT_HOME/repository/conf/datasources/master-datasources.xml file for all carbon servers. By default, all WSO2 products use the in-built H2 database. Since Governance Registry in this example is using a MySQL database named 'registrydb', the master-datasources.xml file needs to be configured so that the datasource used for the registry and user manager in Governance Registry is the said MySQL database.

Download and extract WSO2 Governance Registry distribution from http://wso2.com/products/governance-registry.

Navigate to $G-REG_HOME/repository/conf/datasources/master-datasources.xml file where G-REG_HOME is the Governance Registry distribution home. Replace the existing WSO2_CARBON_DB datasource with the following configuration:

<datasource>
   <name>WSO2_CARBON_DB</name>
   <description>The datasource used for registry and user manager</description>
   <jndiConfig>
        <name>jdbc/WSO2CarbonDB</name>
   </jndiConfig>
   <definition type="RDBMS">
       <configuration>
           <url>jdbc:mysql://x.x.x.x:3306/registrydb</url>
           <username>root</username>
           <password>root</password>
           <driverClassName>com.mysql.jdbc.Driver</driverClassName>
           <maxActive>50</maxActive>
           <maxWait>60000</maxWait>
           <testOnBorrow>true</testOnBorrow>
           <validationQuery>SELECT 1</validationQuery>
           <validationInterval>30000</validationInterval>
        </configuration>
   </definition>
</datasource>

Change the values of the following elements according to your environment.

<url>: URL of the MySQL database.
<username> and <password>: The username and password of the mySQL database.
<validationQuery>: Validate and test the health of the DB connection.
<validationInterval>: The specified time intervals at which the DB connection validations should run.

Navigate to $PRODUCT_HOME/repository/conf/axis2/axis2.xml file in all Carbon-based product instances to be connected with the remote registry, and enable clustering with the following configuration.
```
<clustering class="org.wso2.carbon.core.clustering.hazelcast.HazelcastClusteringAgent" enable="false">
```
The above configuration is required only when caching is enabled for the Carbon server instances and <enableCache> parameter is set to true. This provides cache invalidation at the event of any updates on the registry resources.
Copy the 'mySQL JDBC connector jar' (http://dev.mysql.com/downloads/connector/j/5.1.html) to G-REG_HOME/repository/components/lib directory.
Start the Governance Registry server with -Dsetup so that all the required tables are created in the database. For example, in Linux:
```
sh wso2server.sh -Dsetup
```

The Governance Registry server is now running with all required user manager and registry tables for the server also created in ‘registrydb’ database.

Configuring the Carbon server nodes

Now that the shared registry is configured, let's take a look at the configuration of Carbon server nodes that use the shared, remote registry.

Download and extract the relevant WSO2 product distribution from the 'Products' menu of https://wso2.com. In this example, we use two server instances (of any product) by the names CARBON-Node1 and CARBON-Node2 and the configuration is given for one server instance. Similar steps apply to the other server instance as well.
We use the same datasource used for Governance Registry above as the registry space of Carbon-based product instances.

Configure $PRODUCT_HOME/repository/conf/datasource/master-datasources.xml where PRODUCT_HOME is the distribution home of any WSO2 Carbon-based product you downloaded in step 1. Then, add the following datasource for the registry space.

Configuring master-datasource.xml

<datasource>
        <name>WSO2_CARBON_DB_GREG</name>
        <description>The datasource used for registry and user manager</description>
        <jndiConfig>
             <name>jdbc/WSO2CarbonDB_GREG</name>
        </jndiConfig>
        <definition type="RDBMS">
             <configuration>
                   <url>jdbc:mysql://x.x.x.x:3306/registrydb</url>
                   <username>root</username>
                   <password>root</password>
                   <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                   <maxActive>50</maxActive>
                   <maxWait>60000</maxWait>
                   <testOnBorrow>true</testOnBorrow>
                   <validationQuery>SELECT 1</validationQuery>
                   <validationInterval>30000</validationInterval>
              </configuration>
         </definition>
</datasource>

Change the values of the relevant elements accordingly.

Navigate to $PRODUCT_HOME/repository/conf/registry.xm l file and specify the following configurations for both server instances setup in step 1.

Add a new db config to the datasource configuration done in step 3 above. For example:
Configuring registry.xml file
```
<dbConfig name="remote_registry">
      <dataSource>jdbc/WSO2CarbonDB_GREG</dataSource>
</dbConfig>
```
Specify the remote Governance Registry instance with the following configuration:
```
<remoteInstance url="https://x.x.x.x:9443/registry">
    <id>instanceid</id>
    <dbConfig>remote_registry</dbConfig>
    <cacheId>root@jdbc:mysql://x.x.x.x:3306/registrydb</cacheId>
    <readOnly>false</readOnly>
    <enableCache>true</enableCache>
    <registryRoot>/</registryRoot>
</remoteInstance>
```
Change the values of the following elements according to your environment.
- <remoteInstance url>: URL of the remote G-Reg instance.
  
  In terms of Atom and WS this is mandatory, as this URL is used to connect to the remote instance. In the case of JDBC it is not mandatory but it is required for certain features such as Atom Feeds and Subscriptions available for the repository. Subscriptions for other components of the ESB (for example), are not affected by this parameter.
  
  In the case of a remote mount, the content actually resides remotely and can be updated from multiple destinations. It is important that all of these updates are globally available. Due to this, subscriptions and atom feeds are managed/generated from a single location (i.e., the registry to which you mount to). So, if you need to use these features available in G-Reg/ESB, then you need to have G-Reg up and running and also a proper URL in this field.
  
  In most instances, features such as Atom Feeds and Subscriptions available for the Repository are not required. In such cases, it is best to provide a value like "https://localhost:9443/registry" for this parameter - since the schema validation expects the existence of this parameter though it does not actually need to point to a running instance of WSO2 Governance Registry.
- <dbConfig>: The dbConfig name specified for the registry database configuration.
- <cacheId>: This provides information on where the cache resource resides.
- <enableCache>: Whether caching is enabled on the Carbon server instance.
Define the registry partitions using the remote Governance Registry instance. In this deployment strategy, we are mounting the governance partition of the Carbon-based product instances to the remote Governance Registry instance. This is graphically represented in Figure 3 at the beginning of this page.
```
<mount path="/_system/governance" overwrite="true">
    <instanceId>instanceid</instanceId>
    <targetPath>/_system/governance</targetPath>
</mount>
```
- mount path : Registry collection of Carbon server instance that needs to be mounted
- mount overwrite : Defines if an existing collection/resource at the given path should be overwritten or not. Possible vales are:
  - true - The existing collection/resource in the specified location will always be deleted and overwritten with the resource/s in the remote registry instance.
  - false - The resource/s will not be overwritten. An error will be logged if a resource exists at the existing location.
  - virtual - If the existing location has a resource/collection, it will be preserved but virtual view of the remote registry resource/s can be viewed. The original resource/collection can be viewed once the remote registry configuration is removed.
- target path : Path to the remote Governance Registry instance where the registry collection is mounted.
Navigate to $PRODUCT_HOME/repository/conf/axis2/axis2.xml file where PRODUCT_HOME is the distribution home of any WSO2 Carbon-based products to be connected with the remote registry. Enable carbon clustering by copying the following configuration to all Carbon server instances:
Configuring axis2.xml file
```
<clustering class="org.wso2.carbon.core.clustering.hazelcast.HazelcastClusteringAgent" enable="false">
```
The above configuration is needed only when caching is enabled in the server instances and <enableCache> parameter set to true. Clustering enables cache invalidation in configured nodes at the event of any changes to the registry resources by any of the Carbon server nodes in the deployment setup.
Copy 'MySQL JDBC connector jar' (http://dev.mysql.com/downloads/connector/j/5.1.html) to $PRODUCT_HOME/repository/components/lib in both Carbon server instances.
Start both servers and note the log entries that indicate successful mounting to the remote Governance Registry instance. Also navigate to the registry browser in the Carbon server's management console and note the governance partition indicating successful mounting to the remote registry instance.

For large deployments it is recommended to have separate databases for config registry per product. Follow the configurations as below for such deployments.

Create a new datasource in master-datasources.xml.

<datasource>
        <name>WSO2_CARBON_AS_CONFIG</name>
        <description>The datasource used for registry and user manager</description>
        <jndiConfig>
             <name>jdbc/as_config</name>
        </jndiConfig>
        <definition type="RDBMS">
             <configuration>
                   <url>jdbc:mysql://x.x.x.x:3306/registrydb</url>
                   <username>root</username>
                   <password>root</password>
                   <driverClassName>com.mysql.jdbc.Driver</driverClassName>
                   <maxActive>50</maxActive>
                   <maxWait>60000</maxWait>
                   <testOnBorrow>true</testOnBorrow>
                   <validationQuery>SELECT 1</validationQuery>
                   <validationInterval>30000</validationInterval>
              </configuration>
         </definition>
</datasource>

Navigate to $PRODUCT_HOME/repository/conf/registry.xm l file and specify the following configurations.

<!-- config db -->
<dbConfig name="config">
<dataSource>jdbc/as_config</dataSource>
</dbConfig>

<remoteInstance url="https://localhost:9443/registry">
<id>config</id>
<dbConfig>config</dbConfig>
<readOnly>false</readOnly>
<registryRoot>/</registryRoot>
<enableCache>true</enableCache>
<cacheId>root@jdbc:mysql://10.45.67.89:3306/as_config</cacheId>
</remoteInstance>