How to Enable SAS CONNECT external access to SAS Viya
The SAS/CONNECT Programming with SAS Viya: SIGNON article presents multiple ways to use the SIGNON statement in a SAS client to start and connect to a remote server session executing in the SAS Viya platform. One of the options covers the use case of external clients, with a brief list of preliminary configuration steps required to enable the capability. This article dives into the detailed steps behind that summary list, including a step-by-step recorded demo.
What are we trying to accomplish?
In a default deployment, the SAS/CONNECT spawner service is only reachable from internal clients. An example of an internal client is a SAS Studio session that submits the SIGNON command.
An internal client connecting to the SAS/CONNECT spawner to launch a server.
Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.
External clients need additional configuration to reach the SAS/CONNECT spawner from outside the Kubernetes cluster. You have to create either a LoadBalancer or NodePort service. Examples of external clients are a SAS 9.4 Display Manager session executing on a laptop, or a SAS Studio session running in a different SAS Viya cluster or namespace.
External clients connecting to the SAS/CONNECT spawner via a Kubernetes LoadBalancer or Nodeport to launch server sessions.
The configuration steps
Preliminary: verify that internal connections work as expected
Before even starting any configuration change, it’s a good practice to test that the default functionality is working as expected. You can verify that internal SAS/CONNECT connections are OK, in your SAS Viya environment, by logging into SAS Studio and submitting this simple test code – no changes required:
/* launch a SAS/CONNECT session on the same cluster */
%let session1=sas-connect-spawner 17551;
/* authenticate re-using the already logged-in credentials */
SIGNON session1 user="_OAUTH_";
%put The client session is running on host: &SYSHOSTNAME;
rsubmit;
%put The server session is running on host: &SYSHOSTNAME;
endrsubmit;
SIGNOFF;
This code will do the following:
- Sign on to the SAS Connect Spawner using the Kubernetes service name
sas-connect-spawner, which is only available inside the namespace, re-using the same credentials you entered when logging into SAS Studio - Locally output the hostname of the pod where the client SAS session is running
- Use rsubmit to return the hostname of the pod where the SAS/CONNECT session is running
- Sign off from the remote session
If this all works, you are ready to perform the steps to enable external access.
1. Enable external access to the SAS/CONNECT spawner.
You can follow the instructions from the README file at <deploy>/sas-bases/docs/configure_sasconnect_spawner_in_the_sas_viya_platform.htm, in the section “Provide External Access to sas-connect-spawner via a Load Balancer”.
As you can read there, SAS provides a sample file (sas-bases/examples/sas-connect-spawner/enable-external-access/sas-connect-spawner-enable-loadbalancer.yaml) that you can copy in your sas-config directory, customize as needed, and include in the kustomization.yaml used for the original deployment. Then it’s just a matter of re-applying it using the same method as the original deployment (manual kubectl commands, sas-orchestration CLI, etc.)
An effective customization I always like to do is to reuse the load balancer frontend, which was already provisioned for the SAS Viya Ingress. This can bring a couple of benefits:
- Lower infrastructure costs, by avoiding the creation or provisioning of another load balancer.
- May simplify the TLS configuration, as detailed in the next step, by re-using the same external IP address and DNS alias as the Ingress.
If you want to do it, you have to find the IP of the ingress load balancer with a command such as:
NS=ingress-nginx
kubectl -n ${NS} get service ingress-nginx-controller -o json | jq -r ".spec.loadBalancerIP"
Then add it to the sas-connect-spawner-enable-loadbalancer.yaml as the last line, as in this example:
Example configuration of sas-connect-spawner-enable-loadbalancer.yaml
After the new configuration has been applied and submitted to Kubernetes, it's always a good practice to verify that the load balancer service gets created as expected, listening on an IP address external to the cluster:
NS=sasviya
kubectl -n ${NS} get service sas-connect-spawner-loadbalancer
Sample result:
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
sas-connect-spawner-loadbalancer LoadBalancer 10.42.230.223 10.XXX.XX.X 17551:31883/TCP 15m
2. Verify the DNS name presented by the SAS/CONNECT spawner TLS certificate.
In the previous step, we added the new Kubernetes LoadBalancer service to an existing external load balancer that had already been configured in the corporate DNS and whose DNS alias was already specified in SAS Viya kustomization.yaml. For that reason, the certificates generated by SAS Viya already include that DNS name. The simplest way to verify that is to find the DNS name used for the ingress, and confirm that it is included in the SAN field of the SAS/CONNECT spawner TLS certificate.
To find the DNS name of the ingress, you can look into the kustomization.yaml file used to deploy SAS Viya:
grep INGRESS_HOST kustomization.yaml
Sample result:
- INGRESS_HOST=sasviya.gelenable.sas.com
Now list all the aliases in the SAN field of the SAS/CONNECT spawner TLS certificate:
NS=sasviya
CONNECT_SPAWNER_SECRET=$(kubectl -n ${NS} get secrets | grep sas-connect-spawner | awk '{print $1}')
kubectl -n ${NS} get secret ${CONNECT_SPAWNER_SECRET} -o jsonpath="{.data['tls\.crt']}" | base64 -d | openssl x509 -text -noout | grep -A 1 "Subject Alternative Name"
With these commands, we first get the name of the Kubernetes secret used by the SAS/CONNECT spawner. Then, we extract the certificate from tls.crt field of that secret, base-64 decode it, and pass the result to an OpenSSL command that prints the details of the certificate in a human-readable format. Finally, we filter the results to only show the "Subject Alternative Name" details.
The result should be similar to the following. Note that it includes the full DNS name found in the previous step.
X509v3 Subject Alternative Name:
DNS:localhost, DNS:sas-connect-spawner, DNS:sas-connect-spawner-8b9cd797b-5wswp, DNS:sasnode07, DNS: sasviya.gelenable.sas.com, IP Address:10.42.126.166, IP Address:10.43.17.98, IP Address:10.XXX.XX.X, IP Address:127.0.0.1
If you did not reuse the existing load balancer, and you created a new load balancer with either a new frontend IP address or a different DNS alias for the SAS/CONNECT spawner, then you’ll have to follow the additional steps described in the Encryption in SAS® Viya®: Data in Motion guide in the section Add the External Host Name or IP Address to the SAN in the Signed Certificate.
3. Configure the client to trust the SAS Viya root CA certificate.
It is quite common to deploy the SAS Viya platform using a self-signed SAS Viya root CA certificate. This CA certificate is unknown to clients external to the cluster, so they cannot trust certificates presented by any SAS Viya server - including SAS/CONNECT. You can tell you are in this situation when, the first time you log into a web application, such as SAS Studio, your browser presents you with a security warning that you have to accept before you can get in. In this case, to be able to use SAS/CONNECT from an external Windows client, you have to obtain the SAS Viya root CA certificate, and then import it into the Windows client truststore. After that, the client will trust the certificates presented by SAS Viya servers. The official documentation lists a simple command to save the root certificate into a temporary file:
NS=sasviya
kubectl -n ${NS} get secret sas-viya-ca-certificate-secret -o go-template='{{(index .data "ca.crt")}}' | base64 -d > /tmp/SASViya_ca.crt
Then you have to copy the resulting SASViya_ca.crt file to your Windows client (you can email, ftp, network copy… ), and import it in the Windows truststore, for example following the instructions in the Encryption in SAS® Viya®: Data in Motion guide in the section Import CA Certificates into the Windows Trusted Root Certificate Authorities Store.
Finally: Connect!
After you get this far, it’s time to enjoy the fruit of your work. From the client machine, you can start a SAS session and submit some code to verify if all is fine and SAS/CONNECT is configured for external connections. You can use code like the following, after substituting the DNS alias or IP address of the load balancer in the session1 macro variable:
/* launch a SAS/CONNECT session from outside the cluster */
/* set TLS connection options */
OPTIONS NETENCRYPTALGORITHM=SSL;
/* connect using a fully-qualifies hostname or DNS alias */
%let session1=sasviya.gelenable.sas.com 17551;
/* authenticate with an authinfo file */
SIGNON session1 password="_AUTHINFO_";
rsubmit;
%put &SYSHOSTNAME;
endrsubmit;
SIGNOFF;
The resulting submission should print, in the SAS log, the name of the SAS/CONNECT server pod that gets started in the SAS Viya cluster, as in the following screenshot:
Recorded Demo
A recording of the configuration of a demo environment, showing all the steps listed above, is available on the SAS YouTube channel: SAS Demo | Configuring SAS/CONNECT for external access to SAS Viya
Summary
When you have an external SAS client that you want to connect to a SAS Viya environment, you have to perform some configuration steps before you can connect them.
- Enable the SAS/CONNECT spawner to support external clients.
- Add the external host name or IP address to the SAN in the SAS/CONNECT spawner certificate.
- Obtain the SAS Viya root CA certificate and add it to the truststore of the external client.
Links
- Official documentation to configure SAS/CONNECT for external access:
- The README file available in your deployment directory at
<deploy>/sas-bases/docs/configure_sasconnect_spawner_in_the_sas_viya_platform.htm, in the section "Provide External Access to sas-connect-spawner via a Load Balancer" - The "External Client Sign-On to TLS-Enabled SAS Viya SAS/CONNECT Spawner" section of the SAS® Viya® Platform Administration documentation
- The README file available in your deployment directory at
- Sample SAS/CONNECT code to sign-on from internal or external Clients
- Ensure the TLS certificate presented by SAS/CONNECT spawner includes the external hostname used to c...
- Ensure the client accepts as valid the TSL certificate presented by the SAS/CONNECT spawner:
Obtain the SAS Viya Platform Generated Root CA Certificate
and
Import CA Certificates into the Windows Trusted Root Certificate Authorities Store - SAS 9.4 and SAS Viya 3.x client requirements
Find more articles from SAS Global Enablement and Learning here.
