SAS Viya provides import and export functionality for user-created content like reports and data plans. Often, in addition to content, an administrator will want to save configuration so that it can be reloaded or updated and applied to a different system. SAS Viya provides the capability to save and reload configuration using the SAS Viya command-line interfaces that are documented here and that I covered in a previous blog post.

The configuration plug-in of the sas-admin command-line interface provides this key functionality. The configuration plug-in allows an administrator to interact with the SAS Viya micro-services configuration from the command line.

Before we look at a save and reload, let’s look at the format of the micro-services configuration. The configuration is created at time of deployment and can be supplemented, edited and updated in the SAS Environment Manager Configuration area.

A service’s configuration consists of the following components:

• configuration definition: a schema that describes a type of configuration.
• configuration instance: a collection of name-value pairs that a service uses.

In Environment Manager there are two “views” where you can add or edit configuration instances. You can select a service to see the configuration instances for that service, or select a definition to see all configuration instances that are defined by the configuration definition.

This screenshot shows the configuration instances for the identities service, with (a few of) the name value pairs for the sas.identities.providers.ldap.user visible.

It is possible to save a set of configuration settings and reload them to the same or a different system. This can be useful when you have your configuration established and you wish to keep a backup, or make a selective backup of configuration prior to making a change.

The connection to LDAP is a key early step in a SAS Viya implementation. With the configuration CLI, once you have the SAS Viya LDAP configuration established, you can export it to a file, and then use that file (with any necessary modifications) to stage additional systems, or as a backup prior to making changes to your existing systems configuration.

How to save and reload configuration

As always, when using the command-line interfaces you must create a profile and authenticate.

In this example, we use the sas-admin CLI, using sas-configuration-cli plugin and the configurations command to manage configuration objects in the configuration service.

The examples use the download command to download the configuration for a service and a definition name.

View the Configuration

As a first step, you can view the configuration. To view configuration you need to know the configurations id. This can be returned using the list command, passing the definition-name and service.  (NOTE: The CLI calls assume you are in the CLI install directory /opt/sas/viya/home/bin/)

In this case, we get the id of the ldap user SAS Viya configuration.

./sas-admin configuration configurations list --definition-name sas.identities.providers.ldap.user  --service identities

Next, using the id from the previous step you can list the configuration properties.

./sas-admin configuration configurations show -id b313a5a7-1c73-4f4a-9d3d-bba05b626939

Save LDAP Configuration

The save process creates json files. The following steps use the download command to save to json files the connection, user and group configuration instances for the SAS Viya connection to LDAP.

./sas-admin configuration configurations download --target /tmp/ldapconnection.json  --definition-name sas.identities.providers.ldap.connection  --service identities
 
 
./sas-admin configuration configurations download --target /tmp/user.json  --definition-name sas.identities.providers.ldap.user  --service identities
 
 
./sas-admin configuration configurations download --target /tmp/group.json  --definition-name sas.identities.providers.ldap.group  --service identities

You should open the json files and check that the correct configuration has been saved. It is possible for the process to complete without errors and return json that is not what you are expecting. This would cause problems with your reload, so checking the saved json is important.

You can keep the JSON file as is, or make changes to key attributes. You may want to do this if you are importing to a different system.

Load the SAS Viya LDAP Configuration

To load you simply use the update command and pass the json file.

./sas-admin configuration configurations update --file /tmp/ldapconnection.json
 
./sas-admin configuration configurations update --file /tmp/user.json
 
./sas-admin configuration configurations update --file /tmp/group.json

The impact of isDefault

There is a value, isDefault, stored within the configuration which has an impact on the persistence of changes made to configuration.

isDefault impacts how services treat existing configuration when a service starts. When a service starts a setting of:

• isDefault=true in the existing configuration means the service will overwrite the configuration object with new defaults.
• isDefault=false in the existing configuration means the service will NOT overwrite the existing configuration object.

In other words, if the configuration is flagged as “default” then the service is permitted to update or add to the default values.

Objects created by the services at startup always have isDefault set to true. Objects created in Environment Manager always have isDefault set to false. This means changes in Environment Manager are always respected by services on restart, they will not be overwritten.  But services are allowed to overwrite their own defaults at startup.

When using the CLI, the administrator needs to decide what is the appropriate value for isDefault. If you require the configuration change to persist across service restarts then set isDefault=false.

Saving and Reloading Micro-Service Logging Levels

Let’s look at another use case for save and reload of configuration. Updating micro-service logging configuration levels in batch can be very useful. You may want to save your current logging configuration and modify it to raise logging levels. You may create multiple json files with different logging configurations for different scenarios. When debugging an issue in the environment you could load a verbose logging configuration. If you wish to keep the new configuration you would edit the json and set IsDefault=false.

The step below saves all configuration instances created from the logging.level configuration definition. These configuration instances control the logging level for the SAS Viya microservices and servers.

./sas-admin configuration configurations download --definition-name logging.level -target /tmp/default_logging.level.txt

If you wish to persist your new logging configuration, edit the file to set metadata.isDefault=false, save the new file and then and update the logging configuration using the update command:

./sas-admin configuration configurations update --file /tmp/new_logging.level.txt

When you are done, you can use the original file to reset the logging level back to default values.

In most cases a server restart is not required after a configuration update, exceptions are documented in the SAS Viya Administration Guide. If you are interested in how configuration storage and update works you can also find details in the administration guide.