Making user home directories available to SAS Viya
Users of SAS Studio and other SAS Viya programming clients are used to having their operating system home directories available while they work. These locations provide persistent personal file storage for users. In SAS Viya 4, additional configuration is required to make home directories available. In this post, I will look at options for making home directories available to SAS Viya 4 clients and servers. NOTE: This is an update of a previous post on this topic.
There are two documented options to make home directories available:
- Use Kubernetes NFS volume
- Use a Kubernetes persistent volume
My previous post addressed the first approach. In this post, I will review the second. Using Kubernetes Volumes for User Home Directories provides great flexibility, and since you can specify the volume type, it works with a variety of storage types. In the post, we will use a Kubernetes Persistent Volume Claim. This option can also be used to make home directories available via NFS in a more transparent and native manner.
Configure SAS Studio
Out of the box, SAS Studio on Viya does not surface the operating system file system. As a result, we must update the SAS Studio configuration to make home directories accessible to the user interface.
To do this, as a SAS Viya Administrator, update the SAS Studio configuration so that the user interface surfaces shared storage ("showServerFiles": true) and the directory tree starts at the user's home directory ("fileNavigationRoot": "User"). We can do this with the sas-viya CLI configurations plugin or SAS Environment Manager
In SAS Environment Manager under Configuration > All Services > Definitions 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 user's home directory
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
As an alternative to using the UI, you can use the sas-viya CLI's configuration plugin and pass a JSON file containing the two key settings.
MEDIATYPE=$(sas-viya configuration configurations download -d sas.studio | jq -r '.items[]["metadata"]["mediaType"] ' )
tee /tmp/update_studio.json > /dev/null << EOF
{
"name": "configurations",
"items": [
{
"metadata": {
"isDefault": false,
"mediaType": "${MEDIATYPE}"
},
"showServerFiles": true,
"fileNavigationRoot": "USER"
}
]
}
EOF
sas-viya configuration configurations update --file /tmp/update_studio.json
Home Directories: CAS and Compute
There are some important differences in how CAS and Compute servers run that impact the use of home directories.
Compute sessions start by default as the identity of the requesting user. The process runs as the requesting user's identity, and all permissions and access to file system resources are governed by their UID and GID. By default, home directories use hostPath storage (/home/username) and assume that the user directories are available locally on the Kubernetes nodes.
CAS sessions start by default as the CAS service account(1001). Consequently, all operating system access for that CAS session is governed by the UID of 1001. By default, the user's personal CAS library (CASUSER) is on the CAS data PVC as a subdirectory of /cas/data/caslibs/casuserlibraries; for example, it would be /cas/data/caslibs/casuserlibraries/Henrik.
Important CAS Considerations
CAS can be configured to run CAS sessions under the identity of the requesting user.
Often, it is useful to standardize CAS with Compute to make it easier to manage access to file system resources. In addition, if Python integration with the CAS Server is required or the environment uses Kerberos authentication, the CAS Server must be enabled for host-launched CAS sessions. The host-launched CAS session requires a user's home directory be available at the location set by the identities service.
To enable CAS sessions to run as the requesting user's identity, you must enable host-launched CAS sessions by including cas-enablehost.yaml in your kustomization.yaml. You must also do either of the following:
- Define the CASALLHOSTACCOUNTS environment variable. This will ensure that all CAS sessions started by all users run as the requesting user's identity.
- OR, add specific users to the CASHostAccountRequired custom group. This will result in CAS sessions for those users running as the requesting user's identity.
Host-launched CAS sessions create and use the CASUSER directory in the user's configured home directory.
Using Kubernetes Volumes for User Home Directories
The identities service property config/identities/sas.identities/identifier.homeDirectoryPrefix controls how user home directories are defined and discovered by the Identities service, and how other services (such as CAS, Compute Server) determine a user’s home directory. The prefix must match the mount path for the home directories inside the CAS and Compute containers. The Identities service creates a full path by concatenating the prefix with the logged-in user's username. For example, if you set the property to/home, then Henriks' home directory should be available at /home/Henrik.
Update the Identities Service
To set the configuration property for identities in SAS 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.
Using the configurations plugin of the sas-viya CLI. Pass a JSON file including the setting.
MEDIATYPE=$(/opt/sas/viya/home/bin/sas-viya configuration configurations download -d sas.identities | jq -r '.items[]["metadata"]["mediaType"] ' )
tee /tmp/update_identities.json > /dev/null << EOF
{
"items":
[
{
"version": 1,
"metadata": {
"isDefault": false,
"services": [
"identities"
],
"mediaType": "${MEDIATYPE}"
},
"identifier.homeDirectoryPrefix": "/home",
"defaultProvider": "local"
}
]
}
EOF
sas-viya configuration configurations update --file /tmp/update_identities.json
This configuration change requires restarting the identities service. To do that, we can delete the identities POD, and Kubernetes will start a new one.
kubectl delete pods -l app=sas-identities
Make the home directories Persistent Volume available to Compute
The launcher-user-homedirectory-volume.yaml allows you to specify the runtime storage location of the user's home directory. The mount location is determined by the identities
service(identifier.homeDirectoryPrefix=/home) and is mounted using the specified {{ VOLUME-STORAGE-CLASS }}.
Create the location ../site-config/sas-launcher/configure/ and copy ../sas-bases/examples/sas-launcher/configure/launcher-user-homedirectory-volume.yaml file to the ../site-config/sas-launcher/configure/ location.
Here is a snippet from the file.
patch: |-
- op: add
path: /template/spec/volumes/-
value:
name: sas-launcher-userhome
{{ VOLUME-STORAGE-CLASS }}
In the file, replace {{ VOLUME-STORAGE-CLASS }} with the specification of the Kubernetes volume of your choice. In the file below, we specify a persistent volume claim. The volume type is specified at path /template/spec/volumes/-
NOTE: We assume the Kubernetes administrator has created the home-rwx-claim PVC.
patch: |-
-patch: |-
- op: add
path: /template/spec/volumes/-
value:
name: sas-launcher-userhome
persistentVolumeClaim:
claimName: home-rwx-claim
To specify an NFS volume rather than a PVC, the replacement for {{ VOLUME-STORAGE-CLASS }} would look like this:
patch: |-
- op: add
path: /template/spec/volumes/-
value:
name: sas-viya-gelcorp-volume
nfs:
path: /home
server: mynfs.demo.com
In your kustomization.yaml file, add a reference to the new file in the transformers block. For example:
transformers:
...
- site-config/sas-launcher/configure/launcher-user-homedirectory-volume.yaml
Make the home directories Persistent Volume available to CAS
For the CAS server, when using host-launched CAS sessions, create a patch transformer that mounts the home-directories PVC. Unlike the Compute server, for CAS you must provide both the volume and the volume mount. The volume mount must match the location set in identifier.homeDirectoryPrefix(/home). For example, create the file cas-user-homedirectory-volume.yaml
patch: |-
apiVersion: builtin
kind: PatchTransformer
metadata:
name: cas-add-homedir
patch: |-
- op: add
path: /spec/controllerTemplate/spec/volumes/-
value:
name: cas-add-homedir
persistentVolumeClaim:
claimName: home-rwx-claim
- op: add
path: /spec/controllerTemplate/spec/containers/0/volumeMounts/-
value:
name: cas-add-homedir
mountPath: /home
target:
group: viya.sas.com
kind: CASDeployment
version: v1alpha1
Add a reference in the kustomization.yaml.
transformers:
...
- site-config/cas-user-homedirectory-volume.yaml
Apply the Changes
Now that kustomization.yaml has been updated, we can build and apply site.yaml. Using the manual deployment method, you would:
cd ~/project/deploy/gelcorp kustomize build -o site.yaml
kubectl apply -f site.yaml
For the CAS server to pick up the changes, you must restart the CAS controller.
kubectl delete pod --selector='app.kubernetes.io/managed-by=sas-cas-operator'
kubectl wait pods -l casoperator.sas.com/node-type=controller --for condition=ready --timeout 900s
Does it Work?
To test for the user Douglas, in SAS Studio you can run this SAS program, which will:
- Output the User's home directory as it's understood by the launched Compute process to the SAS Log.
- Create a file details.txt in the home directory to test permissions.
- Print the location of the CASUSER directory, which should be inside the user's home directory
- Load a table into the CASUSER CAS library to test that permissions are correct.
filename homedir ” &_USERHOME/details.txt”;
data _null_;
/* list the attributes of this session */
%put NOTE: I am &_CLIENTUSERNAME;
%put NOTE: My home directory is &_USERHOME;
%put NOTE: My POD IS &SYSHOSTNAME;
file homedir;
put “NOTE: I am &_CLIENTUSERNAME”;
run;
/* is my CASUSER directory mounted from NFS */
cas mysess;
proc cas;
builtins.userinfo;
table.caslibinfo / caslib=’CASUSER’ verbose=true;
run;
quit;
caslib _all_ assign;
proc casutil;
load data=sashelp.cars outcaslib=”public” casout=”cascars” replace;
quit;
proc casutil;
save casdata=”cascars” incaslib=”public” outcaslib=”casuser” casout=”cascars” replace;
quit;
cas mysess terminate;
The SAS Log shows that the home directory has been relocated.
0 data _null_;
81
82 /* list the attributes of this launcher session */
83
84 %put NOTE: I am &_CLIENTUSERNAME;
NOTE: I am Douglas
85 %put NOTE: My home directory is &_USERHOME;
NOTE: My home directory is /home/Douglas
86 %put NOTE: My Launcher POD IS &SYSHOSTNAME;
NOTE: My POD IS sas-compute-server-92d7b776-5e58-45c6-96b2-eeed8338247a-6
87 run;
NOTE: DATA statement used (Total process time):
real time 0.00 seconds
cpu time 0.00 seconds
The results show that the user's Personal Caslib is located inside the home directory.
There are no errors from the step where the data is saved to the personal caslib.
104
105 proc casutil;
NOTE: The UUID 'a9a2b406-c934-e149-97d7-387cfd4d21fe' is connected using session MYSESS.
106 save casdata="cascars" incaslib="public" outcaslib="casuser" casout="cascars" replace;
NOTE: Cloud Analytic Services saved the file cascars.sashdat in caslib CASUSER(Douglas).
NOTE: The Cloud Analytic Services server processed the request in 0.02115 seconds.
107 quit;
NOTE: PROCEDURE CASUTIL used (Total process time):
real time 0.02 seconds
cpu time 0.00 seconds
By accessing the launched POD for the user, you can see the results in the file system.
id Douglas
kubectl exec -it $(kubectl get pod -l launcher.sas.com/requested-by-client=sas.studio,launcher.sas.com/username=Douglas --output=jsonpath={.items..metadata.name}) -- bash -c "id && ls -al /home/Douglas"
The results shows the correct permissions for the files created in the users home directory.
uid=4001 gid=2003 groups=2003,3003,3007
total 20
drwxrwxrwx 3 root root 4096 Apr 8 17:42 .
drwxr-xr-x 1 root root 4096 Apr 8 17:41 ..
drwx------ 2 4001 2003 4096 Apr 8 17:41 casuser
-rw-r--r-- 1 4001 2003 19 Apr 8 17:41 details.txt
-rw-r--r-- 1 4001 2003 666 Apr 8 17:42 myFirstPGM.sas
With the correct permissions and NFS server configuration, SAS Viya will create user home directories when using an NFS volume.
To allow SAS Viya to create user home directories on NFS, the NFS server must export the parent filesystem with write access and no root squashing, typically something like rw,no_root_squash,no_subtree_check (and crossmnt if sub‑mounts are involved), so container processes running as root can create directories.
The parent home directory (for example, /export/shared/gelcontent/home) must be owned by root:sasusers (or a shared Viya group) and have setgid permissions (usually chmod 2770) so that new home directories inherit the correct group and are writable by users in that group. If either root_squash is enabled on the export or the parent directory lacks group write and setgid, SAS Viya will fail to create usable home directories. In many cases, these settings may be seen as a security risk; in that case, administrators should provision user home directories outside of SAS Viya.
Wrap Up
SAS Viya 4 requires explicit configuration to surface user home directories to servers and clients. By enabling file access in SAS Studio, setting a consistent home directory prefix in the Identities service, and mounting persistent storage into both Compute and CAS (with host-launched CAS where needed), you can provide users with persistent, permission-correct home directories that work seamlessly across programming clients and servers, including CASUSER personal caslibs.
Thanks to my colleagues Niklas Nilsson, Rob Collum, Raphael Poumarede, and Simon Williams for their input to this post.
Additional Resources in the area of storage, permissions and home directories.
Announcing Project Mountpoint – Guidance to configure storage for SAS Viya
Implementing File System Security for SAS Viya
Securing OS Resources in SAS Viya
SAS Viya and POSIX attributes (UID and GID)
Find more articles from SAS Global Enablement and Learning here.
