WSO2 Puppet Modules - New Architecture and Deployment

Introduction

Is WSO2 Product Deployment Complicated?

The WSO2 middleware product stack supports the agility and innovation that is essential for successful digital transformation. The products are designed to serve as the core of any digital business. They are easy to assemble with other parts of an enterprise’s infrastructure and work seamlessly with each other as a single cohesive platform. Because of this, configuring and installing WSO2 products according to your requirement or solution architecture is slightly onerous and time-consuming, especially if your knowledge of the platform and overall middleware technology space is limited.

Thinking About Practical Scenarios

Configuring the WSO2 API Manager fully distributed deployment with the Analytics-server (this is titled as deployment pattern-3 [1]) can be stated as an example deployment which has a total of seven WSO2 server instances needing file configurations and one might need to follow the guide to do it precisely [2] in WSO2’s official documentation to do it precisely. This might take from a few hours to many hours, depending on the doer’s expertise and even after that, it may result in errors at runtime/server-up time, if he or she had followed things incorrectly. So yes it is a time consuming and complex task for a new WSO2 user, though it might not be for a middleware expert or more specifically, a WSO2 expert. A WSO2 expert would still have to expend a few hours to complete this deployment, so the time consumption is an important concern.

There are literally seven WSO2 API Manager deployment patterns, which are used widely and commonly (with differentiations) and it’s impractical to expend that much time/expertise to do this same, standardized procedure repeatedly for multiple use cases.

In spite of the above, sometimes there are requirements for redeployment of a complete enterprise deployment due to particular reasons. For example:

1. If the product servers are running in Amazon EC2 instances, sometimes it will be required to increase the memory or number of CPU cores of the server instances after a few weeks/months of the initial deployment. Set up will need to be redeployed in new enhanced instances.
2. Server instances completely go down.

In cases such as this, do we have to repeat the same previous process again to redeploy the setup?

No it is NOT Complicated in the End!

So at the end of the story, isn’t there a solution to overcome the above mentioned unrequited tasks? Has WSO2 left the users with this complicacy? WSO2 products are introduced as easy to assemble and adapt, hence the answer is no. We will clarify further on this throughout the article and it is not a surprise that the well reputed WSO2 products full of unique and flexible features provide such a solution(s).

Configuration Automation

One solution is Puppet, the well known configuration automation tool which is using either a distributed (Master-Agent) setup or a standalone setup with configuration instructions (which are referred to as manifests in Puppet) that are executed on a target resource (such as virtual machines, physical servers and Docker images) to maintain a given state of a set of resources (such as services and files). This is the definition of Puppet related to WSO2 products [3]. We will describe this in detail in the next section.

Two sets of users would require knowledge on Puppet-with-WSO2:

1. Users who directly want to setup/configure a Puppet environment to deploy a certain enterprise production deployment.
2. Developers who want to customize a WSO2 Puppet module (to facilitate further flexibility with more patterns or add more parameterized configurations).

‘Developers’ require more technological expertise than ‘users’, but in common, both will go through a step called ‘environment setup’.

What is Done by Puppet with WSO2 Products; The Short Story

Before reading further, it is required to clarify, what Puppet does with respect to WSO2 products. For a Puppet beginner, and for those who are ready to tackle WSO2 Puppet modules, the following is a very simple and premature introduction on what Puppet does (this concept could be common for any other puppet module in the middleware world too).

This diagram (Figure 1) simply illustrates what occurs when we use a WSO2 Product (i.e. WSO2 APIM 2.1.0) Puppet module to deploy and configure the product in a prefered environment.

