Introducing WSO2 Cloud Gateway

  • By Rajika Kumarasiri
  • 24 Sep, 2012

Applies To

WSO2 Cloud Gateway 1.0.0
WSO2 ESB 4.5.0
WSO2 Application Server 5.0.0


$CG_HOME The location where WSO2 Cloud Gateway is extracted
$ESB_HOME The location where WSO2 ESB is extracted
$AS_HOME The location where WSO2 Application Server is extracted

Table of Content


WSO2 Cloud Gateway (CG) enables organizations to share their internal services beyond their private networks
and out to the public Web, securely and in a controlled manner. Mostly, it is similar to a SSH tunnel from
internal machines to outside locations, but implemented at the SOA interactions level.

The Problem

The following diagram describes the problem that WSO2 Cloud Gateway tries to solve. Imagine a service that is available in the cooperate
IT infrastructure. For example, employee details service which returns the information about an employee given the
registration number. The HR manager can access the service when he/she is in the office. What if he/she wants to
access the service out side of the office? As most of the co-operate firewalls don't allow random connection from
out side of the firewall into the organization he/she will not be able to access the service from out side. WSO2 Cloud
Gateway can help in this situation. WSO2 Cloud Gateway allows users to access private services publicly in a controllable and
secure manner.

Figure1: The problem that WSO2 Cloud Gateway tries to solve

The Solution

The solution is to implement a high performance reverse transport. This is described in Figure 2. WSO2 Cloud Gateway
consists of two components. First the WSO2 Cloud Gateway server component itself. Second it also has the Agent component
known as Cloud Agent component which needs to be installed in the server which host the private service (for example
WSO2 Application Server). There
will be a polling transport which creates a connection from the Agent side to the server side. Since Agent polls
the server for any requests messages there will not be any inbound connection out side of the firewall to the
inside of the firewall.

Figure2: The reverse transport implementation

Cloud Gateway deployment

As described WSO2 Cloud Gateway consists of two components. WSO2 Cloud Gateway will be deployed out side of the firewall while
WSO2 Cloud Gateway Agent component will be deployed within the firewall where the private services are hosted. This deployment
is described in the following diagram. The out bound connection port for the Apache Thrift server that runs in the
Cloud Gateway server (by default 15001) has to open at the firewall.

Figure3: WSO2 Cloud Gateway deployment

Another more suitable deployment pattern is to use WSO2 ESB to have a proxy for each of these private services
and publish those proxies into the public Cloud Gateway. This way it will help the system administrators to monitor and lookup
in a central location for management and monitoring purposes.

Apache Thrift based implementation

The following diagram describes some of the underline implementation of WSO2 Cloud Gateway. It uses the Apache Thrift based
implementation for the polling transport.

Figure4: WSO2 Cloud Gateway implementation

Following are a few points about the above architecture.

  • Cloud Gateway consists of two parts. Cloud Gateway Server which is out side of the cooperate firewall. Cloud Gateway Agent, which is
    normally installed into one of the service hosting products, that lies within the cooperate firewall.
  • Cloud Gateway Server consists of
    and an
    in-VM thrift server
    . The in memory server starts
    as part of the Cloud Gateway server boot up. CGTransportSender is responsible for doing an in memory copy of the
    incoming message into the thrift server without even
    touching the body

    of the message
  • There will be an instance of
    (in the
    an instance of

    was used)
    for each published service in the in VM thrift server. CGTransportSender will place the message into this queue.
  • Cloud Gateway Agent consists of
    which polls the in VM thrift server queues at the Cloud Gateway server
    in a busy loop for any request messages. The polling transport at the other side will pick the message
    from the queue in #3 and will invoke the business logic and will send the respond back to another instance
    of BlockingQueue at the Cloud Gateway server.
  • Cloud Gateway Agent's polling mechanism is based on Apache Thrift. A generic client/server was generated which
    transfer binary data between server (in VM thrift server) and client (Cloud Gateway Agent).

Performance figures

