10 Oct, 2019

WSO2 API Manager for Pivotal Cloud Foundry

  • Muhammed Shariq
  • Software Engineer - WSO2

Full API lifecycle management for Pivotal Cloud Foundry

WSO2 API Manager is an open-source solution to design, develop, publish, document, and consume APIs in a secure manner. The solution is highly extensible and customizable and can be deployed in highly scalable configurations.

Pivotal Cloud Foundry (PCF) is a multi-cloud platform to develop, deploy, and manage enterprise applications in a highly available and highly scalable architecture. PCF abstracts the underlying infrastructure platform, thereby allowing to run PCF on most popular infrastructure providers, including AWS, GCP, Azure, and VSphere.

WSO2 API Manager for Pivotal Cloud Foundry brings WSO2 API Manager’s cutting-edge capabilities to PCF. The API Manager tile for PCF can be downloaded from PivNet. Organizations with an existing PCF infrastructure can install a distributed API Manager deployment on PCF with a few clicks. The tile provisions a fully configured, ready-to-use API Manager deployment complete with analytics capabilities that eliminates the need for manual configuration.

Architecture of the API Manager tile

The PCF tile for WSO2 API Manager is built using native PCF components. Refer below for details on the tile’s building blocks.

What is a PCF tile?

A tile in the PCF world is a self-contained archive that contains a set of software that is intended to be installed in a PCF environment, which, in turn, makes a set of software services available for application developers. The archive itself should have the “.pivotal” extension and is typically installed via the Ops Manager. User inputs required to run the software can be passed to the tile via the Ops Manager during the installation process.

The API Manager tile simply wraps a BOSH Release and provides custom forms to fetch user inputs required for the installation process.

What is a BOSH Release?

Cloud Foundry BOSH is a tool for release engineering, which is capable of managing deployments and the lifecycle of distributed systems. Through its Cloud Provider Interface (CPI) abstraction, BOSH is capable of supporting multiple infrastructure as a service (IaaS) providers, such as AWS, GCP, Azure, and more. BOSH allows software developers and distributors to package their software in an infrastructure-agnostic manner, thereby unifying the software release process.

A BOSH Release is a versioned archive produced by BOSH. It contains a set of software packages and instructions/scripts on how to install/execute it. In other words, a BOSH release is a comprehensive software package that includes all the required binaries (e.g., database drivers), configuration files, startup scripts, and anything else required to deploy and run software in a reproducible manner.

Key components of a BOSH Release

At a higher level, there are three main components used to create a BOSH release.

  • Jobs → An application or a service that is spawned/executed as part of the release. A job would typically be executed in a VM of its own, known as Job VM. A job consists of a spec file (i.e., job specification), monit file (i.e., a monit script to monitor the job process), and a templates directory. The templates directory contains configuration files that have values that change based on the deployment (e.g., database connection information). Templates files are written using the embedded ruby (ERB) format.
  • Packages → Packages provide binary distributions and dependencies that are required to execute jobs.
  • Source → Contains the source files that are required by the packages. These source files are compiled into executable binaries when the BOSH release is compiled.

Internals of the WSO2 API Manager tile for PCF

The WSO2 API Manager for PCF tile simply wraps a BOSH release of WSO2 API Manager. The tile provides a convenient mechanism for configuration via forms. Operators configuring the tile should configure it with appropriate values prior to installation.

WSO2 API Manager requires external databases that store various information, such as API metadata, user data, and security tokens. The underlying database server can be a managed service such as Relational Database Services on AWS or an on-premises database server. The API Manager tile abstracts out the underlying database infrastructure by prompting the operators to enter the database connection information via forms.

Another prerequisite to install the API Manager tile is a WSO2 Subscription. Since the tile contains all the latest updates shipped by WSO2, only users with a valid WSO2 Subscription can install the tile. If you do not have a subscription, you can sign-up for a 15-day free trial subscription, which would allow you to install the tile and try it out.

Figure 1: A high-level architecture of WSO2 API Manager’s tile for PCF

The above diagram shows the high-level component architecture of WSO2 API Manager for PCF. The tile provisions a distributed API Manager deployment that allows the API gateway and key manager to be scaled independently.

The WSO2 API Manager tile consists of the following BOSH jobs.

  • wso2apim → this job consists of the API publisher, API store, and the traffic manager component. Two instances (VMs) of the wso2apim job will be spawned once the tile is successfully installed.
  • gateway → as the name suggests, this job spawns up API gateway instances that server API traffic. Two instances of the gateway node will be spawned by default, but the gateway node can be scaled up to ten instances.
  • keymanager → this is the component responsible for creating tokens required to access APIs and also validating those tokens. As with the gateway instance, the keymanager instance can also be scaled up to ten nodes.
  • apim_analytics → the analytics job gathers stats published by the other jobs, aggregates them, and stores them in relevant databases so that information can be visualized by the publisher and store applications.
  • nfs_server → an nfs server job is used to synchronize files between jobs. For example, the nfs server is used to synchronize API artifacts between the gateway instances. This way, if additional gateway nodes are added on-demand, the API artifacts will be made available to the new gateway nodes via the nfs server.

