How to connect to a non-default CAS server from code
In SAS Viya, a CAS server called cas-shared-default is normally created for you during initial deployment and is the default CAS server for all sorts of actions when you don't specify a CAS server, including a cas; statement in SAS code to start a CAS session.
However, you are not limited to just cas-shared-default, you can create other CAS servers.
Some customers will create a CAS server per department, or per project, depending on their need to separate CAS workload, run CAS servers with different configuration etc.
For the purposes of this article, I created a new CAS server called cas-shared-gelcorp, which exists alongside the original cas-shared-default. However in SAS Viya 2020.1 and later it is not very obvious how to specify your non-default CAS server from a cas; statement in SAS code. The documentation says you should specify a controller-host-name., but what should that host name be in SAS Viya deployment running on Kubernetes? The answer is that you should provide the Kubernetes service name associated with that CAS server as the 'host' parameter or CASHOST environment variable.
TL;DR - specify the Kubernetes Service Name as the controller-host-name
When you create a CAS server called e.g. cas-shared-gelcorp, the script that you run to create it also creates a corresponding Kubernetes service named e.g. sas-cas-server-shared-gelcorp-client. So in your SAS program you might start a CAS session on the cas-shared-gelcorpCAS server like this :
option cashost="sas-cas-server-shared-gelcorp-client";
cas myGelcorpSession;
...or simply:
cas myAltGelcorpSession host="sas-cas-server-shared-gelcorp-client";That is all you need to know. But if you really want to learn how to find the service name, see how to test it works, or want to know why I wrote a blog post about this in the first place, read on!
Some current docs say to specify controller host name
So why don't we specify the actual host where CAS runs? That is what you would do in SAS Viya 3, and what our documentation for the CASHOST= system option (and perhaps other documentation) says for SAS Viya 2021.2.2.
For the CAS statement (previously also referred to controller-host-name, but now fixed as of 19 Jan 2022! Thank you!):
HOST="Kubernetes-service-name" | ("Kubernetes-service-name"<, "Kubernetes-service-name">)
specifies the service name of a CAS server running in the SAS Viya Kubernetes framework.
For the CASHOST= system option:
Syntax
Syntax Description
primary-controller-host-name
specifies the CAS primary server host name.
Note the struck-through sections above, which reference a backup-controller-host-name. That syntax is correct for SAS Viya 3.5. But for SAS Viya 2020.1 and later which runs on Kubernetes, the CAS controller's Kubernetes service always points to whichever CAS controller (primary or backup) is currently active, so there is no need to specify an alternative service name for host or CASHOST. The service name does not change when a CAS server fails over to a backup CAS controller. Thanks to @EdoardoRiva for pointing this out!
Why not directly specify a host name?
Because you won't know it, even if sometimes you can indirectly work it out. Kubernetes chooses the node on which the CAS server(s) run, and thus it indirectly chooses the host machine(s) on which those CAS servers run. We normally deploy SAS Viya with constraints on which nodes Kubernetes can choose to run CAS pods by creating a CAS node pool (using labels, taints, blah blah...). But within those constraints we set, Kubernetes still decides which node/host will run the CAS server, and not the administrator.
Since in Kubernetes we aren't meant to know which host a given application service will be running on at any particular moment, Kubernetes has resource type called Services. It is a Service's job is to route network traffic to the right pod, wherever it is currently running. See Service | Kubernetes.
So, by specifying the service name for the HOST= parameter in your cas; statement, Kubernetes deals with directing the calls to start a CAS session to the right place.
How to find the service name
So now we know we need to specify a service name, how can we find that name for the CAS server we plan to use?
Thanks to Logan Chandler for pointing out that the easiest place to see it is in the 'host' column of the Servers page in SAS Environment Manager. Despite its title, this column contains the Kubernetes services name for each CAS server:
Whoever creates the new CAS server needs kubectl access to the Kubernetes cluster, and someone with that access can run this bash statement to list CAS service names, and filter them to only service names containing the strings 'sas-cas-' and 'client':
kubectl get services | grep sas-cas- | grep client
Here is some example output from our GEL SAS Viya 4: Administration workshop deployment, after running that hands-on exercise 05_051_CAS_Add_and_Remove_Servers.md:
sas-cas-server-default-client ClusterIP 10.43.145.244 <none> 5570/TCP,8777/TCP 7h26m
sas-cas-server-shared-gelcorp-client ClusterIP 10.43.37.248 <none> 5570/TCP,8777/TCP 10m
The picture below shows the same thing in Lens.
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
You can see that the service names, sas-cas-server-default-client and sas-cas-server-shared-gelcorp-client contain the same elements as their corresponding CAS server names, cas-shared-default and cas-shared-gelcorp, but there are other elements in the names too. The naming pattern might also vary a bit depending on how the CAS server was created - service names for CAS servers migrated from an earlier version of SAS Viya might follow a different naming pattern.
However, it is generally obvious which CAS server each of those service names corresponds with, especially if your CAS servers have distinctive names.
Demonstration
Let's walk through some example code to illustrate this working. First, let's see the default value of the CASHOST system option:
proc options option=cashost; run;Expected output:
CASHOST=sas-cas-server-default-client
...or...:
CASHOST=(sas-cas-server-default-client,sas-cas-server-default-client)
...depending on whether you have a backup CAS controller or not. But actually, as Edoardo says, the second syntax (CASHOST=(sas-cas-server-default-client,sas-cas-server-default-client)) is unnecessary, and the first syntax above (CASHOST=sas-cas-server-default-client) will always work in SAS Viya 2020.1 or later.
In my deployment I do have a secondary CAS controller, so I get the second one of those output examples. But later on, we will 'restore' the original value using the first example, and expect it to work just fine.
We'll note the service name sas-cas-server-default-client for later - and again we can see that it differs from the default CAS server name, cas-shared-default.
Now let's start a CAS session on that default CAS server, and see the log output confirming which service name the SAS compute server has used to connect to CAS. It we expect it should be the same, so this should not contain any surprises:
* Start a CAS session in the default CAS server;
cas myDefaultSession;
* List some of its properties;
cas myDefaultSession listabout;
Expected output:
NOTE: The session MYDEFAULTSESSION connected successfully to Cloud Analytic Services sas-cas-server-default-client using port 5570.
The UUID is 3b120094-93a5-5e44-becb-d806a970ad1a. The user is geladm and the active caslib is CASUSER(geladm).
NOTE: The SAS option SESSREF was updated with the value MYDEFAULTSESSION.
NOTE: The SAS macro _SESSREF_ was updated with the value MYDEFAULTSESSION.
NOTE: The session is using 3 workers.
Section: About
CAS = Cloud Analytic Services
Version = 4.00
VersionLong = V.04.00M0P10172021
Viya Release = 20211210.1639132795115
Viya Version = Long-Term Support 2021.2
Copyright = Copyright © 2014-2020 SAS Institute Inc. All Rights Reserved.
ServerTime = 2021-12-14T13:31:15Z
Section: System
Hostname = controller.sas-cas-server-default.gelcorp.svc.cluster.local
OS Name = Linux
OS Family = LIN X64
OS Release = 3.10.0-1062.12.1.el7.x86_64
OS Version = #1 SMP Tue Feb 4 23:02:59 UTC 2020
Model Number = x86_64
Linux Distribution = Red Hat Enterprise Linux release 8.4 (Ootpa)
Section: license
site = GEL VLE SAS VML OFFERING
siteNum = 70180938
expires = 02Jul2024:00:00:00
gracePeriod = 45
warningPeriod = 46
CASHostAccountRequired = OPTIONAL
Transferred = NO
NOTE: Request to LISTABOUT completed for session MYDEFAULTSESSION.
Okay, lots of information there, but in the very first line we see connected successfully to Cloud Analytic Services sas-cas-server-default-client using port 5570. Good - that's what we expected. Terminate that CAS session:
* Terminate it.;
cas myDefaultSession terminate;Expected output:
NOTE: Deletion of the session MYDEFAULTSESSION was successful.
NOTE: The default CAS session MYDEFAULTSESSION identified by SAS option SESSREF= was terminated. Use the OPTIONS statement to set
the SESSREF= option to an active session.
NOTE: Request to TERMINATE completed for session MYDEFAULTSESSION.
Using options CASHOST=kubernetes-service-name;
Now let's specify the new cas-shared-gelcorp CAS server in the CASHOST= system option, and check the value was set:
option cashost="sas-cas-server-shared-gelcorp-client";
proc options option=cashost; run;
Expected output:
CASHOST=sas-cas-server-shared-gelcorp-clientStart a CAS session in the default CAS server, and list some of its properties:
cas myGelcorpSession;
cas myGelcorpSession listabout;
Expected output:
NOTE: The session MYGELCORPSESSION connected successfully to Cloud Analytic Services sas-cas-server-shared-gelcorp-client using
port 5570. The UUID is 8ef44bc5-87fc-df4e-8573-0649b5c766f5. The user is geladm and the active caslib is CASUSER(geladm).
NOTE: The SAS option SESSREF was updated with the value MYGELCORPSESSION.
NOTE: The SAS macro _SESSREF_ was updated with the value MYGELCORPSESSION.
NOTE: The session is using 3 workers.
Great! In the first line we see ...connected successfully to Cloud Analytic Services sas-cas-server-shared-gelcorp-client.... So setting the CASHOST system option to the value of the Kubernetes service name worked. Just for completeness, we will test it the other way too.
First terminate this session:
cas myGelcorpSession terminate;
Output not shown - it's similar to before.
Using cas host=kubernetes-service-name;
Now we will restore the initial default cashost value (or rather, the simplified version of it, CASHOST=sas-cas-server-default-client😞
option cashost="sas-cas-server-default-client";
proc options option=cashost; run;
Expected output:
CASHOST=sas-cas-server-default-client
Finally, let's launch a CAS session on the gelcorp CAS server, using the host= parameter to set the service name, rather than the CASHOST= system option. We'll also just go ahead and terminate this session after confirming it works as we've seen that step a couple of times now and there's no need to call it out separately any more:
cas myAltGelcorpSession host="sas-cas-server-shared-gelcorp-client";
cas myAltGelcorpSession listabout;
cas myAltGelcorpSession terminate;
Expected output - the full SAS log this time:
1 %studio_hide_wrapper;
77
78 cas myAltGelcorpSession host="sas-cas-server-shared-gelcorp-client";
NOTE: The session MYALTGELCORPSESSION connected successfully to Cloud Analytic Services sas-cas-server-shared-gelcorp-client using
port 5570. The UUID is 20c1f6c7-f36c-a343-b4b0-03d5b8d02737. The user is geladm and the active caslib is CASUSER(geladm).
NOTE: The SAS option SESSREF was updated with the value MYALTGELCORPSESSION.
NOTE: The SAS macro _SESSREF_ was updated with the value MYALTGELCORPSESSION.
NOTE: The session is using 4 workers.
79 cas myAltGelcorpSession listabout;
Section: About
CAS = Cloud Analytic Services
Version = 4.00
VersionLong = V.04.00M0P10172021
Viya Release = 20220113.1642073141621
Viya Version = Long-Term Support 2021.2
Copyright = Copyright © 2014-2020 SAS Institute Inc. All Rights Reserved.
ServerTime = 2022-01-18T16:41:54Z
Section: System
Hostname = controller.sas-cas-server-shared-gelcorp.gelcorp.svc.cluster.local
OS Name = Linux
OS Family = LIN X64
OS Release = 3.10.0-1062.12.1.el7.x86_64
OS Version = #1 SMP Tue Feb 4 23:02:59 UTC 2020
Model Number = x86_64
Linux Distribution = Red Hat Enterprise Linux release 8.4 (Ootpa)
Section: license
site = GEL VLE SAS VML OFFERING
siteNum = 70180938
expires = 02Jul2024:00:00:00
gracePeriod = 45
warningPeriod = 46
CASHostAccountRequired = OPTIONAL
Transferred = NO
NOTE: Request to LISTABOUT completed for session MYALTGELCORPSESSION.
80 cas myAltGelcorpSession terminate;
NOTE: Deletion of the session MYALTGELCORPSESSION was successful.
NOTE: The default CAS session MYALTGELCORPSESSION identified by SAS option SESSREF= was terminated. Use the OPTIONS statement to
set the SESSREF= option to an active session.
NOTE: Request to TERMINATE completed for session MYALTGELCORPSESSION.
81
82
83 %studio_hide_wrapper;
93
94 So there we have it: to open a CAS session on a non-default CAS server in SAS Viya 2020.1 or later, specify the Kubernetes service name corresponding to the CAS server where you would previously have specified a hostname, leave the default port number (5770), and it will work as normal.
Thanks to @SimonWilliams for suggesting this topic by asking me how to do it. Thanks also to Logan Chandler and @EdoardoRiva for their fact-checking and other helpful suggestions. See you next time!
Find more articles from SAS Global Enablement and Learning here.
