Custom SASWORK with SAS Viya 2023.02 and Later

1 Like

Starting with the 2023.02 SAS Viya release, there are small but significant changes to the process required to configure SAS temporary storage (SASWORK). In this post, we will delve into the implementation details and the steps you must follow to keep your configuration current.

What has not changed

Let’s start by listing what has not changed. The performance requirements for SASWORK have not changed. The architectural considerations are still the same.

In short, the two main reasons to use a separate, high-I/O throughput volume for SASWORK are still:

To improve the performance of SAS compute processing.
To protect other volumes in your deployment from being filled up if users fill the disk used by SASWORK.

There are plenty of articles on these topics, see for example:

How to apply the customization

The high-level steps needed to perform this customization have not changed as well. You can find official instructions in the README file $deploy/sas-bases/docs/ sas_programming_environment_storage_tasks.htm.

In summary:

Copy the change-viya-volume-storage-class.yaml example from sas-bases to site-config
Replace the {{ VOLUME-STORAGE-CLASS }} placeholder with the desired storage class (i.e., hostPath)
Add a reference to this file into the base kustomization.yaml
Apply the new configuration to your cluster using the same method originally used to deploy SAS Viya

No need to restart any pod. The next time a compute server will start, it will use the new definition.

What has changed, then? Digging a bit, you’ll find that the differences from previous releases lie in the content of the sample file change-viya-volume-storage-class.yaml and how to reference it in the base kustomization.yaml (i.e., points 1) and 3)).

Let’s see both in detail.

The patch file

Here is a comparison of the content of the sample file change-viya-volume-storage-class.yaml, before and after the change:

Up to SAS Viya 2023.01: Kustomize Patch	Starting with SAS Viya 2023.02: Kustomize Transformer

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

As you may notice, although the syntax is quite different, both the old and the new methods perform the same 2 actions:

Delete the current definition of the viya volume
Define a new viya volume using the storage class you will place in the placeholder {{ VOLUME-STORAGE-CLASS }}

Kustomization.yaml

The second change is how to reference that custom file in the base kustomization.yaml. Here is a partial printout to show a comparison of the old and new syntax:

Up to SAS Viya 2023.01: add a new entry in the patch section	Starting with SAS Viya 2023.02: add a reference to the custom file in the transformers section

Notice that the old method placed the "target" lines with a PodTemplate selector in the patch section of kustomization.yaml, while, with the new syntax, the same goes in the change-viya-volume-storage-class.yaml file (twice, once per Transformer)

Also, note that the new instructions require placing the line referencing the custom change-viya-volume-storage-class.yaml before the existing line '- sas-bases/overlays/required/transformers.yaml', as shown above.

Why this change?

Given that the end result is still the same as with previous releases, you may wonder what's the reason for this change. Well, it all has to do with a change in the supported version of the tool used to parse the configuration directory, Kustomize.

Since the release of SAS Viya 2020, we’ve always been using the same tried and true Kustomize 3.7.0. The time for an upgrade was so due, that we did it twice in a row. SAS Viya stable 2023.02 requires Kustomize 4.5.7, while SAS Viya 2023.03 and later releases (both stable and LTS) require Kustomize 5.0.0. (Note: this is accurate as of the time of writing. Always refer to the official requirements for the correct version for your release)

Kustomize dropped support for the old syntax a few versions ago, so we had to change to avoid parsing errors.

Am I affected by this change?

Let’s start with the easy answer. If you have an existing environment where you accepted the default configuration, nothing has changed there, so you are not affected.

If you are going to deploy or change an environment for the first time, then you have to use the syntax following the instructions included in your release. If this is SAS Viya stable 2023.02 or later, that means the new instructions: no need to care about what earlier SAS Viya releases required.

The only case where you should care is if you have an existing environment, deployed with a release older than 2023.02 (either stable or LTS) where you applied the old-style patch to configure a custom location for SASWORK. Even in this case, the runtime environment will not be affected if you leave it "as is": users can still use their applications with no errors. But, as soon as you try to upgrade the installation to the 2023.02 release or later, the upgrade process will fail if you leave the previous file and configuration in place. You have to change the custom change-viya-volume-storage-class.yaml that was placed under your site-config directory, then change the base kustomization.yaml, as shown above. If you do not, you may initially not get any error, but the resulting manifest (site.yaml) will be invalid. The old custom files, used with kustomize 4 or later, will output PodTemplates totally missing any SASWORK definition:

Comparing a “default” manifest (right) with one created with the old-style patch and kustomize 5.0.0 (left)

As soon as you try to apply that incorrect manifest, the operation will fail with errors such as:

Error from server (Invalid): error when applying patch:
...
Resource: "/v1, Resource=podtemplates", GroupVersionKind: "/v1, Kind=PodTemplate"
Name: "sas-batch-cmd-pod-template", Namespace: "viyaorch"
for: "site.yaml": PodTemplate "sas-batch-cmd-pod-template" is invalid: template.spec.containers[0].volumeMounts[1].name: Not found: "viya"

Conclusion

Starting with the 2023.02 SAS Viya release, there have been small but significant changes to the steps required to configure SAS temporary storage (SASWORK). While the high-level steps have not changed, there are differences from previous releases in the content of the sample file change-viya-volume-storage-class.yaml and how to reference it in the base kustomization.yaml. The changes are required by the newer version of Kustomize used with recent SAS Viya releases, and the end result is still the same as with previous releases. Be sure to check and update your existing customizations to avoid any errors!

Find more articles from SAS Global Enablement and Learning here.