SAS Viya: making user home directories available to compute
There's no place like home.
Users of SAS Studio and other SAS Viya programming clients are used to having their operating system home-directories available while they work. In previous versions of SAS Viya this is something that happened automatically with no additional configuration (at least before SAS Studio in Viya 3.4). In the new SAS Viya (2020.1 and later) this is not the case and additional configuration is needed. To make home-directories available in Viya on kubernetes there are a few moving parts. In this post we will go through the step by step process of making home-directories available to SAS Studio compute sessions in the new SAS Viya (2020.1 and later) .
Customers often have users home directories available on some form of shared storage like an nfs server. The process to make these home-directories available in the new SAS Viya (2020.1 and later) is:
- Annotate the compute pod template to tell it home directories are available and where the nfs server is located
- Update identities service configuration to set identifier.homeDirectoryPrefix, the path to the home-directories on nfs
- Configure SAS Studio for file system access.
Mount NFS directories into Compute Pods
In the new SAS Viya (2020.1 and later) compute sessions are started by the launcher. The launcher Service looks for a Kubernetes PodTemplate that contains information that is used to construct a Kubernetes job request. The PodTemplate information is used to generate the container that is run in the pod. The container in the pod performs the SAS processing. The compute pod template is where we need to add the configuration to make external content available. The first change we will make is not strictly needed for the home-directories. But we will need it to access our data in stored on nfs which is located at /shared/gelcontent.
Add the shared storage mount to the POD Template
Create a kustomize overlay in site-config/compute-server-add-nfs-mount.yaml that adds the volume (the path on the shared storage) and the volume mount (the location to mount the volume inside the container).
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 the kustomization yaml add the patch in the patches section and target the sas-compute-job-config.
Now we can access the data stored in /shared/gelcontent in the pod at the location /gelcontent.
Annotate the compute POD template
In our environment the home-directories are on our nfs server at /shared/gelcontent/home.
Create a kustomize overlay in site-config/compute-server-annotate-podtempate.yaml that adds an annotation to the compute pod template. The annotation value is the fqdn of the nfs server.
NOTE: the ~1 in the overlay is used for the / character so that kustomize does not interpret the / as part of the path but rather part of the
annotation. In the generated yaml the path will look like this launcher.sas.com/nfs-server: rext03-0135.race.sas.com
In the kustomization yaml add the patch in the patches section and target the sas-compute-job-config.
Now that kustomization.yaml is updated we can build and apply our site.yaml.
kustomize build -o site.yaml
kubectl apply -f site.yaml
For more details on the kustomization process you can check out this article.
At this point we have the shared storage available to the compute PODs. But wait, there is more. The compute pod currently only knows the nfs server not the path on the nfs server to be mounted. The path to the home-directory location is provided in the next step.
Update Identities Service Configuration
On the identities service the attribute identifier.homeDirectoryPrefix must be set, once it is set the software will mount the home directory, for each user, from the nfs server specified in the annotation by concatenating identifier.homeDirectoryPrefix with the username returned from the identities service, for example /shared/gelcontent/home/Henrik. Documentation on this overlay is here
To set the configuration property for identities in Environment Manager under Configuration > All Services select Identities and edit sas.identities. Set the identifier.homeDirectoryPrefix to the parent-path where home directories are stored in the nfs location.
This configuration change requires a restart of the identities service. To do that we can delete the identities POD and kubernetes will start a new one.
With these steps completed the next compute POD that is launched will have the home-directory available.
Configure SAS Studio
The last step will be to update the SAS Studio configuration. In the new SAS Viya (2020.1 and later) SAS Studio cannot, by default, access the file system. SAS Studio is initially configured without access to the file system. However, it is possible to configure Studio to access the file system, and to make users home directories available from an NFS mount. In the following steps Environment Manager is used to configure SAS Studio to do just that, these steps could also be completed in batch using the sas-viya configuration CLI.
In Environment Manager under Configuration > All Services select SAS Studio and edit sas.studio. In the dialog change:
- "showServerFiles": true to allow Studio to access the file system
- "serverDisplayName" : "NFS gelcontent" to name the node in Studio
- "fileNavigationRoot": "USER" to start navigation at the users home directory
Documentation of the Studio configuration settings is here.
What about CAS
In this blog we have dealt with Compute, this also works for CAS. There are two requirements to make the shared home-directory available to CAS.
- set the identifier.homeDirectoryPrefix
- the user must be a member of the CASHostAccountRequired Custom Group
Does it Work?
To test for the user Henrik we can copy the following program to their home-directory at /shared/gelcontent/home/Henrik/gel_launcher_details.sas. We will test for Compute and CAS by using some code to view the home-directory setting in SAS and CAS.
data _null_;
%put NOTE: I am &_CLIENTUSERNAME;
%put NOTE: My home directory is &_USERHOME;
%put NOTE: My Launcher POD IS &SYSHOSTNAME;
run;
/* is my CASUSER directory mounted from NFS */
cas mysession;
proc cas;
builtins.userinfo;
table.caslibinfo / caslib='CASUSER' verbose=true;
run; quit;cas mysession terminate;
run;
Logon to SAS Studio as the user Henrik and check if we can access and run the Program that is in Henrik's home-directory. The result should be:
- home directory available in Studio
- SAS program available in the home-directory
- Program runs and shows the home-directory setting
- CASUSER directory created on shared storage in home-directory
NOTE: you can click on the gif to see it full size.
I hope you find this post useful.
For additional information:
How do I kustomize my Viya 4 deployment?
SAS Studio Configuration Reference
Identities Configuration Reference
Find more articles from SAS Global Enablement and Learning here.
