This post will guide you through how to setup, build and finally run a WSO2 API Manager Micro-Gateway instance in Windows environment. The steps will be more or less same in a Unix-Like environment, except for running the Micro-Gateway as a windows service.
Let begin with the question what is WSO2 API Manager Micro-Gateway?
What is WSO2 API Manager Micro-Gateway
A typical API gateway is a component which governs the API traffic, enforcing the policies and authentication/authorization of the users. A micro gateway in the other hand contains all the capabilities of the regular gateway component, in addition, it is lightweight in size and can operate in more isolated fashion than its predecessor. A micro gateway can be started in just a few seconds and start serving API requests, it can work independently fully utilizing the available resources to cater the API traffic. With the WSO2 API Manager, The Microgateway can be used to deploy single API per micro-gateway, Where a dedicated gateway for serving API request(Private Jet mode), or you can label set of APIs and serve those API through a separate micro gateway instance. Further, you can setup K8S cluster to deploy a pod per micro gateway instance and scale your API ecosystem automatically with the increasing number of APIs or traffic. You can find more information about WSO2 API-Microgateway and some reference solution architectures from their documentation.
To run initialize a micro-gateway instance,
- Oracle Java 1.8
- Need to have WSO2 API Manager 2.5 or above.
- This is required to bootstrap the micro-gateway.
- WSO2 Microgateway CLI tool
- NSSM (the Non-Sucking Service Manager)
- If you need to run the micro-gateway as a windows service
Setup a Micro-Gateway project
and then start the WSO2 API Manager server. Once the server is started, create a new API from Publisher and publish it as well.
In the next 2 steps, we will create a label from Admin application and assigned it to the above API. This is to demonstrate how to deploy a micro-gateway for a particular gateway label. But it is not required to assign a label to an API in order to deploy it in a micro-gateway.
Then login to the admin application and goto manager labels section and create a new label. You will be asked to provide a name and a URL. This URL will be shown in the API Store as the gateway URL, if you select this label for an API.
Select the previously created label for the API in the 3rd step of the API edit wizard
Now we can set up a micro-gateway project for the above-created gateway label. Note that, When you assign the new gateway label to the API, The gateway URL shown in the store will be changed to the URL which you have given when creating the gateway label.
Unzip the downloaded wso2am-micro-gw-toolkit-2.5.0.zip to a convenient location (i:e C:\Program Files\wso2\micro gateway cli\). Then copy the <Path-To-wso2am-micro-gw-toolkit>\bin path and append it to the path windows system variable as shown below.
Once you append the Micro-gateway toolkit \bin directory path to path system variable, You can invoke the micro-gw command from any directory in the system via the command line. So let’s initialize a project.
Open the Microsoft command line (cmd.exe) and change the location (cd <directory location>) where you want to setup the Micro-Gateway project. Then run the following command to bootstrap a Microgateway project for sample_label gateway label.
You can give any project name as you prefer, but you have to give a valid gateway label which is available in the API Manager server in which you want to fetch the API metadata.
micro-gw setup <project_name> -l <LABEL_NAME>
In here, If you want to set up a microgateway project for single API, You can do so by giving its name and version information as below.
micro-gw setup <project_name> -a <API_NAME> -v <API_VERSION>
This will create a project for that particular API name-version, Hereafter the rest of the process will be the same for both label based project or private jet API project.
Let’s see what is happening behind the scene when you run the setup command:
First, you will be asked for a username which CLI tool will be used to authenticate the user in API Manager server.
Next, of course, the password for the above user, and the following is API Manager server URL. In this step, you have to give the API Manager server running location and this URL will be used to make the DCR call and generate CS/CK for product REST APIs and fetch API metadata.
Next, you will be asked for certificate trust store location and its password for initializing the SSL connection with API Manager server, You can leave them blank if you do not want to change the default parameter. (default parameters are shown in brackets)
All the above-given information will be preserved (except for password) for later use. If you want to reset the project you can use the –reset argument as below.
micro-gw reset -c <em><path_to_project></em>\conf\deployment-config.toml
During the setup phase, Micro-gateway CLI tool will fetch the API Metadata such as API JSON itself and throttling policies from the Publisher and Admin REST APIs. Then those data will be used to generate the Ballerina code using pre-packaged mustache templates by filling up the data.
In addition to code generation, CLI tool will keep JSON mapping of the hashed dynamic data file to detect the API changes and notify the callee of the micro-gw command using an exit code (34). Users of micro-gw can check for the exit code and decide whether they will continue with re-deploying the micro-gateway instance or not.
This hashing method will be very useful Since Micro-Gateways are operated in an immutable way, Where a change to micro-gateway would require to go through the setup -> build -> deploy cycle again.
By now, There should be a directory created with the given project name ( first parameter for setup command) and the structure of the project should be as below.
So now we have set up the micro-gateway project, with all the generated codes in place, Next step is to build the micro-gateway using the generated Ballerina source code.
Go to the Micro-Gateway project root directory (If you have not change the directory after step 6 it’s the same directory where you ran the setup command) and run the following command to build the project. Use the same project name which you have given when setting up the project.
micro-gw build <project_name>
During the build process, CLI tool will execute the Ballerina run command on the \src
ballerina build src -o %project_name%.balx"
using the Ballerina distribution packed with the CLI tool.
This will output a compiled .balx file in the <project_name>\target directory. (But you won’t able to see the compiled .balx after build success, This file will be deleted once the micro-gateway distribution created)
Then all the artifacts(ballerina bytecode, config files ect…) will put in order to make the micro-gateway distribution .zip file. This is done through the micro-gateway CLI tool.
So after running the above build command, You can find the micro-gateway distribution (micro-gw-<project_name>.zip) specifically designed to the given gateway label or API name-version.
Take the micro-gw-<project_name>.zip file from <project_name>\target directory and extract the files to where you want to run the micro-gateway. If you are running the micro-gateway in windows environment use the gateway.bat script in the extracted micro-gw-<project_name>/bin directory. Simply run the
file to start the micro-gateway instance in the foreground.
Step 8 (Optional)
If you want to start the micro-gateway server as Windows Service, use the NSSM tool to install the gateway.bat script as a windows service. Make sure you have set the JAVA_HOME variable as a system variable
or use the current user as the user who starts the windows service.
To test the micro-gateway server, You can invoke the API through microgateway using CURL, By default, microgateway is serving HTTPS/WSS request in 9095 port. So the sample CURL would be
curl -v -k https://mg.knnect.com:9095/wolaa/1.1.1/getmeall -H "Authorization: Bearer 104cd62f-a8ab-3089-bc12-f7cc36e73e77"