IBM z/OSMF - Group home

Provision z/OS network resources using Cloud Provisioning and Management and Ansible

  

IBM Cloud Provisioning and Management for z/OS (CP&M) provides integrated infrastructure in z/OS to support automated and repeatable processes for middleware configuration and consumer-driven provisioning of middleware as a service. CP&M can speed up z/OS application environment provisioning significantly, thus improving the application developer’s agility and efficiency. For details, see the CP&M content solution page: https://www.ibm.com/support/z-content-solutions/cloud-provisioning/

A key component of Cloud Provisioning and Management is the pre-defined resource pools from which resources are obtained during z/OS application environment provisioning. These resource pools represent z/OS resources, such as:

  • Network resources, such as TCP/IP ports and DVIPA
  • Security resources
  • Workload management (WLM) resources.


CP&M provides interfaces that its middleware provisioning workflow uses to obtain resources from these predefined resource pools dynamically.


Though the main capability of Cloud Provisioning and Management is to provision a complete application environment, such as CICS, IMS, IBM MQ queue managers, Db2 subsystems, WebSphere Liberty servers, Cloud Provisioning and Management can be also used to provision specific z/OS resources. You can write a z/OSMF workflow and create a template that invokes the interfaces provided to obtain z/OS resources. Using such a  “micro-service” template, you can provision z/OS users, network resources, file systems, and so on.


In this blog, let’s look at an example of “micro-service” template published in the ‘zorow’ open source community, which can be used to obtain network resources in a self-service model using the Ansible playbook.


Get the template:
Use following link to download the network resource provisioning template manifest and XML files from the ‘zorow’ open-source community.
https://github.com/openmainframeproject/zorow/tree/master/provisioning-workflows/zOS/NetworkResources

Review the README.md documentation provided with the template and transfer the template manifest and XML files to a z/OS system in binary format. As described in documentation, make sure that Cloud Provisioning and Management is configured and running on your z/OS system.

Configure the template:
Log in to z/OSMF and launch the Software Services task. Here, you will create a template in the ‘default’ domain by using the template manifest file that you downloaded to the z/OS system. In this example, we’ll use the default domain that comes with Cloud Provisioning and Management, but you can use another domain, if you have one configured in your environment.  To see how to create a template, watch the following video. You won’t need to make any further modifications to the template after you create it.
https://mediacenter.ibm.com/media/0_ds5t1cbr

Configure a resource pool for the template:
After you have created the template, you can associate it with the ‘default’ tenant in the ‘default’ domain, and then create a resource pool for the template. If you have defined a specific tenant, you can create the resource pool for the template to your choice of tenant. To learn how to create resource pool for the template, see the following video. Note that the network resource provisioning template requires a network resource pool to be setup. Therefore, as described in video, select ‘Create Network resource pool’ when creating resource pool.

https://mediacenter.ibm.com/media/0_tarv9ew3

 

At this point, the resource pool is in “Incomplete” state. Here, you must work with your network administrator to define a network resource pool. To learn how to create network resource pool for the template, see the following video. After the network resource pool is defined, the resource pool for template automatically switches to “Complete” state.

https://mediacenter.ibm.com/media/0_b9hz9t6s

Test and publish the template:
After the resource pool is in ‘Complete’ state, you can test-run and publish the template. Doing so will allow consumers identified in the tenant definition to obtain network resources by using the network resource provisioning template. To learn how to test-run and publish the template, see the following video.
https://mediacenter.ibm.com/media/0_dxypa7uq

Provisioning z/OS network resources with Ansible:
Cloud Provisioning and Management provides ansible roles and sample playbooks in ibm_zos_zosmf collection, which is available in the Ansible Galaxy. For the steps to follow to install and set up Ansible to drive the CP&M playbook, follow the instructions provided in the documentation site:

https://ibm.github.io/ibm_zos_zosmf/index.html

After you download the collection, follow these steps to set up the playbook to provision network resources, such as a TCPIP port.

  1. Update the inventory to manage the target z/OS system. To update the hosts file, see the following documentation:
    https://ibm.github.io/ibm_zos_zosmf/playbooks.html#inventory
  2. If /tmp directory is not appropriate to save provisioned instance specific data, update the instance_record_dir variable in host specific host vars file. See the following documentation for more details:
    https://ibm.github.io/ibm_zos_zosmf/playbooks.html#host-vars
  3. Make a copy of sample playbook sample_role_cpm_provision.
  4. Update the playbook to point to the host identified in ‘hosts’ file.
  5. Update the template specific fields highlighted below. Network provisioning template also requires ‘input_vars’ as mentioned here. Specify the job name of the server that will be using the provisioned port. If the job name is not known, you can specify “*”. If the network resource pool is setup with application specific usage type you must specify the usage type. In this example, usage type is left blank because the network resource pool is not setup with usage type.
  6. When the playbook completes, the resources obtained from z/OS are written out to the file in the directory identified by the ‘instance_record_dir’ parameter in host_vars. You can add following logic in the playbook to display the ports obtained from the z/OS.


    - name: Display results

          vars:

               instance_info_json: "{{lookup('file', instance_info_json_path)}}" # Path of the instance json file contains cics public variables

          set_fact:

             NEW_PORT: "{{ instance_info_json['registry-info'] | json_query('variables[?name == `PORT`]') | join(' ') }}"

        - name: Display

          debug:

              msg: "Newly allocated port number : {{ NEW_PORT.value }}"

  7. After the playbook to provision the network resource is updated, run the playbook. Switch to ../ibm_zos_zosmf/playbooks directory and invoke the following command to run the playbook. Replace the playbook_name with the playbook that you created:
    ansible-playbook -i hosts playbook_name.yml

    Enter your z/OS credentials when prompted.
  8. After the playbook to provision network resources completes, you will see the file name which contains instance specific data. Make a note of the file name; you will need it for running the deprovisioning action. The port number returned from the Cloud Provisioning and Management is also displayed if you added logic to the playbook, as mentioned previously.

Deprovisioning z/OS network resources with Ansible:

Follow these steps to set up the playbook to deprovision the provisioned network resources:

  1. Make a copy of sample playbook sample_role_cpm_manage_instance
  2. Update the playbook to point to the host identified in ‘hosts’ file.
  3. After the playbook to manage the provisioned instance is updated, run the playbook. Switch to ../ibm_zos_zosmf/playbooks directory and invoke the following command to run the playbook. Replace the playbook_name with the playbook that you created.
    ansible-playbook -i hosts playbook_name.yml

    Enter your z/OS credentials when prompted. Enter the file name associated with the provisioned instance and specify the ‘deprovision’ action to perform.
  4. When the playbook completes, you should see the following results. The provisioned port is returned to the network resource pool that is managed by Cloud Provisioning and Management.

In this example, playbook is written to prompt for various input such  use credentials, the path to the instance info file and desired action, but for most users' scenarios those values can be pre-set with variables and in turn the playbook can be run in a fully automated fashion.