Overview of installing and using the SAS Viya containerized CLI (2024)

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

export SOURCE_CLUSTER=sas-crunchy-platform-postgresclimage=$(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:

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 POD.

export VIYA_USER=sasadmexport VIYA_PASSWORD=lnxsasexport SAS_SERVICES_ENDPOINT=https://gelcorp.pdcesx02193.race.sas.comdocker 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.comLogin succeeded. Token saved.Id sasadmName SAS AdministratorTitleEmailAddresses [map[value:sasadm@gelcorp.com]]PhoneNumbersAddresses [map[country: locality:Cary postalCode: region:]]State activeProviderId ldapCreationTimeStampModifiedTimeStamp

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=sasadmMY_PASSWORD=lnxsasexport SAS_SERVICES_ENDPOINT=https://gelcorp.pdcesx02193.race.sas.comdocker 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_USERunset VIYA_PASSWORD/opt/pyviyatools/savetoken.pyexport SAS_SERVICES_ENDPOINT=https://gelcorp.pdcesx02193.race.sas.comexport 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 geladmName geladmTitle Platform AdministratorEmailAddresses [map[value:geladm@gelcorp.com]]PhoneNumbersAddresses [map[country: locality:Cary postalCode: region:]]State activeProviderId ldapCreationTimeStampModifiedTimeStamp

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

Using the docker run command we can run ad-hoc CLI commands 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.comLogin 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| |—— PublicOutput:

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 reports 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

For either of the above approaches, 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.comLogin 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-cliUSER 0#install required softwareRUN 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 pyviyatoolsRUN cd / ; git clone https://github.com/sassoftware/pyviyatools.git; /pyviyatools/setup.pyRUN ln -s /opt/sas/viya/home/bin/sas-viya /usr/bin/sas-viyaUSER 1000ENTRYPOINT [ "" ]

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 entrypoint 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 file. 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:

Overview of installing and using the SAS Viya containerized CLI (2024)

Getting the sas-viya-cli container image

Authenticate to SAS Viya

Use the sas-viya-cli contaner Image

Run commands and retrieve output

Run commands from inside the container

Build your own image

Wrap-up

References