Zowe CLI — Getting Started, Made Easy!
{Core} Fresh out of the oven from the Zowe CLI squad is an enhancement that improves the initial setup of the command line interface by making configuration information easier to share and easier to store within projects.
Status Quo
The Zowe command line interface interacts with z/OSMF out of the box but can be extended to integrate with many mainframe services through plug-ins. As of this writing, there are 25 Zowe v1 LTS conformant plugins. Services can typically be accessed directly or via the Zowe API Mediation Layer. In either case, connection information needs to be provided. Rather than specify these settings on every command, users create profiles to store connection information as well as user preferences. In the Zowe v1 LTS version of the CLI, profiles are created from the command line: zowe profiles create … . These profiles can then be updated either from the command line or by editing the profiles directly in the folder structure. They are located in ~/.zowe/profiles/<profile_type>/<profile_name>.yaml.
Profiles are difficult to share in Zowe v1 LTS for multiple reasons. Directories tend to be more challenging to share than a single file. In addition to connection info, profiles may contain user preferences and possibly credential information which should not be shared.
Profiles in Zowe v1 LTS are also global in scope. If you are working on multiple projects interacting with different services, then you may need to switch your default profiles every time you switch projects. Due to this inconvenience, I automated profile configuration in my projects that leverage Zowe v1 LTS. You can see an example in Tip #5 of this blog.
Typically how I observed folks get started with the CLI is that someone within an organization would create a shared set of instructions on what commands to run to get set up. Alternatively, we would see a conversation emerge like the one below:
The Fresh Experience
The new experience focuses on simplifying configuration to a single easily shareable file, separating user preference information, and enabling configuration to be tied to a specific project.
Simplified Configuration
Only one member on a team needs to create this single configuration file. After that, it can be easily shared amongst team members. However, our goal is to make the experience better, even for those creating the initial configuration. To get started, we issue zowe config init --global and open the generated config template.
Let’s walk through two configuration examples. First, we’ll provide a recommendation on how to set up the new configuration file if you are accessing services directly. Then, we’ll provide an example where services are accessed via the Zowe API Mediation Layer.
Remember, after this configuration has been created, it can be easily shared with others either as part of a project (more on that later) or users could copy it into their global configuration.
Accessing Services Directly
First, open a terminal and issue zowe config init -g. If you want to store your creds securely, respond to the prompts for username and password. If omitted, these values won’t be stored and will need to be supplied on subsequent commands. Then, open the generated zowe.config.json. The path to this file should be in the command output. It will be in the hidden .zowe directory under your home directory. This is global location and the config was placed here because the -g flag was specified on the zowe config init command.
First, there is a schema property. The zowe.schema.json file was generated based on the plug-ins you have installed. It provides IntelliSense when editing the document.
Next, there is a profiles property. This is where all shared configuration information will be stored. Nested configuration is supported and is useful for minimizing the number of properties you must maintain. In the initial config template, it guides you to set up the config organized by LPAR. This is how many folks refer to many products/services on the mainframe today. I’m working on CA Endevor on mylpar, for example. Underneath the LPAR level are your services. An initial entry is created for all profile types available based on the CLI plug-ins you have installed. I recommend updating "lpar1" to the actual name of your LPAR. Then you will need to add the hostname of the system. Following that, you can add/edit any other properties needed for your connections.
Next, scroll down to see your base type profile. Base profiles are useful for storing fallback information. Initially, we just see the rejectUnauthorized setting. To be secure by default, Zowe CLI does not interact with services supplying self-signed certificates. If you are working only with services that have self-signed certificates, you can change this value to false.
After that, there are defaults. These are the default profiles of each type to use when running commands. You will need to update all instances of lpar1 to your specified LPAR name.
The plug-ins entry is a work in progress and may be covered in a future blog. Just as we are supporting sharing configuration information for connecting to services, we are considering support for sharing CLI plug-ins. Perhaps a future command would install all plug-ins listed here.
Last, we have the important secure array. This array contains any field that should be stored securely and not checked into source control or shared with others. By default, your base username and password are stored securely. The initial values come from your responses to the prompts of the zowe config init command. To update any secure field, you can issue zowe config secure and respond to the prompts.
Now you can use the CLI to get the real work done! Okay, I’ll admit there was still some work involved. However, the beauty of this approach is it is now done for your team. Nobody else needs to undertake this endeavor. If you provide them with the zowe.config.json you created, they can drop it into their .zowe folder, issue zowe config secure to enter their credentials, and be on their way, accessing as many services as you set up.
Seriously, after copying zowe.config.json, the experience will be like this 😸
Leveraging the Zowe API Mediation Layer
Services flowing through the API Mediation Layer are not organized by LPAR. In fact, you can interact with a service without being aware of the LPAR that is consuming that work. You can even have redundant services on multiple LPARs to improve performance. Here is an example of how I would structure the config.
// accessing multiple services via the API ML (where MFA/SSO is achievable via token-based authentication)
{
"$schema": "./zowe.schema.json",
"profiles": {
"zosmf": {
"type": "zosmf",
"properties": {
"basePath": "api/v1"
}
},
"jclcheck": {
"type": "jclcheck",
"properties": {
"basePath": "api/v1/my_jclcheck"
}
},
"my_base": {
"type": "base",
"properties": {
"host": "example1.com",
"port": 443,
"rejectUnauthorized": true
}
}
},
"defaults": {
"zosmf": "zosmf",
"cics": "cics",
"db2": "jclcheck",
"base": "my_base"
},
"plugins": [],
"secure": [
"profiles.my_base.properties.authToken"
]
}With the API Mediation Layer and Zowe Conformant services, it is not necessary to store credentials at all. You can login to the mediation layer via zowe auth login apiml. Behind the scenes, this will provide your client with an authentication token (securely stored, see the secure array above) that can be leveraged to access services until your token expires. This works especially well in environments where passwords expire frequently or multi-factor authentication is required.
In the upcoming quarter, we are planning to further improve the experience for adopters of the API Mediation Layer and its conformant services. We intend to automatically fill in much of this configuration so all you need to do is connect to the API Mediation Layer. You will not need to determine the base-path for each service.
Additional configuration examples for various environments exist in our documentation.
Separated User Preference Information
In the previous sections, we outlined how zowe.config.json was shareable and how credentials to access services are securely stored. But what if you wanted to store some user-preference information in plain text? You can make use of zowe.config.user.json. To get started, issue zowe config init -g --user and open the generated file. Notice that the structure of this file looks similar to the zowe.config.jsongenerated file. You can specify any custom user overrides you want in this file. zowe.config.user.json enables easy customization while zowe.config.json enables easy sharing.
Project Based Configuration
Project based configuration is my favorite feature of this new configuration. Instead of storing information globally and needing to update your default profiles when switching projects, you can now store CLI configuration information as part of your project. This allows you to switch projects at ease without making any changes. Another important aspect is compartmentalization. The user doesn’t need to mix details from multiple projects, making the contents of the file smaller, easier to understand, and easier to manage.
Project based configuration also enables the use of source control to manage and share zowe.config.json. User overrides are also supported in projects, but you should not check zowe.config.user.json into source control (i.e. add it to .gitignore).
Getting started with project config is exactly the same as with global config, just remove the -g flag. That is, zowe config init and zowe config init --user while your terminal is positioned at the root of your project. Then from anywhere within your project, this configuration will be leveraged when running commands.
Note: if you are leveraging both global and project based configuration, the defaults specified in project config override anything set in global config and if there are like-named profiles, the one specified in project config is used.
Try it Out!
To try this for yourself:
1. Install the next version of the Zowe CLI, npm install -g @zowe/cli@next
2. Verify the installed version via zowe --version, it should be 7.0.0+
3. Follow the steps outlined in this blog, starting with zowe config init
4. Leave us your feedback/issues on GitHub at https://github.com/zowe/zowe-cli/issues
Also, once you have reviewed this functionality, jump over to Dan Kelosky’s blog on Zowe CLI — A Faster Experience to try out some cool functionality also included in this technical preview!
A Note for Extenders
You may have noticed that we initially place some values in zowe.config.json after running zowe config init. We believe these values are commonly modified. We template out these values in order to make it easier to get started. Of course, if you need to add a lightly used property like responseTimeout, IntelliSense is provided when editing in VS Code to help you. Plug-ins can influence what properties are prepopulated to help their users get started. Plug-ins will benefit from the IntelliSense with no changes.
