Create and customize virtual application patterns
Add components and capabilities with the IBM Workload Plug-in Development Kit
IBM PureApplication™ System supports application-centric deployment models with virtual applications. Deployers describe virtual applications in terms of application artifacts (components and their wiring via links) and required qualities of service (policies). The platform (infrastructure and middleware) that is required to host a virtual application is determined at deploy time.
This Platform as a Service capability is realized by a combination of PureApplication System and workload-specific content. PureApplication System provides a generic framework and extension mechanism for designing, deploying, and managing virtual applications. Workload-specific content is added as extensions (plug-ins). These plug-ins define the components, links, and policies available for describing virtual application patterns, as well as the middleware and automation required to realize the patterns in deployment.
Developers create the plug-ins; deployers use the plug-ins to describe and deploy patterns. This article describes how to create plug-ins using the IBM Workload Plug-in Development Kit.
What is a plug-in?
A plug-in is the primary mechanism for delivering and installing extensions to PureApplication System in support of customer workloads and applications. For example, a plug-in is the basic unit of content for virtual application workloads. It generally implements a specific capability, such as the WebSphere® Application Server (WAS) plug-in which provides components to host WAR/EAR/EBA applications in WebSphere Application Server or the WAS/DB plug-in which provides a link to connect a WAR/EAR/EBA with a database.
Plug-ins provide the key parts of a virtual application, as well as the underlying implementation that makes the application deployable in the cloud.
Virtual Application Builder
PureApplication System provides a Virtual Application Builder (VAB) to construct virtual applications:
- Virtual applications are constructed from components.
- Policies can be applied to components.
- Components can be connected through links.
- Components, links, and policies can have attributes, such as userids, passwords, database names, or archive files, like a WAR file, to which the user assigns values during the virtual application construction process.
In PureApplication System, the completed saved virtual application is
saved as an application model
JSONObject. The app model can
then be deployed.
When constructing a virtual application, the first step is opening the Virtual Application Builder and choosing the pattern type. Pattern types are groups of plug-ins. The pattern type determines your options and user experience in the Virtual Application Builder. The user builds his virtual application from the set of components, links, and policies that the plug-ins in the pattern type chose to expose.
The plug-in that contributes a component or link completely determines its semantics and operation. It is responsible for realizing its embodiment when the virtual application is deployed and through its entire life cycle. For example, a plug-in must contribute proper life cycle scripts to manage the virtual application through its various life cycle events.
Components, links, and policies are the most user-visible capabilities a plug-in may contribute, but there are others. The IBM Workload Plug-in Development Kit is provided to allow you to construct and build your own plug-ins. You can then import these plug-ins into PureApplication System to use them to add new capabilities.
In PureApplication System, users can interact with running virtual applications through operations available on the virtual application console. Plug-ins contribute these operations and their implementation.
What is a pattern type?
Pattern types are the containers of solution-specific and topology-specific resources that are required for different types of virtual applications; they are collections of plug-ins, such as web applications (IBM Workload Deployer Pattern for Web Applications) or databases (IBM Workload Deployer Pattern for DB2 Workgroup Edition).
A PureApplication System cloud administrator can import pattern types and individual plug-ins. Plug-ins may expose global configuration options that can be set by a PureApplication System cloud administrator.
Designing application-centric plug-ins
Plug-ins should be designed for application-centric usage. That means components, links, and policies should represent application artifacts and qualities of service, not explicit infrastructure or middleware artifacts. For example, application artifacts might be WAR files and database instances. A link is required to associate WAR files with the database instances.
Possible extensions include support for elastic scaling of the web application. Scaling is a quality of service which would be modeled as a policy object on the WAR file component. (Adding the scaling policy might result in additional processes in the deployment like a proxy, cache for session replication, etc., but the plug-in handles the details based on the deployer's intent.)
The design should also consider application management. For example, deployers might want to replace the WAR file on the running deployment.
A plug-in developer may choose to create a new pattern type to isolate the user experience. An alternative is to add the plug-ins to an existing pattern type such as the Web Application Pattern Type which gives deployers access to the combination of new and existing plug-ins.
The association of pattern types and plug-ins is controlled by the plug-in. A pattern type represents a named collection; each plug-in can specify its association with one or more pattern types. This member-driven approach enables third parties to extend any pattern type.
Plug-ins can extend PureApplication System in various places, including design time (components, links, and policies), deployment (binaries and automation scripts), transformation logic, and management.
A plug-in declares its associations to pattern types in a
patterntypes object A plug-in may associate with one primary
pattern type and one or more secondary pattern types. A primary
association implies licensed association; secondary associations may also
be specified to show simple sharing. If a primary is specified, then the
plug-in is not made available until the primary pattern type has been
packages object provides an abstraction for the specific
parts delivered by the plug-in. Parts are groups of files installed onto
the virtual machines where needed and parts may be specific to the target
machine (such as an operating system, architecture). The advantage for
transformers — used to transform a component, link, or policy in
the application model into a topology document fragment that can be used
for deployment by the framework — is that a transformer simply adds
packages to vm-templates; PureApplication System later resolves the
packages into parts according to the target machine. Thus transformer
logic does not need to deal with machine specifics.
What can the PDK do?
The PDK is a tool designed to help PureApplication System plug-in developers build their own plug-ins and pattern types for Workload Deployer. The PDK contains a plug-in and pattern type build environment, samples, and a tool to create new plug-in projects. For more information, see the Plug-in Development Guide.
Plug-ins and pattern types are built and packaged using Apache Ant. The PDK provides Ant XML build files for this purpose. These build files can be run from the command line or from within Eclipse (other development environments may also work, but the toolkit only supports command line and Eclipse).
The requirements for using the PDK are:
- Java™ SE6, 32-bit,
- Apache Ant, 1.7+.
- Eclipse V3.6.2, 32-bit. The Java Enterprise Edition (JEE) version is recommended.
Eclipse is not required, but if you use it, use the version listed above. If you use Eclipse, you can use the Ant that comes with it and do not need to install Ant separately. Ant is in your Eclipse installation directory at eclipse/plugins/org.apache.ant_1.*.
Installing the PDK
The first step is to download the PDK to your workstation. You can download the PDK from your PureApplication System from the welcome screen after login or from the PDK wiki. The PDK comes as a ZIP file and once it is downloaded and extracted, open a command prompt in the directory where you extracted the ZIP file and run Ant.
The PDK is a licensed product. When you run Ant, a license screen displays. You must accept the license presented to continue and unpack the contents of the PDK. You will see the PDK contents afterwards.
Introducing the patterntype.hello sample
The hello sample pattern type allows deployment of a simple hello virtual application. Pattern types may provide components, links, and policies which can be used in the Virtual Application Builder to construct virtual applications.
The hello pattern type has two components and a link:
- HCenter: This component deploys a virtual machine containing a simple message center middleware named HelloCenter. HelloCenter opens port 4000, listens to client requests, and generates and returns greeting messages.
- Hello: This component deploys a VM containing a client component of HelloCenter. The client sends a request with the message sender identity to the HelloCenter and tries to get the returned greeting message and display the message on the console.
- HClink: This link links Hello and HCenter components. It provides the Hello client with the IP address of the HCenter server which allows the client to send a request to the server. This link also has an attribute that specifies the receiver name of the greeting message.
In the hello example, each component and link is provided by its own plug-in of the same name. In general, a plug-in may provide any number of components, links, and policies.
Building plug-ins and pattern types with the PDK
To build a plug-in or pattern types from the PDK, from the command line enter:
cd iwd-pdk-workspace/plugin.depends ant /*This command will build all the plug-ins in the workspace.*/ cd ../patterntype.hello ant -f build.patterntype.xml /*This command will build the hello pattern type, the sample included in the PDK described following. The export directory contains the built pattern type ready for installation into IWD.*/
Note that these Ant build scripts can be run from Eclipse (or your IDE) by right-clicking on the build.xml file and choosing Run As > Ant build.
After building the hello pattern type, you can import it into PureApplication System, construct a virtual application from its components, and deploy the virtual application.
PDK contents and details
The remainder of this article discusses the PDK contents in detail, including the sample application.
The plugin.depends project/directory
The plugin.depends project/directory contains Workload Deployer plug-in libraries for development, build tools for plug-in and pattern types, and an Ant build library, including:
- The lib folder that includes all of the Java archive files (JAR) that are required for plug-in development.
- The lib-build folder that includes all of the libraries required for the plug-in build script.
- The build/build.plugins.xml file which is the base internal build script file for single plug-in building. The build script file of each plug-in imports this build script file first then adds more actions if necessary.
- The build/build.patterntypes.xml which is a generic pattern type building script. The build script file of each pattern type imports this build script file first then adds more actions, if necessary.
- The create.plugin.project.xml file which is an Ant script used to create projects for the plug-ins in your workspace.
You can use the create.plugin.project.xml of plugin.depends to create projects for your plug-ins. This file creates a template or a Java-based plug-in project. There are two required parameters: project-name and plugin-name. Using these two parameters creates a template project. The third parameter, java.classname, is optional. If a valid class name is given, a Java plug-in project is created. The class name can be a simple name like MyPlugin or a package-qualified name, like com.acme.iwd.plugin.MyPlugin. And it's important to not put .java on the end, since that extension is assumed.
- plugin-project-template is used by the create.plugin.project.xml Ant script to create plug-in projects.
Sample pattern types and plug-ins
There are four projects in the form of plug-ins included in the PDK ZIP package. These plug-ins show how to design an application model, configuration, virtual machine template, and Python scripts of a plug-in.
The plug-in project of HCenter plug-in
This plug-in provides the HelloCenter component that represents the deployed VM with the HelloCenter server function. In this plug-in, you can learn how to write the life cycle scripts such as install, configure, start, and stop for middleware like HelloCenter. You can use the following Python scripts:
- install.py: Downloads artifacts from storehouse and installs the
middleware. If you want to download and extend the TGZ installation
file from the storage server, use the
- configure.py: Downloads the artifacts uploaded by the plug-in and configures the middleware and opens the firewall to accept customer requests. Export its IP address.
- start.py: Starts the HelloCenter server and changes the role status to Running.
- stop.py: Stops the HelloCenter server.
You can also access the maestro module and use the logger to log your
messages. For more details about the maestro module and the advanced log
maestro.trace_call, see the plug-in PDK.
The plug-in project of Hello plug-in
This plug-in provides the component that represents the deployed machine that accesses the HelloCenter, so it must work together with the HClink plug-in. This plug-in contains the following scripts:
- configure.py: Logs the sender information.
- start.py: Changes the role status to Running.
The plug-in project of HClink plug-in
This plug-in links Hello and HelloCenter and is installed along with the Hello plug-in on the same virtual machine. The following script is included in this plug-in:
- changed.py: This script runs only after the Hello and HelloCenter plug-in roles are in the Running state. This script checks to see if the depended role HelloCenter exists and reads the transferred parameters from HelloCenter which is exported in the HelloCenter configure.py script. The change.py script uses the HelloCenter IP address to access HelloCenter and prints the returned messages. This script also shows how to localize your messages.
With Hello, HelloCenter, and HClink plug-ins, learn how to:
- Transfer parameters between two plug-ins.
- Make two or more plug-ins work together.
There is a sample application model and configuration, virtual machine template, and virtual machine template configuration included with the plug-ins.
You can design your artifacts based on these sample application models, configurations, virtual machine templates, and virtual machine configurations rather than creating them from the scratch. For more details, see the PDK.
The pattern type project of patterntype.hello
In the pattern type project of patterntype.hello:
- The patterntype.json file provides a sample on how to configure your pattern type.
- The build.patterntype.xml file is used to build the pattern type into a package. Attention: Before running this script, you must run the build.xml in the plugin.depends project to build all plug-ins in your workspace.
- The licenses folder includes all license documents of all supported languages.
- The locales folder stores all translated files of all supported languages for the message.json file.
We hope this article has provided a good tour of the IBM Workload Plug-in Development Kit. But wait ... there's more. The companion article, Using the IBM Workload Plug-in Development Kit, describes four basic tasks to give you some hands-on experience with the PDK.
- Find IBM PureSystems resources on developerWorks
- In the developerWorks cloud developer resources, discover and share knowledge and experience of application and services developers building their projects for cloud deployment.