This post was kindly contributed by SAS Users - go there to comment and to read the full post. |
This post is written in the hopes of easing the SAS Viya deployment process for novices like me. Firstly, deploying SAS Viya, like most enterprise software packages, isn’t a skill we’re innately born with. We’re going to need a little help, some good documentation, and time to absorb the intricoes of the task.
There are many parts and pieces to standing up SAS Viya, depending on what you’re trying to accomplish and how you’d like to go about doing it. Know that the documentation and process can seem colossal and overwhelming, so take your time and don’t rush things. You got this.
Scope of the post
What this blog is and is not
This post will not walk you through the entirety of a deployment. Instead, it’ll point you to the right resources, guide you away from pitfalls, and show you how to accomplish certain tasks the documentation may not entirely cover. Many of these nuances were hard-earned lessons either by me or by people who have been kind enough to show me the way.
Please note the following
- my experience is limited, and mostly pertains to AWS and Azure
- the information is current at the time of this writing (December, 2021)
Please feel free to reach out to me if you have any suggestions, comments, or spot any mistakes. Many thanks!
Santa’s Workshop
Deploying SAS Viya is akin to creating toy trains in Santa’s workshop.
At its core, each toy train requires an engine, several cars, and a track. Likewise, each SAS Viya deployment requires a CAS engine that lives on a Kubernetes cluster together with several other servers (e.g., Compute, Connect, Stateful/Stateless), and storage.
Each toy train can be modified in numerous ways depending on the person’s preferences, whether it’s a steam locomotive or a bullet train. Or maybe it’s something more trivial, like merely the color of the train. Regardless of the need, Santa’s workshop contains a plethora of tools, materials, and plenty of knowledgeable elves who have different expertise and insights to customize the pipelines and trains.
Once again, each instance of SAS Viya can also be modified greatly depending on the customer’s needs. There are many hosts, flavors of servers, storage options, and common customizations. A SAS Viya deployment has its own kitchen sink full of tools, pipelines, and methods. And just like in Santa’s workshop, there are plenty of people who are experienced with deploying SAS Viya (and have specialties in different aspects of the deployment) who will assist if you run into issues.
Links Galore
There’s never a shortage of links required to complete deployments. I find myself with multiple windows filled with tabs (for referencing info) while I’m deploying so here’s a list of some I have found helpful.
-
- SAS Viya Operations Documentation
- This is the most important link, since it’s the official documentation covering deployment.
- The different pages (e.g., Virtual Infrastructure Requirements) referenced in this blog will be italicized and navigable through the left hamburger menu
- IMPORTANT! Please ensure you’re on the most recent version of the documentation (at the time of this writing, the link points towards 2021.1.6)
- SAS Viya Operations Documentation
- Setting up SAS Viya Monitoring for K8S
- Configuring LDAP
- IaC – Infrastructure as Code
- SAS Viya 4 Resource Guide
Setting Up Your Environment
There are several required tools for deployment. These include but are not necessarily limited to:
- kubectl v1.19.9
- kustomize 3.7.0
- Docker
Ensure your environment is set up precisely the way the docs recommend. For example, if you’re going the Terraform route from Viya4-IaC-AWS, you’re going to need this:
- Terraform v1.0.0
- kubectl v1.19.9
- jq v1.6
- AWS CLI v2.1.29
The documentation is rather specific in terms of the required version, so please read carefully.
Starting Off
To start off, there are a few required readings to get a better understanding of SAS Viya architecture and requirements. Please review these webpages as often as you’d like to ensure understanding and avoid missing any steps.
- Getting Started portion of the Viya Operations documentation (linked previously).
- In the System Requirements section, please pay special attention to the “Kubernetes Client Machine Requirements” (under Virtual Infrastructure Requirements) to ensure you have the right tools and versions installed.
- When you’re done reading the above, it’s time to set up the IaC.
Choose the corresponding link for “Help with Cluster Setup” (under Virtual Infrastructure Requirements) based on your cloud host of choice.
IaC
IaC stands for Infrastructure as Code. These are essentially scripts allowing you to build your cloud infrastructure and provision them through code instead of through the GUI. Several things to note here:
- I prefer cloning the IaC repo alongside the other folders, not within them so they’re better organized. It looks something like this:
Viya4 <– Parent directory
|– IaC
|– Deploy - Grab a sample .tfvars file under /examples and paste it into the root IaC directory. I recommend the “sample-input-minimal.tfvars” file if you’re just practicing.
- Rename this file to “terraform.tfvars” (or preferred name, just be aware that the doc’s instructions assume that you have named it “terraform.tfvars”)
- This file has several important values to keep in mind / input.
-
- This file contains the cluster configuration and details what all will be created
- “prefix” is essentially the name given to all your resources
- “default_public_access_cidrs” are CIDRs that you’d like to allow access to your cluster.
- “tags” you should include are {“resourceowner”=”your_Email”} (this is to ensure that people will be able to tell who owns the resource. Also, note that the preferred syntax is dependent on the cloud provider, please check the docs to be sure)
- “postgres_servers” should only be uncommented if you require an external db server (more expensive), if you don’t and you’re just practicing, leave it commented and it should create an internal one
- I highly recommend going the Docker route instead of Terraform (I have personally run into fewer problems through Docker, especially the tearing down process as compared to Terraform).
- It takes a while to create the cloud resources so have patience (takes about 15 mins at most).
- Once the resources exist, ensure you copy the
[prefix]-eks-kubeconfig.conf
file into your$(pwd)
as well as your~/.kube/config
file if you’d like to keep it. The command to copy the conf file to your~/.kube
location iscp <.conf file> ~/.kube/config
- After you’re done with the above, make sure you run
export KUBECONFIG=<.conf file>
- Test that your deployment is actually up:
kubectl get nodes
Post-IaC
The next section covers additional SAS Viya requirements for the cluster after standing it up. There are a few things I’d recommend building after ensuring the deployment is up.
- Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v0.44.0/deploy/static/provider/cloud/deploy.yaml
- Cert Manager
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.2.0/cert-manager.yaml
- Helm/nfs-provisioner (this part is specifically for AWS)
What’s happening here is that we’re getting the elastic load balancer URL from the ingress-nginx, the EFS ID, and installing the NFS server provisionerkubectl get service -n ingress-nginx ELBURL=$(kubectl get svc -n ingress-nginx ingress-nginx-controller --output jsonpath='{.status.loadBalancer.ingress[0].hostname}') echo $ELBURL EFSFSID=$(aws efs describe-file-systems --region $AWS_DEFAULT_REGION --query "FileSystems[*].FileSystemId" --region $AWS_DEFAULT_REGION --output text) echo $EFSFSID helm repo add stable --force-update helm install stable/nfs-server-provisioner kubectl get storageclass # to check if the NFS server is up
- Create a namespace where your SAS Viya deployment lives in the cluster –
kubectl create ns
. It is critical to go through the System Requirements entirely to ensure you don’t miss any steps (Just be sure that you’re following the portions meant for your cloud host). Examples in the Hardware and Resource Requirements page:- Azure – There’s an “Additional PVC Requirements for Microsoft Azure”: a link for “Specify PersistentVolumeClaims to Use ReadWriteMany StorageClass” where you’re required to add a file in the
/site-config
directory and an additional portion under “transformers” in thekustomization.yaml file
- AWS – Under “File System and Shared Storage Requirements” refer to the notes on installing a provisioner for the EBS volumes. (The instructions are in the code block above)
- Azure – There’s an “Additional PVC Requirements for Microsoft Azure”: a link for “Specify PersistentVolumeClaims to Use ReadWriteMany StorageClass” where you’re required to add a file in the
Installation
This section sets up the parameters and additional customizations to included in the $deploy folder. It falls specifically under the Deployment tab of the SAS Viya Operations documentation.
After retrieving the required files (under the desired version!), the certificates, license, and all assets and untarring them, take a good look at the section named “Directory Structure” so you have an understanding your desired file structure.
Under “Installation -> Initial kustomization.yaml file”, once you’ve created your kustomization.yaml
file, there are a few things of note here to change:
- {{ NAME-OF-NAMESPACE }}
- If you haven’t already created the namespace where SAS Viya will live, do so now (instructions above #4)
- Once you have a namespace, replace the entire thing including the {{}} with the name you have chosen.
- You can always check what namespaces your cluster has by running
kubectl get ns
- {{ NAME-OF-INGRESS-HOST }} and {{ PORT }} (note that there are multiple references in the kustomization.yaml file)
- Use
kubectl get service -n ingress-nginx
and use the external-ip of the output - port is 80
- Use
There are plenty of instructions beneath the kustomization.yaml
file example, be sure to read through them and follow their instructions thoroughly.
Additionally, the Common Customizations page is chock full of useful information for the deployment. A few sections to note:
- Using a Mirror Registry
- Configure TLS
- Configure PostgreSQL
- Specify PersistentVolumeClaims to Use ReadWriteMany StorageClass
Deployment!
Once you’re satisfied with your customizations, it’s time to deploy. You can either go through the Orchestration Tool or deploy manually.
If you deploy manually, you can either run the following:
kustomize build -o site.yaml kubectl apply --kubeconfig=kubeconfig-file --selector="sas.com/admin=cluster-wide" -f site.yaml kubectl wait --kubeconfig=kubeconfig-file --for condition=established --timeout=60s -l "sas.com/ admin=cluster-wide" crd kubectl apply --kubeconfig=kubeconfig-file --selector="sas.com/admin=cluster-local" -f site.yaml --prune kubectl apply --kubeconfig=namespace-kubeconfig-file --selector="sas.com/admin=namespace" -f site.yaml --prune |
OR
kustomize build . | kubectl apply -f -
(Note that this is the shortcut of building and piping the results to be applied in kubectl. It does not output a site.yaml file.)
There are a few false-positive errors that may appear during the process (the documentation outlines them pretty clearly).
Post-Deployment
You may run the readiness service to check for when your deployment is ready. Note that this process is lengthy and the fastest I’ve seen a deployment go up is about 15-20 mins. (Now’s a good time to go for a walk or get a cup of coffee).
I highly recommend using Lens to visualize the deployment process and to take a look at the pods and their logs (mini section below).
While all of these steps are possible in Lens, it’s good to know the commands required to inspect and manipulate pods.
kubectl get pods -n # Take a look at all the pods, add a -W flag to watch them as they update kubectl describe pod -n # To describe specific pods kubectl logs -n # To see the logs of specific pods kubectl delete pods -grace-period=0 --force # To force deletion of pods, pods will automatically restart after being deleted. |
Important pods to look at:
- Logon
- Consul
- Cache
These pods are pre-requisites for many other pods to come up. If they’re stuck, go ahead and delete them to initiate a restart. This seems to work frequently.
If the pods look good, try going to this website: www.name-of-ingress-host:port/SASDrive
. You should see a blue background and a SAS login screen.
Hooray! Now you just have to follow the Sign In as the sasboot User instructions and complete other post deployment tasks (Post-Installation Tasks, Validating the Deployment, etc.” that are pertinent to your use case.
Quick aside: Lens
K8s Lens is an incredibly useful IDE to visualize what is going on in your Kubernetes cluster.
Here are two quick screenshots to help you get situated when you’re looking at pods.
First, you need your .conf file to connect to your cluster. Upon entry, click on Workloads -> Pods to look at the pods. Also click on your namespace for all of the pods for the SAS Viya Deployment to show up.
There are times where you’ll see a yellow triangle with an exclamation mark. While this is technically a warning, it may be an indicator of an error your pod is suffering from. (If you see a HTTP 503 Readiness Probe error, it may just mean that the pod is starting up)
Click on the pod and the lines on the top right in order to see the logs for the chosen pod.
Conclusion
Hopefully this post was helpful for your start in deploying SAS Viya.
Please remember there’s a lot more to it than is covered here. Don’t be disheartened if this wasn’t particularly easy, it certainly wasn’t for me.
Know there are plenty of customizations as well as a constant stream of changes (updates, product related etc.), new methods, and places to deploy.
So there’s always plenty to learn.
Please feel free to reach out and let me know if you have any questions or suggestions for this post.
Acknowledgements
Many thanks to my colleagues Ali Aiello and Jacob Braswell for answering my incessant questions and helping me on this journey!
A Novice Perspective on SAS Viya Deployment was published on SAS Users.
This post was kindly contributed by SAS Users - go there to comment and to read the full post. |