The aforementioned jobs have to be configured correctly in order to run. For example, the wso2apim job should be configured with the database connection information and the gateway job should be configured with information to connect to apim_analytics instances to effectively publish statistics to the analytics. In order to achieve these tasks effectively, several native BOSH constructs are used. A brief overview of these constructs are provided below.

  • BOSH Properties → BOSH properties provide a convenient mechanism to parameterize a set of values in a BOSH job. As discussed in the previous section, a BOSH job consists of templates that are ERB templates. Values that have to be parameterized can be implemented as BOSH properties, which, in turn, marks them as placeholders that are evaluated during the tile installation process. Properties in a job template can be denoted using the syntax ; <%= p(“property.name”) %>. During the tile installation process, each and every property is evaluated and parsed before it is sent to the job VM.
  • BOSH Links → BOSH links is absolutely essential when one job VM requires to communicate with another job VM. For example, the gateway instance needs to know the IP address of the analytics instance in order to publish statistics. BOSH links provide a convenient mechanism to discover other instances in the deployment and link to those. The following snippet;<%= link(“link.name”).instances[0].address %> can be used to obtain the IP address of a dependent job VM.
  • Route registrar → The route registrar component of the routing release is used in order to register API Manager components with the Gorouter. The route registrar provides a convenient mechanism to expose the API publisher, API store, and the gateway internally for applications running with PCF and also for external users.

Note that the previous section provides a brief overview of BOSH components used to implement the WSO2 API Manager bosh release. For more information on how to implement BOSH releases using these components, please follow the embedded documentation links.

The key benefits of running WSO2 API Manager on PCF

  • Monitoring jobs with monit → Each BOSH job consists of a monitoring script based on the monit utility. This ensures that the job is always running by checking the process ID of the job. If by any chance the process is not running, monit will automatically start the job, thereby eliminating the need for human intervention while also minimizing downtime.
  • Monitoring job VMs → Hardware failures and VM crashes are inevitable when running at scale on IaaS platforms. The BOSH Director, which manages the job VMs and the deployment at large, is capable of detecting any job VM crashes. The Director automatically respawns the VM and initializes the job, which again eliminates the need for manual intervention. Since the platform itself provided monitoring and auto-healing capabilities, there is no need to install additional monitoring tools.
  • Log aggregation → PCF provides a convenient mechanism to aggregate logs produced by applications running in a job VM. These aggregated logs can be downloaded via the Ops Manager. Thus, log files can be obtained via a centralized UI instead of having to ssh into the VMs.
  • Automatically expose services via Gorouter → PCF provides an inbuilt router named Gorouter, which is capable of handling internal and external traffic. As part of the tile installation, API Manager is registered with Gorouter, which allows apps running in Pivotal Application Service (internal traffic) as well as API developers/consumer (external traffic) to access API Manager. The API publisher, store, and gateway components can be simply accessed via Gorouter.
  • Scaling → The API Manager tile by default will deploy two instances of each job VM to ensure high availability. However, based on the load, the API gateway and the key manager components, which receive the bulk of the traffic, can be scaled up to 10 VMs each. Scaling up the number of job VMs can be done via the Ops Manager itself and does not require any downtime or additional configurations.
  • Easily apply OS updates → The operating system for a job VM is provisioned via a stemcell. A stemcell is a versioned image of an operating system coupled with IaaS specific packages. The WSO2 API Manager tile is based on the ubuntu-trusty stemcell. Pivotal released a newer version of stemcell, which address various mandatory security fixes as well as other updates via PivNet. In essence, the tile takes care of operating system hardening and updates, thereby reducing the burden on system operators.
  • Easily apply WSO2 Updates → WSO2 provides updates in order to address critical security fixes as well as bug fixes. Applying these updates is critical to maintaining a secure and bug-free deployment. Newer versions of the WSO2 API Manager tiles will be released periodically, which would contain the latest updates released by WSO2. While applying software updates can be cumbersome at times, installing updates for WSO2 API Manager running on PCF is as simple as uploading the newer version of the tile and installing it via Ops Manager.

What’s around the corner?

The WSO2 API Manager tile for PCF simplifies the installation of WSO2 API Manager on PCF. The next step is to provide functionalities necessary for an application running on Pivotal Application Service to integrate with API Manager in an effective manner. Some proposed solutions to achieve this are discussed in the next section.

WSO2 API Manager Service Broker for PCF

Service broker is a tool that allows vendors to offer their services independent of the underlying IaaS. Service broker adheres to the Open Service Broker API, which specifies how the lifecycle of a service should be managed. The platforms interact with the service broker provision service and manage those service effectively.

Once the WSO2 API Manager service broker is installed in the PCF environment, users/developers would be able to interact with the broker via the Cloud Foundry CLI. The service broker would provide the following capabilities:

  • Create/delete APIs
  • Create/delete OAuth2 applications
  • Create/delete subscriptions

Once the OAuth2 applications are created, developers will be able to bind it to their applications running on Pivotal Application Services, which would allow the applications to integrate with APIs deployed in WSO2 API Manager in a seamless manner.

WSO2 Microgateway Buildpack for PCF

WSO2 Microgateway is a lightweight, developer-centric decentralized API gateway designed to facilitate microservices architecture. With the proposed Microgateway Buildpack, developers would be able to deploy a microservice as a Cloud Foundry Application by running the cf push command.

Microgateways deployed via the buildpack leverage the advantages provided by Pivotal Application Service, such as auto-scaling and high availability. The Microgateway Buildpack would also be ideal for users with existing on-premises API Manager deployments. Instead of moving the entire API Manager deployment to PCF, organizations can first move the API gateways to PCF by running one or more microgateways that tie into on-premises deployment for throttling policies, analytics, etc. This provides an ideal pathway for organizations interested in migrating their on-premises API Manager deployment to PCF.

Downloading the WSO2 API Manager for PCF tile

The WSO2 API Manager for PCF tile is available for download on Pivotal Network. Instructions for installing and trying out the tile is available in this documentation.


About Author

  • Muhammed Shariq
  • Software Engineer
  • WSO2

Shariq is a Technical Lead and part of the Cloud team at WSO2. His areas of interest include Java Enterprise application design and development, distributed business applications, distributed artificial intelligence, and agent technology.