Configuring SAS Viya for R Integration

1 Like

In a previous post, I looked at the SAS Configurator for Open Source and how it is useful for building R and Python for use with SAS Viya. After R is built, administrators have to perform a few additional steps to configure SAS Viya for integration with the R language, all of which are documented in multiple README files found in the deployment assets. In this post, I will consolidate the information found in those files and share with you the steps I took to integrate R with the SAS Viya deployment I use for research.

The steps to configure R integration with SAS Viya are similar to those needed to configure Python integration with SAS Viya. The instructions for key steps are outlined in $deploy/sas-bases/examples/open-source-config/README.md and the R-specific instructions are in $deploy/sas-bases/examples/open-source-config/r/README.md in your deployment assets.

The steps I followed to integrate R with SAS Viya were to:

Install R and additional packages
Make R visible to SAS Viya
Configure SAS Viya to connect to R
Configure CAS for external languages.

Because there are a few SAS Viya integration points with R (e.g., PROC IML, SAS Visual Forecasting's TSMODEL procedure, the FCMP procedure, etc.), not every step above is required for all integration method. While it is possible to configure only specific integration points, it makes sense to me, as an administrator, to configure all of the integration points at once so users are able to choose the most appropriate option for their work without the need for me to configure additional options later.

Throughout this post I will use $deploy as a reference to the SAS Viya deployment directory. On my research system, $deploy refers to ~/project/deploy/gelcorp. The $deploy directory contains the base kustomization.yaml file and the sas-bases and site-config directories for your SAS Viya deployment.

1. Install R and additional packages

As an administrator you may already have R installed or you may choose to handle the installation of R on your own. If you care to use it, SAS provides the SAS Configurator for Open Source utility, which automates the download and installation of R from source by creating and executing the sas-pyconfig job.

I chose to use the SAS Configurator for Open Source to install R so I followed the instructions in $deploy/sas-bases/examples/sas-pyconfig/README.md.

One quick note about building R. During the build process, R dynamically creates a shell wrapper with explicit, absolute directory names for the Rscript command used to invoke the R interpreter. This means that you must maintain consistency in the directory names you use when building R and the mountPath values you later use to attach persistent storage to SAS Viya pods.

2. Make R visible to SAS Viya

Now that R is installed on persistent storage, you need to make that storage available to the CAS and launcher-based pods so they can access R.

Instructions for this step are documented in $deploy/sas-bases/examples/sas-open-source-config/r/README.md.

The first step is to copy the example manifest files from $deploy/sas-bases/examples/sas-open-source-config/r to the $deploy/site-config/sas-open-source-config/r directory so you can configure them for your deployment.

export deploy=~/project/deploy/gelcorp
mkdir -p $deploy/site-config/sas-open-source-config/r
cp $deploy/sas-bases/examples/sas-open-source-config/r/* "$_"
chmod 644 $deploy/site-config/sas-open-source-config/r/*.yaml

Now you can edit $deploy/site-config/sas-open-source/r/r-transformer.yaml which will define the mountPath of the persistent storage where R is installed. This single file defines the R mountPath for CAS and the launched pods (i.e., compute, SAS/CONNECT, and batch).

Within r-transformer.yaml, identify the persistent volume that contains your R install. Since I used the SAS Configurator for Open Source to build R, I changed all occurrences of this volume definition.

# Add R volume
-op: add
  path: /template/spec/volumes/-
  value: {name: r-volume, {{VOLUME-ATTRIBUTES}} }

to identify the sas-pyconfig persistent volume claim (PVC) that the SAS Configurator for Open Source used when it built R. The sas-pyconfig PVC is created when you deploy SAS Viya

# Add R volume
- op: add
  path: /template/spec/volumes/-
  value:
    name: r-volume
    persistentVolumeClaim:
      claimName: sas-pyconfig

If you manage your own R build on other persistent storage you will need to change the template above to point to NFS or other storage class that you use for R. There are examples of alternative configurations in the $deploy/sas-bases/examples/sas-open-source-config/r/README.md.

With the r-volume identified, you now need to define the mountPath for the R volume, which is the path name by which pods will access R. If you manage your own R storage you can set this to any value as long as you remember it for later.

As covered in Using the SAS Configurator for Open Source to Build Python and R, the sas-pyconfig job creates symbolic links that enable me to dynamically refer to the most current R build using profile names. As of this writing, the symbolic links require a mount path of /opt/sas/viya/home/sas-pyconfig so that is what I configured here instead of the default mountPath value of /r. I modified all occurrences of the mountPath definition in my file to look like this

# Add mount path for R
- op: add
  path: /template/spec/containers/0/volumeMounts/-
  value:
    name: r-volume
    mountPath: /opt/sas/viya/home/sas-pyconfig
    readOnly: true

An important note about the mountPath for CAS if you plan to configure SAS Viya with integration for both R and Python and you use the SAS Configurator for Open Source... Because the SAS Configurator for Open Source expects you to use a mountPath of /opt/sas/viya/home/sas-pyconfig when attaching the sas-pyconfig PVC, you cannot define the same CAS mountPath for the r-volume in both the r-transformer.yaml and the python-volume in python-transformer.yaml as the duplicate mountPath definition will prevent CAS pods from starting. In this case, select one of the two files to define the mountPath for CAS and comment out the entire "Add mount path for R" definition block in the other.

These configuration steps allow the SAS Viya CAS and launcher-based pods to invoke my default profile's build of R with this command:

/opt/sas/viya/home/sas-pyconfig/default_r/bin/Rscript

The last change we need to make in r-transformer.yaml is down toward the bottom where we need to allow the Open Code node of SAS Visual Data Mining and Machine Learning to access R. This value needs to identify the fully qualified path to the R executable in the R home directory.

The value I used includes the R mount path I configured earlier plus default_r, which is the symbolic link for the default R profile, followed by lib64/R/bin/Rscript which is where the R executable is in the R home directory.

---
apiVersion: builtin
kind: PatchTransformer
metadata:
  name: add-r-sas-java-policy-allow-list
patch: |-
  - op: add
    path: /data/SAS_JAVA_POLICY_ALLOW_DM_RHOME
    value: /opt/sas/viya/home/sas-pyconfig/default_r/lib64/R/bin/Rscript
target:
  kind: ConfigMap
  name: sas-programming-environment-java-policy-config

One of the advantages of using the SAS Configurator for Open Source is that it will always automatically keep the symbolic links for each profile updated to refer to the latest build. This means that we can configure this value one time and not need to change it for subsequent build changes.

Save the changes and then add $deploy/site-config/sas-open-source-config/r/python-transformer.yaml to the transformers field of your base kustomization.yaml before the sas-bases/overlays/required/transformers.yaml.

transformers: 
  ... 
  - site-config/sas-open-source-config/r/r-transformer.yaml 
  - sas-bases/overlays/required/transformers.yaml
  ...

3. Configure SAS Viya to connect to R

With R mounted to our SAS Viya pods, the next step is to provide CAS and launched pods with the information they need to connect to R and its supporting components.

Instructions for this step are located in $deploy/sas-bases/examples/sas-open-source-config/r/README.md.

To do this, you need to edit $deploy/site-config/sas-open-source-config/r/kustomization.yaml which is one of the files you copied over in step #2. This file defines environment variables that are used by the SAS Viya pods to locate R executables and associated libraries.

Referencing the mount path defined in step #2, I configured the three default environment variables.

DM_RHOME is used by the Open Source Code node in SAS Visual Data Mining and Machine Learning
SAS_EXTLANG_SETTINGS controls access to R from CAS (more on this later)
SAS_EXT_LLP_PYTHON is used when the base distribution or packages for open-source software require additional run-time libraries that are not part of the shipped container image, similar to the LD_LIBRARY_PATH concept.

If you have licensed SAS/IML, you also need to create two new environment variables to enable R to be called by PROC IML in a SAS Program.

R_HOME points to the lib64/R directory within your mounted R directory
SASV9_OPTIONS must be set to "=-RLANG"

configMapGenerator:
- name: sas-open-source-config-r
literals:
- DM_RHOME=/opt/sas/viya/home/sas-pyconfig/default_r/lib64/R
- SAS_EXTLANG_SETTINGS=/opt/sas/viya/home/sas-pyconfig/extlang.xml
- SAS_EXT_LLP_R=/opt/sas/viya/home/sas-pyconfig/default_r/lib64/R/lib
- R_HOME=/opt/sas/viya/home/sas-pyconfig/default_r/lib64/R
- SASV9_OPTIONS=-RLANG

Save the changes and add a reference to the directory containing this file in the resources field of the base kustomization.yaml file.

resources: 
  ... 
  - site-config/sas-open-source-config/r 
  ...

4. Configure CAS for external languages

There are a few additional steps to configure CAS for external language integration. Normally, the CAS process runs as the 'sas' user which has permissions and privileges that we do not want external languages to have access to. Therefore, we need to configure CAS to launch sessions using the identity of the user for better access control.

Enable host identity sessions

The first step is to configure CAS for host access which enables CAS to do host identity session launching.

Copy $deploy/sas-bases/examples/cas/configure/cas-enable-host.yaml to $deploy/site-config and reference it in your base kustomization.yaml file's transformers field before the required transformers.yaml.

transformers: 
  ... 
  - site-config/cas-enable-host.yaml 
  - sas-bases/overlays/required/transformers.yaml
  ...

Configure users who need host identity sessions

For any CAS user needing to run Python, one of the following is required for user authentication:

If only selected users require access to R, those users must be a member of the CASHostAccountRequired group. For information, see The CASHostAccountRequired Custom Group in SAS Viya: Identity Management. Be aware that when you create the CASHostAccountRequired custom group, the ID (CASHostAccountRequired) is case-sensitive.
Alternatively, the CASALLHOSTACCOUNTS environment variable can be set which enables host identity sessions for all users. For information, see env.CASALLHOSTACCOUNTS in SAS Viya: SAS Cloud Analytic Services.

I used SAS Environment Manager to create the CASHostAccountRequired custom group and added three users to it: geladm (my administrator), Delilah, and Henrik.

Configure CAS access for External Languages

This step is needed if you intend to use R with SAS Visual Forecasting's TSMODEL procedure and/or its timedata.RunTimecode action, or FCMP.

The TSMODEL procedure of SAS Visual Forecasting includes an External Language (EXTLANG) package that enables users to incorporate code from external languages such as Python and R. Because the functionality of the EXTLANG package might conflict with security policies, the EXTLANG package includes mechanisms that enable CAS server administrators to control users’ access to installed external-language interpreters and usable storage areas.

Access to external languages is managed by way of an XML file. In step #3 we configured an environment variable SAS_EXTLANG_SETTINGS with a value of/opt/sas/viya/home/sas-pyconfig/extlang.xml. This identifies extlang.xml as the file containing access control information for CAS to use with the EXTLANG package of TSMODEL.

The file has to be accessible to CAS, and because it relates to open source languages, I chose to add the XML file to the sas-pyconfig persistent volume.

The extlang.xml file shown below has

allowAllUsers="BLOCK" which prevents all users not listed in a GROUP below from using external languages from CAS
A DEFAULT block that
- Defines default values for users permitted to use external languages
- Defines the external language commands and default settings for CAS to use
- Blocks users from changing the interpreter command or defining environment variables
A GROUP block that allows the geladm user to
- Invoke both Python and R languages
- Set environment variables
- Specify a different R or Python interpreter
A second GROUP block that allows Henrick and Delilah to
- Invoke R and Python languages
- To execute inline code.

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

For more information on this please see SAS Help Center: External Languages Access Control Configuration.

Configure CAS for external access (optional)

If your users are going to be accessing CAS from outside your Kubernetes cluster, you will need to configure CAS to accept external connections. Because there are nuances to this step, I am going to suggest you read SAS Viya - Access CAS from Outside the Viya Deployment by my colleague Gilles Chrzaszcz that describes this step.

This step is not needed for my research deployment but is likely to be needed in situations where users want to access SAS Viya from their own machines or from other applications.

Apply the configuration changes

With the configuration complete, we need to rebuild the SAS deployment and apply the changes to the cluster. How you do this is dependent upon the deployment method used with your SAS Viya deployment. I use the SAS Deployment Operator which means that I rebuild the sasdeployment custom resource definition and then apply it to my cluster. If you use the manual deployment method then you will need to use kustomize to rebuild your site.yaml manifest and then apply that to your cluster.

See Modify Existing Customizations in a Deployment for guidance on this task.

If you deployed using the viya4-deployment GitHub project, you should consult the project documentation for guidance.

Validate R Access

It is finally time to make sure SAS Viya can successfully integrate with R.

First, let's submit a program in SAS Studio to verify that the RLANG system option has been set and that the compute server knows where R can be found.

Next, let's submit PROC IML code that calls R to verify the launched pods and IML are integrated properly with R. If you need sample code to test with you can find several examples in SAS Help Center: Calling Functions in the R Language.

Lastly, let's verify that CAS can access R. I tested with a program that uses PROC TSMODEL to process data in CAS using R code. If you need example TSMODEL code to test with you can find a good example in SAS Help Center: Calculate Moving Average of the Airline Series. Running this test as one of the three named users in the EXTLANG XML file above (geladm, Henrik, or Delilah) should show results. Running as any other user will show in the log that the user is not authorized to use the EXTLANG package.

To test the Visual Data Mining and Machine Learning's Open Source Code node you can follow the steps outlined in the Open Source Code Node Example found in the Model Studio: SAS® Visual Data Mining and Machine Learning documentation.

Summary

This post outlines the steps required to integrate R with SAS Viya. The information for all of the steps above are spread across multiple README.md files in your deployment assets. I hope, however, that having the information from those individual files outlined in this one post will make it easier for you to integrate R with your SAS Viya deployment.

For more information...

Find more articles from SAS Global Enablement and Learning here.