Automating post-deployment SAS Viya tasks with REST and the administration CLI
The sas-admin command-line interfaces and the REST architecture, for me, are two of the coolest things about SAS Viya. The CLI's make it easy to automate many administrative tasks, and the REST API makes it easy to fill any gaps in the CLI using your favorite REST client. My group uses these tools a lot to stage, in batch, new SAS Viya images for training and to provide solutions exercises for hands-on in our classes.
You may have heard that going forward containers will be a big part of the SAS Viya landscape. This exercise of a batch process loading content and configuration will become more important as a way to spin up new SAS Viya environments and restore their state.
In a previous article, I provided an introduction to the sas-admin command-line interface. There are two preliminary steps required to use the command-line interface; you need to create a profile and authenticate. You can create and use multiple profiles to connect to different Viya environments. The profiles, once created, are stored in the user's home directory in a file <homedir>/.sas/config.json.
Using separate profiles, an administrator can administer multiple Viya environment from the same machine by switching from one profile to another. While the sas-admin CLI ships with Viya (/opt/sas/viya/home/bin), you can also download and install any plug-ins you need from support.sas.com.
To create a default profile (you can also create named profiles):
sas-admin profile set-endpoint "http:myserver.demo.myco.com"
The profile is stored in the user's home directory in a file <homedir>/.sas/config.json
One of the challenges of using the CLI in scripts which run in batch is how to stay authenticated.
To authenticate using the command-line interface:
sas-admin auth login --user sasadm --password ********
You can also use Kerberos authentication. Regardless of how you authenticate the process creates a token in a file stored in the users home directory which is valid for, by default, 12 hours. The file location is <homedir>/.sas/credentials.json. If your Viya environment is at the default expiration was changed to 10 hours to match Kerberos.
Hard-coding the logon step above within scripts is not really a great idea. In addition to being a security risk, it reduces the portability of the scripts.
One potential approach is to lengthen the expiration period of the token. To change the token expiration, you can:
Change the default expiration for the token
To change the expiration for all tokens issues by the system.
In the SAS Environment Manager > Configuration, select All Services > SAS Logon Manager.
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
Select New Configuration > sas.logon.jwt
Set the values of the following attributes to the number of seconds for the timeout.
policy.accessTokenValiditySeconds
policy.global.accessTokenValiditySeconds
Save the changes.
This could also be accomplished in batch using the configurations plug-in of the sas-admin CLI.
/opt/sas/viya/home/bin/sas-admin configuration configurations create --file "/root/admin/solutions/initialtasks/shared/set_timeout.json"
The json file contains the configuration attributes and sets the expiration to 604800 seconds or 7 days.
Whichever way you create the configuration, you will need to restart the SASLogon service for the changes to be applied.
Register a new client and give it a custom expiration period
Another option is to register your own client ID and when you register it, you can specify the token lifetime just for that client ID. The advantage to this approach is that you don’t impact all tokens issued on the system. The process of registering new client IDs and obtaining tokens to call APIs is documented here. I'll cover more details on this approach in a subsequent article.
Read the Credentials from a .authinfo file
A different approach is to read the credentials from a secure location and authenticate. Authinfo files are currently used in Viya to authenticate from any of the programming interfaces (Python, Java, Lua, Base SAS). Stuart Rogers describes this process: "... the programming interfaces are able to load a set of credentials from a separate file at run-time. This uses an Authinfo file to store the credentials. The default location for the Authinfo file is the user’s home directory. The use of the Authinfo file makes the code far easier to share and means the credentials are stored in one secure file rather than hundreds of unsecured code files."
Currently the CLI does not support using .authinfo file. To support our batch execution, we created a solution to this in the GEL pyviyatools. The pyviyatools use the Viya REST API and the Python requests module to make it easy to develop custom tools to automate administrative and other tasks, usually in cases where the CLI does not have equivalent functionality.
loginviauthinfo.py is a tool that will read credentials from a .authinfo file and use them to authenticate and create a token using sas-admin command-line interface. In this way you can use the tool and an .authinfo file to make your scripts portable and ensure that they do not fail due to expired tokens.
With authentication established, you can use the CLI and, if needed, the pyviyatools to perform administration tasks in batch in your SAS Viya environment.
For more information see:
- SAS Viya 3.4 Administration: Using the Command-Line Interfaces documentation
- Introducing Python-based command-line tools for SAS Viya article
- SAS Viya REST API documentation
- SAS Viya Administration | Command Line Interfaces YouTube video
