Overview of installing and using the SAS Viya containerized CLI

1 Like

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

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

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

ronan

Hi @GerryNelson ,

Thank you for this interesting post full of details. Is there any plan to integrate this new image into a standard k8s deployment

part of Viya Manifest (optionnaly) installed alongside Viya microservices ? A single pod deployment would suffice.

The k8s cluster UI manager (Lens, Openshift console) would then provide a http *serverless* shell terminal to run VIYA Cli commands

in addition to the ssh/docker/Jumpbox approach.

One step further would be to provide a new (http Restful) plugin for Web Environment Manager with a ssh console running *into* the Viya CLI Pod

under the authenticated user own credentials. Adding some additionnal CLI to the image (kubectl, kustomize, git, jq) would enable to replace the

need for an extra SSH/Linux terminal with full security including client/server authentication sequence (cli auth login) automatically performed.

Ronan