Deploy WSO2 API Microgateway in Docker in 5 minutes

WSO2 API Manager Microgateway is a lightweight message processor for APIs. The microgateway is used for message security, transport security, orchestration, routing, and other common API Management related quality of services. It has the throttling capabilities as well as the usage metering capabilities.

Docker

The microgateway is designed to be a container native and this aligns with microservices architecture. This is being designed to work in decentralized environments and the connectivity to the API Management system is optional.

Prerequisites:

1. WSO2 API Manager 2.5.0
2. WSO2 API Manager Microgateway Toolkit 2.5.0
3. Docker in your machine

WSO2 API Manager Microgateway toolkit is responsible for microgateway related management tasks. It comes with a command line tool which accepts commands issued by the user. With this command line tool, users are able to communicate with the API management core runtime (API publisher) and build the microgateway runtime. The API microgateway toolkit can communicate with the API publisher to retrieve API metadata that is required to create the microgateway runtime.

In this tutorial we are going to perform the following tasks.

• API Create, subscribe and JWT token generation
• Prepare Configurations
• Setting up API Microgateway project
• Building the API Microgateway project
• Run API Microgateway in docker
• Access the API in the API Microgateway docker container

1. API Create, subscribe and JWT token generation

Create an API with the following details in API Manager 2.5.0. You can create an application which supports JWT tokens. Then you can subscribe to the API and get a JWT token to invoke the API.

Please refer [1] for more information on getting a JWT token.

API details

2. Prepare Configurations

Create a deployment.toml file in with the following content. You can place this file inside the wso2am-micro-gw-toolkit-2.5.0 root directory. Let’s call this location as the TOOLKIT_HOME.

In the following configuration, replace the <TOOLKIT_HOME> with the correct directory path.

[docker]
  [docker.dockerConfig]
    enable = true
    name = "hello_world"
    registry = 'docker.wso2.com'
    tag = 'v1'
    #buildImage = ''
    #dockerHost = ''
    #dockerCertPath = ''
    #baseImage = ''
    #enableDebug = ''
    #debugPort = ''
    #push = ''
    #username = ''
    #password = ''
  [docker.dockerCopyFiles]
    enable = true
    [[docker.dockerCopyFiles.files]]
        source = '<TOOLKIT_HOME>/resources/conf/micro-gw.conf'
        target = '/home/ballerina/conf/micro-gw.conf'
        isBallerinaConf = true

This is deployment.toml file which contains the relevant deployment configurations such as docker image name, registry, tag, etc. In addition to that if you want to connect to an external docker host, you can provide those details as below. Then the docker image will be created in that docker host’s registry.

dockerHost = ‘tcp://192.168.99.100:2376’
dockerCertPath = ‘/home/user/.minikube/certs’

Note: The API Microgateway has all the configurations in a single file and it is called the micro-gw.conf. This file has the configurations such as key manager configurations, jwt configurations, etc. In order to function the API Microgateway, micro-gw.conf has to be copied to the docker image. This can be done using docker copy files configurations by giving relevant source and target details. In addition this, if you need to copy any file to the API Microgateway, such as file1, this can be done as below.

[docker.dockerCopyFiles]
    enable = true
    [[docker.dockerCopyFiles.files]]
        source = '<TOOLKIT_HOME>/resources/conf/micro-gw.conf'
        target = '/home/ballerina/conf/micro-gw.conf'
        isBallerinaConf = true
[[docker.dockerCopyFiles.files]]
        source = '/home/user/file1'
        target = '/home/ballerina/file1'

3. Setting up API Microgateway project

When setting up the API Microgateway project, the API Microgateway tool kit connects to the API Management Core (API publisher) to get the API details, policies, etc. Based on the details received, using the mustache templates, it creates the API definitions.

To get started setting up the microgateway project, go to the wso2am-micro-gw-toolkit-2.5.0/bin location.

Let’s create a project call hello_world_project with the following command. We need to provide the deployment.toml file as an input.

./micro-gw setup <Project_Name> -a <API_Name> -v <API_Version> — deployment-config <Location_of_Deployment.toml_File>

./micro-gw setup hello_world_project -a hello_world -v v1 — deployment-config <TOOLKIT_HOME>/deployment.toml

This commands creates the following folders under the hello_world_project folder.

The folder structure of the project

If you check the hello_world_v1.bal file, you can notice @docker annotations are being added to the service file. These annotation enables the docker support for the API Microgateway.

@docker:Config {
    name:"hello_world",
    registry:"docker.wso2.com",
    tag:"v1"
}


@docker:CopyFiles {
    files: [
            {  source:"<TOOLKIT_HOME>/resources/conf/micro-gw.conf", 
               target:"/home/ballerina/conf/micro-gw.conf", 
               isBallerinaConf:true 
            }
    ]
}

4. Building the API Microgateway project

When you build the API Microgateway project, it creates the docker image in your local registry. This can be used to spawn an API Microgateway docker container.

Let’s build the hello_world_project as follows.

./micro-gw build <Project_Name>

./micro-gw build hello_world_project
@docker    - complete 3/3 

Run following command to start docker container:
docker run -d docker.wso2.com/hello_world:v1
Build successful for the project - hello_world_project

You can check the built docker image as below.

Results for docker image command

5. Run API Microgateway in docker

We can start the API Microgateway docker container as below.

docker run -d docker.wso2.com/hello_world:v1

Note: Docker for Mac has several limitations. There is no docker0 bridge on mac. Hence you can not connect to the docker container using the docker IP from your machine

You will need to start the docker container with the following command to bind the docker container ports to the localhost or the docker host machine.

docker run -d -p 9090:9090 -p 9095:9095 docker.wso2.com/hello_world:v1

Also, you can start the docker container to use the host network driver for your container as follows. But unfortunately this only works on Linux.

docker run — network host -d docker.wso2.com/hello_world:v1

You can list down the running docker containers as below.

Results for docker ps command

6. Access the API in the API Microgateway docker container

In order to access the API, we need to figure out the docker container IP address. This can be figured out by using the following command.

docker inspect <Container_ID> | grep “IPAddress”

Note: The container id can be figured out using the docker ps command. If you are running on Mac, your container IP is localhost as you have started with -p flag.

With a REST client or using the curl command, you can access the API.

URL — https://<Container IP>:9095/hello/v1/check

Headers: Authorization: Bearer <JWT_TOKEN>

Method — GET

Note: As JWT is a self contained access token, the microgateway does not need to connect to the key manager. But if you are using an Oauth2 access token, you need to point the microgateway to the key manager to do the key validation. The configuration file of microgateway which is micro-gw.conf has the key manager details as below.

[keyManager]
serverUrl="https://localhost:9443"
username="admin"
password="admin"
tokenContext="oauth2"
timestampSkew=5000

You can provide API Microgateway accessible serverUrl as for the key manager serverUrl. As SSL hostname verification is enabled by default, you need to add the public key to the API Microgateway truststore which resides in the <API_Microgateway>/runtime/bre/security location.

For this demonstration, I have deployed a single API in the docker container. You can group multiple APIs using labels and deploy APIs in a single docker container. Please refer [1] for more information.

[1] — https://docs.wso2.com/display/AM250/Working+with+the+API+Microgateway