Zowe™ CLI with IBM Z System Automation plug-in
IBM Z System Automation is a policy-based, self-healing, high-availability solution to optimize efficiency and availability of critical systems and applications. It is designed to reduce administrative and operational tasks; customization and programming effort; and automation implementation time and costs associated with Parallel Sysplex automation and policy-based automation.
IT management is evolving and facing with new challenges like losing z/OS expertise in favor of young talents not used to z/OS interfaces and need to integrate z/OS actions in hybrid cloud applications, processes, and workflow. For this reason, mainframe customers request to the vendors is to modernize their offerings to enable an easier integration in hybrid cloud application, reduce the learning curve for new people facing with z/OS and z/OS tools, in order to protect the investments made on the platform and on the related tools in the last decades.
IBM Z System Automation team keep modernizing the product to support users and customers in this challenging transformation. The most recent feature added to modernize the offering is a plug-in for ZoweTM Command Line Interface (CLI) that administrators and operators can use to interact with IBM Z System Automation, announced as part of IBM Z System Automation v 4.3.
Are you familiar with the Open Mainframe Project’s ZoweTM CLI? Zowe is an integrated and extensible open-source framework for z/OS. Zowe offers modern interfaces to interact with z/OS and allows you to work with z/OS in a way that is like what you experience on cloud platforms today. Zowe CLI provides a command-line interface that lets you interact with the mainframe remotely and use common tools such as Integrated Development Environments (IDEs), shell commands, bash scripts, and build tools for mainframe administration or development. You can use these interfaces as delivered or through plug-ins and extensions that are created by clients or third-party vendors. In a recent blog I described how to use Zowe CLI to create scripts that can fully automate some of your typical, repetitive job scheduling activities, eliminating manual effort and even reducing the potential for errors, thanks to the IBM Z Workload Scheduler plugin for Zowe CLI. In this other blog, I described how to use Zowe CLI to interact with IBM Z NetView and manage automation table statements and more.
In this blog I will describe the main capabilities of Zowe CLI plug-in to interact with IBM Z System Automation, that is shown in the following picture as result of zowe -h command.
Zowe CLI with IBM Z System Automation plug-in commands
What is shown in the picture below is the result of the following command, that returns useful information about the commands that are available as part of system-automation (sa) command group
zowe system-automation -h
I could iterate with the online help for each command to drill down on the different commands, their parameters and so on, but I find more consumable to open the web help where I can find all the commands available for Zowe CLI, easy to navigate. So, I issue the following command
zowe system-automation --help-web
that will open the following page in a browser:
Where you have the list of all the commands available for the plug-in that you have installed in your environment.
This view is easy to navigate, to see all the options for the specific command you need, with samples that can be easily copied and customized:
Another option to see all the commands available without even installing the plugin is to leverage Zowe documentation here.
Zowe system-automation commands drill down
In this section of the blog, I will show some of the commands available. with potential use-cases of them and some tips. The flow is simply based on what I personally made to get used with this Zowe CLI plugin, based on what I though can be useful, however the power of this plugin is so much higher and the limit to the use cases that can be implemented leveraging it is just your imagination.
“list resources” command
Let’s start with the simple list of automated resources if you issue the following command
zowe system-automation list resources
without any filter it will return the full list of automated resources on all the systems managed … that can end-up of being un-manageable even for a small demo environment like the one I am using:
To mitigate the problem, let’s use the filters that are available (you can find all the filters available in the online or web help). In my case, I use the filter on the resource name (with wildcard) and the system:
zowe system-automation list resources --name EAP_3* --system MVS1
What I get as result is the list of the resources belonging to the EAP_3 application group, shown in the Service Management Unite dashboard with the dependency below:
Multiple filters are available for the list resources command, for example you can filter on the type of resources with the option -- type (allowed values are APL, APG, SYS, MTR, GRP, SYG, DMN, REF) to get the list, for example, only of application group:
or on the observed status with the option --observed (allowed values are AVAILABLE, DEGRADED, HARDDOWN, PROBLEM, SOFTDOWN, STANDBY, STARTING, STOPPING, SYSGONE, UNKNONW, WASAVAILABLE) to get the list, for example, of application group with an observed status DEGRADED
Check out all the possible options available issuing the command
zowe sa list resources –help-web
to have a browser page opened for an easy consultation while you are typing your commands or editing the script to invoke Zowe CLI plugin for IBM Z System Automation
“view resource” command
To get the details on a specific automated resource, I leveraged the “view” command. Consider that to identify uniquely an automated resource, the following attributes are required: <<name>> <<type>> and <<system>>, so the 3 options --name <<name>> --type <<type>> and --system <<system>> are needed ... however, it is possible to concatenate them issuing the command with the option
--name <<name>>/<<type>>/<<system>>
like the following
zowe system-automation view resource --name EAP_9PA/APL/MVS1 --showvotes
The result of this command is showed below
As you can see, the output includes
-
-
- general information on the automated resource
- the resource current status (observed) as well as the desired and the compound status
- commands to start and stop the resource (in this example empty)
- the requests that were submitted on the resource
- the votes (added thanks to the --showvotes option)
Important to note that the option -rjf is always available to get the output in JSON format. A JSON file can be then parsed in a script that execute a multi-step procedure, where a step can be dependent on the result of the previous one.
Below you can see the result of the command
zowe sa v resource --name EAP_9PA/APL/MVS1 --showvotes --rfj > EAP_9PA.json
Commands to suspend and resume the automation on a specific automated resource
In IBM Z System Automation v 4.1 an important enhancement was added in order to suspend the automation on a specific automated resource. Leveraging this feature, it is possible to “say” to the product to not take care of the status of the resource until the automation is “resumed”. In some situations, for instance, when maintenance activities require manual startup or shutdown of a resource, the involvement of the automation is not wanted. In fact, it would be even counterproductive if the automation driven by the product "corrected" that. More details about the feature can be found here.
It is now possible to suspend the automation on a specific resource even through the Zowe CLI plugin for System Automation, leveraging the suspend command. In the example below, automation is suspended on the EAP_3PA resource that we visualized previously, extending the command to al the descendants through the option --scope=ALL.
The command used is the following, where we specify even a comment to clarify the reason of the request,
zowe sa suspend resource --name EAP_3PA/APL/MVS1 --comment="automation suspended for maintenance" --scope=ALL
Through the Zowe CLI list command, it is possible to retrieve all the request submitted. Using filters, we can retrieve the requests submitted on a specific resource, like the one we are acting on through the following command:
zowe sa list requests --name=EAP_3PA/APL/MVS1 –showid
The command result shows that DDALTER (myself) submitted a Suspend_All request on the resource specified and it was successfully executed.
It is even possible to get the details of the specific request, through the view command already used above:
If we list the EAP_3* resources, it is possible to check the status of the resource and his child after the suspend command:
zowe sa list resources --name EAP_3*/APL/MVS1
And the details through the view command
zowe sa view resource --name EAP_3PA/APL/MVS1
zowe sa view resource --name EAP_3CH/APL/MVS1
To resume the automation once the maintenance activity is over, it is enough to issue the following command
zowe sa resume resource --name EAP_3PA/APL/MVS1
the effect of this command, once executed, is that the parent and the child applications are back under System Automation control, indeed the “suspend” column is now empty in the result of “list” command
So either the System administrator knows that a specific automated resource is going under maintenance and need to suspend the automation manually, or there is some level of automation that drive the steps needed for the automation, the Zowe CLI commands to suspend/resume the automation can be used to perform the specific step in the maintenance workflow.
Commands to stop and (re)start a specific automated resource
Through the Zowe CLI plugin for IBM Z System Automation is even possible to stop or start an automated resource. Similar to what was described earlier the suspend command, it is possible to add a comment to the stop request (--comment="this is a test to stop a resource"), specify the options to stop even the descendants (--scope=ALL) and specify the priority of the request (--priority=high) through the following commands:
zowe sa stop resource --name EAP_3PA/APL/MVS1 --priority=high --comment="this is a test to stop a resource" --scope=ALL
and to view the details of the request submitted
zowe sa list requests --name EAP_3* --showid
zowe sa view request –id <<request_id>>
In our example the request to stop is still pending … once completed the resource will be stopped as well as the child resource, as you can see through the following command:
To start the resource, the following command can be leveraged:
zowe system-automation start resource --id=RESOURCE_ID --priority=high --comment="This is a request to start the resource"
Commands to work with templates, create and delete dynamic resources
In IBM Z System Automation v4.2 the concepts of template and dynamic resource were introduced. It is a new capability for ad-hoc automation of dynamically provisioned resources (such as CICS regions, IMS message processing regions, WebSphere® Liberty Profiles, and similar workloads) that are based on application templates. Some examples include the form of a cloud-like self-service model or along with rapid DevOps-like provisioning workflows. With dynamic resources, administrators can predefine the shape and form of a resource in a template, building a new automation configuration on one template. Later on, a real automation resource can be created from a template by using a command within IBM Z NetView® or a request driven, for example, through IBM z/OS Management Facility (z/OSMF), without the need to build, distribute, and refresh a new configuration. Learn more about this feature here.
Based on above, it is easy to see a scenario of automated provisioning of a new resource that need to be put under the control of the automation tool in use. If the automation tool is IBM Z System Automation and the proper template was created, the step to add the automation can be integrated in the provisioning automation through the related commands made available as part of the Zowe CLI plugin for System Automation. Let’s see the commands involved in this scenario.
The list command, already mentioned and used earlier, can be used even to list templates available:
zowe system-automation list templates --showid
Leveraging the --showid option we get the ID of the template available, that will be needed to create a dynamic resource … action that is as easy as submit the following command:
zowe system-automation create resource --id=xMXU1sHX19Nh8vDy8mDx8WDw-ePx9Xrw-Xr0-A --name=DYNRES --system=MVS1 --sdesc=”new dynamic resource” --group= DEMOGRP --comment=” request to create a resource from a template”
In the command we specified:
-
-
- the template to be used (through the template id)
- the name of the dynamic resource being created (--name option)
- the system of the resource (--system)
- the description of the resource (--sdesc)
- the application group that will include the dynamic resource (--group)
- a comment for the request (--comment)
Not all the options are required, it is just an example.
To see the created dynamic resource, it is possible to leverage the option --dynamic option of the list command:
zowe sa list resources --dynamic=true
The dynamic resource created is “suspended”, so it is needed to resume it to have the automation in place, through the command that was already used:
zowe sa resume resource --name DYNRES/APL/MVS1
When the resource can be de-provisioned, even the automation needs to be removed … and it is easy though the delete command
zowe system-automation delete resource --name=DYNRES --system=MVS1
Few other commands available
As it was shown at the beginning, as result of the help, so many other commands are available as part of the Zowe CLI plugin for IBM Z System Automation, in this section, let’s see few of them.
The first one is another option of list command, to show all the configuration members currently defined:
zowe sa ls mem
It shows the primary automation manager and the 2 NetView agents. It is useful to see where the Primary Automation Manager (PAM) is running (MVS1 vs MVS2)
Another command very useful is the command the refresh the configuration that updates all SAPlex members (Automation Manager and Agents) with the definition that is stored in the specified policy dataset. Using '*' as policyName causes a refresh of current policy.
zowe system-automation activate policy *
So many other commands are available even to switch the Primary Automation Manager and so on.
Wrap-up
What was shown in the blog is obviously just a small part of the power of the IBM Z System Automation plug-in for Zowe CLI and there is no limit on how many scenarios can be implemented, how much automation you can achieve leveraging this plugin. As mentioned at the beginning, the power of the Zowe CLI is not just the individual commands but the ability to write scripts (in the scripting language of your choice) to build multi-step actions to automate IBM Z System Automation or any other product with Zowe CLI extensions. These scripts can have variable substitution, use additional script functions (grep, awk, etc.) to build powerful productivity tools.
On the other hand, I am aware of users that are leveraging the System Automation plug-in in an interactive way, to avoid using the console just to issue a command, to start a resource or to refresh the configuration. Ultimately, different users will use the plug-in in different ways. The Zowe CLI can have scripts that cross z/OS products and systems to allow coordination of actions in many ways.
A few customers commented on the power of Zowe in general during last IBM zDay 2022. What I found especially interesting was the interview to Stephen Westwood (Lloyds) that talked about the power of IBM extensions of Zowe CLI, describing how he uses in daily basis the Zowe CLI extensions for IBM Z NetView and IBM Z System Automation, take a look at it here. The inspiration for the picture on top of this blog comes from a comment Stephen made. He said that he created a script to update the System Automation configuration on all the systems he manages leveraging the Zowe CLI plugin and while it runs, he can have a toast and a coffee 😊.
An important point to make is that customers that leverage IBM Z System Automation, get IBM Z Distribution for Zowe as supporting program, so the support (for the scenarios that are related to the integration) is granted from IBM at no charge. This is important because many enterprises do not allow unsupported software in their production environment.
If you want to learn more about IBM Z Distribution for Zowe, visit the content page, you can find there other details about IBM product extensions and more.
If you want to download the IBM Z System Automation plug-in for the Zowe CLI, it is available here or from your IBM Z System Automation v4.3 DVD image.
Zowe is owned and managed by the Open Mainframe Project, which is a Linux Foundation project.
#zowe #opensource #IBMz #systemautomation #automation