Updating The SAS Viya Platform Orchestration Tool (sas-orchestration)

2 Likes

The SAS Viya platform administrator must update the SAS Viya platform deployment regularly. SAS expects customers to update their SAS Viya platform deployment at least every 4 months on stable or every 6 months on LTS. If the deployment method is using the SAS Deployment Operator or the sas-orchestration command, SAS Viya platform administrator has to ensure that the sas-orchestration tool image that is pulled is the same as the one required by the new SAS Viya platform deployment assets.

In this article, I will show you how to update the sas-orchestration tool and provide you with a script to help you in this task.

The SAS Viya platform deployment methods

SAS Viya platform can be deployed using several deployment methods:

Kubernetes commands approach using kustomize and kubectl.
Deployment Operator
The sas-orchestration command
Deployment as Code (DAC) using:
- Deployment Operator (the default option).
- The sas-orchestration command (option).

The SAS Viya platform administrator could have to update the sas-orchestration tool before updating the SAS Viya platform deployment if it was deployed using the SAS Deployment Operator or the sas-orchestration command (This de facto includes the DAC method).

How to know if the sas-orchestration tool needs to be updated?

When the SAS Viya platform deployment must be updated, the SAS Viya platform administrator must:

Download the new SAS Viya platform deployment assets.
Validate that the current version of the sas-orchestration tool is the same as the one described in the new SAS Viya platform deployment assets.

The sas-orchestration tool version validation could be done using these two steps:

Find the current sas-orchestration tool version

