Where to configure the SAS Programming Run-time with broader or narrower scope

3 Likes

There are at least four different breadths of scope over which you can configure the SAS Programming Run-time. They are:

SAS Launcher: broadest scope, affects all Programming Run-time sessions in the whole SAS Viya deployment
Compute, Connect or Batch Service
Compute, Connect or Batch Context
User-specific autoexec, user-specific custom SAS code: narrowest scope, affects only one user, in SAS Studio

Not all of these breadths of scope apply to all services or clients. Even so, this is really useful because it allows, e.g. the maximum number of SAS Programming Run-time sessions a user is allowed to have running at once to be defined in a single place and yet apply across every SAS programming run-time sessions in the whole SAS Viya deployment. At the same time, other settings e.g. a very task-specific SAS macro or library definition can be defined only for the user who needs it, or only in the programming run-time context in which it is used. The intermediate locations provide degrees of broader or narrower scope between those extremes.

All this gives SAS Administrators fine control over how broadly or narrowly individual aspects of programming run-time session, such as localization (language, character encoding, timezone), LOCKDOWN paths, macro definitions, SAS options and other configuration are applied. It's good for SAS Administrators to know all the places where they can apply such configuration, to affect just the programming run-time sessions they intend to affect.

So, in this post, we'll review the main parts of the SAS Programming Run-time that can be configured, and we'll consider the effective breadth of scope - which sessions they will affect - for their configuration settings.

SAS Launcher

In SAS Viya, all compute and batch sessions, and by default all connect* sessions, run on processes in sas-programming-environment containers in pods which are started by the SAS Launcher Service.

What can you change?

Examples of global configuration settings which can be adjusted for Kubernetes resource definitions at the SAS Launcher level include:

Modifications to all podTemplates used by SAS Launcher, targeted like this: "target": {"labelSelector": "sas.com/template-intent=sas-launcher", "kind": "PodTemplate"}.
- To pick an example, you might change the path of the viya volumes in these podTemplates, to relocate temporary files such as those used in the SASWORK library to faster or larger storage than whatever is used by a Kubernetes emptyDir in your cluster.
Adjustments to the amount of memory and CPU made available to launched SAS Programming Run-time pods.
- These adjustments are made by setting one or more of a set of eight variables that control default and maximum values for the CPU and Memory requests and limits in launched pods.
When SAS Workload Management is not included in the deployment, changes to the SAS_LAUNCHER_USER_PROCESS_LIMIT, which sets an upper limit to the number of launched pods that each user can have running at once. This limit applies across launched compute, connect and batch pods.
When SAS Workload Management is included in the deployment it takes over responsibility for launching all compute, connect and batch servers from the SAS Launcher. In this case, as my colleague Rob Collum wrote in his post Improving Concurrency Performance in SAS Viya, you must use a alternative setting to limit Maximum Jobs Allowed per user:
- As an administrative user in SAS Environment Manager, navigate to the SAS Workload Orchestrator configuration
- Under Host Types, expand the desired section (“default” is the default)
- Change the maximum number of jobs value to a better value, like 50, or 100.

There is no global autoexec.sas code block or file. To globally define the sorts of things that go in an autoexec, like libraries and macros or SAS Options, you must add the definition separately to each of the Compute, Connect and Batch service autoexec_code blocks.

Where can you change it?

Changes to these things are best made in YAML files in your SAS Viya deployment's site_config directory, by copying and editing sample overlays. There are some additional examples here: SAS Help Center: Common Customizations.

What is the scope of these changes?

Configuration changes applied to the SAS Launcher Service have a global scope - they affect every launched* SAS Programming Run-time server, and the session(s) it runs. * SAS/CONNECT in older versions of SAS Viya could spawn connect sessions directly in the SAS Connect Service pod, without launching any new pods. This can still be enabled, but in recent releases spawned connect sessions are disabled by default.

Compute, Connect and Batch Services

The SAS Viya Compute, Connect and Batch Services run all the time. Each of these acts as a front end for client applications and services to launch, submit code to, check the status of and get program logs and results from programming sessions.

What can you change?

