WSO2 Puppet Modules - New Architecture and Deployment
By Samitha Chathuranga
- 9 Oct, 2017
WSO2 Product Deployment
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.
Some Practical Scenarios to Consider
Configuring the WSO2 API Manager fully distributed deployment with the Analytics-server (this is titled as deployment pattern-3 ) 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 . This might take a few hours for many, 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, complex task for a new WSO2 user and even a WSO2 expert would 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:
- 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.
- Server instances completely go down.
In cases such as this, do we have to repeat the same previous process again to redeploy the setup?
Ease of Product Deployment
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).
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 . We will describe this in detail in the next section.
Two sets of users would require knowledge on Puppet-with-WSO2:
- Users who directly want to setup/configure a Puppet environment to deploy a certain enterprise production deployment.
- 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, however both will need thorough knowledge on environment setup.
Brief Overview of Using Puppet with WSO2 Products
For beginners of Puppet who are preparing to tackle WSO2 Puppet modules, the following is a very simple introduction to Puppet.
This diagram (Figure 1) 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 WSO2 Puppet module repository (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.) so as 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 the other one is api-manager.xml (configuration file in the vanilla pack).
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).
When Puppet is “run”, 3 basic steps are executed as illustrated in the above figure. (Please note that we used the phrase “run puppet” to simply and denote a process that implements the puppet configuration automation execution which may occur through various approaches.
- Apply the configuration data (of the required pattern/profile), into the Puppet template files.
- Replace the vanilla wso2am-2.1.0 product's pack’s configuration files with the modified template files of Step 1.
- Copy the modified product pack in Step 2, into the production environment (virtual machines, physical servers) and start the product server.
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 adaptively, supporting customizability and reducing redundancy.
Currently WSO2 maintains a new Puppet module organization, under a new architecture from late 2016 which is very different from the old legacy Puppet releases   that were made from the WSO2 Puppet-modules repository. 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):
Both points listed in 2 and 3 are required for a Puppet deployment of a WSO2 product. 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.
1. The 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). 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:
- wso2am_runtime - WSO2 API Manager 2.1.0
- wso2am_analytics - WSO2 APIM Analytics Server 2.1.0
- 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 provides certain features for installing and configuring WSO2 products. An overview of its functions is listed below:
- Install Java Runtime
- Clean CARBON_HOME directory
- Download and extract WSO2 product distribution
- Apply Carbon Kernel and WSO2 product related patches
- Apply configuration data (hiera data)
- 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 2 approaches to setup a Puppet environment:
- Using Vagrant and Oracle VirtualBox
- 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, this is not the recommended approach from the beginning. Yet if you are not a newcomer to Puppet and knowledgeable of how Puppet modules work with WSO2 products, then you may use this approach.
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.
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
|Convenience of setup||High||Very low|
|Convenience of debugging||Low||Very high|
|Environment up-time||Very high||Low|
|Good for Puppet beginner||No (can learn less about puppet )||Yes (can learn a lot about puppet)|
|OS/instances required||Single OS/instance is sufficient (until hardware specs support)||One OS/instance needed per product node|
|Recommended usage||Test a WSO2 product Puppet module (may be after relevant template or hiera data customizations)||Deploy/install WSO2 products in an actual production environment, develop a Puppet module from the beginning, and do major customizations to the existing puppet modules|
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 .
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 one of which 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 and organized functionally in three types of repositories as 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.
-  https://docs.wso2.com/display/AM210/Deployment+Patterns?preview=/58468521/58589966/apim-2.1.0-pattern-3.png
-  https://docs.wso2.com/display/am210/Distributed+Deployment+of+API+Manager#ClusteringtheAPIManager-ConfiguringtheAPIPublisher
-  https://docs.wso2.com/display/PM200/Introduction
-  https://docs.wso2.com/display/PM210
-  https://github.com/wso2-attic/puppet-modules/releases
-  https://docs.wso2.com/display/AM210/Using+Puppet+Modules+to+Setup+WSO2+API-M
Table of content
- Configuration Automation
- Brief Overview of Using Puppet with WSO2 Products
- Organization of WSO2 Puppet Repositories
- Setting-up a Puppet Environment
- Samitha Chathuranga
- Software Engineer
- WSO2 Inc