docker images */*/sas-orchestration | awk -F " " '{print $2}'

TAG                          
1.93.2-20230413.1681403534588

Note: The TAG value is the sas-orchestration tool version.

Find the SAS Viya platform deployment assets expected sas-orchestration tool version
```
grep "docker pull" $deploy/sas-bases/examples/kubernetes-tools/README.md | awk -F ":" '{print $NF}'
```
```
1.97.4-20230503.1683146435603
```
If these two versions are different (E.G.: 1.93.2-20230413.1681403534588 versus 1.97.4-20230503.1683146435603), the sas-orchestration tool must be updated.

If this sas-orchestration tool validation version is skipped but the sas-orchestration tool update is required, the next time the SAS Viya platform administrator runs a docker run sas-orchestration command an error message is generated as illustrated below...

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

In this case, the SAS Viya platform administrator must update the sas-orchestration tool before re-running the command.

The sas-orchestration tool update process

The sas-orchestration tool update process is documented only in the SAS Viya platform deployment assets inside the /sas-bases/examples/kubernetes-tools/README.md file. This file contains the exact version of the sas-orchestration image and how to pull it into the SAS Viya platform deployment.

Assuming that the new SAS Viya platform deployment assets was downloaded...

Using the updated SAS Viya platform deployment assets, navigate to the /sas-bases/examples/kubernetes-tools/.
Locate the prerequisites section of the README.md file.
Then run the two docker commands from the README file. The commands are customized for your particular deployment and already reference the proper sas-orchestration version you need to use. Do not modify the commands before running them, except if you use a SAS Viya Platform docker images mirror repository.
1. The first command pulls the required sas-orchestration image for easier reference: docker pull cr.sas.com/viya-4-x64_oci_linux_2-docker/sas-orchestration:[version specific to your deployment].
2. The second command tags the new sas-orchestration image: docker tag cr.sas.com/viya-4-x64_oci_linux_2-docker/sas-orchestration:[version specific to your deployment] sas-orchestration.
  
  The image tag is like an alias. This is required to be able to use the image without having to pass a specific version.
  
  Note: If you use a SAS Viya platform docker images mirror repository, you will have to replace cr.sas.com with your mirror repository address in both commands above.
The new version of the sas-orchestration tool is now available in your environment.

Note: If you use a SAS Viya platform docker images mirror repository, you will have to replace cr.sas.com with your mirror repository address in both commands above.

Script the sas-orchestration tool update process

Because you will need to frequently update the sas-orchestration tool, I have written a bash script that will update the sas-orchestration tool using the same steps I just described.

The script allows you to pass arguments to set:

The path to your SAS Viya platform deployment assets.
The SAS Viya platform docker images mirror repository if you use one.
The sas-orchestration docker image tag in case you must manage several versions in a single Kubernetes cluster.

#!/bin/bash
#
# This script is to update the sas-orchestration tool in your SAS Viya platform deployment using your latest deployment assets.


# Initialize environment variables
_deploy=~/project/deploy/gelcorp   # You can replace this value with your default SAS Viya platform deployment assets path
_sasRepository=cr.sas.com          # The default SAS Viya platform docker images repository
_repository=${_sasRepository}
_sasTag=sas-orchestration          # The default SAS Viya platform sas-orchestration docker image tag
_tag=${_sasTag}
_otherParameters=
_debug=0


# Define functions
helpMessage () {
   printf "
Usage: ./sas-orchestrationUpdate.sh [arguments]

   Arguments:
      -d or --debug      : To list arguments values for validation, but do not execute the script.
      -h or --help       : To display the help message
      -p or --path       : To set your SAS Viya platform deployment assets path
      -r or --repository : To set your SAS Viya platform docker images mirror repository
      -t or --tag        : To set the SAS Viya platform sas-orchestration docker image tag

      Other parameters/arguments values are just ignored.

"
}

debugMessage () {
   printf "
\n#############################
# current parameters values #
#############################

Deployment assets path : ${_deploy}
Deployment repository  : ${_repository}
sas-orchestration tag  : ${_tag}

Other bad arguments are: \"${_otherParameters[*]}\"
#############################\n\n"
}


# Parse script arguments
while [[ ${#} -gt 0 ]]
do
   key="${1,,}"

   case ${key} in
      -d|--debug)        # To use the debug mode. Nothing executed.
         _debug=1
         shift # Past argument
         ;;
      -h|--help )        # To see this help message
         helpMessage
         exit 130
         shift # Past argument
         ;;
      -p|--path)         # Set the path to the SAS Viya platform deployment assets
         _deploy=${2}
         shift # Past argument
         shift # Past value
         ;;
      -r|--repository)   # Set the required SAS Viya platform docker images repository
         _repository=${2}
         shift # Past argument
         shift # Past value
         ;;
      -t|--tag)          # Set the required SAS Viya platform sas-orchestration docker image tag
         _tag=${2}
         shift # Past argument
         shift # Past value
         ;;
      *)                 # Unknown option
         _otherParameters+=("${1}") # Save it in an array for later
         shift # Past argument
         ;;
   esac
done


# Debug message
if [[ ${_debug} -ne 0 ]]
then
   debugMessage
   exit 130
fi


# Error message
if [[ "${_otherParameters[*]}" != "" ]]
then
   debugMessage
   helpMessage
   exit 130
fi


# Script arguments validation
if [[ -z "${_deploy}" ]] || [[ ! -d "${_deploy}" ]];
then
   echo "You have to pass a valid path for the SAS Viya platform deployment assets."
   helpMessage
   exit 128
fi
if [[ -z "${_repository}" ]] || [[ ${_repository} != *"."* ]];
then
   echo "You have to pass a valid repository name to access the SAS Viya platform docker images."
   helpMessage
   exit 128
fi


# Pull the required sas-orchestration tool image
_dockerPullCommand=$(grep "docker pull" ${_deploy}/sas-bases/examples/kubernetes-tools/README.md)
echo "${_dockerPullCommand}"
if [[ ${_repository} != ${_sasRepository} ]];
then
   # To use a specific SAS Viya platform docker images mirror repository
   _dockerPullCommand=$(echo "${_dockerPullCommand}" | sed "s/cr\.sas\.com/${_repository}/g")
   echo "${_dockerPullCommand}"
fi
${_dockerPullCommand}


# Tag the new sas-orchestration tool image as sas-orchestration (creates a kind of alias)
_dockerTagCommand=$(grep "docker tag" ${_deploy}/sas-bases/examples/kubernetes-tools/README.md)
echo "${_dockerTagCommand}"
if [[ ${_repository} != ${_sasRepository} ]];
then
   # To use a specific SAS Viya platform docker images mirror repository
   _dockerTagCommand=$(echo "${_dockerTagCommand}" | sed "s/cr\.sas\.com/${_repository}/g")
   echo "${_dockerTagCommand}"
fi
if [[ ${_tag} != ${_sasTag} ]];
then
   # To use a specific SAS Viya platform sas-orchestration docker image tag
   _dockerTagCommand=$(echo "${_dockerTagCommand}" | sed "s/${_sasTag}/${_tag}/g")
   echo "${_dockerTagCommand}"
fi
${_dockerTagCommand}


#    Validate the docker image tag
docker image ls sas-orchestration*:*
docker images | grep "/sas-orchestration"

I hope this article has been helpful to you.

References:

SAS documentation:

SAS® Viya® Platform Administration

SAS® Viya® Platform Operations

Getting Started / Deployment Considerations / Deployment Methods