Planning the URL names of your SAS Viya deployment – part 1
Understanding the Ingresses and Ingress controllers' concept is key to planning and implementing your SAS Viya deployment.
Although you could perform what appears to be a successful deployment of the new SAS Viya with a wrong value for the {{ NAME-OF-INGRESS-HOST }} variable, and have all your Viya services up and running, the problem is that nobody will be able to use the deployed environment...
Because without the proper Ingress name, no one can connect to the Viya Web applications ...
In this series (2 parts), we’ll discuss the networking comimplications to make SAS Viya web apps, CAS or 3rd party applications (like the logging and monitoring tools for Viya or the Viya API for CLIs access) reachable from outside of the Kubernetes Cluster.
We will link them to the DNS requirements and show how they map to the settings that need to be defined during the deployment.
The Ingresses, Ingress Controller and Services, are clearly not the simplest concepts to understand in Kubernetes.
So we'll also illustrate them with several diagrams to show what it means in a Viya deployment.
If you are new to the Kubernetes networking concepts, then Rob Colum's article, K8S Primer for Viya: Networking, would the perfect starting point before reading this post.
The famous {{ NAME-OF-INGRESS-HOST }}
If you are planning to deploy the new SAS Viya, you have probably opened the "Initial kustomization.yaml File" page in the Deployment Documentation.
The kustomization.yaml file is the main configuration file for your deployment and, as the Installation engineer, you are expected to write it, based on:
- The Architecture design that was previously approved by the customer (at least in Theory !)
- and any customization that might have been required (external PostgreSQL, mirror registry, additional CAS MPP, full HA, CAS settings, etc).
After that, all you must do is to run 2 commands to build the Kubernetes manifests from this kustomization.yaml file and apply them to the Kubernetes Cluster to deploy SAS Viya.
The deployment guide, kindly provides an example of the file:
Mobile users: To view the images, select the "Full" version at the bottom of the page.
OK it seems easy…But wait …you need to replace each variable that is enclosed by braces ({ }) with the values that are appropriate for your deployment !
Let’s have a better look at that.
{{ NAME-OF-NAMESPACE }}: this one is easy. You know that each Viya deployment will run in its own Kubernetes namespace (which is like a personal folder in the Kubernetes to gather and hold a set of objects). For example, it can be LAB, DEV-TEST or VIYAPROD or whatever the customer wants to call this specific Viya deployment.
{{ DIRECTORY PATH }}: simply corresponds to the directory on your client machine where you have placed your deployment assets specific “site” configuration.
Now, {{ NAME_OF_INGRESS_HOST }} corresponds to the URL base that the customer wants to expose to the SAS applications users. The {{ PORT }} parameter is optional, as the HTTP schema is usually determined by the start of the url ("http" or "https").
So, for example, you will replace {{ NAME_OF_INGRESS_HOST }} with something like:
- viyalab.example.com
- or pdcesx4532.race.sas.com
- or eatus.cloudapp.azure.com
- or gelsandbox.gke.unx.sas.com
- or viya.giga.com
It corresponds to a DNS name or alias that the customer needs to provide so their end-users can access the applications.
As a reminder a DNS (Domain Name System) is what lets users connect to websites using domain names instead of IP addresses.
While with SAS 9 or Viya 3.5 the SAS applications’ URLs are usually based on the web server machine name concatenated with the domain name, with the new SAS Viya we need to ask the customer for a real DNS entry for each Viya environment that we want to expose to the outside world.
Understand what you are doing
So before being in position to provide the correct value for this {{ NAME_OF_INGRESS_HOST }} parameter in the kustomization.yaml file, you need to know this DNS name and understand how it will send the users to your SAS Applications.
Let’s look at how it works in Azure Kubernetes Service – or “AKS” (as it is still – at the time of this article – the only supported Kubernetes environment).
The NGINX Ingress controller was installed in your cluster as part of the deployment pre-requisite. During its installation a new Load-balancer service was created, called “Nginx Controller”.
Each time that a K8s LB service is created, an external IP address is automatically provisioned by the Cloud provider.
You can get the IP address easily with the command below.
LBIP=$(kubectl get service -n ingress-nginx | grep LoadBalancer | awk '{print $4}') echo $LBIP
In AKS it means that a new external IP address was provisioned and added as a Front-end IP for our AKS Load-balancer.
Having an external IP address is good as it makes our applications visible outside of the Kubernetes Cluster, but who wants to type an IP address in the browser URL to access his applications?
What we need now, is to associate a DNS name to our IP address !
By default, Azure lets you do it, quite easily, either with the Azure CLI command or in the Azure Portal, as you can see below.
In this example we have set the DNS name with the Azure CLI command, to: frarpovk.eastus.cloudapp.azure.com
However, it is generally not what you want to do... because the DNS names always ends with <azure region>.cloudapps.azure.com and you can associate only one DNS name for each public IP address.
What is much more likely to happen with the customer is that they will associate a DNS entry to the Azure External IP address in their own corporate DNS Server. That way, their corporate DNS top-level domain can be used to provide something like sasviya.site.com.
Regardless of how the DNS name is provided, that’s the value you need to use for the {{ NAME_OF_INGRESS_HOST }}value in the kustomization.yaml file.
With this information, the deployment manifests create the Kubernetes Ingress rules that NGINX (our Ingress Controller) uses to send the users request to the appropriate services.
Let’s summarize this process in a diagram.
You can also see it in Lens if you are using it:
If you have this vision for your customer use case, it will really help you to know what the {{ NAME_OF_INGRESS_HOST }} should be.
OK, but I made a mistake with the {{ NAME_OF_INGRESS_HOST }} and deployed with the wrong value!
Don't worry. If you don't have the {{ NAME_OF_INGRESS_HOST }} value perfectly right from the beginning, that's ok, you don't have to redeploy everything, just change the value in your kustomization.yaml file, rebuild the manifests and reapply them, so only the ingresses will be updated to match the DNS name.
OK, but what if I want another Viya environment?
Well, if you want to deploy another Viya environment you will need another DNS name.
Deploying another Viya environment in the same Kubernetes cluster requires a new namespace and a new kustomization.yaml file. The best practice is to create a different dedicated directory for this new environment where you can have the deployment assets and the associated kustomization.yaml file and "site-config" directory.
Once you have your new DNS name for the new Viya deployment, just set it in the {{ NAME_OF_INGRESS_HOST }} and perform the deployment in the new namespace.
As you can see below, at the end of the deployment, you will then have new ingresses for the second Viya environment (for example: “viyaprod”) and your Ingress Controller, based on the URL and “viyaprod” ingresses, will redirect the end-users to the corresponding Kubernetes services running in the appropriate namespace.
That's it for today!
In the next article (part 2), I go a step further by explaining how to expose the monitoring and logging tools and also TCP services such as CAS and SAS/CONNECT.
Thanks for reading.
