Note: For the current operational status of this Quickstart, click here to redirect to the SAS repository.
This README for SAS Viya Quickstart Template for Azure is used to deploy the following SAS Viya products in the Azure cloud:
- SAS Visual Analytics 8.5 on Linux
- SAS Visual Statistics 8.5 on Linux
- SAS Visual Data Mining and Machine Learning 8.5 on Linux
- SAS Data Preparation 2.5
This Quickstart is a reference architecture for users who want to deploy the SAS platform, using microservices and other cloud-friendly technologies. By deploying the SAS platform in Azure, you get SAS analytics, data visualization, and machine-learning capabilities in an Azure-validated environment.
For assistance with SAS software, contact SAS Technical Support. When you contact support, you will be required to provide information, such as your SAS site number, company name, email address, and phone number, that identifies you as a licensed SAS software customer.
- SAS Viya Quickstart Template for Azure
- Contents
- Solution Summary
- Prerequisites
- Best Practices When Deploying SAS Viya on Azure
- Deployment Steps
- Additional Deployment Details
- User Accounts
- Optional Post-Deployment
- Usage
- Troubleshooting
- Appendix A: Configuring the Identities Service
- Appendix B: Managing Users for the Provided OpenLDAP Server
- Appendix C: Security Considerations
- Appendix D: Telemetry
By default, Quickstart deployments enable Transport Layer Security (TLS) for secure communication.
This SAS Viya Quickstart Template for Azure will take a generic license for SAS Viya and deploy SAS into its own network. The deployment creates the network and other infrastructure. After the deployment process completes, you will have the outputs for the web endpoints for a SAS Viya deployment on recommended virtual machines (VMs).
When you deploy the Quickstart with default parameters in a symmetric multiprocessing (SMP) environment, the following SAS Viya environment is built in the Microsoft Azure cloud, shown in Figure 1. In SMP environments, the CAS Node Count parameter is set to one, indicating that only one CAS controller is configured.
Figure 1: Quickstart architecture for SAS Viya on Azure in an SMP Environment
When you deploy the Quickstart with default parameters in a massively parallel processing (MPP) environment, the following SAS Viya environment is built in the Microsoft Azure cloud, shown in Figure 2. In MPP environments, the CAS Node Count parameter is set to a value of 2 or more, indicating the number of CAS workers that are configured in addition to the CAS controller.
Figure 2: Quickstart architecture for SAS Viya on Azure in an MPP Environment
For details, see SAS Viya 3.5 for Linux: Deployment Guide.
You are responsible for the cost of the Azure services used while running this Quickstart deployment. There is no additional cost for using the Quickstart. You will need a SAS license to launch this Quickstart. Your SAS account team and the SAS Enterprise Excellence Center can advise on the appropriate software licensing and sizing to meet workload and performance needs. SAS Viya Quickstart Template for Azure creates three instances, including:
- 1 compute virtual machine (VM), the Cloud Analytic Services (CAS) controller
- 1 VM for administration, the Ansible controller
- 1 VM for the SAS Viya services
Here are some recommended example VM sizes based on the number of licensed cores:
Licensed Cores | Virtual Machine | SKU Memory(RAM) | Maximum Dataset Size | Cache Size |
---|---|---|---|---|
4 | Standard_E8s_v3 | 64 GB | 20-40 GB | 128 GB |
8 | Standard_E16s_v3 | 128 GB | 20-40 GB | 256 GB |
16 | Standard_E32s_v3 | 256 GB | 90-170 GB | 512 GB |
If you are installing VDMML or a similarly large installation, we recommend that you use at least the Standard E16s_v3 VM size.
Before deploying SAS Viya Quickstart Template for Azure, you must have the following:
-
Azure user account with Contributor and Admin Roles
-
Sufficient quota of at least 28 Cores, based on four licensed SAS cores in an SMP environment. In MPP environments, apply this sizing to the CAS workers as well as the CAS controller.
-
A SAS Software Order Confirmation Email that contains supported Quickstart products:
SAS Visual Analytics 8.5 on Linux SAS Visual Statistics 8.5 on Linux SAS Visual Data Mining and Machine Learning 8.5 on Linux
-
The license file in .zip format from your software order uploaded to an Azure blob
-
Verification that your required SAS Viya file upload sizes do not exceed the limits of the Application Gateway. For details about limits, see "Application Gateway limits."
-
A resource group that does not already contain a Quickstart deployment. For more information, see Resource groups.
When you run the deployment, you will need the blob Shared Access Signature (SAS) URL as a parameter.
Before you run the deployment:
-
Upload the license file to Azure Blob Storage. Follow the Microsoft Azure instructions to "Create a Container" and "Upload a Block Blob."
-
Create a Shared Access Signature (SAS) token. Follow these steps to create a Service SAS:
- Navigate to the license file blob and select Generate SAS, and then click Generate blob SAS token and URL.
- Make a note of the blob SAS URL for use during deployment.
For details, see "Using Shared Access Signatures."
For your repository, you can do either:
- Use the default method, which downloads the installation files directly from SAS.
- Upload an entire mirror to Azure blob storage.
To use a mirror repository, create a mirror repository as documented in "Create a Mirror Repository" in the SAS Viya 3.5 for Linux: Deployment Guide.
Note: For the deployment to recognize the mirror directory, the URL must end with a "/" directly before the SAS key.
- Upload the mirror:
az storage blob upload-batch --account-name "$STORAGE_ACCOUNT" --account-key "$STORAGEKEY" --destination "$SHARE_NAME" --destination-path "$SUBDIRECTORY_NAME" --source "$(pwd)"
-
Create a SAS key that has (at a minimum) List blob and Get blob privileges on the blob store.
-
During deployment, set the DeploymentMirror parameter to the URL of the folder in the Azure blob that is qualified by that SAS key.
Note For the mirror storage, use the same storage account that you used for the license file in "Upload the License Zip file."
We recommend the following as best practices:
- Create a separate resource group for each Quickstart deployment. For more information, see Resource groups.
- In resource groups that contain a Quickstart deployment, include only the Quickstart deployment in the resource group to facilitate the deletion of the deployment as a unit.
You can click the "Deploy to Azure" button at the beginning of this document or follow the instructions for a command-line (CLI) deployment using the scripts in the root of this repository.
The deployment takes between 1 and 4 hours, depending on the quantity of software licensed.
The vmuser host operating system account is created during deployment. Use this account to log in via SSH to any of the machines.
The sasadmin and sasuser SAS Viya user accounts are also created during deployment. These accounts exist in LDAP, and are the default user accounts for logging in to SAS Viya. You cannot directly log on to the host operating system with these accounts.
Here are the location and sizes of key files and folders that are useful for troubleshooting and performing maintenance tasks:
By default, the Quickstart deployment generates a highly unique DNS name for your deployment and a self-signed certificate for secure connections. This is enough for limited use cases or proofs of concept. However, because a self-signed certificate provides limited protection against man-in-the-middle attacks and the default DNS is computer-readable, it is recommended that you change the DNS name and provide a Trusted Root signed certificate. After acquiring a domain name and a TLS certificate from your corporate IT department, Domain Name Registrar, or Certificate Authority, update your Domain Name Server entry to support one of the following choices:
- create a CNAME or Alias record at the current unique Domain Name of the application gateway. (Refer to the DNS name attribute under the PrimaryViyaLoadbalancer_PublicIP resource for the current deployment's unique Domain Name.)
- create a traditional A record at the application gateway IP. (Refer to the IP address under the PrimaryViyaLoadbalancer_PublicIP resource for the current deployment's application gateway IP.)
If you have acquired a new domain name or are using an existing domain name, you can upload a trusted root signed certificate for that domain to the application gateway. For details, see "Renew Application Gateway certificates."
To access an existing data source from your SAS Viya deployment, add an inbound rule to each security group or firewall for the data source as follows:
-
If your data source is accessed via the public internet, add a public IP to the SAS Viya services VM and SAS Viya controller VM. Add an Allow rule to your data source for both the services VM and controller VM public IP addresses. When creating the public IP addresses for each SAS Viya VM, a Static IP using the "Standard" SKU is recommended. For details, see "Create, change, or delete a public IP address."
-
If you have an Azure-managed database, add the service endpoint for the database to the private subnet of your SAS Viya network. For details, see "Use Virtual Network service endpoints and rules for Azure SQL."
-
If you have peered the virtual network, add a rule to "Allow the private subnet CIDR range" for the SAS Viya network. (By default, 10.0.127.0/24). For details, see "Virtual network peering."
Data sources accessed through SAS/ACCESS should use the SAS Data Agent for Linux Deployment Guide instructions to "Configure Data Access" and "Validate the Deployment."
If you are using SAS/ACCESS with SSL/TLS, unvalidated SSL certificates are not supported. In this case, a trust store must be explicitly provided.
Note: For most Azure-managed data sources, the standard OpenSSL trust store validates the data source certificate:
/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt
- Locate the following two odbc.ini files:
- CAS controller: /opt/sas/viya/home/lib64/accessclients/odbc.ini
- SAS Viya services: /opt/sas/spre/home/lib64/accessclients/odbc.ini
- For each file, modify the parameters.
-
For detailed information about configuring data access, see "Configure Data Access" in SAS Data Agent for Linux: Deployment Guide.
-
For specific DataDirect information, see "Configuration Through the System Information (odbc.ini) File."
- For SQLServer, specify the appropriate driver location:
- For SAS Viya: /opt/sas/spre/home/lib64/accessclients/lib/S0sqls28.so
- For CAS controller: /opt/sas/viya/home/lib64/accessclients/lib/S0sqls28.so
[SQLServerTest]
Driver=<driver location>
Description=SAS Institute, Inc 7.1 SQL Server Wire Protocol
AlternateServers=
AlwaysReportTriggerResults=0
AnsiNPW=1
ApplicationName=
ApplicationUsingThreads=1
AuthenticationMethod=1
BulkBinaryThreshold=32
BulkCharacterThreshold=-1
BulkLoadBatchSize=1024
BulkLoadFieldDelimiter=
BulkLoadOptions=2
BulkLoadRecordDelimiter=
ConnectionReset=0
ConnectionRetryCount=0
ConnectionRetryDelay=3
Database=sqlserver
EnableBulkLoad=0
EnableQuotedIdentifiers=0
- Save the odbc.ini files.
-
Perform the pre-installation and installation steps in SAS Data Agent for Linux: Deployment Guide. For the post-installation tasks, you can either:
- (Recommended) Use the post-installation playbooks as specified in steps 6 and 7 below.
- Perform the manual steps in the SAS Data Agent for Linux: Deployment Guide.
-
In the SAS Viya and SAS Data Preparation environment, open the firewall to allow access on port 443 as follows:
a. Obtain the public IP of the SAS Data agent firewall. The SAS Data Agent firewall address is either the public IP of the machine where the HTTPS service is running or the public IP of the NAT that routes outgoing traffic in the SAS Data Agent network.
b. Modify the security group of the Application Gateway. By default, this is called "PrimaryViyaLoadbalancer_NetworkSecurityGroup" and will be under the resource group of your SAS Viya deployment. Add an inbound rule for port 443 for the public IP that is specified in step 2a.
-
To verify that the connection works, on the machine assigned to the [httpproxy] host group in the Ansible inventory file in your SAS Data Agent environment:
sudo yum install -y nc nc -v -z <DNS-of-SAS-Viya-endpoint> 443
If the output from the nc command contains "Ncat: Connected to <IP_address:443>", the connection was successful.
-
To allow access from your SAS Viya network, open the firewall of the SAS Data Agent Environment. You can either:
-
Add a public IP address to both the controller and services VMs and allow port 443 from the public IPs of your installation. In this case, a Static IP using the "Standard" SKU is recommended. For details, see "Create, change, or delete a public IP address."
-
Allow general access to port 443 for all IP addresses.
-
-
To verify the connection, on the services host:
sudo yum install -y nc nc -v -z <IP-or-DNS-of-the-SAS-Data-Agent-host> 443
If the output from the nc command contains "Ncat: Connected to <IP_address:443>", the connection was successful.
-
Register the SAS Data Agent with the SAS Viya environment. As the deployment vmuser, log on to the Ansible controller VM and run the following command from the /sas/install/ansible/sas_viya_playbook directory:
Note: The password of the admin user is the value that you specified during deployment for the SASAdminPass input parameter.
cp /sas/install/postconfig-helpers/dataprep2dataagent.yml ./dataprep2dataagent.yml
ansible-playbook dataprep2dataagent.yml \
-e "adminuser=sasadmin adminpw=<password of admin user>" \
-e "data_agent_host=<FQDN(DNS)-of-SAS-Data-Agent-machine>" \
-e "secret=<handshake-string>" \
-i "/sas/install/ansible/sas_viya_playbook/inventory.ini"
-
Register the SAS Viya environment with the SAS Data Agent. Copy the following file from the Ansible controller in your SAS Viya deployment into the playbook directory (sas_viya_playbook) in your SAS Data Agent deployment:
/sas/install/postconfig-helpers/dataagent2dataprep.yml
From the playbook directory (sas_viya_playbook) for the SAS Data Agent:
ansible-playbook dataagent2dataprep.yml \ -e "data_prep_host=<DNS-of-SAS-Viya-endpoint>" \ -e "secret=<handshake-string>"
Note: The DNS of the SAS Viya endpoint is the value of the SASDrive output parameter, without the " prefix and the "/SASDrive" suffix.
-
To access the data sources through SAS/ACCESS, see "Configure Data Access" in the SAS Data Agent for Linux: Deployment Guide.
-
Validate the environment, including round-trip communication. For details, see the "Validation" chapter in the SAS Data Agent for Linux: Deployment Guide.
-
To log in to any machine via SSH to check on a deployment or to perform maintenance, log in as vmuser.
-
To log in to SAS Viya initially, use one of the following default user accounts: sasadmin (administrative user) or sasuser.
-
To access SAS Viya applications, navigate to the Outputs screen and access SASDrive or SASStudio.
- To connect to VMs through Azure Bastion:
- Log in to the Azure Bastion server as vmuser:
ssh vmuser@<AnsibleControllerIP>
- From the Azure Bastion server, connect to the services, controller, and worker VMs as vmuser:
ssh vmuser@services
ssh vmuser@controller
ssh vmuser@worker01
ssh vmuser@worker02
If your deployment fails:
- Check to ensure that the location of your license is accessible.
- If you created a mirror, verify that the mirror is correct.
- Review the failed deployment steps and see "Deployment errors" in the Azure troubleshooting documentation.
- If the value of the DeploymentDataLocation is left as "", then the Azure resources have been allocated, but SAS Viya has not been installed. You must delete the deployment and redeploy with a valid link to your license. For more information, see "Upload the License Zip file."
-
In general, issues that occur in the primary deployment but do not originate from a sub-deployment are platform issues such as the inability to obtain sufficient resources in a timely manner. In these cases, you must redeploy your software. When the deployment is run via the CLI, the primary deployment is called "azure-deploy". When the deployment is run via the UI template, the primary deployment is called "Microsoft.Template". The names of sub-deployments usually begin with "AnsiblePhase".
-
If the error comes from a sub-deployment (for example, “AnsiblePhase4PreViyaInstall”), review the log files.
Ansible is the primary virtual machine that is used for the installation. Most of the deployment log files reside on the Ansible virtual machine.
The /var/log/sas/install directory is the primary deployment log directory. Other logs follow:
-
runAnsiblePhase*.log files: logs that are produced by the extensions
-
install_runner.log: logs that are created by an asynchronous task started in phase 1 and ending in phase 7. Sections of the text are returned as the results in the runAnsiblePhase* logs.
-
Commands.log: a listing of the parameters supplied to the Ansible start script.
- /var/log/sas: parent folder for SAS Viya application logs. If there is a startup issue after installation, the information in these logs might be helpful.
- /var/log/sas/install
- prerequisites.log: log that is created by the first setup script on the services VM that prepares it for Ansible to run against it and to mount /mnt/viyashare
- viya_mirror_download.log: If no deployment mirror is specified, then this is the location of the mirror manager log
- /var/log/sas: SAS logs. If there is a startup issue after installation, this will be the location for the information.
- /var/log/sas/install
- prerequisites.log: log that is created by the first setup script on the CAS Controller VM that prepares it for Ansible to run against and to mount /mnt/viyashare
While all the services can be started on each box independently, the Viya-Ark toolkit provides an efficient way to restart all the services across all the boxes from the Ansible controller.
Viya-Ark can check the status of the services by issuing the following commands as the vmuser on the Ansible controller:
cd /sas/install/ansible/sas_viya_playbook/
ansible-playbook viya-ark/playbooks/viya-mmsu/viya-services-status.yml
Viya-Ark can restart all of the services by issuing the following commands as the vmuser on the Ansible controller:
cd /sas/install/ansible/sas_viya_playbook/
ansible-playbook viya-ark/playbooks/viya-mmsu/viya-services-restart.yml -e enable_stray_cleanup=true
If you encounter the following errors, remove the deployment and redeploy the software again.
This error is the result of issues related to dns/network during some critical times during the build. (In most cases, the system is set to reconnect or retry.).
This error is the result of RHEL RPM mirrors that are not always correct in Azure. The error is rare. Typically the repositories are back in sync within a few hours.
Ensure that the correct port on your Lightweight Directory Access Protocol (LDAP) or secure LDAP (LDAPS) machine can be accessed by the SAS Viya machines:
- Port 389 if using LDAP
- Port 636 if using secure LDAP (LDAPS). For more information about securing LDAP connections, see Encrypt LDAP Connections in the Encryption in SAS Viya: Data in Motion.
Create a service account in your LDAP system. The service account must have permission to read the users and groups that will log on to the system.
Note: OpenLDAP systems and customized AD setups might require additional configuration that is beyond the scope of this guide.
- See Configure the Connection to Your Identity Provider in the SAS Viya for Linux: Deployment Guide for more information about configuring the identities service.
- See Encrypt LDAP Connections in Encryption in SAS Viya: Data in Motion for more information about securing LDAP connections.
In the SAS Environment Manager, on the Configuration tab, select the Identities service. There are three sections to configure: connection, user, and group.
- host - the DNS address or IP address of your LDAP machine
- password - the password of the service account that SAS Viya will use to connect to your LDAP machine.
- port - the port your LDAP server uses
- userDN - the DN of the LDAP service account
- accountID - the parameter used for the user name. This can be uid, samAccountName or name depending on your system
- baseDN - DN to search for users under
- accountID - the parameter used for the name of the group
- baseDN - DN to search for groups under Set the default values to work with a standard Microsoft Active Directory system.
- Log in to SAS Viya with your LDAP accounts. You might need to restart SAS Viya for the LDAP changes to take effect.
- Run the ldapsearch command from one of the SAS Viya machines.
ldapsearch -x -h <YOUR LDAP HOST> -b <YOUR DN> -D <YOUR LDAP SERVICE ACCOUNT> -W
- Enter the password to your LDAP service account. If verification is successful, the list of your users and groups is displayed.
Because SAS Studio does not use the SAS Logon Manager, it has different requirements for integration with an LDAP system. SAS Studio manages authentication through a pluggable authentication module (PAM). You can use System Security Services Daemon (SSSD) to integrate the PAM configuration on your services machine with your LDAP system. To access SAS Studio, the following conditions must be met:
- The user must exist locally on the system.
- The user must have an accessible home directory.
For details about configuring SSSD against your LDAP setup, see the RedHat documentation. In many cases SSSD is configured to automatically create home directories when a user logs on to the system locally or via SSH. Because SAS Studio does not do this; you must manually create home directories for each remote user. After SSSD has been configured, you might need to restart the services machine.
From the Ansible controller VM, log in to the services VM:
ssh services.viya.sas
To list all users and groups:
ldapsearch -x -h localhost -b "dc=sasviya,dc=com"
- Create a user file that contains all the user info:
Note: You must increment the UID from the last one displayed by the ldapsearch command.
dn: uid=newuser,ou=users,dc=sasviya,dc=com
cn: newuser
givenName: New
sn: User
objectClass: top
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: posixAccount
loginShell: /bin/bash
uidNumber: 100011
gidNumber: 100001
homeDirectory: /home/newuser
mail: [email protected]
displayName: New User
- To add the entry to the directory:
ldapadd -x -h localhost -D "cn=admin,dc=sasviya,dc=com" -W -f /path/to/user/file
Note: You will be prompted for the admin password (the same one you specified when you created the stack).
- To enable the new user to access SAS Viya products, add the user as a member of the sasusers group by creating an ldif file with the following data:
dn: cn=sasusers,ou=groups,dc=sasviya,dc=com
changetype: modify
add: memberUid
memberUid: newuser
add: member
member: uid=newuser,ou=users,dc=sasviya,dc=com
ldapadd -x -h localhost -D "cn=admin,dc=sasviya,dc=com" -W -f /path/to/user/file
- Add the home directories for your new user on the services and controller VMs. From the Ansible controller VM:
ssh services
sudo mkdir -p /home/newuser
sudo chown newuser:sasusers /home/newuser
exit
ssh controller
sudo mkdir -p /home/newuser/casuser
sudo chown newuser:sasusers /home/newuser
sudo chown newuser:sasusers /home/newuser/casuser
exit
ldappasswd -h localhost -s USERPASSWORD -W -D cn=admin,dc=sasviya,dc=com -x "uid=newuser,ou=users,dc=sasviya,dc=com"
Note: To prevent the command from being saved to the bash history, preface this command with a space. The string following the -x should match the dn: attribute of the user.
ldapdelete –h localhost -W -D "cn=admin,dc=sasviya,dc=com" "uid=newuser,ou=users,dc=sasviya,dc=com"
SAS Viya Quickstart for Azure uses the following network security groups to control access to the servers and load balancers from sources outside the virtual network. All server to server communication between subnets in the SAS Viya virtual network is permitted.
Name | Ingress Rules | Egress Rules | Servers/Load Balancers | Notes |
---|---|---|---|---|
AnsibleController_NetworkSecurityGroup | Allow port 22/tcp from CIDR prefix specified in the "AdminIngressLocation" parameter. Deny all others. | Allow All | Ansible | Ansible/bastion server can be connected to through SSH only. |
PrimaryViyaLoadbalancer_NetworkSecurityGroup | Allow port 443/tcp from CIDR prefix specified in the "WebIngressLocation" parameter. Deny all others. | Allow All | PrimaryViyaLoadbalancer | The primary load balancer can be connected to only through https. |
Viya_NetworkSecurityGroup | Deny All | Allow All | Services Controller | No external connections can be directly made to the SAS Viya servers. |
By default, the OpenLDAP provider is set up if you provide a user password that does not use TLS to secure the communications between the controller and the OpenLDAP server. Most connections should be authenticated by the OAuth provider in SASLogon, which communicates by loopback with the OpenLDAP server. In a production environment, it is recommended that you enable TLS encryption for OpenLDAP queries. For information about enabling LDAPS, refer to the OpenLDAP documentation.
The Quickstart deployment is built to get you "up and running" quickly. However, the deployment trades some security for the assurances that a large quantity of SAS licensed products can be loaded without issue. Before you load highly valuable data, it is recommended that you:
- Lock down the communication between the servers to allow only those ports that your licensed products are using.
- Ensure that the user rights of created users are as minimal as possible.
During installation, yum updates servers but will not automatically apply patches after deployment is complete. To apply patches either:
- Schedule updates on the boxes through cron
- Regularly log on to the system and run a "yum update" command to keep security patches up to date on the operating system
When you deploy this template, Microsoft is able to identify the installation of SAS software with the Azure resources that are deployed. Microsoft is able to correlate the Azure resources that are used to support the software. Microsoft collects this information to provide the best experiences with their products and to operate their business. The data is collected and governed by Microsoft's privacy policies, which can be found at Microsoft Trust Center.