In the repository, which we call WSO2 Puppet module, (for example wso2-apim-2.1.0 puppet module, there are configuration files acting as templates for each file that needs to be edited/configured in a product deployment. E.g. axis2.xml, carbon.xml, master-datasources.xml.

The difference between an actual vanilla product pack's config file and a related Puppet template file is that the latter has been replaced with variables/parameters (assisted with appropriate conditionals, etc.) in order to be able to alter their values at runtime. This can be clarified by examining the following files (as an example related to api-manager.xml config file in wso2-apim-2.1.0); one is the api-manager.xml.erb (Puppet template file).

And a Puppet module basically includes files (hiera files - eg. api-publisher.yaml) with lists of values to be passed to each parameter/variable in each of those config files. These values, which we call hiera data, are defined separately for each deployment pattern (or profile if available).

So when we "run" puppet, 3 basic steps are executed by Puppet as illustrated in the above figure. (Please note that we used the phrase “run puppet” to simply denote a process that implements the puppet configuration automation execution which may occur through various approaches.

1. Apply the configuration data (of the required pattern/profile), into the Puppet template files.
2. Replace the vanilla wso2am-2.1.0 product's pack’s configuration files with the modified template files of Step 1.
3. Copy the modified product pack in Step 2, into the production environment (virtual machines, physical servers) and start the product server.

So this is what is implemented with Puppet, related to WSO2 products. In the next section, the parts and particles of WSO2 Puppet modules will be described.

Organization of WSO2 Puppet Repositories

The Puppet module implementation of WSO2 products is more or less illustrated by the above diagram in Figure 1. However this is only the underlying story within it which could be common for any other Puppet module as well.

WSO2 Puppet modules are designed and organized well adaptively, supporting customizability and reducing redundancy too.

Please note that WSO2 is currently maintaining a new Puppet module organization, under a new architecture from late 2016 which is very different from the old legacy Puppet releases [4] [5] that were made from the WSO2 Puppet-modules repository. So now the Puppet modules of each WSO2 product are in separate git repositories (and so released separately) as opposed to the old structure where all were in one (so released as a single lump). The former WSO2 Puppet-modules repository has now been deprecated and all the latest product related Puppet scripts are written under the new architecture.

If you are going to work with a certain WSO2 product (for a Puppet deployment), you may have to deal with three functional components, which are found as separate git repositories (there are releases made with them and it is better to use those releases rather than the master branch):

1. The certain WSO2 product related repository
2. puppet-base repository
3. puppet-common repository

Both repositories mentioned in points 2 and 3 above are required for a Puppet deployment of a WSO2 product mentioned as 1. Simply, puppet-base is the main controller responsible for performing many tasks and manipulating the processes. It uses some files in puppet-common for certain tasks with the ultimate objective of deploying the related puppet product module (which acts as a real world “puppet”). This is illustrated in Figure 2 below.

Figure 2

1. The Certain WSO2 Product Related Repository

Each WSO2 product has a Puppet-module repository. (i.e. puppet-apim, puppet-is, puppet-das, puppet-esb, puppet-iot, puppet-ei, etc.). Most of these have been released to support the latest product GA release (as per the status by June 2017). The complete list of these puppet module repositories can be found here. These consist of Puppet scripts that support multiple patterns of deployment and multiple profiles if available.

For example, if you are using the WSO2 API Manager Puppet modules (Release v2.1.0), it consists of three Puppet modules that are related to the WSO2 API Manager product. These are listed below, along with the specific product related to each module:

1. wso2am_runtime - WSO2 API Manager 2.1.0
2. wso2am_analytics - WSO2 APIM Analytics Server 2.1.0
3. wso2is_prepacked - Pre-packaged WSO2 Identity Server 5.3.0 (for IS as Key Manager APIM deployment)

The wso2am_runtime module includes Puppet scripts which facilitate deployment of the product API manager in 7 deployment patterns, with 5 APIM profiles. wso2am_analytics and wso2is_prepacked Puppet modules are required to complete these 7 patterns.

2. Puppet-base Repository

Puppet-base is also another Puppet module in accordance with the puppet perspective. The WSO2 base Puppet repository can be found here and it provides certain features for installing and configuring WSO2 products. An overview of its functions is listed below:

1. Install Java Runtime
2. Clean CARBON_HOME directory
3. Download and extract WSO2 product distribution
4. Apply Carbon Kernel and WSO2 product related patches
5. Apply configuration data (hiera data)
6. Start WSO2 server as a service or in foreground

As such, Puppet-base can be described as the basic driver in WSO2 Puppet modules. It gives the instructions for each process in a puppet “run”, using the data and instructions in puppet-common and product-puppet-module.

3. Puppet Common Repository

WSO2 Puppet Common repository provides some non-trivial files required for setting up a Puppet environment to deploy WSO2 products. This is not a puppet module as puppet-base.
manifests/site.pp: Puppet site manifest
scripts/base.sh: Base bash script file which provides utility bash methods.
setup.sh: The setup bash script for setting up a PUPPET_HOME environment for development work.
vagrant: A vagrant script for testing Puppet modules using VirtualBox.

Setting-up a Puppet Environment

There are basically two approaches to setup a Puppet environment:

1. Using Vagrant and Oracle VirtualBox
2. Master agent environment

It is recommended to select the appropriate approach considering the requirement.

1. Using Vagrant and Oracle VirtualBox

Vagrant can be used to set up the Puppet development environment to easily test a WSO2 product's Puppet module. Testing refers to either testing after simple template changes or testing after adding the user specific hiera data accordingly.

In this approach, Vagrant’s duty is to automate the creation of a VirtualBox VM (Ubuntu 14.04) and deploy/install the WSO2 product using the WSO2 Puppet modules.

This approach is far simpler compared to the Master-agent approach considering the convenience of setup. However it is less convenient in the case of debugging for errors as Vagrant takes more time to up a WSO2 product server with Puppet as the process, includes creating a virtual machine in Virtual Box too. If you are developing a WSO2 Puppet module from the beginning, this is not the recommended approach. Yet if you are not a newbie to Puppet, and have good expertise of how Puppet modules work with WSO2 products, then you may use this approach (as you will make less errors).

This Puppet environment cannot be used to deploy and install a certain WSO2 product into an actual production environment, as .this installs the product into a VirtualBox virtual machine which is created automatically on the go.

For more information on using these steps as per the official WSO2 documentation Wikis in github, click here.

2. Master-agent Environment

Master-agent environment can be used to deploy/install WSO2 products in actual production environments. It is best to follow this approach if you are developing a Puppet module from the beginning, performing major customizations to the existing Puppet modules or if your development task would take multiple days/weeks. The reason for this being it is convenient in the case of debugging, testing time for each run, re-running after customizations, etc. Yet it can be slightly cumbersome to setup this master-agent environment as it takes more time and also needs multiple OS instances/computers.

To setup a Master-agent Puppet environment with WSO2 Puppet modules, follow the steps in official WSO2 Documentation Wikis in github.

Comparison of Two Puppet Environment Setting Approaches

The following table summarizes a comparison between the 2 approaches of setting up a puppet environment.

Table 1: Comparison -Vagrant based vs Master-Agent setup

Step by step guides for setting up WSO2 products using puppet modules are provided within READMEs in each puppet module and also in official WSO2 documentation. For WSO2 API Manager, docs can be found here [6].

Conclusion

The deployment of WSO2 products according to the required architecture needs sound expertise and the task can be time consuming. Yet, solutions have been introduced to overcome this and one of them is Puppet. These WSO2 Puppet modules can be used to automate the configuration of WSO2 products for various deployments and widely used deployment patterns are ‘puppetized’ already. Furthermore, developers can customize/enhance them as per their requirements. In order to facilitate this, WSO2 Puppet modules are created in a well organized manner in three types of repositories and understanding of its architecture and their interconnection is substantially important for a developer. Setting up a Puppet environment is an essential task in using Puppet and there are two approaches for it: Vagrant and Master-agent. Users can decide upon which approach to proceed with following the pros and cons of each approach, and how they best suit their requirements.

References

• [1] https://docs.wso2.com/display/AM210/Deployment+Patterns?preview=/58468521/58589966/apim-2.1.0-pattern-3.png
• [2] https://docs.wso2.com/display/am210/Distributed+Deployment+of+API+Manager#ClusteringtheAPIManager-ConfiguringtheAPIPublisher
• [3] https://docs.wso2.com/display/PM200/Introduction
• [4] https://docs.wso2.com/display/PM210
• [5] https://github.com/wso2-attic/puppet-modules/releases
• [6] https://docs.wso2.com/display/AM210/Using+Puppet+Modules+to+Set+up+WSO2+API-M