Overview

 

API Microgateway is a flavor of Cloud API Manager/Gateway product, which helps to create managed APIs for Application Integration endpoints hosted on-premises. API Microgateway consists of two components, API Microgateway Service, a secure agent service that helps in creating, building, and deploying the API Microgateway component. The API Microgateway is the runtime component that proxies the Application Integration endpoints by applying the configured API policies.

The approach taken towards making the gateway is to create an API management project and build an immutable docker image from that project. The docker images are hosted in the secure agent Docker Runtime environment using a blue-green deployment strategy to support zero-downtime upgrades of the gateway component.

API Microgateway Service

API Microgateway service is the secure agent service that is responsible for creating the managed APIs with supported policies, building API micro gateway docker images, and deploying those images to the Docker runtime environment. This service follows the same lifecycle model like any other secure agent service. API Microgateway Service will be automatically downloaded and installed on all the secure agents once the necessary licenses have been assigned to the org. The status of the service will be available through the Administrator - Runtime Environments page. The activity log will also have the chronological status updates of the service.

Similar to any other secure agent service, the API Microgateway service logs will be available in the logs folder under the specific version.

  1. apimgw.log - captures all the logs related to API Microgateway Service
  2. scripts.log - captures all the logs related to the lifecycle of the API Microgateway Service

 

Note: For October 2020 release, API Microgateway service will be supported only with Linux-based secure agent environments.

License

ApiMicrogatewayService custom license is required to download/install and work with API microgateway service in the secure agent.

  • Contact Informatica Global Customer Support to request a custom license.

 

Prerequisites

  1. For October 2020, API microgateway is supported only in secure agents hosted in linux environments.
  2. Docker Runtime Environment should be configured and available in the same secure agent host
  3. Enable TCP without TLS to run Docker daemon

API Microgateway Service Installation

API Microgateway service will be downloaded and installed on all the secure agents associated with the org when the licence gets provisioned. Similarly periodical updates to the service will be automatically rolled out without any interventions.

The new version of the service can be tracked using the application version in the secure agent and the same will be reflected in the Administrator- Runtime Environments page. As and when the new versions are rolled out, the older versions of the service will be retired and the new service version will handle the managed APIs project, building and deploying the API management changes.

Configurations

List of configurations

 

Name

Default value

Description

project-nameapi_projectThe managed APIs and their policies are grouped under a project which gets built into a microgateway application. The default project name is api_project. This can be changed as per requirement or in case when a new project is required discarding the old project.
docker-registry-nameinfa.agent.apimgwThe local docker registry name under which all the api microgateway docker images are tagged.
blue

http-port: 16090

https-port: 16095

http/s ports of the blue container. Change the ports if there are conflicts
green

http-port: 17090

https-port: 17095

http/s ports of the green container. Change the ports if there are conflicts
haproxy

http-port: 6090

https-port: 6095

http/s ports of the haproxy container. Change the ports if there are conflicts. Haproxy is used as router to switch traffic between blue/green containers for zero downtime.

Policies

For October 2020 release, API MGW supports the following policies

  1. Rate Limit
  2. IP Filtering
  3. Basic Authentication

Rate Limit

Rate limit defines the throttling limit for the API usage. Using this policy, usage restrictions can be placed on each API defining the allowed limit of usage for a defined duration.

IP Filtering

IP Filtering enables white listing/black listing of IP ranges for API usage. Multiple IP rules can be specified to grant/deny access to various IP ranges. The order of precedence is based on the listing of the rules.

Basic Authentication

APIs can be secured using basic authentication which verifies the user credentials against Informatica's Identity service.

Usecase Flow

Consider the use case to manage an Application Integration API. The typical flow is:

  1. Create a managed API using the service. Define the required policies as part of the creation step.
  2. Build the microgateway app
  3. Deploy the microgateway app

High-level architecture

 

API Microgateway is a proxy which applies the configured policies before forwarding the requests to backend Application Integration endpoints. The API microgateway is a generated app build from the managed API configurations. It is packaged as an immutable docker image and deployed using blue/green deployment strategy to provide zero downtime during updates.

 

apimgw_deploy.png

The deployment uses HAProxy container that acts as a router to route traffic to one of the active API Microgateway containers.

 

For October 2020 preview release, the API Microgateway service does not have a UI to create managed APIs. REST endpoints are exposed to the service which can be used to create managed APIs. Similarly, build and deploy are exposed as endpoints. The API Microgateway Service endpoints are described below.

Managed API creation

The following are the CRUD endpoints for the managed API

 

Name

URL

Method

Sample Payload

Response

Create

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/apispec

POST

{

  "id": "getbasic",

  "path": "/rt/BasicAuth_Lin",

  "methods": [

    "GET",

    "POST"

  ],

"policies": {

"rateLimit": {

"limit": 4,

"duration": 1,

"timeUnit": "min"

    },

"authType": "BASIC", 

  

"ipRangeRules": [

      {

        "type": "ALLOW",

        "high": "255.255.255.255",

        "low": "0.0.0.0"

      }

    ]

  },

  "endpoints": [

    "https://{{endpointhost}}

      :{endpointport}/process-engine"

  ]

}

201 Created

Get all managed API

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/apispec

GET

NA

200 OK

{List of all managed APIs}

Get single managed API

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/apispec?path={path}

GET

200 OK

 