Each of them has configuration settings which allow you to specify autoexec code that runs while a compute, connect or batch pod initializes its respective programming session. You can also specify configuration options (SAS Options like in a sasv9.cfg file in SAS 9), restricted options whose values are set by the SAS Administrator and cannot then be overridden by users, and startup commands for each of the three kinds of SAS Programming Run-time server. The full set is documented here in the SAS Viya Administration Guide.

Where can you change it?

Configuration for the Compute, Connect and Batch services is stored in the SAS Configuration Server. View and modify it in SAS Environment Manager's Configuration page, or using the sas-viya CLI's configuration plug-in, and its configurations keyword, e.g. (using jq to help):

sas-viya configuration configurations show --id $(sas-viya configuration configurations list --definition-name sas.compute.server | jq -r '.items[] | select (.name | contains("autoexec_code")) | .["id"]')

What is the scope of these changes?

The configuration options for each type of SAS Programming Run-time server apply to all programming sessions started under that type of server, and are specific to that type of server; they don't impact the other two types.

Launcher Contexts

Per the documentation, A launcher context is a specification that enables SAS administrators to apply environmental and access constraints on processes that are run by a launcher service. Each Compute, Connect and Batch context references a single Launcher context. The Launcher context references a podTemplate.

What can you change?

Launcher Contexts represent some - though not all - of the configuration to be applied when starting compute, connect and batch servers.

They specify which podTemplate should be used to create the compute, connect or batch server pod. Each podTemplate comes with a number of configuration settings of its own.

They also provide a place to define environment variables, e.g. to set character encoding or locale, specify OS commands - usually shell scripts - which must be executed as the SAS programming session starts, and/or specify the queue that the session should be placed in for SAS Workload Orchestrator. Personally, I have not come across a use case for modifying a launcher context yet, but I have not needed to change a deployment's character encoding and locale or configure its Workload Management queues lately. This is a good place do those things.

Where can you change it?

Launcher Contexts are managed by the Launcher service, and stored in the SAS Configuration Server.

View and modify them in SAS Environment Manager's Contexts page (in the Launcher Contexts view), or using the sas-viya CLI's compute plug-in, and its launchers keyword, e.g. sas-viya compute launchers list.

The podTemplates referenced by launcher contexts can also be modified (like the SAS Launcher service itself) using YAML files in your SAS Viya deployment's site_config directory, by copying and editing sample overlays.

What is the scope of these changes?

Changes to a launcher context affect SAS Programming Run-time sessions started in a compute, connect or batch context that use that launcher context. You can usually tell which these are from the launcher context name. But you may need to inspect a number of compute, connect or batch contexts to find all of them that use a specific launcher context.

Compute, Connect and Batch Contexts

Compute, Connect and Batch Contexts provide SAS Administrators with a place to define configuration settings for SAS Programming Run-time sessions. Documentation: SAS Help Center: Server Contexts: Concepts.

Each context is intended to be used by a either specific SAS client (e.g. SAS Studio, SAS Model Manager), or for a specific purpose (e.g. data mining, managing CAS formats, running backup jobs), and you can even create compute contexts for specific groups of users.

In some client applications like SAS Studio, the end user can choose which context their programming session runs under, from a list that is filtered to only show contexts the user has permission to use. Out of the box, all compute, connect and batch contexts are accessible by all users, but a SAS Administrator can create their own contexts (of any of the three types), and can restrict which users and groups can use them.

What can you change?

Several compute contexts are created out-of-the-box in a SAS Viya deployment, and you can add your own. Out-of-the-box (in my deployments) there is only one connect context and two batch contexts. As my colleague Edoardo Riva pointed out, starting in SAS Viya 2021.2.6 (released in April 2022), there is a second batch context for command-line commands. If your deployment of SAS Viya is an earlier version than 2021.2.6, you will likely only have one batch context out-of-the-box, but you can create your own.

Compute contexts (and by extension, presumably batch and connect contexts too), provide a place to specify attributes that modify the behaviour of a compute (or connect or batch) session. Examples include runServerAs, used to run sessions under the context as another user, reuseServerProcesses used to make compute servers reusable, or serverMinAvailable, used to pre-start a pool of available servers.

They also have a place to define additional SAS autoexec statements, SAS options or a SAS Workload Management queue.

