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.

Workflow steps for the IBM Cloud Provisioning and                 Management plug-in
Workflow steps for the IBM Cloud Provisioning and Management plug-in

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.

The tools directory contains a helper workflow to create a z/OSMF registry for datasource creation.

The properties directory contains the 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 WLP_ENABLE_DVIPA, are flags that you can set to TRUE or FALSE 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 file, each copy with specific configurations.

The workflows directory contains all of the workflow XML files, scripts, server configuration templates, and sample applications:

  • The provision.xml file is the main workflow that is used to create and configure your Liberty server instance. The actions.xml file 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.xml file is an instantiation of all the variables that the workflows use.
  • The templates subdirectory contains all of the scripts that are run by various steps in the workflows. The variables within these templates are pulled directly from the file upon execution.
  • The config subdirectory 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.
  • The apps subdirectory contains three sample applications. At run time, these applications are deployed to the dropins directory in the newly provisioned server. You can use them to test various features by setting the APPS_DIR variable 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 workflows 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 properties file 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:

  1. Download and install Liberty on your z/OS system. The following Liberty releases are compatible: with iFix PI47476,, or 16.x.x.x.
  2. Send your workflows to your z/OS system by using FTP. The workflows/templates/ file 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 file

Configure your workflows as needed. For this tutorial, we use the following simple configuration:

  1. Set WLP_INSTALL_DIR to the directory where you installed Liberty.
  2. Set JAVA_HOME to the Java directory on your system.
  3. Set APPS_DIR to the absolute path of the workflows/apps directory.
  4. Set WLP_ENABLE_DVIPA to FALSE. We allocate unique ports instead.
  5. Set IP_ADDRESS to the IP address of the system.
  6. Set MOUNT_POINT to a writable directory where you want your server instance created.
  8. Set UNAUTH_USER to IZUGUEST (the default).
  11. 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:

  1. Start z/OSMF and log in to the console.
  2. In the left pane of the Cloud Provisioning and Management plug-in, expand Cloud Provisioning and click Software Services.
  3. On the Software Services page, on the Templates tab, click Add Template. Software Services page
    Software Services page
  4. Select the domain under which this service will be provided. We use the default domain.
  5. Define the paths for the template:
    1. In the Template Name field, enter the name of the template.
    2. In the Workflow file field, enter the path of the provision.xml file.
    3. In the Actions file field, enter the path of the actions.xml file.
    4. In the Workflow variables input file field, enter the path of the file. Define the paths for the template
      Define the paths for the template

      Alternatively, you can load the file 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.

      Template service on the Templates tab
      Template service on the Templates tab
  6. 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.
  7. If you are the user who is listed, select the steps, click Actions, and click Approve. Approve the actions
    Approve the actions
  8. 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:

  1. In the left navigation pane, expand Cloud Provisioning and select Resource Management.
  2. Select the domain that you specified when you created your workflow.
  3. From the list of available tenants, select the tenant that you need. We use the default tenant.
  4. Select Actions -> Templates and resource pools -> Add.
  5. 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. Configure the template
    Configure the template
  6. Select Create network resource pool, and click OK.

Configure the network resource pool

To configure the network pools for this template:

  1. In the left navigation pane, expand Configuration and select Configuration Assistant.
  2. On the Configuration Assistant page, select Manage z/OS Cloud configuration, and click Proceed.
  3. On the next page, select the appropriate domain and click Proceed.
  4. On the Systems tab, verify that your Group, Image, and Stack are set up. If they are not setup, create them. Verifying the Group, Image, and Stack setup
    Verifying the Group, Image, and Stack setup
  5. If you create the Stack, allocate two data sets to use for the Include and Dynamic update fields as shown in the following figure. Allocating data sets
    Allocating data sets
  6. On the Network Resource Pools tab, click the pool that you created for your workflow, and select Actions -> Modify.
  7. 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 allocation pool.
    1. On the Port Allocation tab, select Actions -> New.
    2. Enter a name for your port range and a range of the available ports on your system. Port range
      Port range
    3. Ensure that both Is Quiesced fields are cleared.
    4. Click Save to return to the previous page.
  8. 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:

  1. Back on the Software Services page, select your template, click Actions, and select Test Run.
  2. 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.pdf file. 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."

    Being-provisioned status on the Instances tab
    Being-provisioned status on the Instances tab

    You can see the workflow steps running in real time by clicking Workflows in the left pane.

  3. When your server instance is successfully provisioned, refresh the page to view the updated status. Updated status as Provisioned
    Updated status as Provisioned

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.

IP address and dynamic ports
IP address and dynamic ports

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 actions.xml file:

  1. Select your server instance and go to Actions -> Perform.
  2. Select your server from the list.
  3. 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:

  1. In the left navigation pane, expand Cloud Provisioning, and click Software Services.
  2. 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. Published template
    Published template
  3. In the left pane, select Marketplace Administration, and click Add Service. Adding a service to the marketplace
    Adding a service to the marketplace
  4. Select your template, and complete the required fields. Click OK. Defining the service template
    Defining the service template
  5. In the left pane, go to the Marketplace to see your published service.
  6. From here, click Subscribe to request a Liberty server.

    You are prompted with the same fields from when you test ran your template. You see your server instance on the My Subscriptions page.

    Server instance on the My Subscriptions page
    Server instance on the My Subscriptions page
  7. 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.

Downloadable resources

Related topics


Sign in or register to add and subscribe to comments.

ArticleTitle=Bring WebSphere Liberty and the cloud to your z/OS system