Overview of installing and using the SAS Viya containerized CLI
With the 2024.03 release of SAS Viya the sas-viya command-line interface is available for download in a container image. This new feature will be handy for automating SAS Viya administrative tasks. This is a topic I have addressed in the past where we built our own container image containing the sas-viya CLI. In this post, I will provide an overview of the new SAS-delivered sas-viya-cli container image and review how you can install it and use it to perform SAS Viya administration tasks.
Getting the sas-viya-cli container image
To use the sas-viya-cli in a container we need to pull it from the container registry. The sas-viya CLI Container image is available with an SAS Viya license. To pull the container image SAS Mirror Manager is used to identify the latest image in the SAS Container registry and to return the credentials to login into the registry. In this step, passing the certificates from our Viya order, we use mirror manager to return the image name of the sas-viya cli image in our order. The name of the image in the registry contains the string sas-viya-cli. In this step we store the name in the environment variable ${climage} for later use
climage=$(mirrormgr list remote docker tags --deployment-data /home/cloud-user/project/deploy/license/SASViyaV4_${GELLOW_ORDER}_certs.zip --cadence stable-2024.03 | grep sas-viya-cli)
echo Order Number is ${GELLOW_ORDER} and latest image is ${climage}
Output:
Order Number is 9CYNLY and latest image is cr.sas.com/viya-4-x64_oci_linux_2-docker/sas-viya-cli:1.1.0-20240319.1710834807264
To pull the images we need to authenticate to the docker registry. In this step, we use mirror manager to retrieve the login credentials and log in to the docker registry.
logincmd=$(mirrormgr list remote docker login --deployment-data /home/cloud-user/project/deploy/license/SASViyaV4_${GELLOW_ORDER}_certs.zip)
echo $logincmd
eval $logincmd
Output:
docker login -u 9CYNLY -p '!|gd^X3Vq0fVJbiL1h9N1JVJ#0mqf986' cr.sas.com
WARNING! Using --password via the CLI is insecure. Use --password-stdin.
WARNING! Your password will be stored unencrypted in /home/cloud-user/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded
Once we are authenticated to the docker registry we can pull the sas-viya-cli image and tag the pulled image with an easy-to-use name.
docker pull ${climage}
docker tag ${climage} sas-viya-cli:v1
Now we can address the image with the simplified name and test that it works. To do that we will do a docker run of the image and, for test purposes pass the --help command to the CLI. By default, the container image has an entry point, that entry point will run the command sas-viya.
docker container run -it sas-viya-cli:v1 --help
Authenticate to SAS Viya
Now that we have the cli image we can use it for the same Viya administration tasks that we use for the standard sas-viya cli. The same as the sas-viya CL to authenticate we need the .certs file from the SAS Viya environment. In this step copy the certificates file to the /tmp directory.
kubectl cp $(kubectl get pod | grep "sas-logon-app" | head -1 | awk -F" " '{print $1}'):security/trustedcerts.pem /tmp/trustedcerts.pem
The containerized CLI gives us a few different methods to authenticate. The simplest method is to pass the SAS Viya endpoint, the username, and the password in environment variables. In the step below, we use the docker run command to authenticate as sasadm and run sas-viya identities whoami. Notice that to make the certificates file available, we also mount the local /tmp directory to the /security directory inside the container.
export VIYA_USER=sasadm
export VIYA_PASSWORD=lnxsas
export SAS_SERVICES_ENDPOINT=https://gelcorp.pdcesx02193.race.sas.com
docker run -it -e SAS_SERVICES_ENDPOINT -v /tmp:/security -e VIYA_USER -e VIYA_PASSWORD sas-viya-cli:v1 --output text identities whoami
Output:
https://gelcorp.pdcesx02193.race.sas.com
Login succeeded. Token saved.
Id sasadm
Name SAS Administrator
Title
EmailAddresses [map[value:sasadm@gelcorp.com]]
PhoneNumbers
Addresses [map[country: locality:Cary postalCode: region:]]
State active
ProviderId ldap
CreationTimeStamp
ModifiedTimeStamp
NOTE: in this syntax, you must use the export command to set the environment variables. An alternative approach shown below is to use the -e VAR=VALUE.
MY_USER=sasadm
MY_PASSWORD=lnxsas
export SAS_SERVICES_ENDPOINT=https://gelcorp.pdcesx02193.race.sas.com
docker run -it -e SAS_SERVICES_ENDPOINT -v /tmp:/security -e VIYA_USER=${MY_USER} -e VIYA_PASSWORD=${MY_PASSWORD} sas-viya-cli:v1 --output text identities whoami
When you use this approach the sas-viya cli, running inside the container, will authenticate to SAS Viya on every execution. This is achieved inside the container by running an entry-point script that authenticates. The entry point also runs the sas-viya command, meaning that to execute a plugin command, you pass after the container name:
- any options for the sas-viya cli e.g --output text
- the name of the CLI plug-in to run e.g identities
- the plug-in command e.g. whoami
The second method to authenticate is to pass a JWT token. For this method to work, you must NOT have the environment variables VIYA_USER and VIYA_PASSWORD set. But you should set the environment variable JWT_TOKEN to the value of a JWT_TOKEN. If you authenticate outside the container with the sas-viya cli a credentials file is created at ~/.sas/credentials.json. The credentials file contains the JWT_TOKEN and a refresh token. The JWT token is in the “access_token” field and can be extracted from this file. In the code below, we use a Python program, savetoken.py to do this (you can use any tool of your choice). In the example below, the JWT_TOKEN was created when the geladm user authenticated.
unset VIYA_USER
unset VIYA_PASSWORD
/opt/pyviyatools/savetoken.py
export SAS_SERVICES_ENDPOINT=https://gelcorp.pdcesx02193.race.sas.com
export JWT_TOKEN=$(cat /home/cloud-user/.sas/gelcorp_token.txt )
docker run -it -e SAS_SERVICES_ENDPOINT -v /tmp:/security -e JWT_TOKEN sas-viya-cli:v1 --output text identities whoami
Output:
Login succeeded. Token saved.
Id geladm
Name geladm
Title Platform Administrator
EmailAddresses [map[value:geladm@gelcorp.com]]
PhoneNumbers
Addresses [map[country: locality:Cary postalCode: region:]]
State active
ProviderId ldap
CreationTimeStamp
ModifiedTimeStamp
Use the sas-viya-cli contaner Image
There are three main ways we can use the containerized version of the sas-viya CLI.
Run commands and retrieve output
We can run ad-hoc CLI commands using the docker run command and return the command’s output. This is an approach we have already seen in prior examples. Here, we list the current folders in the SAS Viya Environment. Each execution of the docker run commands starts a container, authenticates to SAS Viya inside the container and runs a SAS Viya plugin and command. The plugin and command are passed after the image name on the docker run command. You do not need to specify sas-viya.
docker run -it -e SAS_SERVICES_ENDPOINT -v /tmp:/security -e VIYA_USER -e VIYA_PASSWORD sas-viya-cli:v1 --output text folders list-members --path / --tree
Output:
https://gelcorp.pdcesx02193.race.sas.com
Login succeeded. Token saved.
|—— Public
|—— Products
| |—— SAS Studio Flow
| |—— SAS Environment Manager
| |—— SAS Visual Machine Learning
| |—— SAS Visual Analytics
| |—— SAS Studio
| |—— SAS Analytics Common Services
|—— Users
|—— Model Repositories
| |—— DMRepository
| |—— Public
Output:
Run commands from inside the container
Run sas-viya CLI commands in interactive mode from inside of the container. If you do not add a CLI command after the container name, the docker run command will open a shell prompt inside the container. You can run ad-hoc CLI commands in this shell window. In this example, we start the session, run two report commands inside the container, and then exit the container.
docker run -it -e SAS_SERVICES_ENDPOINT -v /tmp:/security -e VIYA_USER -e VIYA_PASSWORD sas-viya-cli:v1
There is an additional step if your sas-viya command creates output on the filesystem or you need to accept input from the local filesystem. The file system inside the container is ephemeral by default. That means that if we want to persist file-system output from a CLI command, we need to mount a location from the local filesystem into the container. In the example below, using -v /tmp/cli-output:/tmp we mount the local directory /tmp/cli-output to /tmp inside the container. The command below outputs a JSON file with the SAS Viya identities configuration. If we output that file to /tmp, it will be available at /tmp/cli-output on the local filesystem.
docker run -it -e SAS_SERVICES_ENDPOINT -v /tmp:/security -v /tmp/cli-output:/tmp -e VIYA_USER -e VIYA_PASSWORD sas-viya-cli:v1 configuration configurations download -s sas.identities --target /tmp/identites.json
Output
https://gelcorp.pdcesx02193.race.sas.com
Login succeeded. Token saved.
Write is complete to "/tmp/identites.json".
NOTE: By default, the CLI runs as the user with the UID 1001. To output files, you must make sure that this user has write access to the local file system directory.
Build your own image
You can build your own docker image based on the SAS-provided sas-viya cli image. This allows you to add tools to the image and customize it to your needs. The docker file below shows the definition of a new sas-viya-cli image.
FROM registry.unx.sas.com/convoy/sas-viya-cli
USER 0
#install required software
RUN dnf -y install git \
dnf -y install python3-pip \
pip3 install requests configobj\
ln -sfn /usr/bin/python3.6 /usr/bin/python \
dnf clean all
# install pyviyatools
RUN cd / ; git clone https://github.com/sassoftware/pyviyatools.git; /pyviyatools/setup.py
RUN ln -s /opt/sas/viya/home/bin/sas-viya /usr/bin/sas-viya
USER 1000
ENTRYPOINT [ "" ]
Use the file to build the docker image.
docker build . -f sas-viya-cli.Dockerfile -t sas-viya-cli --no-cache
With the updated image, we:
- override the entry point so that the default authentication is not used
- specify the user that the container runs as
- mount the local CLI configuration and credentials file into the container
- specify the CLI profile to use as an environment variable
In the command below we run ad-hoc CLI processing using the new container image. The certs file and the CLI configuration and credentials file are mounted into the container and the SAS_CLI_PROFLE environment variable is set because we overrode the entry point we do need to execute the sas-viya part of the command.
docker container run -it \
-v ${SSL_CERT_FILE}:/cli-home/.certs/`basename ${SSL_CERT_FILE}` \
-v ~/.sas/config.json:/cli-home/.sas/config.json \
-v ~/.sas/credentials.json:/cli-home/.sas/credentials.json \
-e SSL_CERT_FILE=/cli-home/.certs/`basename ${SSL_CERT_FILE}` \
-e REQUESTS_CA_BUNDLE=/cli-home/.certs/`basename ${SSL_CERT_FILE}` \
-e SAS_CLI_PROFILE=default \
sas-viya-cli:latest sas-viya --output text identities whoami
This is a way to easily use different CLI profiles and re-use existing credentials files. The token in the CLI credentials file is valid for 1 hour, but the provided refresh token allows the token to be renewed automatically for 14 days.
Wrap-up
The new sas-viya-cli container image is a great addition to the toolbox for SAS Administrators and others who want to automate tasks in SAS Viya. It has all the benefits of containerization discussed in my previous post like standardized packaging, version control, consistency and scalability. My colleague David Esterich has already started to use it in his Azure DevOps work. Please check out his posts linked below. In addition, the installation and usage of the container is covered in the SAS Viya Administration guide. For more information and related posts check out these resources:
- SAS Viya Administration Guide: Run the CLI from a Container
- SAS Viya Command-Line Interface for Administration (update)
- Introducing New SAS Viya CLI container image in Azure DevOps (March 2024 Update)
- Streamlining SAS Viya Authentication in Azure DevOps
- SAS administration command-line interface in a container: Part 1 Docker
- Using Apache Airflow to automate SAS Viya administration tasks
- Install and use the SAS Viya CLI on Windows
- Automating post-deployment Viya tasks with REST and the administration CLI