And, through their associated launcher context, they provide an indirect way to use a different podTemplate from the default, if you have created additional podTemplates.

Finally, a new feature in SAS Viya 2022.1.3 and later allows SAS Administrators to define Library Connections (also called 'Connections to Data Sources' or 'Data Source Definitions') with the 'Allow all users to view the library connection' option selected. If this option is selected for a Library Connection resource, it is associated with the current compute context as a 'Resource', and will be declared for all compute sessions started under that compute context. See @GerryNelson's post: Managing Connections to Data Sources for Compute sessions in SAS Viya.

Where can you change it?

Compute, Connect and Batch Contexts are managed by their respective services, and stored in the SAS Configuration Server. View and modify them in SAS Environment Manager's Contexts page (in the Compute contexts, Batch contexts and Connect contexts views).

You can also modify compute and batch contexts using the corresponding plugin (computeor batch) for the sas-viya CLI. Here are some examples:

sas-viya compute contexts list
sas-viya batch contexts list

I am not aware of a sas-viya CLI method for modifying Connect contexts in SAS Viya Stable 2022.09.

Library Connections are created in SAS Studio, using the normal New Library button on the Libraries tab. Check the 'Assign and connect to data sources at startup' checkbox in the New Library dialog, and also the 'Allow all users to view the library connection' checkbox, to define the library at the Compute Context level, rather than just for yourself. The Library Connection is added to the list of resources associated with the compute context. Access to it is managed either in SAS Studio or in SAS Environment Manager > Contexts > Compute Contexts > [choose compute context] > Resources tab. See this post for details.

What is the scope of these changes?

Changes to a compute, connect or batch context affect all SAS Programming Run-time sessions started in that context, and don't affect sessions started in any other context.

User-specific

So far as I am aware, the only SAS client to explicitly support user-specific configuration for the SAS Programming Run-time is SAS Studio.

What can you change?

You can add user-specific SAS code statements to your own SAS Studio-specific autoexec file, which are run when you open SAS Studio and start a new compute session.

You can use the Custom SAS Code dialog to specify preamble and postamble SAS code statements to be run immediately before and after you run SAS Programs, and also optionally before and after running Tasks, Queries and Imports.

As hinted at earlier, when creating a Library Connections in SAS Studio, if you do not select the 'Allow all users to view the library connection', the library connection is referenced in your user-specific autoexec file and is thus available for you (only) but in ALL compute contexts. See @GerryNelson's post Managing Connections to Data Sources for Compute sessions in SAS Viya .

Where can you change it?

In SAS Studio, once a compute session has started, choose Options > Autoexec file from the application menu bar to show the Autoexec file popup dialog, to which you can add your own SAS code statements to run when your SAS Studio session starts, for example:

The content of your Autoexec file is loaded and runs automatically, once, when you (and only you) start a new SAS Studio compute session, in any compute context. It is not loaded or run for any other users.

In SAS Studio, once a compute session has started, you can also choose Options > Custom code to define your own preamble and/or postamble, and which sorts of SAS Studio tasks it should be run before and after. This custom preamble code runs before your submitted code, and the postamble code runs afterwards, each time you submit code in a SAS Studio session. Again, this applies to code run by you (and only you) in any compute context.

Here is some example preamble code:

And here is some example postamble code:

New Library Connections (also known as 'Connections to Data Sources' or 'Data Source Definitions') are created in the 'New Library' dialog in SAS Studio: open if by choosing the Libraries tab on the left, and then clicking on the 'New Library' button above the list of currently-defined libraries:

Check the 'Assign and connect to data sources at startup' checkbox in the New Library dialog. If you see it (because you are a SAS Administrator) do not check the 'Allow all users to view the library connection' checkbox. The library connection will be defined for only you. You will see its reference in your personal Autoexec file.

What is the scope of these changes?

These configuration settings only appear to affect the user who makes them, in SAS Studio (and not in other SAS clients or e.g. SAS batch programs) but for all Compute contexts.

If you know of other places to configure SAS Programming Run-time sessions, please comment below, or get in touch, and I'll update this post to mention them.

Many thanks to @RobCollum, @GerryNelson and @EdoardoRiva for their insightful comments and suggestions. I'd encourage you to read their posts, linked to from this one.

See you next time!