With the asynchronous architecture described above, WSO2 Cloud Gateway and it's Agent is capable of providing more than
93% transactions per second compare to the direct invocation of the same service. Some performance figures
are given in the Figure 5.

Figure 5: WSO2 Cloud Gateway performance

How to use the Cloud Gateway?

This section describes how to try out WSO2 Cloud Gateway.

Start WSO2 Cloud Gateway server

Download WSO2 Cloud Gateway 1.0.0 from the distribution and unzip and start the server using the
script in the bin folder. At server start up you will see the following log entry on the
console which indicates the under line in VM Thrift server has started.

        [2012-08-08 11:05:42,208]  INFO - CGThriftServer Starting the Cloud Gateway Thrift server on host '' on port '15001'...

Adding a remote CG server in Cloud Agent

  • Go to $ESB_HOME/samples/axis2Server/src/SimpleStockQuoteService and type ant. This will create the
    SimpleStockQuoteService in $ESB_HOME/samples/axis2Server/repository/services/SimpleStockQuoteService.aar.
    Copy this into $AS_HOME/repository/deployment/server/axis2services/.
  • Open $AS_HOME/repository/conf/carbon.xml and set the Offset in Port section to 2. Start the Application Server server using{.bat} in $AS_HOME/bin.
  • Open $ESB_HOME/repository/conf/carbon.xml and set the Offset in Port section to 1.
  • Drop the attach synapse_sample_1000.xml into $ESB_HOME/repository/samples/ and start WSO2 ESB 4.5.0 with
    tha configuration number 1000,{.bat} -sn 1000. This configuration
    has a proxy for the back end SimpleStockQuoteService service deployed in WSO2 Application Server above.
  • Log into the management console of WSO2 ESB and go to Configure->Cloud Gateway Agent menu.

    Figure 6: Cloud Gateway Agent

  • Click Add/Edit CG server to add a remote CG server. This will forward to CG server addition console.

    Figure 7: Adding a new Cloud Gateway server

    Each of the fields has the following meaning.

    1. 1. Cloud Gateway Server Name - Human redable name for the remote Cloud Gatewayserver, e.g. - server1.
    2. 2. Cloud Gateway Server URL - The remote Cloud Gateway server url of the format 'https://host:port/', e.g. https://localhost:9443.
    3. 3. Username - The user name of the remote Cloud Gateway server. Default 'cguser'(without quote).
    4. 4. Password - The password of the remote Cloud Gateway server user. Default 'cguser'(without quote).

Publishing a service

  • Since we have a server now we can publish a service. Go to Publish/Unpublish link from the Cloud Gateway
    Agent menu.

    Select the remote Cloud Gateway server to publish the service. Then click Publish. More information about
    publishing options available in the user guide.

    Figure 8: Publishing StockQuoteProxy service

  • Once the service is published it can be Un-published again.

    Figure 9: Published service option

Invoke the service

Finally it's time to invoke the service. You can either log into the WSO2 Cloud Gateway server and go to the service
listing dashboard and pick the StockQuoteProxy or directly use the 'Try Cloud Gateway Service' option in Figure 9 in Cloud Gateway Agent. Also you can
copy the 'CG service WSDL1.1' to create a project in SOAP UI and invoke the public Cloud Gateway service using SOAP UI.


This documents introduces WSO2 Cloud Gateway, which enables organizations to share their internal services
beyond their private networks and out to public Web, securely and in a controlled manner. We explained the
main idea behind the Cloud Gateway and explained how users can get started with the Gateway.
If you are interested in seeing how this technology is different from existing technology there is a comparison in the research paper presented in the References section.

Future work

1.0.0 release of WSO2 Cloud Gateway only supports publishing a Web service (SOAP, REST, JSON etc.) There
are plans to add the support to publish a private API and a webapp via WSO2 Cloud Gateway in upcoming versions.

WSO2 Cloud Gateway will also be available via WSO2 StratosLive to try out without installing any artifacts locally.


  1. CSG-CloudFlow2012(slides)
  2. CSG-CloudFlow2012(paper) |
    Read at IEEE


Rajika Kumarasiri, Senior Software Engineer, [email protected]