Introduction
The purpose of the tutorial is to introduce the webMethods Microgateway 10.3. It gives some overview and some background information about Microgateway and shows how Microgateway and API Gateway interact. Furthermore it describes how Microgateway instances can be provisioned and configured. Finally the tutorial describes how Microgateway can be provisioned via Docker and how applications can be synched from an API Gateway.
About Microgateway
The adoption of the microservice architecture pattern drives the need for lightweight gateways or Microgateways. Microgateways give control over a microservice landscape by enforcing policies which perform authentication, traffic monitoring and traffic management. The lightweight nature of a Microgateway allows a flexible deployment to avoid gaps or bottlenecks in the policy enforcement.
The above diagram shows microservices implementing the booking related API of the imaginary company NodeTours. The shown microservice mesh or microservice landscape consists of three services. Consumer applications access the APIs via a central API Gateway that performs the enforcement of policies. The problem here is that each microservice exposes an endpoint where no policy enforcement is done. Moreover considering the microservices are interacting with each other all this traffic needs to be routed through the single API Gateway. This leads to additional network latency and the API Gateway potentially becomes a bottleneck. The diagram below shows a deployment where the API Gateway is replaced with a set of Microgateways that are added to the microservices itself. Such a "sidecar" deployment does not leave any gaps and avoids bottlenecks in the policy enforcement.
API Gateway Integration
The Microgateway's responsibility is focused on a single microservice or a small number of microservices. To manage a microservice landscape an API Gateway is needed. It offers the UI for configuring policies and for system configurations. Moreover it is responsible for monitoring the traffic across the microservice landscape. The following figures shows how Microgateways are interacting with an API Gateway.
API providers define their APIs and policies in the API Gateway and the APIs and policies are pulled by the Microgateways during startup. In addition to APIs and policies the pulled assets include application metadata, runtime aliases and administrative settings. The acquisition of assets and settings is performed using the API Gateway REST APIs.
Consumer applications send API requests to the microservices via the the Microgateway endpoints. The available Microgateway endpoints can be obtained from a service registry that holds all the API endpoints exposed by the Microgateways. While processing the API requests and responses the Microgateways calculate runtime analytics information and push these to the API Gateway. The API Gateway does an aggregation and provides a consolidated view covering the microservice landscape via its runtime analytics dashboards.
The acquisition of assets and administrative settings can be done up-front via the Microgateway tooling which allows to provision stand-alone Microgateways which do not require any connection to a running API Gateway. Stand-alone Microgateways do not support a consolidated traffic monitoring of the microservice landscape.
Provisioning Microgateway Instances
The Microgateway provisioning allows to create multiple Microgateway instances from a single Microgateway installation. The Microgateway provisioning comes in 2 flavors:
- Instance based provisioning
- Docker based provisioning
The instance based provisioning means the creation of a Microgateway package from an existing installation and copying it to multiple target machines as shown in the following diagram.
To perform an instance-based provisioning the Microgateway command line interface (CLI) is used. In the installation directory, a Microgateway instance can be created via the following command.
./microgateway.sh createInstance --instance /tmp/Microgateway.zipThe resulting zip file contains all the required artifacts for running a Microgateway:
- Java runtime environment (JRE)
- Microgateway server
- Microgateway CLI
- Configuration files
- Optionally: one or more API Gateway archives
Once copied to a target system the zip file can be unzipped and the provisioned Microgateway can be started via its command line interface (CLI).
Unzip the instance:
unzip /tmp/Microgateway.zip -d /home/demo/MicrogatewayOn Linux the permissions need to be adjusted:
cd /home/demo/Microgateway
chmod u+x microgateway.sh
chmod u+x microgateway-jre-linux/bin/javaNow the Microgateway instance is ready to be started.
Asset Provisioning via Export Archive
The Microgateway can be started with one or more API Gateway asset archives holding the assets to be provisioned. The following screenshot shows the definition of the NodeTours APIs exposing booking capabilities of the imaginary company NodeTours:
- NodeTours Bookings API
- NodeTours Search API
- NodeTours Sign-up API
The following command starts a Microgateway with the archive node-tours.zip holding sample APIs exported from the above API Gateway.
./microgateway.sh start -p 9090 -a ../node-tours.zipOn successful startup the Microgateway prints a status message to the console with the port it is listening on:
Server started using http port 9090According to the status message the Microgateway is running and listening on port 9090 for incoming requests. The status of the running Microgateway can be checked via a GET command against the Microgateway administration API:
GET http://localhost:9090/rest/microgateway/statusThe status response looks like this:
{
"description": "webMethods Microgateway",
"publisher": "Software AG",
"version": "10.3.0.3.92"
}If multiple instances have been started the microgateway status command provides an overview over the running instances:
./microgateway.sh status
Server active on port 9090
Server active on port 9092For fetching details about the deployed APIs, applications, and global policies the following GET request needs to be sent:
GET http://localhost:9090/rest/microgateway/assetsThe details show the provisioned APIs and the policies defined for the NodeTours APIs:
{
"apis": [
{
"apiName": "NodeTours Bookings API",
"apiVersion": "1.0",
"apiDescription": "You found the perfect cruise, now lets get it booked.\nBefore a cruise can be booked, the customer must sign-up to the NodeTours site if they have not already done so. Once signed-up, use the Bookings API can be used to book a cruise. You need the credentials you gave during sign-up to book the cruise. The credentials should be sent to the API using HTTP Basic Authentication (the HTTP header Authorization: BASIC <base64 encoded user:password>).\n\nIf an error occurs while booking a trip, the API will give back an HTTP status code and where appropriate the message body will contain a plain text message giving the reason for the error.",
"type": "REST",
"systemVersion": 1,
"id": "21902a29-ed33-4ebc-89d7-ba923302b239",
"httpEndpoint": "http://localhost:9090/gateway/NodeTours%20Bookings%20API/1.0",
"httpsEndpoint": "",
"policyActions": [
{
"id": "8e3e59a4-0909-4b10-bce8-fb1289cd5981",
"name": "Enable HTTP / HTTPS",
"global": "false",
"stageKey": "transport"
},
{
"id": "811cca64-0537-4f9f-809b-9751c9f3a862",
"name": "Straight Through Routing",
"global": "false",
"stageKey": "routing"
},
{
"id": "callbackURLReplacer",
"name": "Default Callback URL Replacer Action for API ",
"global": "false"
}
]
},
{
"apiName": "NodeTours Search API",
"apiVersion": "1.0",
"apiDescription": "This API enables site visitors to search for tours offered by NodeTours. Once a tour is found and the visitor wants to book the tour, the visitor must do the following:\n\n1. Sign up for an account, if the visitor has not already done so, using the functionality provided in the Sign-up API.\n\n2. Book the tour using the functionality provided in the Bookings API. \n\nThe Search API provides the following search options:\n\n- Show all available cruises.\n- Show cruises based on filter criteria.\n- Show a specific cruise based on its cruise ID.\n\nIf an error occurs, the API returns an HTTP status code and, where appropriate, a plain text message in the message body providing the reason for the error.",
"type": "REST",
"systemVersion": 1,
"id": "f1241e85-70ed-4b92-a64d-65c29a435b32",
"httpEndpoint": "http://localhost:9090/gateway/NodeTours%20Search%20API/1.0",
"httpsEndpoint": "",
"policyActions": [
{
"id": "6e9ddc8e-2fa5-4bb9-a7e9-496e56b3a176",
"name": "Enable HTTP / HTTPS",
"global": "false",
"stageKey": "transport"
},
{
"id": "7a85050e-15b0-4e8f-85ed-01a3eb724f44",
"name": "Straight Through Routing",
"global": "false",
"stageKey": "routing"
},
{
"id": "callbackURLReplacer",
"name": "Default Callback URL Replacer Action for API ",
"global": "false"
}
]
},
{
"apiName": "NodeTours Sign-up API",
"apiVersion": "1.0",
"apiDescription": "API for signing-up to NodeTours.\nThe signing-up resources creates/updates/deletes a customer from SAGTours.\nSign-up and Booking are protected via Basic Authentication.\n\nIf an error occurs, the Sign-up API may give a text message as well as the HTTP response code.",
"type": "REST",
"systemVersion": 1,
"id": "34bf2541-5c2b-49a5-acee-4fdd52dff777",
"httpEndpoint": "http://localhost:9090/gateway/NodeTours%20Sign-up%20API/1.0",
"httpsEndpoint": "",
"policyActions": [
{
"id": "2e41f1ae-656e-423e-ab28-de7fa7e7f57b",
"name": "Enable HTTP / HTTPS",
"global": "false",
"stageKey": "transport"
},
{
"id": "7735cb7c-b0e5-430e-9c60-d1b0b55e3511",
"name": "Straight Through Routing",
"global": "false",
"stageKey": "routing"
},
{
"id": "callbackURLReplacer",
"name": "Default Callback URL Replacer Action for API ",
"global": "false"
}
]
}
],
"applications": [],
"policies": []
}The response shows that the running Microgateway is ready to serve incoming requests against the provisioned NodeTours APIs. An overview over the deployed APIs can also be obtained via the microgateway assets command, the Microgateway is identified by the port it is listening on:
./microgateway.sh assets -p 9090
Number of APIs: 3
NodeTours Bookings API (1.0)
Endpoint:
http://host:9090/gateway/NodeTours%20Bookings%20API/1.0
Policies:
Enable HTTP / HTTPS
Straight Through Routing
Default Callback URL Replacer Action for API
NodeTours Search API (1.0)
Endpoint:
http://host:9090/gateway/NodeTours%20Search%20API/1.0
Policies:
Enable HTTP / HTTPS
Straight Through Routing
Default Callback URL Replacer Action for API
NodeTours Sign-up API (1.0)
Endpoint:
http://host:9090/gateway/NodeTours%20Sign-up%20API/1.0
Policies:
Enable HTTP / HTTPS
Straight Through Routing
Default Callback URL Replacer Action for API The provided overview shows the API, their endpoints and the applied policies. The shown endpoint information is helpful to create requests against the exposed APIs. For example a list of available cruises can be obtained via the following request against the exposed NodeTours Search API (1.0):
GET http://localhost:9090/gateway/NodeTours%20Search%20API/1.0/cruisesTo stop a Microgateway a stop command has to be issued. The following command stops the Microgateway listening on the port 9090:
./microgateway.sh stop -p 9090Downloading Assets from API Gateway
Microgateways can download assets from a running API Gateway. The Microgateway has to be configured with the API Gateway URL and the credentials for accessing it. The required APIs have to also be specified.
./microgateway.sh start -p 9090 -gw http://localhost:5555/rest/apigateway -gwu Administrator -gwp manage -apis "NodeTours Bookings API","NodeTours Search API","NodeTours Sign-up API"The start command pulls the NodeTours APIs from the running API Gateway. Together with the APIs, all associated objects are downloaded, including policies and consuming assets. The command line parameters for starting a Microgateway can become complex. Therefore the Microgateway accepts a yaml file holding the required parameters and additional configurations.
./microgateway.sh start -c config.ymlThe config.yml holds the parameters for downloading the NodeTours APIs from the API Gateway listing on localhost port 5555:
api_gateway:
url: 'http://localhost:5555/rest/apigateway'
user: Administrator
password: manage
ports:
http: '9090'
downloads:
apis: 'NodeTours Bookings API, NodeTours Search API, NodeTours Sign-up API'If the Microgateway can't reach the configured API Gateway the startup fails with the error message:
Start of process failed :
com.softwareag.microgateway.options.yaml.ConfigurationException: API Gateway not active or accessible: status 400, errorMessage: server connection failed (http://localhost:5555)If the Microgateway connects properly to the configured API Gateway the configured APIs are pulled.
Provisioning a Microgateway Docker Instance
The Docker based provisioning means the creation of a Microgateway Docker file from an existing installation, building the image and running it multiple times in a container environment as shown by the following diagram:
For the Docker based provisioning the Microgateway CLI provides the createDockerFile command. The command creates a Docker file that can be consumed by docker build for creating a Docker image. The command exposes the following Docker specific parameters:
- docker_from: Optional base image, for adding an Microgateway layer on top of an existing image. If no base image is given, the default is openjdk:8-jre-alpine.
- docker_dir: Microgateway directory
- docker_file: Optional docker file name. Default is Microgateway_DockerFile
The following command creates a Docker file for running a Docker container configured with the NodeTours APIs.
./microgateway.sh createDockerFile -p 9090 -a ../node-tours.zip --docker_dir .The created Docker file looks as follows:
FROM openjdk:8-jre-alpine
MAINTAINER SoftwareAG
RUN mkdir -p /opt/softwareag/Microgateway/logs
RUN adduser -u 1724 -g 1724 -D -h /opt/softwareag/Microgateway sagadmin
RUN chown -R 1724:1724 /opt/softwareag
COPY --chown=1724:1724 ./config/ /opt/softwareag/Microgateway/config/
COPY --chown=1724:1724 ./lib/ /opt/softwareag/Microgateway/lib/
COPY --chown=1724:1724 ./files/ /opt/softwareag/Microgateway/files/
COPY --chown=1724:1724 ./resources/ /opt/softwareag/Microgateway/resources/
COPY --chown=1724:1724 ./*.jar /opt/softwareag/Microgateway/
COPY --chown=1724:1724 ./*.sh /opt/softwareag/Microgateway/
COPY --chown=1724:1724 ./tmp-docker/node-tours.zip /opt/softwareag/Microgateway/config
USER 1724
EXPOSE 9090
CMD cd /opt/softwareag/Microgateway && ./microgateway.sh start -p 9090 -a config/node-tours.zip -lv ERROR && sleep 1000000dFrom the Docker file the image can be created via docker build:
docker build -t sag:mcgw -f Microgateway_DockerFile .Form the resulting image sag:mcgw multiple Docker containers can be spawned via docker run:
docker run -d -p 9094:9090 sag:mcgwThe Microgateway port 9090 of the Docker container is mapped to the host port 9094. This means the NodeTours Search API can be invoked as follows:
GET http://localhost:9094/gateway/NodeTours%20Search%20API/1.0/cruises
For creating a Docker image by pulling assets from an API Gateway the Docker file needs to be created using the following command:
./microgateway.sh createDockerFile -p 9090 -gw http://localhost:5555/rest/apigateway -gwu Administrator -gwp manage -apis "NodeTours Bookings API","NodeTours Search API","NodeTours Sign-up API"The API Gateway URL, username and password and the APIs are configured via command line parameters. From the resulting Docker file, the Docker image can be created and run via the Docker build and run commands.
Application Synchronization
During startup Microgateway downloads all registered consumers of the downloaded APIs from the connected API Gateway. Any consumer updates on the API Gateway after the Microgateway startup are not automatically synced. If required the Microgateway can be configured to frequently sync application updates. The extended config.yml to sync registered consumers looks as follows:
# API Gateway configuration
api_gateway:
url: 'http://localhost:5555/rest/apigateway'
user: Administrator
password: manage
# Microgateway ports
ports:
http: '9090'
# Specifying assets to download from API Gateway
downloads:
apis: 'NodeTours Bookings API, NodeTours Search API, NodeTours Sign-up API'
# Application Sychronization
applications_sync:
enabled: true
applications_to_sync: registeredApplications
polling_interval_secs: 2
connection_timeout_secs: 10The Microgateway started with the above configuration pulls the configured API Gateway every 10 seconds for updates to the registered applications of the NodeTours APIs. For example if an application MyApp is registered in the API Gateway it appears in the assets command response:
Number of APIs: 3
NodeTours Bookings API (1.0)
Endpoint:
http://daefermion1:9090/gateway/NodeTours%20Bookings%20API/1.0
Policies:
Enable HTTP / HTTPS
Straight Through Routing
Default Callback URL Replacer Action for API
NodeTours Search API (1.0)
Endpoint:
http://daefermion1:9090/gateway/NodeTours%20Search%20API/1.0
Policies:
Enable HTTP / HTTPS
Straight Through Routing
Default Callback URL Replacer Action for API
NodeTours Sign-up API (1.0)
Endpoint:
http://daefermion1:9090/gateway/NodeTours%20Sign-up%20API/1.0
Policies:
Enable HTTP / HTTPS
Straight Through Routing
Default Callback URL Replacer Action for API
Number of Applications: 1
MyApp