{

  "id": "getbasic",

  "path": "/rt/BasicAuth_Lin",

  "methods": [

    "GET",

    "POST"

  ],

  "policies": {

    "rateLimit": {

      "limit": 5,

      "duration": 1,

      "timeUnit": "min"

    },

    "authType": "BASIC",

Update

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/apispec?path={path}

PUT

{

  "id": "getbasic",

  "path": "/rt/BasicAuth_Lin",

  "methods": [

    "GET",

    "POST"

  ],

"policies": {

"rateLimit": {

"limit": 5,

"duration": 1,

"timeUnit": "min"

    },

"authType": "BASIC",

  

"ipRangeRules": [

      {

        "type": "ALLOW",

        "high": "255.255.255.255",

        "low": "0.0.0.0"

      }

    ]

  },

  "endpoints": [

    "https://{{endpointhost}}

      :{endpointport}/process-engine"

  ]

}

200 OK

Delete managed API

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/apispec?path={path}

DEL

 

200 OK

 

Managed API creation URL points to the API Microgateway service deployed and running in the secure agent.

  1. host - refers to the hostname of the secure agent
  2. securechannelport - API Microgateway service secure port assigned during the startup by the agent core. This can be obtained from the agentcore logs or microgateway log files.
  3. endpointhost - refers to the hostname where the endpoint to proxy is running. In case of Application integration, this refers the secure agent host where the process server is running.
  4. endpointport - Application Integration process server port in the secure agent.
  5. pathname - refers to the relative path to access the managed API

Building API Microgateway

 

Name

URL

Method

Sample Payload

Resopnse

Build

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/build

POST

{

  "dockerImage": {

    "name": "apiproject2",

    "tag": "v1"

  },

  "reset": "true"

}

200 OK

Deploying API Microgateway

 

Name

URL

Method

Sample Payload

Resopnse

Deploy

https://{{host}}:{{securechannelport}}/api/v1/agent/apimgw/deploy

POST

{

  "dockerImage": {

    "name": "apiproject2",

    "tag": "v1"

  }

}

200 OK

Accessing Managed APIs

The managed APIs can be accessed using the following URL template

https://{{host}}:{port}/apimgw/{path}

  1. host - secure agent host where the docker images are running
  2. port - port number of the ha proxy (default 6095, can be configured using agent runtime properties)
  3. path - relative path of the managed API

Access / Event Logs

API Microgateway captures the API usage audit in access and event logs statements. For October 2020, these are part of the API Microgateway logs for the blue/green docker containers. These logs can be found under

<agent_home>/apps/ApiMicrogatewayService/logs folder.

 

Sample Access Log

 

2020-09-15 16:22:33,912 INFO [] - Access Log :: Endpoint: /apimgw/soap/BasicAuthGroup_Lin Verb: POST IPAddress: 10.80.226.83 Protocol: REST AuthMethod: BASIC ProviderURL: https://10.75.149.81:7443/process-engine Status: 200 StartTime: 2020-09-15T16:22:32.393Z Duration: 1519ms

Troubleshooting

API Microgateway Service

  1. API Microgateway Service is not available in the secure agent
    API Microgateway Service requires a separate custom license.
    Inspite of having the license provisioned, if the service is still unavailable, check the agent core logs to find out whether there are any issues with package download and installation on the secure agent.
  2. API Microgateway service goes to stopped state / restarts / error state.
    This can happen due to many factors. Check the agent core logs / Secure Agent audit logs for any specific symptoms that could reveal the cause of the error. The secure agent host having low memory resources can also cause interruption to the API Microgateway services.
  3. How to get the secure channel port of the API Microgateway service
    API Microgateway services will be assigned a secure channel port on startup by the agent core platform. This port is dynamically assigned and will be changed on the service restart. The port will be printed in "apimgw.log" found under the  <agent_home>/apps/ApiMicrogatewayService/logs folder.
  4. Common failures of Build API
    There can two types of failures on the build. WSO2 related errors can happen if the managed API and policies do not conform to the open API specification. The managed API creation validates all the configurations and fails fast to prevent these kind of errors. In case if the project goes to a corrupt irreversible state, it is recommended to create a new project and redo the managed API creation and configuration. To create a new project, change the project name in agent configuration, and restart the agent.
    The second type of error can be from docker image generation, any compliance issues with the docker image/tag names. These inputs have been validated by the build API and failure will indicate the possible reasons.
  5. Common failures of Deploy API
    The deploy API failures are primarily related to docker image deployment. The error messages will reveal the cause of failure. In the case of API Microgateway blue/green deployment, if the previous image is removed from the registry, then the deployment will fail. To overcome this problem, the reset flag can be passed in the payload to force resetting the blue/green deployment states.

API Microgateway

  1. Unable to access the managed APIs
    Check whether blue/green API Microgateway docker containers are running. Check the API Microgateway logs under <agent_home>/apps/ApiMicrogatewayService/logs. Check if the haproxy docker container is up and the corresponding logs for any routing failures.
  2. Rate limit is not applied
    Rate limit specified based on the time block. Say for instance if the rate limit is 5 per minute, the rate limit counter will reset at the start of every minute in the clock. Similarly, if the API Microgateway is updated and redeployed, the rate limit counter will get reset.
  3. IP filtering is not applied
    IP filtering works based on the rules and the order it is defined. The first rule in the list overrides the second one. The last rule is the default rule that allows/denies the entire IP range. Check access/event logs for the application of IP rules and their results
  4. How to stop the API Microgateway
    API Microgateway runs as docker containers. To stop the API Microgateway, stop the blue, green, and haproxy containers.

 

Author: Raja Kumar Thiruvasagam, Development Architect, Informatica.