Bring WebSphere Liberty and the cloud to your z/OS system
Explore the IBM Cloud Provisioning and Management plug-in
In today's enterprise, you need fast and convenient access to development and test environments. However, on IBM® z/OS®, getting access and configuring servers and resources is time-consuming and costly, and the mainframe's steep learning curve presents a challenge especially for teams that are geared for front-end application work. Now, with the IBM z/OS Management Facility (z/OSMF®) V2.2 and IBM WebSphere® Liberty, you can take advantage of a fully functioning cloud environment right on your z/OS system with the IBM Cloud Provisioning and Management plug-in.
With this plug-in, you can dynamically request Liberty servers, and other middleware resources, simply and securely. The IBM Cloud Provisioning and Management plug-in manages the lifecycle of each Liberty instance so that you can provision, deprovision, and start and stop your servers, all from the convenience of a web browser. Your teams can now focus on application development without spending time and resources on manually configuring their servers. Likewise, your test teams can create customized test server environments on demand.
This article introduces you to the IBM Cloud Provisioning and Management plug-in and the configuration options for Liberty. It also takes you through the steps to set up and use the plug-in to create your own cloud environment to provision Liberty on z/OS.
Overview of the Cloud Provisioning and Management plug-in
The IBM Cloud Provisioning and Management plug-in is a workflow engine. It hosts user-defined workflows as services in an externally accessible catalog. You can browse this catalog and request a service. The workflow is then run, and the instance is provisioned. You can then perform specific actions on that instance that are defined within the workflow. In this basic framework, you can customize your service as much or as little as you need, depending on the workflow that you define.
A workflow is an XML file that outlines a series of steps to perform when a request is made. The workflow steps include various actions, such as running scripts, making REST calls, or submitting job control language (JCL) jobs. You can delay or skip steps based on various conditions, and you can even run them under different user IDs for security purposes. You can also customize your workflows with variables that are defined in an external properties file.
To get started in creating your own workflow to provision Liberty, you can use the fully functional samples that are available in the WASdev directory in GitHub. The next section explains the contents of the sample workflows.
Inside the sample Liberty workflows
Download and extract the sample project from WASdev
directory in GitHub. The project contains three directories and some
documentation files. The main documentation in the
Setup_and_Configuration.pdf file explains the workflow steps,
variables, configuration options, and prerequisites.
tools directory contains a helper workflow to create a
z/OSMF registry for datasource creation.
properties directory contains the
workflow_variables.properties file. You can use the
properties file to define all of the variables that are used
throughout the workflows. These variables are broken into sections that
are based on specific features and have descriptions of what they are and
how to set them. Some variables, such as
are flags that you can set to
enable or disable certain features that result in skipping specific
workflow steps. You can also use the
properties directory to
hold copies of the
workflow_variables.properties file, each
copy with specific configurations.
workflows directory contains all of the workflow XML
files, scripts, server configuration templates, and sample
provision.xmlfile is the main workflow that is used to create and configure your Liberty server instance. The
actions.xmlfile outlines all of the actions that are available to a provisioned instance. Selecting any of the actions runs the respective workflow (the other XML files that are listed here). The
Variable_imports.xmlfile is an instantiation of all the variables that the workflows use.
templatessubdirectory contains all of the scripts that are run by various steps in the workflows. The variables within these templates are pulled directly from the
workflow_variables.propertiesfile upon execution.
configsubdirectory contains all of the Liberty server configuration. These configuration files are configured and copied to a newly provisioned server by the workflows according to your customization.
appssubdirectory contains three sample applications. At run time, these applications are deployed to the
dropinsdirectory in the newly provisioned server. You can use them to test various features by setting the
APPS_DIRvariable to this directory (or any directory that you choose). Any applications at that location are deployed to your provisioned servers.
You do not need to configure anything in the
directory for these sample workflows to work. All configuration and
customization is done through the
properties file. However,
you can open these files and see what they look like and do. When you are
familiar with how the steps are structured and ordered, you can change,
add, or remove any that you choose.
Customizable feature highlights
The sample Liberty workflows have many customizable features that are
outlined in detail in the
Setup_and_Configuration.pdf file. A
few highlights are worth mentioning here before you start the tutorial.
Network resource provisioning options
With the Cloud Provisioning and Management plug-in, you can configure and manage network resource pools. This way, your workflow can dynamically allocate unique or shared IP addresses and ports for each workflow instance. These sample Liberty workflows take advantage of these functions, including two configurable options:
- You can use the same IP address for all server instances and provision unique ports from a pre-configured pool.
- You can provision dynamic virtual IP addresses (DVIPAs) from a preconfigured pool and use the default Liberty HTTP port (9080) and HTTPS port (9443).
Location management options
The sample Liberty workflows have several options for you to manage the location of each provisioned instance:
- You can specify a common directory in the
propertiesfile where each server instance will be provisioned.
- You can provision each server instance in the requesting user's home directory.
- Optional: For either of these options, you can create and mount a new z/OS File System (zFS) for each server instance that is created.
DB2 datasource binding
The sample workflows provide the option to bind to an existing IBM
DB2® subsystem during provisioning or on an already provisioned
instance by using the
db2Bind action. Requesting users can
also specify a JNDI name to use for the datasource configuration, allowing
for custom integration with their applications.
This feature requires an administrator to first create a z/OSMF registry for the specific DB2 subsystem. This registry is a set of key value pairs with information that is necessary to configure a data source on the server (that is the location, IP, and port). When you bind the data source to a database, you pass in the name of this registry (the DB2 subsystem name), and the workflow looks up the information it needs.
For convenience, the sample workflows contain a
db2_registry_add_subsystem.xml workflow in the tools
directory. When you run this workflow, it prompts you for the information
it needs and automatically creates a secure registry in z/OSMF.
Security approvals and execution
By default, all workflow steps run under the ID of the user who logged in and requested the server. However, this setting limits the functions of the workflow because some steps might require elevated authority. With the Cloud Provisioning and Management plug-in, steps can run under a different user ID that, for security reasons, was approved when the workflow was created. Various steps in these sample workflows take advantage of this feature. Therefore, the elevated user IDs and the IDs of the approvers must be configured in the properties file before the workflow is run.
Set up and configure the sample Liberty workflows
The following tutorial explains how to set up and configure the sample Liberty workflows. Before you begin, you must have a basic understanding of z/OSMF and the Cloud Provisioning and Management plug-in. The plug-in is available for z/OSMF V2.2 with PTF UI42847 (plus supporting PTFs) as explained in APAR PI70526.
For more information about the Cloud Provisioning and Management plug-in, see the What Cloud Provisioning is topic in the IBM Knowledge Center. Install the plug-in and configure it to allow your user ID access to create and run software services.
To get started:
- Download and install Liberty on your z/OS system. The following Liberty releases are compatible: 188.8.131.52 with iFix PI47476, 184.108.40.206, or 16.x.x.x.
- Send your workflows to your z/OS system by using FTP. The
workflows/templates/wlp-provisioning.shfile is the only file that you need to convert to EBCDIC. All other files are functional in either ASCII or EBCDIC. You might want to convert these files for readability on z/OS. Alternatively, you can use an FTP application, such as FileZilla, to read and edit remote files on your local workstation.
Configure the workflow_variables.properties file
Configure your workflows as needed. For this tutorial, we use the following simple configuration:
WLP_INSTALL_DIRto the directory where you installed Liberty.
JAVA_HOMEto the Java directory on your system.
APPS_DIRto the absolute path of the
FALSE. We allocate unique ports instead.
IP_ADDRESSto the IP address of the system.
MOUNT_POINTto a writable directory where you want your server instance created.
- In the Approval and run-as user ID definitions section, configure the user IDs that will approve and run the elevated steps in the workflow. If you are using a personal test system (as in this tutorial), you can set your ID for all of these properties.
Add a template
A template defines your workflow and the resources that are associated with it. To add a template:
- Start z/OSMF and log in to the console.
- In the left pane of the Cloud Provisioning and Management plug-in, expand Cloud Provisioning and click Software Services.
- On the Software Services page, on the Templates tab, click Add Template.
- Select the domain under which this service will be provided. We use the default domain.
- Define the paths for the template:
- In the Template Name field, enter the name of the template.
- In the Workflow file field, enter the path of
- In the Actions file field, enter the path of
- In the Workflow variables input file field, enter the
path of the
Alternatively, you can load the
provisionWLP.mffile as the Template source file to automatically load configured paths for these fields.
You now see your template service listed on the Templates tab in the "Draft pending approvals" state.
- Select the template, click Actions, and select Approvals. Depending on the values that you set for the step approvers in your properties file, you see a list of user IDs that are authorized to approve various steps in the workflow. You must approve these actions.
- If you are the user who is listed, select the steps, click Actions, and click Approve.
- Close and return to the previous page.
You now see that the state is "Draft approved."
Add the template to a domain
Now that you have created the workflow template, add it to a domain or tenant to configure the necessary resource pools:
- In the left navigation pane, expand Cloud Provisioning and select Resource Management.
- Select the domain that you specified when you created your workflow.
- From the list of available tenants, select the tenant that you need. We use the default tenant.
- Select Actions -> Templates and resource pools -> Add.
- On the next page, select your template, and configure the required fields. For the instance name prefix, select Specify, and enter a prefix to use for server instance naming.
- Select Create network resource pool, and click OK.
Configure the network resource pool
To configure the network pools for this template:
- In the left navigation pane, expand Configuration and select Configuration Assistant.
- On the Configuration Assistant page, select Manage z/OS Cloud configuration, and click Proceed.
- On the next page, select the appropriate domain and click Proceed.
- On the Systems tab, verify that your Group, Image, and Stack are set up. If they are not setup, create them.
- If you create the Stack, allocate two data sets to use for the Include and Dynamic update fields as shown in the following figure.
- On the Network Resource Pools tab, click the pool that you created for your workflow, and select Actions -> Modify.
- On the resulting page, set up your IP and port ranges, depending on
how your workflow is configured. For this tutorial, we use a
configured IP address and unique ports, so we must create a port
- On the Port Allocation tab, select Actions -> New.
- Enter a name for your port range and a range of the available ports on your system.
- Ensure that both Is Quiesced fields are cleared.
- Click Save to return to the previous page.
- On the Attributes tab, select Is Complete to mark your network pool as ready for use. Set the Port Limit. Each server needs two ports. Then, click Save.
You have now configured the network resource pool.
Provision a Liberty instance
Your workflow service is now ready to run. To provision a Liberty instance to run it:
- Back on the Software Services page, select your template, click Actions, and select Test Run.
- On the next page, leave blank the additional runtime options for DB2
binding and group sharing. We do not use these options for this
tutorial. You can learn more about them in the
Setup_and_Configuration.pdffile. Click OK.
You automatically go to the Instances tab, where you see an entry for your new Liberty server instance with the status of "Being-Provisioned."
You can see the workflow steps running in real time by clicking Workflows in the left pane.
- When your server instance is successfully provisioned, refresh the page to view the updated status.
Your Liberty server instance is now provisioned and ready for use.
Click the instance name to see a list of variables that are used in the workflow. Here you can find the IP address that we configured and the dynamic ports allocated.
Test the server instance
To test your server, you can access any of the sample applications that
were deployed to your server. Open a new tab on your web browser, and
enter the following URL:
You see the date, time, and IP address of your browsers.
You can also go to the following URL:
Enter your user name and password. Only the ID that requests the server has access. Again, you see the date, time, and IP address of your browsers.
Now that your Liberty server is up and running, you can run any of the
available actions that are defined in the
- Select your server instance and go to Actions -> Perform.
- Select your server from the list.
- Stop the server and verify that the sample applications are no longer accessible.
Add and publish a service
The IBM Cloud Provisioning and Management plug-in includes a sample marketplace, which makes software services available to marketplace consumers. You can publish your workflow template to this marketplace for a more convenient way for users to request servers. Before you do, import the Cloud Portal plug-in, if you have not already done so. After you import the plug-in, you see the Marketplace and Marketplace Administration links under Cloud Provisioning in the left pane.
To add and publish a service:
- In the left navigation pane, expand Cloud Provisioning, and click Software Services.
- On the Templates tab, select your workflow template, click Actions, and select Publish. Your template is now published (see the following figure) and permission is given to other users in your domain or tenant to access it.
- In the left pane, select Marketplace Administration, and click Add Service.
- Select your template, and complete the required fields. Click OK.
- In the left pane, go to the Marketplace to see your published service.
- From here, click Subscribe to request a Liberty
You are prompted with the same fields from when you test ran your template. You see your server instance on the My Subscriptions page.
- Click the plus sign (+) to view information about your server, such as the IP address and ports. You can use this information to access your new Liberty server and connect it to the WebSphere Developer Tools.
The IBM Cloud Provisioning and Management plug-in provides simple yet powerful cloud capabilities to z/OS. By completing this tutorial, you learned how to set up a basic cloud environment by using sample Liberty workflows. You can now test the more advanced features that the samples provide and expand them to create custom workflows for your environment.
- Liberty Profile z/OS – Quick Start Guide
- WebSphere Liberty articles in the developerWorks library
- developerWorks WASDev Developer Center
- IBM Middleware User Community