Embed Size (px)
Citation preview
SAS® Viya®: Migration
2020.1.1 - 2020.1.3This document might apply to additional versions of the software. Open this document in SAS Help Center and click on the version in the banner to see all available versions.
Migration from SAS Viya: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2What Is Migration? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2What Migration Scenarios Are Supported? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3What Migration Scenarios Are Not Supported? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Migration from SAS Viya 3.X: Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4How Does Migration Work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Participating Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Migration Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Step 1: Plan (SAS Administrator) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Step 2: Back Up (SAS Administrator) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Step 3: Restore (Cluster Administrator) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Step 4: Restore User Modifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Step 5: Validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Migration from SAS Viya 4: Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25How Does Migration from SAS Viya 4 to SAS Viya 4 Work? . . . . . . . . . . . . . . . . . . . . . . . . . 25Migration Documentation Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Step 1: Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Step 2: Obtain BackUp (Cluster Administrator) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Step 3: Restore (Cluster Administrator) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Step 4: Validate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Migration from SAS Viya: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Scan and Publish . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Provision the SAS Viya 4 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40PATHLISTFILE Parameter File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Tokens in cas-migration.yaml File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Patch File Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Remove Temporary CAS Permstores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Migration Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46User-modified Files from SAS Viya 3.X . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Additional Migration Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Backups from the SAS Inventory Report CSV Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Override the Default Source Time Zone Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Examples of Transferring Data from Persistent Volumes (PVs) . . . . . . . . . . . . . . . . . . . . . . 54
Migration from SAS Viya: Troubleshooting from SAS Viya 3.X . . . . . . . . . . . . . . . . . . . . . . 56Before Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56After Restore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Migration from SAS Viya: Overview
What Is Migration?Migration to SAS Viya 4 is the movement of content and data from a specific version of a SAS Viya on-premises deployment or from a SAS Viya deployment in a hosting facility to a SAS Viya 4 cloud-based environment. Migration is a four-step process. Although each step is independent, a successful migration requires that you perform each step in order and completely. An Ansible playbook enables you to properly plan and back up your content to migrate, and then you can carefully select what is ultimately migrated.
Here are the four steps:
PlanAs a SAS administrator, scan your source system by running the Plan and Backup Ansible playbook that you generate. From the resulting inventory reports, review the data and content that is to be backed up. Provide information to your Kubernetes administrator who is installing SAS Viya 4 to ensure that SAS Viya 4 resources are sufficiently provisioned to accommodate the migration.
BackupAs a SAS administrator, use the Plan and Backup Ansible playbook to create a backup package. The backup package contains a copy of your source content and data for use during the restore step.
RestoreWith Kubernetes administrative permissions on your cluster, apply a Kubernetes manifest to copy the content and data from your backup package to your target SAS Viya 4 environment. This process overwrites existing data and content. After the restore, the original manifest is used to start your target SAS Viya 4 environment.
ValidateAs a SAS administrator, compare the content and data on your source system to ensure that migration was successful. In SAS Environment Manager, you can review reports that are generated from the restore process.
2
What Migration Scenarios Are Supported?Migration to SAS Viya 4 includes moving content and data from a single-tenant SAS Viya 3.4, a single-tenant SAS Viya 3.5, or from an existing SAS Viya 4 deployment. This document covers the following target SAS Viya 4 scenarios:
n moving to a private cloud
n moving to a public cloud
What Migration Scenarios Are Not Supported?You cannot migrate from the following SAS Viya environments:
n SAS Viya 3.3 or earlier
n a multi-tenant environment
n a Windows environment
n a PowerLinux (PLX) environment
n a SAS Viya 3.X or SAS Viya 4 smp environment to a SAS Viya 4 mpp environment
n a SAS Viya 3.X or SAS Viya 4 mpp environment to a SAS Viya 4 smp environment
In addition, you cannot migrate from a SAS 9.x environment using the same tools, processes, and steps that are used to migrate from SAS Viya. However, promotion of SAS 9.x content is supported. For more information, see “Promotion from SAS 9.4: Tasks” in SAS Viya: Promotion (Import and Export).
For additional information, see “Additional Migration Details” on page 51.
3
Migration from SAS Viya 3.X: Tasks
How Does Migration Work?
Using Ansible to Migrate to SAS Viya 4
The BasicsYou must use Ansible to migrate to SAS Viya 4. Using Ansible automates the commands that migrate your content, and enables you to control what content is migrated. SAS provides a playbook that facilitates migration.
For a list of supported Ansible versions, see SAS Viya Install Center.
n Ansible is configuration management software that provides a straightforward approach to migrating to SAS Viya 4. To migrate using Ansible, you customize files for your environment, and then you run commands to migrate according to the values in those files. The set of files, known collectively as the Plan and Backup Ansible playbook, provides the instructions about what content is migrated on which machines.
The migration process includes a planning step that runs scans and publishes a report, and a backup step that backs up the SAS Viya 3.X environment. Each of these steps involves the execution of an Ansible command that invokes a specific “play”, specifically a “scan play” and a “backup play”. In this guide, “run the playbook with the scan play” means to execute the planning step of migration, and “run the playbook with the backup play” means to execute the backup step of migration.
n You will use the inventory plug-in of the SAS Viya command-line interface (CLI) to generate the Plan and Backup Ansible playbook.
SAS Viya 3.X Deployment File Used by MigrationThe inventory.ini file that is created during the deployment of SAS Viya 3.X is used to migrate to SAS Viya 4 using Ansible. The migration process uses the inventory.ini file to determine on which machines (or hosts) the SAS Viya components that are migrating reside on.
See Edit the Inventory File in the SAS Viya 3.5 for Linux: Deployment Guide to verify that the inventory.ini file is up to date.
Participating ResourcesMigration is supported for the following resources in SAS Viya 3.4 and SAS Viya 3.5:
n SAS Infrastructure Data Server (your PostgreSQL server database content)
4
n SAS Configuration Server (Consul) content
n any RabbitMQ persistent storage
n key CAS library content consisting of the following caslibs:
o Formats
o ModelPerformanceData
o Models
o ModelStore
o VAModels
TIP SAS recommends that you do not migrate these caslibs:
n AppData
n ProductData
n ReferenceData
n SystemData
n key file system content
o transient analytics caslibs
o ASTOREs that are written by SAS Model Manager and TKMAS
o Python scoring results (“pickle” files) that are written by SAS Model Manager
o User modified files (USERMODS)
Note: The migration of user modified files might require some manual intervention.
Migration is not supported for the following resources in SAS Viya 3.4 and SAS Viya 3.5:
n CAS content from DBMS caslibs
n SAS Infrastructure Data Server (PostgreSQL) properties stored in the SAS Configuration Server (Consul)
n logging configuration XML files that determine how log events are processed
n Transport Layer Security (TLS) settings are handled differently in SAS Viya 4
Note: We do not recommend migrating content from NFS caslibs except for key NFS caslibs used for HA support.
Migration RequirementsThe user account that is used to generate and run playbooks must meet the following requirements:
n Must have super user (sudo) or root access.
To verify that your user ID is included in the sudoers file, run the following command:
5
sudo -v
As an alternative, to verify your sudoers privileges, run this command:
sudo -l
Make sure that commands that can be run as “sudo” are unrestricted on the Ansible controller.
This user account must be able to access the following accounts as “sudo”: root, sas, and cas.
n Must have the appropriate permissions to create subdirectories in the directory where you saved the playbook. The recommended path is /sas/install/sas_viya_playbook.
n Must be the same user account that is used to download the SAS Viya command-line interface (CLI) and install the plug-ins.
Step 1: Plan (SAS Administrator)
About These Tasksn In SAS Viya 4, denylist and allowlist refer to what was formerly known in SAS Viya 3.X as blacklist
and whitelist.
n Migrated SAS Viya 3.X denylist paths have been changed to an unrestricted allowlist in SAS Viya 4.
Note: Allowlist paths control the paths in which non-administrative users can create caslibs.
n These tasks assume that you are familiar with the specific product or offering information in “Additional Migration Details” on page 51.
n During deployment, you created a deployment directory that SAS recommended that you name deploy or an alternative name that is meaningful to you. This directory is referred to as $deploy in this guide. Replace $deploy with the directory name that you chose.
n This document refers to the backup package that is produced during the backup step as the SAS Viya 3.X migration package.
n The inventory.ini file that was used to deploy SAS Viya. 3.X must exist in the sas_viya_playbook directory. The deployment must be defined in the inventory.ini file in order for migration to work.
n The process for configuring PostgreSQL and TLS has changed for SAS Viya 4. As a result, some of the associated configuration properties are filtered out during the migration process, and are not restored to SAS Viya 4.
For information about configuring these properties in SAS Viya 4:
TLS TLS configuration is not migrated to SAS Viya 4. In SAS Viya 4, TLS is configured during deployment. For information about how to manually configure TLS, see “How To” in Encryption in SAS Viya: Data in Motion.
6
PostgreSQL For information about how to configure PostgreSQL, see one of the following files:
n Markdown file at $deploy/sas-bases/examples/configure-postgres/internal/custom-config/README.md
n HTML file at $deploy/sas-bases/docs/configuration_settings_for_postgresql_database_cluster.htm
Backup and restore See SAS Viya: Backup and Restore for information about how to configure backup and restore.
Plan for MigrationPerform the following steps to examine the SAS Viya 3.X source environment to determine readiness to move and provision the SAS Viya 4 Kubernetes environment accordingly.
1 From the SAS Viya 3.X source environment, generate the Plan and Backup Ansible playbook1
with the inventory plug-in to the sas-admin CLI.
a Download the sas-admin CLI as the same user that will run the Plan and Backup Ansible playbook and install the inventory, cas, and backup plug-ins. If you are migrating from a SAS Viya 3.4 environment, the inventory plug-in is a new plug-in that is required for migration. See Download the CLI Executable in the SAS Viya 3.5: Administration Guide for download instructions.
Here are additional details:
n You must download the most recent version of the inventory, cas, and backup plug-ins in order to migrate to SAS Viya 4. You cannot migrate with an older version.
Plug-In Minimum Required Version
inventory 1.8.0 or higher
cas 1.12.10
backup 1.6.3 or higher
n You cannot generate or run the Plan and Backup Ansible playbook on Windows.
b Run the GENERATE-PLAYBOOK command of the inventory plug-in to the sas-admin CLI to create the Plan and Backup Ansible playbook.
sas-admin inventory generate-playbook --output-location path_location
1The Plan and Backup Ansible playbook leverages the same scan and backup capabilities as in SAS Viya 3.5 with some additional tools. See “Workflow” on page 33 for more information.
The following files are created when you generate the Plan and Backup Ansible playbook.
7
File Description
viya_plan_backup_vars.yml The YML file that the user edits.
viya-plan-backup.yml The Plan and Backup Ansible playbook.
viya-plan-backup-profilelogin.sh The login script for the sas-admin CLI that is run by the playbook.
viya-plan-backup-profilelogout.sh The log out script for the sas-admin CLI that is run by the playbook.
credentials.txt The sample credentials file.
get-timezone.jar The JAR file that calculates the time zone.
getTimeZone.sh The script that executes the get-timezone.jar.
2 From the OUTPUT-LOCATION specified with the GENERATE-PLAYBOOK command of the inventory plug-in to the sas-admin CLI, generate a credentials.txt file as follows:
a Copy the sample credentials.txt file to your home directory.
cp credentials.txt $HOME/.sas/
b The file must contain a clear-text password and must have Read and Write permissions only for the owner. Use chmod to change the permissions:
chmod 600 ~/.sas/credentials.txt
c Replace user and password in the file with the credentials for a member in the SAS administrators group.
d Save the file.
3 Edit the following parameters of the viya_plan_backup_vars.yml file:
Parameter Description
endpointServer The endpoint URL of the SAS Viya 3.X server. Use the following format:communications-protocol://web-server-host-name:web-server-port.
customerID The customer name for the deployment that is being inventoried.
Note: Any spaces in the value of this parameter are replaced with underscores.
deploymentLabel The identifier for the deployment that is being inventoried.
Note: Any spaces in the value of this parameter are replaced with underscores.
8
Parameter Description
inventoryResultsLocation The path location for subdirectories that contain all of the files that result from running the Plan and Backup Ansible playbook.1
pathListFile The file with its path location that contains additional paths to scan. If no file is specified, then only the file systems used by SAS Viya are scanned.2
reportCASServer The CAS server name where the published inventory CSV files need to be loaded for use in the SAS Viya Inventory report in SAS Environment Manager
inventoryReportVersion The version of report packages to include. The valid values are 3.4 and 3.5.
SAS_BACKUP_ID The ID of the SAS Viya 3.X migration package. The ID must be unique for each run of the Plan and Backup Ansible playbook. The playbook stops running if a migration package with the specified ID already exists.
Note: Any spaces in the value of this parameter are replaced with underscores.
migrationPackageLocation The storage location for the SAS Viya 3.X migration package.
sharedVaultLocation The network location that preserves the backups from all tiers. This value should match the sharedVault property in the Backup service configuration.
WaitForBackupCount The number of 60-second intervals to wait for backup status while waiting for the backup to complete. The default is 720, which is 12 hours.
1The following subdirectories are automatically created within the directory location specified in the INVENTORYRESULTSLOCATION parameter:
Name Description
/INVENTORYRESULTSLOCATION/allScanResults The path location for all of the files that result from the scans.
/INVENTORYRESULTSLOCATION/publishedCSVFiles The path location for the CSV files produced for the SAS Viya Inventory Report.
9
Name Description
/INVENTORYRESULTSLOCATION/contentSelection The path location for the files that determine what content to back up for each host machine. This location must be accessible during the backup step.
Note: This location is automatically populated with a /short-host-name / directory for each host machine. Each directory contains the backup files for that specific host machine.
2The file specified in the PATHLISTFILE parameter of the viya_plan_backup_vars.yml file contains a list of additional paths to scan. Create the file as follows:
n Place each path on a separate line.
n Place paths from all hosts in this file, since each host is scanned for the additional paths.
n Consider organizing the list by placing the host name in a comment prior to the paths that exist on each host.
See example of PATHLISTFILE parameter file on page 42.
Here is a sample viya_plan_backup_vars.yml file:
---# viya-plan-backup.yml required variables## http://<serverFQDN> or https://<serverFQDN>:<port> # http://host.example.com # https://host.example.com:443endpointServer: https://endpoint_host.example.com# Customer label to be used in the data.# Could be GelCorp, ACME...customerId: customerName# An identifying label for a single deployment. This label is used in # file names as a way of creating unique and identifying files. This # label is also stored in the data for use in reporting to distinguish# each SAS deployment data. Could be Production, Test, Development...deploymentLabel: Deployment1# A directory to store the various inventory results. Sub-directories # will be created in this location to organize:# allScansResults - a centralized set of scan results,# publishedCSVFiles - published CSV files to be imported into CAS# contentSelection - editable content selection used to direct backupinventoryResultsLocation: /opt/sas/viya/inventory# Specify the file including the path that contains additional# paths to scan. If no file is specified, only the file systems used by# SAS Viya are scanned.pathListFile: # One CAS controller hostname, which is specified in the inventory.ini # file, where the resulting inventory CSV files should be published # to the System Data CAS LibraryreportCASServer: cas-shared-default# The version of report packages to include in the publish. The valid# values are 3.4 and 3.5.inventoryReportVersion: 3.5# A mounted directory location to store the migration package. It should
10
# be accessible from the consul host and will be accessible as a# persisted volume for the Viya 4.0.1 environment.migrationPackageLocation: /opt/sas/viya/migration# A unique directory location to store the migration package within# the <migrationPackageLocation>. This path should be provided during # the restoration process.SAS_BACKUP_ID: timeStamp-viya35-deployment1# Any network location for storing the backups from all tiers. This# value should match the sharedVault property in the Backup service# configuration.sharedVaultLocation: /opt/sas/viya/sharedVault# The number of retries for backup status before giving up. The count of # 60 second intervals to wait for the backup to complete. # Default: 720, or 12 hours.WaitForBackupCount: 720
4 Consider placing the paths for any PATH or DNFS-based caslibs in the file specified in the PATHLISTFILE parameter of the viya-plan-backup-vars.yml file. This scan can provide information in the inventory report about any additional valid migration content that might be located in this location. See “PATHLISTFILE Parameter File” on page 41 for more information.
5 Save the edited viya_plan_backup_vars.yml file in the sas_viya_playbook directory.
6 Save the deployment log on page 46 in a known location to preserve this information.
7 Copy the Plan and Backup Ansible playbook (the viya-plan-backup.yml file), the viya-plan-backup-profilelogin.sh file, the viya-plan-backup-profilelogout.sh file, the get-timezone.jar file, and the getTimeZone.sh file into the sas_viya_playbook directory.
8 Ensure that you are at the top level of the sas_viya_playbook directory before running the Plan and Backup Ansible playbook.
Running the playbook with the scan play does the following actions:
n creates a sas-admin CLI profile named userid-SAS_BACKUP_ID. See Create at Least One Profile in the SAS Viya 3.5: Administration Guide for more information.
Note: The profile name consists of information from the credentials.txt and viya_plan_backup_vars.yml files.
n scans your deployment, and puts the resulting files in the /INVENTORYRESULTSLOCATION/allScanResults location.
n generates the data (CSV files) for the SAS Viya Inventory report in SAS Environment Manager, and puts them in the /INVENTORYRESULTSLOCATION/publishedCSVFiles location.
n creates a set of YAML files that describe the CAS library and file system content to be backed up, and puts them in the /INVENTORYRESULTSLOCATION/contentSelection location.
Note: The YAML files are created only when you run the playbook with the scan play.
Run the playbook with the scan play, by using the --tags option and specifying ‘inventoryScan’.
Here is the command:
ansible-playbook viya-plan-backup.yml --tags 'inventoryScan'
11
9 The scan play of the Plan and Backup Ansible playbook produces files that enable you to populate and use the SAS Viya Inventory report from SAS Environment Manager. These files are located in the /INVENTORYRESULTSLOCATION/publishedCSVFiles from the viya_plan_backup_vars.yml file.
The following CSV files that are produced are imported into the SystemData library of the server specified in the REPORTCASSERVER parameter in the viya_plan_backup_vars.yml file.
SASViyaInventory.csv
SASViyaInventory_NFSPaths.csv
SASViyaInventory_CASSrvDetails.csv
SASViyaTypes.csv
The scan also creates two SAS Visual Analytics reports in JSON format. Prior to using the SAS Viya Inventory report in SAS Environment Manager, you must import the JSON files that are produced into SAS Environment Manager to create the updated SAS Viya Inventory 3.X report. If you do not import the updated report, you will not get the correct information in the report (if migrating from SAS Viya 3.5) or you will have no report at all (if migrating from SAS Viya 3.4).
Here are the JSON files that you must import:
SASEV_SASViyaInventory_V3.json
SASEV_SASViyaInventoryComparison_V3.json
Note: If the JSON file name includes V3, then a SAS Viya 3.5 report is created. If the JSON file name includes V2, then a SAS Viya 3.4 report is created.
For information about importing the JSON files, see the following:
Report Documentation link
SAS Viya 3.4 report Start at Step 2
SAS Viya 3.5 report Start at Step 2
10 Review the SAS Viya Inventory report in SAS Environment Manager to identify items that you want to back up. The report is available only to SAS administrators. See “Open a Report” in SAS Visual Analytics: Designing Reports for more information about working with predefined reports from SAS Visual Analytics.
Note: For more information about the SAS Inventory report, see “SAS Viya Inventory Report” on page 37.
11 The scan results are copied to the /INVENTORYRESULTSLOCATION/allScanResults location specified in the viya_plan_backup_vars.yml file. A set of YAML files that describe the content to back up are copied to the /INVENTORYRESULTSLOCATION/contentSelection location from the
12
viya_plan_backup_vars.yml file. These directories are either on the Ansible controller or on a network location that is accessible by the Ansible controller
n From the /INVENTORYRESULTSLOCATION/allScanResults directory, review any output files that contain content that is associated with items that you want to back up. See this step on page 12 for more information about using the SAS Viya Inventory report to identify these items. See “Scan Output Files” on page 34 for more information about the output files.
n You can select which content to back up using one of the following methods:
o From the /INVENTORYRESULTSLOCATION/contentSelection directory, review the YAML files that were created. Evaluate the content that has been selected for backup. If you want to add or remove any locations to be backed up, edit these YAML files.
YML File Parameter and Value Description
gatherFiles: true Back up files at this path.
gatherFiles: false Do not back up files at this path.
gatherTables: true Back up tables in this caslib.
gatherTables: false Do not back up tables in this caslib.
o You can use the SAS Viya Inventory report to visually explore the content that is selected for backup during the scan, and export your selections to CSV files that will be used to direct the backup process.
1 From the CAS Backup Planning and Filesystem Backup Planning tabs from the SAS Viya Inventory report, filter the CAS tables and file system paths so that only the items that you want to back up are displayed. See “Backups from the SAS Inventory Report CSV Files” on page 52 for more information about the filtering and back up process.
2 Export the filtered tables from the CAS Backup Planning and Filesystem Backup Planning tabs as CSV files. Prefix the name of the CAS table with “CAS”, and the name of the File System table with “Filesystem” so that the Plan and Ansible Playbook recognizes that they are intended to direct the backup process.
For more information, see “Export Data from Objects” in SAS Visual Analytics: Working with Report Data. Be sure to export the tables as CSV files.
3 Save the CSV files in the /INVENTORYRESULTSLOCATION/contentSelection location specified in the viya_plan_backup_vars.yml file.
Note: If you use the CSV method, then any conflicting changes made to the YAML files are overridden.
n Make note of each location’s backup size, or the sum of all backup location sizes depending on the planned architecture of your Kubernetes deployment.
12 To help make decisions about provisioning the SAS Viya 4 Kubernetes environment:
a Use the SAS Viya Inventory report from SAS Environment Manager to learn about your system.
See “Provision the SAS Viya 4 Environment” on page 40 for more information.
13
b Edit the YAML files in the /INVENTORYRESULTSLOCATION/contentSelection location from the viya_plan_backup_vars.yml file or export tables from the filtered reports to control what is backed up.
See this step on page 12 for more information about how to control what is backed up.
Communicate your findings about sizing requirements to the person who is provisioning the SAS Viya 4 Kubernetes environment.
13 Suspend scheduled jobs in the SAS Viya 3.X source environment to prevent them from automatically starting after migration.
a Navigate to the Jobs page from SAS Environment Manager in the SAS Viya 3.X source environment. See Jobs and Flows: Overview in the SAS Viya 3.5: Administration Guide for more information.
b See step 1 under “Schedule a Job” in the SAS Viya 3.5: Administration Guide to determine what jobs are scheduled.
c See Disable the Schedule for a Job in the SAS Viya 3.5: Administration Guide to disable the triggers for each scheduled job.
Note: The sas-admin CLI in SAS Viya 3.X is now known as the sas-viya CLI in SAS Viya 4.
Step 2: Back Up (SAS Administrator)
About These TasksHere are key points about these tasks:
n The deployment being backed up must be running.
n The backup process generates a backup package. This document refers to the backup package as the SAS Viya 3.X migration package.
n Part of the backup package has to be accessible by the account that is chosen to run CAS. You might need to adjust the permissions on these directories in the SAS Viya 3.X migration package prior to performing a restore:
cas-server-name/permstore
data
n Any content that is created or updated after the SAS Viya 3.X migration package has been generated will not be available in SAS Viya 4.
n Make sure that you specified a value for the MIGRATIONPACKAGELOCATION parameter in the viya_plan_backup_vars.yml file.
n If you would like to add customer-modified content, be sure to run the Plan and Backup Ansible playbook with the scan play before attempting a backup. This creates YAML files that can be edited to modify the content that is intended for backup. These files are located in the /
14
INVENTORYRESULTSLOCATION/contentSelection location specified in the viya_plan_backup_vars.yml file. Without any customizations, running the Plan and Backup Ansible playbook with the backup play performs a backup using only the content that SAS recommends (no customer modified content).
IMPORTANT In the SAS Viya source environment, do the following:
n specify a value for the sharedVault property in SAS Environment Manager
n determine whether to set setfacl permissions on the CAS controllers
n perform other preliminary tasks for running a backup with the Backup service. See Backup and Restore: Initial Tasks for more information.
Back Up Your DeploymentFor a list of content that is backed up, see “Participating Resources” on page 4, taking into account any edits made to the YAML files or CSV files that were created when you ran the scan play of the Plan and Backup Ansible playbook.
Note: There might be a conflict between the edits made in the YML files and the CSV files that you created from the SAS Viya Inventory report. If so, and the CSV files from the SAS Viya Inventory Report exist in the directory that you specified in the /INVENTORYRESULTSLOCATION/contentselection location specified in the viya_plan_backup_vars.yml file, then the filtered results from the CSV files take precedence over the edits in the YML files.
1 Navigate to the top level of the sas_viya_playbook directory before running the Plan and Backup Ansible playbook1.
Running the backup play of the Plan and Backup Ansible playbook does the following actions:
n Initiates another scan of the environment. If some time has passed since you ran the scan play during the Plan step, this ensures that any changes in the environment made during the ensuing time are also reflected in the scan.
n Creates the SAS Viya 3.X migration package.1The Plan and Backup Ansible playbook leverages the same scan and backup capabilities as in SAS Viya 3.5 with some additional tools.
2 Run the Plan and Backup Ansible playbook with this command:
ansible-playbook viya-plan-backup.yml
The SAS Viya 3.X migration package is created as a directory with the following name:/migrationPackageLocation/SAS_BACKUP_ID/_default_.
3 Place the SAS Viya 3.X migration package in a location that will be accessible by the SAS Viya 4 Kubernetes environment. Share this location with the Kubernetes administrator.
Before attempting the restore process, make sure that the backup files inside the package are readable by the restore processes (for example, CAS, Postgres, and Consul restores). The permissions of the backup files must grant Read permission to the UID of the user that owns the restore process. For example, the CAS restore runs as the sas user, so the permissions of the backup files must grant Read permission to the UID of the sas user.
15
Step 3: Restore (Cluster Administrator)
About These TasksHere are key points about these tasks:
n To perform these tasks, you must have elevated Kubernetes permissions.
n The Kubernetes environment must be running.
n The SAS Viya 3.X migration backup package must be in a location that is accessible by the SAS Viya 4 Kubernetes environment and the Kubernetes administrator must know this location.
n The SAS Viya 3.X migration backup package contains customer data. It is your responsibility to adjust the permissions on the content of the migration backup package so that it can be accessed by SAS Viya 4 during the restore. Permissions for the migration backup package directories that contain customer data are restricted to the user account that created the backup.
Specifically, if the user account in SAS Viya 3.X that created the migration backup package is different from the user account in SAS Viya 4 that performs the restore, you might need to adjust the permissions on the following directories in the migration backup package:
cas-server-name/permstore
data
Note: These directories must be accessible by the account that is chosen to run CAS.
IMPORTANT For further security, we recommend that you store your migration backup package in an encrypted file system provided by your organization.
n Set an environment variable for each pod that needs restoration to indicate that a restore is needed. Use the same environment variable for each pod.
n The SAS Viya 3.X backup package persistent volume (PV) must be available to all CAS pods, the PostgreSQL pods, the Consul pods, and the SAS Model Manager pods.
n These tasks are performed on a machine that can be reached by your kubectl machine or on the kubectl machine itself.
n These tasks assume that the cluster administrator has already set up persistent mounts with sufficient storage.
n The user identifiers (UID) and the group identifiers (GID) are the same on the source SAS Viya environment and the target SAS Viya environment.
16
Restore from SAS Viya 3.X to SAS Viya 41 As a pre-validation step, deploy SAS Viya 4 by following the steps in the SAS Viya Operations:
Deployment Guide .
This document applies to the version with the latest patches applied. To apply the latest patches, from my.sas.com select the version for the software order, download the latest deployment assets, and update the environment.
IMPORTANT The following steps migrate your SAS Viya 3.X system to SAS Viya 4. When the content is restored during migration, most of the pre-validated system is overwritten.
n SAS Infrastructure Data Server or your PostgreSQL server database content is overwritten.
n Consul properties are partially overwritten and new values are merged in.
n SAS Configuration service properties are overwritten, with the exception of new definitions and configurations for which there are no incoming values from SAS Viya 3.5 (for example, the new usermods configurations or the configuration for disabling scim/ldap).
n CAS perm stores are not persisted.
n Data and file restores are overwritten, and new items are added.
n SAS Model Manager content is overwritten.
n Analytics projects might be overwritten.
2 Create a CAS custom resource (CR) from each cas-server-name.yml file from the SAS Viya 3.X migration package.
Note: The cas-server-name.yml file is an output file from the CAS scan of the inventory plug-in to the sas-viya CLI.
a Open the SAS Viya 3.X migration package. The package contains the following directories:
Directory Description
cas-server-name
Note: In environments with multiple CAS servers, there is a cas-server-name directory for each CAS server.
Contains a cas-server-name.yml file.
consul Contains SAS Configuration Server content.
data Contains CAS tables.
Postgres Contains SAS Infrastructure Data Server or your PostgreSQL server database content.
RabbitMQ Contains any RabbitMQ persistent storage.
17
b For each CAS server:
i Navigate to the cas-server-name directory in the SAS Viya 3.X migration package with this command:
cd cas-server-name
Note: Replace cas-server-name with the name of your CAS server.
ii Copy the cas-server-name.yml file that is in this directory to a known location on the Kubernetes jump box.
iii Edit the cas-server-name.yml file with any required customizations.
Here are the parameters that you might need to review:
CPUS
TOTALNUMBEROFCORES
MEMTOTAL
iv Save the cas-server-name.yml file if you made any changes.
v If you already created the migration subdirectory within the $deploy/site-config directory in the base directory of your deployment, proceed to the next step.
From the base directory of your deployment, create a migration subdirectory within the $deploy/site-config directory to contain all migration resources. Although SAS cannot prescribe the organization of your $deploy/site-config directory, we recommend that you create this migration subdirectory.
vi Navigate to the $deploy/sas-bases/examples/migration/cas directory. Run the sas-migration-cas-converter script to create a working CAS CR. Specify the cas-server-name.yml file as input with the -f option. Specify the $deploy/site-config/migration directory (that you created in the last step) as the output location with the -o option.
sas-migration-cas-converter.sh -f /path-to-file/cas-server-name.yml -o $deploy/site-config/migration
The script generates a cas-server-name-migration-cr.yaml file, and places it in the $deploy/site-config/migration directory. The YAML file is the CAS CR.
vii Open the cas-server-name-migration-cr.yaml file and confirm that the contents are what you expect for this CAS server.
c Edit the $deploy/site-config/migration/kustomization.yaml file, and do the following:
i Locate the following line: #- {{ CONVERTED-CAS-MIGRATION CR }}.yaml
ii Uncomment the line by removing the number sign (#).
iii Replace {{ CONVERTED-CAS-MIGRATION-CR }} with cas-server-name-migration-cr, which is the name of your CAS CR.
18
iv For each additional CAS CR, add an additional copy of this line replacing CONVERTED-CAS-MIGRATION-CR with cas-server-name-migration-cr. For example, if you are migrating three CAS servers, you might add these three lines to your kustomization.yaml:
- cas-server-name1-migration-cr.yaml- cas-server-name2-migration-cr.yaml- cas-server-name3-migration-cr.yaml
3 Provide the location of the migration package for CAS server restoration. Edit the $deploy/site-config/migration/cas-components/cas-migration.yaml file to attach the volume that contains the migration package to CAS. This file contains an example using NFS. However, any supported volume can be defined here.
See “Tokens in cas-migration.yaml File” on page 42 for information about filling out the token values in the cas-migration.yaml file.
4 Edit the $deploy/kustomization.yaml file:
a Add the following line to the resources section:
- site-config/migration
b Ensure that any lines that contain sas-bases/overlays/cas-server are commented out from the resources section.
5 Perform the restore.
a Navigate to the $deploy folder.1
b Make a copy of the kustomization.yaml file to recover after temporary changes are made:
cp kustomization.yaml kustomization.yaml.save
c Add the sas-restore-job-parameters code below to the configMapGenerator section of kustomization.yaml, and remove the configMapGenerator line, if it is already present in the default kustomization.yaml:
configMapGenerator: - name: sas-restore-job-parameters behavior: merge literals: - SAS_BACKUP_ID={{ SAS-BACKUP-ID-VALUE }} - SAS_DEPLOYMENT_START_MODE=MIGRATION
Here are more details about the previous code.
n In the previous code, the value that you specify for SAS-BACKUP-ID-VALUE should be the same as the SAS_BACKUP_ID value in the viya_plan_backup_vars.yml file. If you placed the migration package in another location, specify that location here.
n To increase the logging levels, add the following line to the literals section:
- SAS_LOG_LEVEL=DEBUG
n To override the value specified in the time zone file, add the following line to the literals section:
- SOURCE_TZ=timezone_value
Here is an example: - SOURCE_TZ=America/New_York
1. During deployment, you created a deployment directory that SAS recommended that you name deploy or an alternative name that is meaningful to you. The directory is referred to as $deploy in this guide. Replace $deploy with the directory name that you choose.
19
IMPORTANT Replace each variable that is enclosed in braces ({ }) and spaces with the value that is appropriate for your deployment. For example, {{ SAS-BACKUP-ID-VALUE }} should be replaced with a backup ID, such as 2020-04-01T10_22_33_633_0700.
If you want to exclude a specific SAS Viya 3.x schema from being migrated or if you changed the name of your internal PostgreSQL instance, see one of the following files:
File Format Path
Markdown $deploy/sas-bases/examples/migration/postgresql/README.md
HTML $deploy/sas-bases/docs/uncommon_migration_customizations.htm
d Generate a temporary manifest to complete the migration. This manifest is applied in a later step.
kustomize build -o site-migration.yaml
e Modify kustomization.yaml again for the initial phase of migration.
Add the following line to the resources section:
- sas-bases/overlays/migration
Add the following line to the transformers section:
- sas-bases/overlays/migration/migration-replicas-zero-transformer.yaml
f Provide the location of the migration package for the migration-job portion of the restoration process. Templates have been provided for azureFile and NFS volumes in $deploy/sas-bases/examples/migration/migration-job-volume_type-volume.yaml, but any supported volume can be defined. Copy the appropriate template to $deploy/site-config/migration/migration-job-volume_type-volume.yaml and fill in the token values.
See “Patch File Tokens” on page 42 for more information about the token values.
Modify kustomization.yaml again. Add the following line to the transformers section of the kustomization.yaml file:
- site-config/migration/migration-job-patchname-volume.yaml
g From the $deploy directory, generate a second temporary manifest for the initial phase of migration, and apply it:
kustomize build -o site-migration-initial.yaml
kubectl apply -f site-migration-initial.yaml
This stops all services except SAS Configuration Server (Consul) and SAS Infrastructure Data Server or PostgreSQL server and starts the migration job.
h The migration job was started in the previous step. Inspect the status of the job:
kubectl get jobs -n name-of-namespace -l "sas.com/backup-job-type=migration" -L "sas.com/sas-backup-id,sas.com/backup-job-type,sas.com/sas-restore-status"
20
Submit the command until you get the Completed status. Possible statuses are Completed, CompletedWithError, and Failed.
n If you get an Error status or need to rerun the job for any reason, delete the job:
kubectl delete job sas-migration-job -n name-of-namespace
And then perform this previous step again:
kubectl apply -f site-migration-initial.yaml
n If a resource is not available to the pod, the migration job might appear to be running with "0/1" completions, whereas it actually is in a waiting state. You might want to describe the migration pod to confirm that the job has been able to start.
Get the name of the migration pod:
kubectl -n name-of-namespace get pods | grep migration
Describe the pod, substituting the migration pod name that you identified in the last step:
kubectl -n name-of-namespace describe pod migration-pod
i Check the log of the migration job to confirm that the migration was successful.
To view the log of the migration job, find its pod name:
kubectl get pods -n name-of-namespace | grep sas-migration-job
To see the log:
kubectl -n name-of-namespace logs sas-migration-job-pod-name -c sas-migration-job
j In the next step, the services are restarted, and the file system migration for services like CAS begins. The file system migration requires a clean volume. Otherwise, the migration for the volume is skipped.
Get the list of persistent volume claims that are used by the file system migration.
kubectl -n name-of-namespace get pvc -l 'sas.com/backup-role=provider'
If you are using dynamic provisioning, clean up the volumes with this command:
kubectl -n name-of-namespace delete pvc -l 'sas.com/backup-role=provider'
If you are using static provisioning, take the necessary steps to manually clean up the volumes.
k Apply the first temporary manifest to complete the migration:
kubectl apply -f site-migration.yaml
l Confirm that the deployment is running. Verify that all pods are running successfully:
kubectl get pods -n name-of-namespace
Make sure that you are able to sign on to the system.
m Recover the saved kustomization.yaml copy to remove any migration modifications:
mv kustomization.yaml.save kustomization.yaml
The deployment is now ready for use.
n Remove the temporary manifests:
rm site-migration-initial.yaml site-migration.yaml
6 In the $deploy directory, generate the permanent manifest.
kustomize build -o site.yaml
21
7 (optional) Clean up on page 45 any existing CAS permstores.
Step 4: Restore User ModificationsIf any user-modified files were created or modified in your SAS Viya 3 source environment, you need to review these files to make sure that they are correct for your SAS Viya 4 environment. These files ( sasv9_usermods.sh for example) are used to set up site-specific settings for your deployment such as library definitions, language or locale options, or QKB locations. The values in these files might be important to your SAS Viya 4 deployment.
See “User-modified Files from SAS Viya 3.X” on page 46 for information about reviewing and modifying the user-modified files.
Step 5: Validate
OverviewHere are some suggested tasks to perform after the migration is complete:
Task Documentation
Create reports to validate your SAS Viya 4 environment. See “Create Validate Reports” on page 22.
Scheduled jobs in the source SAS Viya 3.X environment automatically resume in the target SAS Viya 4 environment after migration. If you suspended these jobs in the source environment by disabling their job triggers in the Planning step here on page 14, you can now resume the scheduled jobs in the target environment.
See “Schedule a Job” in SAS Environment Manager: User’s Guide for more information.
Create Validate ReportsSAS Viya 4 provides the SAS Viya 4 Inventory and SAS Viya Comparison reports that you can use to compare content between the source SAS Viya 3.X and target SAS Viya 4 environments. These reports, and the associated SASVIYATYPES table are accessible through SAS Environment Manager. To use the reports, you must first generate additional required data by performing the following steps:
1 After the restore is complete, create and run the Kubernetes job to perform an inventory scan on the target SAS Viya 4 environment.
a Download the sas-viya CLI and install the compute plug-in. See “Get the CLI and Its Plug-Ins” in SAS Viya: Using the Command-Line Interface for download instructions.
22
b Create a profile and log in as a SAS administrator as follows:
sas-viya --profile profile-name profile init
sas-viya --profile profile-name auth login
See “Command-Line Interface: Preliminary Instructions” in SAS Viya: Using the Command-Line Interface for more information.
Note: If your deployment is TLS enabled, then you will have to set the SSL_CERT_FILE environment variable with the location of the certificate to access the deployment. See “Provide the Path to Your Bundle of Trusted CA Certificates” in SAS Viya: Using the Command-Line Interface for more information about setting the SSL_CERT_FILE environment variable. See “Obtain the Truststore Files or the SAS Viya Generated Root CA Certificate ” in Encryption in SAS Viya: Data in Motion for information about retrieving the certificate truststore files.
c Store the SAS administrator credentials to be used to perform the ETL using the compute plug-in to the sas-viya CLI as follows:
sas-viya --profile profile-name compute credentials create
Respond to the subsequent prompts as follows:
Userid Specify the name of the LDAP user to perform the ETL.
Password Specify the password for the user ( as it is stored in LDAP).
Description Specify a description for the user.
d If it does not exist, create the directory $deploy/site-config/backup.
See “Retrieve Required Files” in SAS Viya: Deployment Guide for more information about the $deploy directory.
e Navigate to the $deploy/sas-bases/examples/backup directory.
f Copy the $deploy/sas-bases/examples/backup directory to the $deploy/site-config/backup directory.
g Make sure that the Execute permission is set on the generate-backup-job script:
chmod +x generate-backup-job.sh
Make sure that Write permission is set on the kustomization.yaml file.
chmod +w kustomization.yaml
h Execute the script generate-backup-job.sh to generate the manifest file for the Kubernetes scan job.
./generate-backup-job.sh scan ldapUser compare
Replace the values for the ldapUser and compare options as follows:
ldapUser Specify the name of the SAS administrator LDAP user specified in step c above.
23
(Optional) compare Indicates whether inventory scans are to be compared. If the scan job is being run after a migration operation, specify the value 3 for a SAS Viya 3.X to SAS Viya 4 inventory comparison, or the value 4 for a SAS Viya 4 to SAS Viya 4 inventory comparison. Press Enter to skip the compare operation.
This script generates a YAML file with the prefix sas-scan-job, followed by a unique identifier in the same folder (for example, sas-scan-job-m2wk59lf.yaml).
i Edit the kustomization.yaml file. Remove any previous entries from the resources section. Then add the name of the YAML file generated in the previous step.
resources:- sas-scan-job-xxx.yaml
j Navigate to the $deploy directory. Edit the kustomization.yaml file and add the following to the resources section:
resources:- site-config/backup
k Build the manifest using the following command:
kustomize build -o site-scan.yaml
l Create the inventory scan job by applying the manifest:
kubectl apply -f site-scan.yaml
Note: If a SAS Viya 4 service is running but is not responsive, the inventory scan job will retry for up to an hour for a response. Depending on how many SAS Viya 4 services are in this non-responsive state, the time could be longer.
The following reports are published in the SAS Viya 4 environment:
SAS Viya 4 Inventory report Contains information about the newly migrated SAS Viya 4 environment.
SAS Viya Comparison report Compares the source SAS Viya 3.X environment and the target SAS Viya 4 environment.
See “SAS Viya Inventory Comparison Report” on page 39 for more information.
2 Validate that the target SAS Viya 4 system works as expected.
a Review the SAS Inventory Comparison report and output files that resulted from the scans. See “Scan Output Files” on page 34 for more information.
Compare the scans from the source SAS Viya environment with the scans from the target SAS Viya 4 environment. Make sure that all expected content is present in the SAS Viya 4 environment.
b Test the new SAS Viya 4 environment for further validation.
24
Migration from SAS Viya 4: Tasks
How Does Migration from SAS Viya 4 to SAS Viya 4 Work?Migration from a SAS Viya 4 environment to another SAS Viya 4 environment supports scenarios where a new SAS Viya 4 environment is created and data and content from a source SAS Viya 4 environment is restored to it. The restore process is similar to the processes used by SAS Viya 4 backup and restore and disaster recovery. Here are some example usage scenarios:
n Moving to a different cloud provider
n Duplicating an environment on a new Kubernetes cluster (such as for disaster recovery)
n Creating environments used in development, test, or production on the same or different clusters and namespaces
n Creating a tenant on a new namespace
What Migration Scenarios Are Not Supported?n Changing between cadences during migration (for example, from Long-Term Support to Stable or
from Stable to Long-Term Support). Changing cadences must be performed separately as an update or upgrade. See “Software Releases and Versions” in Getting Started with SAS Viya Operations for more information.
n If the number of CAS servers is reduced on the target environment, the data from the dropped server is not restored.
Migration Documentation Detailsn In this document, deployment resources refer to the kustomization.yaml file and the site-config
directory.
n During deployment, you create a deployment directory, which SAS recommends that you name deploy or an alternative name that is meaningful to you. This directory is referred to as $deploy in this guide.
n The $deploy directory contains the downloaded deployment assets and the deployment resources that you create.
25
Step 1: Plan
About These TasksThese tasks assume that you are familiar with the following information about the source SAS Viya 4 environment:
n the software order and cadence version
n the cloud infrastructure
n the cluster and namespace
n the configuration (for example, the configuration of Ingress, TLS, and storage)
n the topology (for example, the number of CAS servers and whether they are SMP or MPP)
Plan for Migration1 Make sure that you have access to the source SAS Viya 4 environment and its deployment
resources.
2 Determine what types of changes are necessary between the source and target SAS Viya 4 environments to facilitate the desired outcome.
Step 2: Obtain BackUp (Cluster Administrator)
About These Tasksn To perform these tasks, you must have elevated Kubernetes permissions.
Back Up Your Source Environment1 Obtain a backup of your source SAS Viya 4 environment by using one of these methods:
n Performing a new backup with the SAS backup job. Be sure to perform a scan of the source SAS Viya 4 environment first as specified in the “Best Practices for Performing Backups” in SAS Viya: Backup and Restore. See SAS Viya: Backup and Restore for more information.
n Selecting a pre-existing backup to use.
2 Make sure that the backup of the source SAS Viya 4 environment is in a location that is accessible by the target SAS Viya 4 environment.
26
Note: The SAS backup job creates a backup package containing content, data, and some configuration (Consul), but does not contain the Kubernetes manifest or templates. See “Backup and Restore: Overview” in SAS Viya: Backup and Restore for more information.
Obtain the Deployment Resources from the Source Environment1 Obtain a copy of the deployment resources (kustomization.yaml file and site-config directory) from
the source SAS Viya 4 environment. Alternatively, you can obtain a copy of the entire $deploy directory.
2 Make sure that the deployment resources from the source SAS Viya 4 environment are in a location that is accessible by the target SAS Viya 4 environment.
Step 3: Restore (Cluster Administrator)
About These Tasksn To perform these tasks, you must have elevated Kubernetes permissions.
n Here is a summary of the restore steps:
o Deploy SAS Viya 4 on the target environment.
Use the deployment resources from the source SAS Viya 4 environment to build a new manifest and apply it to the target SAS Viya 4 environment. If changes are required between the source and target SAS Viya 4 environments, you must modify the deployment resources accordingly.
o Restore the backup of the source SAS Viya 4 environment to the target SAS Viya 4 environment.
Restore to a New Environment1 Obtain the deployment resources for the target SAS Viya 4 environment.
n SAS recommends that you use the same software order as from the SAS Viya 4 source environment.
n The version should be the same or newer for the same cadence. To obtain the same deployment assets as deployed on the source, you can download them again by selecting Download History from the order in the my.sas.com portal.
2 Follow the steps in the SAS Viya: Deployment Guide to deploy SAS Viya 4, using a customized manifest to deploy to the Kubernetes cluster:
27
Note: Be sure to select the same version of the SAS Viya: Deployment Guide as the version of the deployment assets that you download.
a While performing the steps under “Retrieve Required Files” in SAS Viya: Deployment Guide, note the following:
Note: It is assumed that the target environment and the source environment are on the same release cadence of SAS Viya 4.
n If you are migrating to a newer version on the target environment than the version used in the source environment, then download the deployment assets for the new order from the my.sas.com portal to the target environment.
n If you are migrating to the same version on the target environment as the version used in the source environment, then you can use the same deployment assets on the target environment as those used in the source environment. You can download them by selecting Download History from the order in the my.sas.com portal.
b While performing the steps under “Installation” in SAS Viya: Deployment Guide, be sure to do the following:
i Use the deployment resources from the source SAS Viya 4 environment that you obtained in step 1 under "Obtain the Deployment Resources from the Source Environment" on page 27 as the initial kustomization.yaml and site-config directory.
Note: If the source SAS Viya 4 environment was created by a migration or has undergone a backup or restore, make sure that the kustomization.yaml file does not contain any references to migration or backup jobs from the source environment
ii If deploying to a new version, check SAS Viya: Deployment Notes for deployment information for each version between the current version and the version that you are updating to.
iii Review “Common Customizations” in SAS Viya: Deployment Guide or README files to determine customizations for the target SAS Viya 4 environment based on the desired result.
3 Make the backup data available on the target SAS Viya 4 environment.
Note: Multiple persistent volumes (PVs) are used for backup data.
a Run this command to list the PVs where backup data is stored.
kubectl -n name-of-namespace get pvc -l "sas.com/backup-role=storage"
b Copy the backup data from the source SAS Viya 4 environment to the target SAS Viya 4 environment. See “Examples of Transferring Data from Persistent Volumes (PVs)” on page 54 for an example.
c Review the backup data to be restored in the backup PVs.
4 From this point, you perform the same steps as if you are doing a normal restore:
a Navigate to the $deploy folder.1
28
See “Retrieve Required Files” in SAS Viya: Deployment Guide for more information about the $deploy directory.
b Make a copy of the kustomization.yaml file to recover after temporary changes are made:
cp kustomization.yaml kustomization.yaml.save
c Add the sas-restore-job-parameters code below to the configMapGenerator section of kustomization.yaml, and remove the configMapGenerator line, if it is already present in the default kustomization.yaml:
configMapGenerator: - name: sas-restore-job-parameters behavior: merge literals: - SAS_BACKUP_ID={{ SAS-BACKUP-ID-VALUE }} - SAS_DEPLOYMENT_START_MODE=RESTORE
Here are more details about the previous code.
n Replace the value for SAS-BACKUP-ID-VALUE with the ID of the backup that is selected for restore. See “List All Backups” in SAS Viya: Backup and Restore for information about how to locate the backup ID.
n To increase the logging levels, add the following line to the literals section:
- SAS_LOG_LEVEL=DEBUG
IMPORTANT Replace each variable that is enclosed in braces ({ }) and spaces with the value that is appropriate for your deployment. For example, {{ SAS-BACKUP-ID-VALUE }} should be replaced with a backup ID, such as 2020-04-01T10_22_33_633_0700.
d Generate a temporary manifest to complete the restore. This manifest is applied in a later step.
kustomize build -o site-restore.yaml
e Modify kustomization.yaml again for the initial phase of restore.
Add the following line to the resources section:
- sas-bases/overlays/restore
Add the following line to the transformers section:
- sas-bases/overlays/restore/restore-replicas-zero-transformer.yaml
f From the $deploy directory, generate a second temporary manifest for the initial phase of restore, and apply it:
kustomize build -o site-restore-initial.yaml
kubectl apply -f site-restore-initial.yaml
This stops all services except SAS Configuration Server (Consul) and SAS Infrastructure Data Server or PostgreSQL server and starts the restore job.
g The restore job was started in the previous step. Inspect the status of the job:
kubectl get jobs -n name-of-namespace -l "sas.com/backup-job-type=restore" -L "sas.com/sas-backup-id,
1. During deployment, you created a deployment directory that SAS recommended that you name deploy or an alternative name that is meaningful to you. The directory is referred to as $deploy in this guide. Replace $deploy with the directory name that you choose.
29
sas.com/backup-job-type,sas.com/sas-restore-status"
Submit the command until you get the Completed status. Possible statuses are Completed, CompletedWithError, and Failed.
n If you get an Error status or need to rerun the job for any reason, delete the job:
kubectl delete job sas-restore-job -n name-of-namespace
And then perform this previous step again:
kubectl apply -f site-restore-initial.yaml
n If a resource is not available to the pod, the restore job might appear to be running with "0/1" completions, whereas it actually is in a waiting state. You might want to describe the restore pod to confirm that the job has been able to start.
Get the name of the restore pod:
kubectl -n name-of-namespace get pods | grep restore-job-XXXX
Describe the pod, substituting the restore pod name that you identified in the last step:
kubectl -n name-of-namespace describe pod restore-pod
h Check the log of the restore job to confirm that the restore was successful.
To view the log of the restore job, find its pod name:
kubectl get pods -n name-of-namespace | grep sas-restore-job
To see the log:
kubectl -n name-of-namespace logs sas-restore-job-pod-name -c sas-restore-job
i In the next step, the services are restarted, and the file system restore for services like CAS begins. The file system restore requires a clean volume. Otherwise, the restore for the volume is skipped.
Get the list of persistent volume claims that are used by the file system restore .
kubectl -n name-of-namespace get pvc -l 'sas.com/backup-role=provider'
If you are using dynamic provisioning, clean up the volumes with this command:
kubectl -n name-of-namespace delete pvc -l 'sas.com/backup-role=provider'
If you are using static provisioning, take the necessary steps to manually clean up the volumes.
j Apply the first temporary manifest to complete the restore:
kubectl apply -f site-restore.yaml
k Confirm that the deployment is running. Verify that all pods are running successfully:
kubectl get pods -n name-of-namespace
Make sure that you are able to sign on to the system.
l Check the CAS pod logs for these messages to confirm that the restore was successful:
n INFO: Restore for cas data completed successfully.
n INFO: Restore for cas permstore completed successfully.
If both of these messages are present in the log, then the CAS restore was successful. If neither or only one of these messages are present in the log, then the CAS restore was not successful. Check the CAS pod logs for details.
Here is the command to check the CAS pod logs:
30
kubectl -n name-of-namespace logs sas-cas-server-default-controller -c cas
m Recover the saved kustomization.yaml copy to remove any restore modifications:
mv kustomization.yaml.save kustomization.yaml
The deployment is now ready for use.
n Remove the temporary manifests:
rm site-restore-initial.yaml site-restore.yaml
5 Make sure that the site.yaml file is stored in your version control system or backed up to ensure that it is available for updates.
Step 4: ValidateSAS Viya 4 provides the SAS Viya 4 Inventory and SAS Viya Comparison reports that you can use to compare content between the source SAS Viya 3.X and target SAS Viya 4 environments. These reports, and the associated SASVIYATYPES table are accessible through SAS Environment Manager. To use the reports, you must first generate additional required data by performing the following steps:
1 After the restore is complete, create and run the Kubernetes job to perform an inventory scan on the target SAS Viya 4 environment.
a Download the sas-viya CLI and install the compute plug-in. See “Get the CLI and Its Plug-Ins” in SAS Viya: Using the Command-Line Interface for download instructions.
b Create a profile and log in as a SAS administrator as follows:
sas-viya --profile profile-name profile init
sas-viya --profile profile-name auth login
See “Command-Line Interface: Preliminary Instructions” in SAS Viya: Using the Command-Line Interface for more information.
Note: If your deployment is TLS enabled, then you will have to set the SSL_CERT_FILE environment variable with the location of the certificate to access the deployment. See “Provide the Path to Your Bundle of Trusted CA Certificates” in SAS Viya: Using the Command-Line Interface for more information about setting the SSL_CERT_FILE environment variable. See “Obtain the Truststore Files or the SAS Viya Generated Root CA Certificate ” in Encryption in SAS Viya: Data in Motion for information about retrieving the certificate truststore files.
c Store the SAS administrator credentials to be used to perform the ETL using the compute plug-in to the sas-viya CLI as follows:
sas-viya --profile profile-name compute credentials create
Respond to the subsequent prompts as follows:
Userid Specify the name of the LDAP user to perform the ETL.
31
Password Specify the password for the user ( as it is stored in LDAP).
Description Specify a description for the user.
d If it does not exist, create the directory $deploy/site-config/backup.
See “Retrieve Required Files” in SAS Viya: Deployment Guide for more information about the $deploy directory.
e Navigate to the $deploy/sas-bases/examples/backup directory.
f Copy the $deploy/sas-bases/examples/backup directory to the $deploy/site-config/backup directory.
g Make sure that the Execute permission is set on the generate-backup-job script:
chmod +x generate-backup-job.sh
Make sure that Write permission is set on the kustomization.yaml file.
chmod +w kustomization.yaml
h Execute the script generate-backup-job.sh to generate the manifest file for the Kubernetes scan job.
./generate-backup-job.sh scan ldapUser compare
Replace the values for the ldapUser and compare options as follows:
ldapUser Specify the name of the SAS administrator LDAP user specified in step c above.
(Optional) compare Indicates whether inventory scans are to be compared. If the scan job is being run after a migration operation, specify the value 3 for a SAS Viya 3.X to SAS Viya 4 inventory comparison, or the value 4 for a SAS Viya 4 to SAS Viya 4 inventory comparison. Press Enter to skip the compare operation.
This script generates a YAML file with the prefix sas-scan-job, followed by a unique identifier in the same folder (for example, sas-scan-job-m2wk59lf.yaml).
i Edit the kustomization.yaml file. Remove any previous entries from the resources section. Then add the name of the YAML file generated in the previous step.
resources:- sas-scan-job-xxx.yaml
j Navigate to the $deploy directory. Edit the kustomization.yaml file and add the following to the resources section:
resources:- site-config/backup
k Build the manifest using the following command:
32
kustomize build -o site-scan.yaml
l Create the inventory scan job by applying the manifest:
kubectl apply -f site-scan.yaml
Note: If a SAS Viya 4 service is running but is not responsive, the inventory scan job will retry for up to an hour for a response. Depending on how many SAS Viya 4 services are in this non-responsive state, the time could be longer.
The following reports are published in the SAS Viya 4 environment:
SAS Viya 4 Inventory report Contains information about the newly migrated SAS Viya 4 environment.
SAS Viya Comparison report Compares the source SAS Viya 4 environment and the target SAS Viya 4 environment.
See “SAS Viya Inventory Comparison Report” on page 39 for more information.
2 Validate that the target SAS Viya 4 system works as expected.
a Review the SAS Inventory Comparison report and output files that resulted from the scans. See “Scan Output Files” on page 34 for more information.
Compare the scans from the source SAS Viya environment with the scans from the target SAS Viya 4 environment. Make sure that all expected content is present in the SAS Viya 4 environment.
b Test the new SAS Viya 4 environment for further validation.
Migration from SAS Viya: Reference
Scan and Publish
Workflow
33
Scan Details
Scan Output FilesThe scans produce the following sets of output files:
Note: It is recommended that you use the same output location for all of the scans.
34
Table 1 Files Produced by Scans
Type of Scanned Content Files Produced Description
CAS SASViyaInventory_CAS_deployment-label_short-host-name.csv
CSV file that contains results of CAS scan.
SASViyaInventory_CAS_deployment-label_short-host-name_time-stamp.log
Log file of CAS scan.
SASViyaInventory_CAS_deployment-label_short-host-name_CASUSER_Paths.txt
Text file that contains paths of CASUSER libraries.
SASViyaInventory_CAS_deployment-label_short-host-name_Caslibs.yml
YML output file that contains information about caslibs.
cas-server-name.yml YML output file that contains information about CAS servers.
SASViyaInventory_CASSvrDetails_deployment-label_short-host-name.csv
CSV file that contains details about the resources used by the CAS server.
SASViyaInventory_NFSPaths_CAS_deployment-label_short-host-name.csv
CSV file that lists the locations of CAS data that are on NFS paths.
File system SASViyaInventory_Filesystem_deployment-label_short-host-name.csv
CSV file that contains results of file system scan.
SASViyaInventory_Filesystem_deployment-label_short-host-name_time-stamp.log
Log file of file system scan.
SASViyaInventory_Filesystem_deployment-label_short-host-name_Paths.yml
YML output file
SASViyaInventory_NFSPaths_Filesystem_deployment-label_short-host-name.csv
CSV file that lists the locations of the file system directories that are on NFS paths.
Services SASViyaInventory_Services_deployment-label.csv
CSV file that contains results of services scan.
SASViyaInventory_Services_deployment-label_time-stamp.log
Log file of services scan.
35
Type of Scanned Content Files Produced Description
Infrastructure SASViyaInventory_Infrastructure_deployment-label_short-host-name.csv
CSV file that contains results of infrastructure scan
SASViyaInventory_Infrastructure_deployment-label_short-host-name_time-stamp.log
Log file of infrastructure scan.
For example, here are the output files that result from using the inventory plug-in to the SAS Viya command-line interface (CLI) to scan a multiple CAS server environment:
Here are details about the preceding figure:
n The blue text denotes a deployment label.
n The red text denotes the short host name.
n The purple text denotes the CAS server name.
36
Publish Details
OverviewThe migration playbook leverages the same publish capabilities as in SAS Viya 3.5. The migration playbook produces CSV files and databases that are used to populate the SAS Viya Inventory report in SAS Viya 3.X and SAS Viya 4 as well as the SAS Viya Inventory Comparison report in SAS Viya 4.
Reports
SAS Viya Inventory Report
Note: This information describes the SAS Viya Inventory and SAS Viya 4 Inventory reports.
The SAS Viya Inventory report contains merged information from the various scans that are run by the inventory plug-in to the SAS Viya command-line interface (CLI). The report is available only to SAS administrators. See “Access Predefined Reports” in SAS Environment Manager: User’s Guide for more information about working with predefined reports in SAS Environment Manager.
When you open the report, the deployments for which an inventory was run are listed at the top. Select a deployment to display a report.
Select a report page to view. The report pages are represented by these tabs:
StatusDisplays the number of content items and metadata objects found during scans.
What’s Being UsedDisplays an overview of the software usage by either SAS product totals (Content Items Found) or more specific totals of SAS objects (Types of Items Found), SAS servers (Server, Providers and Contexts), and SAS storage (Data Item Storage). From each chart, select for additional options. From the Content Items Found chart, click on a bar to drill down and populate the other charts with information specific to that item.
CAS InventoryExplore the types of CAS libraries found and the tables within them. From each chart, select for additional options. For Library type, select the caslib type for which you want to display information. From the Largest CAS Libraries chart, click on a bar to drill down and populate the other charts with information specific to that item.
Place your cursor over a bar in a graph to view detailed values.
CAS Controls InventoryDrill into the CAS access controls associated with the CAS libraries and tables that were found. For Choose an Identity, select the identity for which you want to view the access controls. From each chart, select for additional options. For Choose a Library, select the caslib for which you want to view the access controls. From the Top Library Controls chart, click on a bar to drill down and populate the other charts with information specific to that item.
Place your cursor over a bar in a graph to view detailed values.
37
Filesystem InventoryExplore the file types that exist on your system and their respective file sizes to determine file system consumption. From the bar below the Filesystem Inventory tab, select the area of the file system for which you want to display the details. From the bar below the file system area bar, select the file extension (within the file system area) for which you want to display the details. From each chart, select for additional options. From the Largest filesystem areas chart, click on a bar to drill down and populate the other charts with information specific to that item.
Place your cursor over a bar in a graph to view detailed values.
Analytics Projects InventoryDrill into the Analytics Suites' project files and their file sizes to discover file system consumption. For Analytics Project Type, select the type of analytics project for which you want to view details. From each chart, select for additional options. From the Largest filesystem areas and Largest projects charts, click on a bar to drill down and populate the other charts with information specific to that item.
Place your cursor over a bar in a graph to view detailed values.
Object InventoryExplore the product usage through the count of each object type created and the services that created them. From the bar below the Object Inventory tab, select the product portfolio for which you want to display the details. From each chart, select for additional options. From the Top Service Counts and Top Item Counts charts, click on a bar to drill down and populate the other charts with information specific to that item.
Place your cursor over a bar in a graph to view detailed values.
Compare Two EnvironmentsCompare the difference between two different deployments or two different executions of the same deployment. From the bar below the Compare Two Environments tab, select the deployment labels of the two deployments that you want to compare. From the top left of the window below the deployment label bar, select the type of scan information that you want to compare. From the resulting chart (CAS Items, Filesystem Items, Content Objects, or Infrastructure), click on a bar to drill down and populate the other charts with information specific to that item.
Place your cursor over a bar in a graph to view detailed values.
Deployment ProvisioningDetermine the recommended items to back up on each server along with sizing information. From each chart, select for additional options. From the Deployment Provisioning tab, select Backup Recommended to show the areas that SAS suggests that you back up. Select Exclude NFS Paths to exclude NFS paths from the sizing.
CAS Backup PlanningFilter the CAS libraries to determine which to back up. From each chart, select for additional options. From the CAS Backup Planning tab, select Backup Is Supported to show only the libraries that you can back up. Edit the value in the box below Maximum Size of CAS Libraries to specify the maximum size of CAS libraries to show. Select Backup Recommended to show only the CAS libraries that SAS suggests that you back up. Select Yor N below Uses NFS Paths? to filter by the CAS libraries with or without NFS paths.
To filter the CAS libraries to back up during migration using these results, you can right-click on the resulting list table (highlighted in blue) and export it to a CSV file. Then, make the file available as input to the backup process by placing it in the directory that you specified in the /INVENTORYRESULTSLOCATION/contentSelection location that you specified in the viya_plan_backup_vars.yml on page 8 file.
38
Filesystem Backup PlanningFilter the file system areas by maximum backup size to determine which to back up. From each chart, select for additional options. Edit the value in the box below Maximum filesystem backup size per area to specify the maximum backup size of file systems to show.
To filter the file system areas to back up during migration using these results, you can right-click on the resulting list table (highlighted in blue) and export it to a CSV file. Then, make the file available as input to the backup process by placing it in the directory that you specified in the /INVENTORYRESULTSLOCATION/contentSelection location that you specified in the viya_plan_backup_vars.yml on page 8 file.
SAS Type DefinitionsExplore the number of customer objects or internal objects in each product portfolio. From each chart, select for additional options. From the SAS Type Definitions tab, select Customer objects to show the number of customer objects or select Internal objects to show the number of internal objects. From the Frequency of Portfolio and Frequency of Sellable Offering charts, click on a bar to drill down and populate the other charts with information specific to that item. Clear filters from the Filters tab.
SAS Viya Inventory Comparison ReportThe SAS Viya Inventory Comparison report contains comparison information about the inventory data in both the source and the target environments, and notes any differences so that they can be reconciled. The two deployments are referred to as "old" and "new". The report is available only to SAS administrators. See “Access Predefined Reports” in SAS Environment Manager: User’s Guide for more information about working with predefined reports in SAS Environment Manager
The report shows counts and differences between the two deployments, categorized by CAS, Filesystem, and Data Objects. The types of differences include the following:
n The content is different.
n The object exists on the old deployment but not on the new deployment.
n The object exists on the new deployment but not on the old deployment.
n The object is different but only in the created or modified dates.
Select a report page to view. The report pages are represented by these tabs:
CAS ItemsShows differences between CAS items, organized by the type of difference. If the object's content is different or differs only in dates, double-clicking on the table displays a page that shows the differences. From each chart, select for additional options.
Place your cursor over a bar in a graph to view detailed values.
Filesystem ItemsShows differences between file system items, organized by the type of difference. If the object's content is different or differs only in dates, double-clicking on the table displays a page that shows the differences. From each chart, select for additional options.
Place your cursor over a bar in a graph to view detailed values.
Content ObjectsShows differences between content objects, organized by the type of difference. If the object's content is different or differs only in dates, double-clicking on the table displays a page that shows the differences. From each chart, select for additional options.
Place your cursor over a bar in a graph to view detailed values.
39
Provision the SAS Viya 4 EnvironmentCompile a document with the following information, and provide it to the Kubernetes administrator to guide them in cluster sizing and planning.
n Determine the sizing requirements for the SAS Viya 3.X migration package using the provisioning pages in the SAS Viya 3.X Inventory report.
o For PostgreSQL, allot 3 times the size of the original PostgreSQL database for the space that it consumes on the SAS Viya 3.X migration package. For example, if the original size of the PostgreSQL database is 10GB, then allot 30GB of space for it on the SAS Viya 3.X migration package.
o The size of the PostgreSQL persistent volume must be at least twice the size of the database before backup to allow for data growth and logs, but no less than 128GB. The default size of the PostgreSQL persistent volume is 128GB.
o Use the “SAS Viya Inventory Report” on page 37 to identify the size to allot for caslibs and analytics projects.
n Overall cluster sizing:
o Determine the basic sizing requirements for SAS Viya 4 and the products being deployed. See “Hardware and Resource Requirements” in System Requirements for SAS Viya for more information.
o Determine whether massively parallel processing (MPP) or multiple CAS servers are needed. Plan for the additional CAS topology:
n number of CAS nodes
n amount of memory per CAS node
n number of CPU cores per CAS node
See “Example of CAS Sizing” on page 41.
o Determine the disk cache configuration on the current CAS servers.
o Determine the amount of space required for each pod that needs persistent volumes and Persistent Volume Claims (PVCs).
n Sizing requirements to restore PostgreSQL databases, including the number of nodes that are replicating content.
n Sizing requirements for any new products that were not included in the SAS Viya 3.4, SAS Viya 3.5, or SAS Viya 4 source environment.
n Volumes that need to be available in Kubernetes.
o Use the “SAS Viya Inventory Report” on page 37 and the files that were edited in the/INVENTORYRESULTSLOCATION/contentSelection location from the viya_plan_backup_vars.yml file to identify any path-based caslibs on the source system and ensure that the content is accessible to the Kubernetes cluster.
o Ensure that the migration package is accessible to the Kubernetes cluster
o Mount the volumes.
n If you are using an external instance of PostgreSQL, provide information about the database management software (DBMS) you are using.
40
Example of CAS SizingGiven a SAS Viya 3.X symmetric multiprocessing (SMP) source environment with these CAS specifications:
Number of nodes 1
Server type Controller
Number of CPUs 16
Number of cores 16
Memory 65808992KB (64.27GB)
A SAS Viya 4 target environment that is provisioned with the following specifications has proven adequate in our testing:
Nodes 5x16GB as described below
Number of cores 4
RAM 16GB
Storage 100GB
For minimum sizing examples for Microsoft Azure, see “Virtual Infrastructure Requirements” in System Requirements for SAS Viya.
PATHLISTFILE Parameter File
Use CaseSometimes you need to scan file locations other than the file systems that SAS Viya uses. In this situation, we recommend that you add any such paths to the PATHLISTFILE parameter of the viya_plan_backup_vars.yml file.
In some situations, the PATHLISTFILE parameter that exists in the viya_plan_backup_vars.yml file is helpful for estimating the size of a path or DNFS-based caslib. The CAS scan returns information about the tables in the top-level directory of a path or DNFS-based caslib (including content that has been accessed, loaded, unloaded, and so on). However, it does not detect whether the path location or subdirectories contain other valid SAS content that is needed for migration. These locations are automatically included when the content is archived. This can cause differences between the reported size of the caslib from the scan and the actual size of the archive file. This additional content can be detected by the file system scan. Therefore, to obtain a more accurate estimate of the size of such a
41
caslib, include the path for the caslib in the file referenced by the PATHLISTFILE parameter of the viya_plan_backup_vars.yml file.
For more information, see the parameters of the viya_plan_backup_vars.yml file on page 8.
ExampleHere is an example of the file specified in the PATHLISTFILE parameter of the viya_plan_backup_vars.yml file:
# viyahost1.test.com/install/viya/sourcecode# viyahost2.test.com/install/divtest/source/DivB
Tokens in cas-migration.yaml FileIf you are using an NFS volume, edit the following attributes in the $deploy/site-config/migration/cas-components/cas-migration.yaml file:
Attributes Description
NFS-MOUNT-PATH Fully qualified path to the location of the migration package. This path does not include the migration package directory itself.
NFS-SERVER NFS server name
Patch File TokensEach patch file has tokens that you must provide a value for. You must know what the migration package directory includes in order to specify appropriate token values.
Migration Package DirectoryThe migration package directory contains the cas-shared-default, consul, data, postgres, and rabbitmq directories. The package is created as a directory and subdirectory with the following name: /SAS_BACKUP_ID/__default__.
The default value of SAS_BACKUP_ID is the value of the SAS_BACKUP_ID parameter in the viya_plan_backup_vars.yml file.
Here are the parameters from the viya_plan_backup_vars.yml file that are related to migration:
42
viya_plan_backup_vars.yml file parameter Description
SAS_BACKUP_ID The ID of the migration package.
MIGRATIONPACKAGELOCATION The mount point directory that contains the migration package.
NFS Patch FileThe NFS patch file (migration-job-nfs-volume.yaml) has these tokens: NFS-SERVER and NFS-PATH. The value of the NFS-SERVER token is the name of the NFS server.
The value of the NFS-PATH token includes the mount point, but does not include the migration package directory itself.
Item Value Description
NFS_PATH mount point1 /migrationPackageLocation The mount point directory and any subdirectories that contain the migration package id. This directory is defined by the value of migrationPackageLocation in the viya_plan_backup_vars.yml file. If you moved the migration package to a different location, substitute that value here.
Migration package location /SAS_BACKUP_ID The directory that will contain the customer backup. This directory is defined by the value of SAS_BACKUP_ID in the viya_plan_backup_vars.yml file. If you renamed the migration package, substitute that value here
Note:This field is limited to 63 characters. The only special characters that are allowed are the hyphen (-), underscore (_), and dot (.).
Customer backup content /__default__ A subdirectory under the migrationPackageId directory that contains the following backup data directories for a customer backup: cas-shared-default, consul, data, postgres, and rabbitmq.
1If the migration package directory is located in a subdirectory of the mount point directory, then /migrationPackageLocation should include the subdirectory. If the migration package directory is located in the mount point directory itself (not in a subdirectory), then this value should be the value of
43
migrationPackageLocation in the viya_plan_backup_vars.yml file. For example, if your mount point path is /vol/IT_testing/users/users1/users1_testing and your migration package is in /vol/IT_testing/users/users1/users1_testing/alluserbackups/mybackup, then /migrationPackageLocation should be /vol/IT_testing/users/users1/users1_testing/alluserbackups.
Example: Suppose that your viya_plan_backup_vars.yml file defines the following values:
migrationPackageLocation: /vol/IT_testing/users/users1/user1_testing migrationPackageID: sas-backup-id-23
In this example, /vol/IT_testing/users/users1/user1_testing (the value of migrationPackageLocation) is your NFS_Path mount point directory, as well as the value of the NFS-PATH token. The migration package directory is /sas-backup-id-23/__default__ (sas-backup-id-23 is the value of migrationPackageID).
Therefore, the migration package /sas-backup-id-23/__default__ is in the mount point directory here: /vol/IT_testing/users/user1/user1_testing/sas-backup-id-23/__default__
If the NFS server is nfs.server.com, then here are the token values for this example:
NFS_PATH: /vol/IT_testing/users/user1/user1_testingNFS_SERVER: nfs.server.com
Here is the NFS patch file (migration-job-nfs-volume.yaml) for this example:
apiVersion: builtinkind: PatchTransformermetadata: name: migration-job-nfs-volume-patchpatch: |- - op: add path: /spec/template/spec/volumes/- value: name: migration nfs: path: /vol/IT_testing/users/user1/user1_testing server: nfs.server.comtarget: apiVersion: v1 group: batch kind: Job labelSelector: app.kubernetes.io/name=sas-migration-job
Azure Patch FileHere are the tokens in the Azure Patch file:
Token Description
SECRET-NAME A standard Kubernetes secret that provides secure access to the file storage account.
SHARE-NAME The name of an Azure file share.
44
Example: Suppose that the SECRET-NAME is azure-storage-account-f2a2f3b2eaff44d0c84b8d0-secret and the SHARE-NAME is kubernetes-dynamic-pvc-4362715a-b14d-4abb-832d-12b90ba1a180. Here are the token values for this example:
secretName: azure-storage-account-f2a2f3b2eaff44d0c84b8d0-secretshareName: kubernetes-dynamic-pvc-4362715a-b14d-4abb-832d-12b90ba1a180
Here is the Azure patch file for this example:
"migration-job-azure-volume.yaml": |- # # NOTE: # # {{ SECRET-NAME }}a Kubernetes secret--> secure access to file storage acct. # # {{ SHARE-NAME }} should be the name of an Azure file share. apiVersion: builtin kind: PatchTransformer metadata: name: migration-job-azure-volume-patch patch: |- - op: add path: /spec/template/spec/volumes/- value: name: migration azureFile: secretName: azure-storage-account-f2a2f3b2eaff44d0c84b8d0-secret shareName: kubernetes-dynamic-pvc-4362715a-b14d-4abb-832d-12b90ba1a180 readOnly: false target: apiVersion: v1 group: batch kind: Job labelSelector: app.kubernetes.io/name=sas-migration-job
Remove Temporary CAS PermstoresEach time a migration is performed, the previous CAS permstore is copied. These files are small, but they can be deleted after migration is successfully completed. These temporary copies can be deleted as follows:
1 Get a shell into the running CAS controller container.
kubectl exec -it sas-cas-server-default-controller -c cas bash
2 Examine the /cas/permstore directories.
cd /cas/permstorels -al
3 Delete any directories with the name primaryctl_backup_timestamp .
rm -rf ./primaryctrl_backup_*
Note: Do not delete the primaryctrl or backupctrl directories with names that do not include a timestamp.
45
Migration Logs
Deployment LogThe deployment.log file that contains log details from the deployment exists in the sas_viya_playbook directory. See Deployment Logs in the SAS Viya 3.5 for Linux: Deployment Guide for more information.
CAS Controller LogThe CAS controller log is created by the sas-server-entrypoint.sh script. It contains logging information from the CAS restore part of migration, including:
n permstore restores
n data restores
n remapping of caslib paths from source environment to target environment
n moving analytics projects to the target environment
Each item in the list above must go well in order for CAS migration to be successful.
See “Migration from SAS Viya: Troubleshooting from SAS Viya 3.X” on page 56 for troubleshooting information using this log.
User-modified Files from SAS Viya 3.X
About These Tasksn You must know the location of the SAS Viya 3.X migration backup package.
n Administrative permissions are required on the SAS Viya 4 system in order to put user-modified files in place in SAS Environment Manager.
n If you modified any of the SAS Viya 4 configuration instances on page 48 described below before beginning the migration process, the modified contents will still be active by default after the migration. Be sure to follow the steps below to either apply the desired applicable changes from your SAS Viya 3 system, or erase any undesired changes from before the migration.
Move User-modified FilesPerform the following steps to retrieve the user-modified files from the SAS Viya 3.X migration package and move them to SAS Environment Manager in SAS Viya 4:
46
1 Open the SAS Viya 3.X migration package that was created in the Back Up step on page 14. It was created as a directory with the name /migrationPackageLocation/SAS_BACKUP_ID/_default_.
Replace migrationPackageLocation with the value of the MIGRATIONPACKAGELOCATION parameter in the viya_plan_backup_vars.yml file here on page 8.
2 Navigate to the data directory in the SAS Viya 3.X migration package.
3 Locate the files in this directory that contain config-etc in their file name. These files contain configuration information that was backed up from the SAS Viya 3.X source environment.
Here is an example of a configuration file that might exist in the data directory: server1.yourorg.com-opt-sas-viya-config-etc.tgz. This file contains configuration information from the backup of the machine, server1.yourorg.com.
If your SAS Viya 3.X system had multiple machines, you might see a set of configuration files for each machine that was backed up.
4 Perform these steps for every configuration file with the file extension TGZ and config-etc in its file name in the data directory.
a Run this command:
gunzip < server-name-configuration-filename.tgz | tar tf - | grep -E 'usermods|sas-compsrv' > YourUsermodFiles-server-name
Here is an example using the name of the file in the previous step:
gunzip < server1.yourorg.com-opt-sas-viya-config-etc.tgz | tar tf - | grep -E 'usermods|sas-compsrv' > YourUsermodFiles-server1.yourorg.com
This command creates a YourUsermodFiles-server-name file that contains a list of the user-modified files that were backed up inside the SAS 3.X migration package for a specific server. If there were no user-modified files, the file is empty, and you should return to step a to look at the next configuration file.
Based on the products that you have deployed on your SAS Viya 3.X system, this file might contain contents such as the following:
n batchserver/default/autoexec_usermods.sas
n batchserver/default/batchserver_usermods.sh
n batchserver/default/sasv9_usermods.cfg
n compsrv/default/autoexec_usermods.sas
n compsrv/default/sasv9_usermods.cfg
n spawner/default/spawner_usermods.sh
n workspaceserver/default/autoexec_usermods.sas
n workspaceserver/default/sasv9_usermods.cfg
n workspaceserver/default/workspaceserver_usermods.sh
n connect/default/connect_usermods.sh
n connectserver/default/autoexec_usermods.sas
n connectserver/default/sasv9_usermods.cfg
n sysconfig/compsrv/default/sas-compsrv
b Run this command to extract the user-modified files to a folder for review and editing if necessary.
47
gunzip < server-name-configuration-filename.tgz | tar xf - --files-from=YourUsermodFiles-server-name
Here is an example using the name of the file in the previous step:
gunzip < server1.yourorg.com-opt-sas-viya-config-etc.tgz | tar xf - --files-from=YourUsermodFiles-server1.yourorg.com
This command extracts the files from the YourUsermodFiles-server-name file to the folder structure shown in the file. For example, suppose you ran this command using the sample YourUsermodFiles content from the previous step. Notice the contents of the workspaceserver/default/ directory after listing:
ls workspaceserver/default/autoexec_usermods.sas sasv9_usermods.cfg workspaceserver_usermods.sh
You can run the command from a different folder if you want the files to be extracted to another location.
c Review these files for items that might need attention before you can use them in SAS Viya 4. For example, there might be library definitions that use paths that are different on your SAS Viya 4 system. Also, there might be TLS settings that need review before you can use them in SAS Viya 4.
To help identify these items, review the following documentation reference sections for the options and variables that are currently supported in SAS Viya 4:
SAS/CONNECT reference documentation “Reference” in SAS Viya: Programming Run-Time Servers
CAS reference documentation “SAS Cloud Analytic Services: Reference” in SAS Viya: SAS Cloud Analytic Services
TLS reference documentation
Note: The TLS options that are used in SAS Viya 4 are already set during deployment.
“Reference” in Encryption in SAS Viya: Data in Motion
If a SAS Viya 3 option is no longer listed in the SAS Viya 4 documentation or has a note or warning that recommends that you not override it in SAS Viya 4 deployments, then consider removing that option from your local copy of your user-modified file before proceeding with adding contents to the SAS Viya 4 configuration instances. Contact SAS Technical Support with any questions.
d Save the files to a known location.
5 Make any necessary changes to the user-modified file settings that you just reviewed and edited to SAS Environment Manager in SAS Viya 4.
To access SAS Environment Manager, select Manage Environment (under ADMINISTRATION) in the Applications menu ( ). In the vertical navigation bar, select .
6 Using the View: drop-down list, choose Definitions.
7 In the navigation pane, select the definition of the corresponding configuration area for each user-modified file (for example, sas.compute.server).
48
Modify the SAS Viya 3.X user-modified file settings from the Configuration page in SAS Environment Manager in SAS Viya 4.
SAS Viya 3.X path Definition Service Configuration instance
compsrv/default/autoexec_usermods.sas
sas.compute.server Compute service autoexec_code
compsrv/default/sasv9_usermods.cfg
sas.compute.server Compute service configuration_options
sysconfig/compsrv/default/sas-compsrv
sas.compute.server Compute service startup_commands
connect/default/connect_usermods.sh
sas.connect.spawner SAS/CONNECT Spawner startup_commands
connectserver/default/connectserver_usermods.sh
sas.connect.server SAS/CONNECT Spawner startup_commands
connectserver/default/autoexec_usermods.sas
sas.connect.server SAS/CONNECT Spawner autoexec_code
connectserver/default/sasv9_usermods.cfg
sas.connect.server SAS/CONNECT Spawner configuration_options
cas/default/casconfig_usermods.lua
sas.cas.instance.config Based on CAS instance name (for example, cas-shared-default)
config
cas/default/cas_usermods.settings
sas.cas.instance.config Based on CAS instance name (for example, cas-shared-default)
settings
cas/default/casstartup_usermods.lua
sas.cas.instance.config Based on CAS instance name (for example, cas-shared-default)
startup
Note: SAS_ALLOW_ADMIN_SCRIPTS is set to false by default, meaning that processing is not enabled for any modifications to the following configuration instances in SAS Environment Manager:
n sas.compute.server: startup_commands
n sas.connect.spawner: startup_commands
n sas.connect.server: startup_commands
n sas.cas.instance.config: startup
n sas.cas.instance.config: config
n sas.cas.instance.config: settings
49
You must set SAS_ALLOW_ADMIN_SCRIPTS to true in order for modifications to these configuration instances to be processed. See $deploy/sas-bases/overlays/sas-programming-environment/README.md for more information.
a Click . Copy the text from inside the corresponding user-modified file that you reviewed, and paste it into the Contents field of the configuration instance, completely replacing the original default text.
b Here are more details:
n When copying over the text from the connect_usermods.sh file into the configuration instance sas.connect.spawner : startup_commands, if you want to maintain the behavior of the -NOSCRIPT option from the SAS Viya 3.X environment, then add the -NOSCRIPT option to any other options that you are copying over. Leave a space between the -NOSCRIPT option and other options (for example, USERMODS="-NOSCRIPT -OPTION2 -OPTION3").
Note: If you need to enable scripted sign-ons for SAS/CONNECT, do not include the -NOSCRIPT option. If you have no other applicable options, ensure that you specify an empty USERMODS environment variable (for example, USERMODS= ).
See “Spawner General Options” in SAS Viya: Programming Run-Time Servers for more information about the -NOSCRIPT option.
n In SAS Viya 3.X, lockdown was disabled by default, whereas in SAS Viya 4, lockdown is enabled by default for the SAS/CONNECT server. See “Lock Down the SAS/CONNECT Server” in SAS Viya: Programming Run-Time Servers for more information, including how to disable or modify the default lockdown behavior.
c Click Save.
See “Edit Configuration Instances” in SAS Environment Manager: User’s Guide for more information about modifying configuration instances.
8 If you want to change the default LOCALE and ENCODING for the Compute server and the SAS/CONNECT Spawner, add an appropriate export LANG=langValue statement in the startup_commands configuration instance for both the sas.compute.server and sas.connect.server definitions. For more information, see “Change the Default ENCODING” in SAS Viya: Programming Run-Time Servers.
9 The new values for the services take effect as follows:
Compute service New values take effect when the service launches a new session.
SAS/CONNECT Spawner New values take effect after a restart of the SAS/CONNECT Spawner. See “Operate the SAS/CONNECT Spawner” in SAS Viya: Programming Run-Time Servers for more information.
CAS server New values take effect after a restart of the CAS server. See “SAS Cloud Analytic Services: How To” in SAS Viya: SAS Cloud Analytic Services for more information.
50
Additional Migration DetailsSee this table for migration information that is specific to a product or offering:
Solution Description
SAS Studio After migrating to SAS Viya 4, you can access only SAS content from SAS Studio. To access the file system, you must do the following:
n Connect the persistent volume that contains your data to the SAS Viya environment. See one of the following files for more information:
o Markdown file at $deploy/sas-bases/examples/sas-compute-server/configure/README.md
o HTML file at $deploy/sas-bases/docs/configuration_settings_for_compute_server.htm
n Change the showServerFiles configuration property in SAS Environment Manager to true. See “Configuration Page” in SAS Environment Manager: User’s Guide for more information.
SAS Assortment Planning Migration to SAS Viya 4 is not currently supported in this version.
SAS Financial Planning Migration to SAS Viya 4 is not currently supported in this version.
SAS Demand Planning Migration to SAS Viya 4 is not currently supported in this version.
SAS Markdown Optimization Migration to SAS Viya 4 is not currently supported in this version.
SAS Size Optimization Migration to SAS Viya 4 is not currently supported in this version.
SAS Risk Modeling As of 2020.1.3, SAS Risk Modeling is available in SAS Viya 4. Migration from SAS Viya 4 to SAS Viya 4 is supported in this version. See “How Does Migration within the Same Versions of SAS Risk Modeling Work?” in SAS Risk Modeling: Administrator’s Guide for more information.
Migration from SAS Viya 3.X to SAS Viya 4 is not currently supported in this version.
51
Backups from the SAS Inventory Report CSV Files
IntroductionFrom the Filesystem Backup Planning and CAS Backup Planning pages of the SAS Inventory Report, you can create CSV files that direct the backup process.
Content That Is Backed UpBy default, the backup contains the following data:
n Selected contents of each unique filesystem path in the CSV file that contains one of the following common parent directories:
/opt/sas/viya/config/data/cas/default/projects
/opt/sas/viya/config/data/modelsvr
/opt/sas/viya/config/etc
customized paths in the PATHLISTFILE parameter of the viya_plan_backup_vars.yml file on page 8
From each filesystem path identified above, the following files are backed up:
Files Searched for by File System Scan Description
.sashdat SASHDAT file
.sas7bdat SAS data set
.sas7bcat SAS catalog
.sas SAS program file
.csv Comma-Separated Values File
USERMODS SAS USERMODS file
.astore Analytic store file
.p Scoring resource file
.pkl Scoring resource file
52
Files Searched for by File System Scan Description
.pickle Scoring resource file
n Any unique caslib that is present in the CSV file.
Backup ProcessFilter the report to identify the filesystem paths and caslibs that you want to back up.
n If any unique filesystem path that contains one of the common parent directories on page 52 is selected, its contents are backed up. The backup includes files whose extension is one of the supported file types. on page 52 The backed up files are from any directory under the common parent directory as well as content from the common parent directory itself.
n For each caslib, the caslib along with all of its tables is backed up.
If any of the following caslibs are present in the report, ensure that they are included in the CSV file.
Formats
ModelPerformanceData
Models
ModelStore
VAModels
IMPORTANT The filesystem path and caslib selections in the resulting CSV file override the settings for the gatherTables (caslibs) and gatherFiles (paths) options in the backup YAML files on page 12 which trigger the backup.
Override the Default Source Time Zone ValueThe migration job internally converts PostgreSQL timestamp values from the source time zone to UTC. By default, it references the source system time zone value from the timezone-info.txt file that is available in the /migrationPackageLocation/_default_/postgres directory in the SAS Viya 3.X migration package. If you need to override that value, add the following line (where timezone_value is a valid time zone recognized by the International Standards Organization) to the literals section of the sas-restore-job-parameters code in the configMapGenerator section of the kustomization.yaml file:
- SOURCE_TZ=timezone_value
53
Examples of Transferring Data from Persistent Volumes (PVs)
Get the Required Information to Mount the Azure Persistent Volume (PV)In this example, the storage class is azurefile.
1 Run the following command on the Kubernetes controller node:
kubectl -n name-of-namespace get pv $(kubectl get pvc -n name-of-namespace | grep persistent_volume_claim | awk '{print $3}') -o json | jq '.spec'
Here is an example of the resulting output when running the command for the sas-common-backup-data PV:
{ "accessModes": [ "ReadWriteMany" ], "azureFile": { "secretName": "azure-storage-account-fbc3e3ecf1289451c913303-secret", "secretNamespace": "d25366", "shareName": "kubernetes-dynamic-pvc-23a787c9-9488-4c80-a86e-f9b263d623ce" }, "capacity": { "storage": "25Gi" }, "claimRef": { "apiVersion": "v1", "kind": "PersistentVolumeClaim", "name": "sas-common-backup-data", "namespace": "d25366", "resourceVersion": "4666", "uid": "23a787c9-9488-4c80-a86e-f9b263d623ce" }, "persistentVolumeReclaimPolicy": "Delete", "storageClassName": "azurefile", "volumeMode": "Filesystem"}
2 Locate the azureFile section in the above JSON file to find the secretName and shareName to use for mounting the volume.
Here are these values using the sas-common-backup-data persistent volume output from the prior step:
secretName azure-storage-account-fbc3e3ecf1289451c913303-secret
54
shareName kubernetes-dynamic-pvc-23a787c9-9488-4c80-a86e-f9b263d623ce
3 Get the Azure storage account name from the value of secretName. Here is an example using the sample values from the prior step:
STORAGEACCT=fbc3e3ecf1289451c913303
Copy Data from an Azure Environment to an Azure Environment1 Make sure that you know the location of the PVs that contain backup data. See “ Get the Required
Information to Mount the Azure Persistent Volume (PV)” on page 54 for examples of finding the location of PVs.
2 Go to the target environment machine where the target persistent volumes are mounted or from where they can be accessed. Mount the source environment path identified in the previous step or go to the actual location if it is already available. If target persistent volumes are not mounted, you can use the same steps as used for mounting the source environment persistent volumes.
If you mount the path locally, make sure that you have the appropriate permissions to mount the file system.
Mount the Azure file share/volume using the standard steps contained in the Azure documentation here.
Here is the command to mount the Azure file share to the local directory.
sudo mount -t cifs //STORAGEACCT.file.core.windows.net/shareName /mnt/MyAzureFileShare -o vers=3.0,username=STORAGEACCT,password=STORAGEKEY,dir_mode=0777,file_mode=0777,serverino
Here is an example of the command when using the sas-common-backup-data persistent volume output identified in this output:
sudo mount -t cifs //fbc3e3ecf1289451c913303.file.core.windows.net/kubernetes-dynamic-pvc-23a787c9-9488-4c80-a86e-f9b263d623ce /mnt/MyAzureFileShare -o vers=3.0,username=fbc3e3ecf1289451c913303,password=71He1K2Z5j5Bv8hCb5tb+m4zGgfJFxsBSiUejsV/+5x6eWHrFEUPREzHaQpMKF26IjB59qnKWN7Ex8cPP8954Q==,dir_mode=0777,file_mode=0777,serverino
3 Copy the required backup ID directory contents using the backup ID identified in “Best Practices for Performing Backups” in SAS Viya: Backup and Restore.
cp -rp source_mounted_directory/backup_idtarget_environment_pv_path
Here is an example of the command when using the sas-common-backup-data PV output from the source environment in the previous step:
cp -rp /mnt/MyAzureFileShare/backup_id /mnt/TargetAzureFileShare
In the above example, /mnt/TargetAzureFileShare is the target environment PV location.
Note: The time required to copy the backup data contents varies based on the size of the backup directory, the disk I/O rate of the system, and the type of file system that you are using.
4 Repeat steps 1 through 3 to copy the backup ID directory contents for all PVs.
55
5 Make sure that the directory and file permissions are the same as on the source environment.
Migration from SAS Viya: Troubleshooting from SAS Viya 3.X
Before Migration
Cannot Run the sas-viya CLIIf one of the following messages occurs while running the sas-viya CLI to generate the playbook, then the sas-viya CLI is not installed or is not the minimum required version:
n Did not find any sas-viya inventory plugin. Please download the latest.
n sas-plugin-cli must be version version or higher
To resolve, ensure that the sas-viya CLI is installed at the required minimum version.
The Shared Vault Location Is InvalidIf the following message occurs while running the scan play of the Plan and Backup Ansible playbook, then the shared vault location might be invalid or does not exist:
Path does not exist. Verify: sharedVaultLocation.
To resolve, ensure that you entered the correct value for the SHAREDVAULTLOCATION parameter in the viya-plan-backup-vars.yml file.
The SAS_BACKUP_ID That Was Specified Already Existsif the following message occurs while running the scan play of the Plan and Backup Ansible playbook, then the SAS_BACKUP_ID already exists:
Migration Package already exists. Choose another.
To resolve, specify another value for the SAS_BACKUP_ID in the viya-plan-backup-vars.yml file or delete the existing backup.
56
Cannot Create the Temporary Directory on the HostThe playbook creates a temporary directory in /tmp on each host that is scanned during the scan play of the Plan and Backup Ansible playbook.. All required files to run the scans are stored in this directory, and then removed when the playbook is complete.
If a message such as the following occurs while running the scan play of the playbook, then there might have been problems creating the temporary directory due to inadequate space or permissions:
n No space left on device while performing this task: Copy required scripts on each machine
n Permission denied while performing this task: Create temporary directory structure
Cannot Create the INVENTORYRESULTSLOCATION DirectoryIf a message such as the following occurs while running the scan play of the Plan and Backup Ansible playbook, then the playbook could not create the INVENTORYRESULTLOCATION directory due to inadequate permissions:
There was an issue creating /inventory as requested: [Errno 13] Permission denied: '/inventory'", "path": "/inventory/allScanResults
To resolve, check the permissions on the path location specified in the INVENTORYRESULTSLOCATION parameter in the viya-plan-backup-vars.yml file.
The Backup Job Failed to StartIf the following message occurs while running the backup play of the Plan and Backup Ansible playbook, then a backup job ID was not captured:
The Backup Job failed to start, or the job id was not parsed properly. Stopping
To resolve, do the following:
1 Verify that the backup service is working. See Backup and Restore: Troubleshooting in the SAS Viya 3.5 Administration Guide for more information.
2 After verifying that the backup service is working, determine whether the backup can be started from the backup plug-in to the sas-viya CLI. See Backup and Restore: How To (CLI) in the SAS Viya 3.5 Administration Guide for more information.
3 After verifying that the backup can be started from the backup plug-in to the sas-viya CLI, try rerunning the backup play of the Plan and Backup Ansible playbook.
The Backup Job Did Not Complete SuccessfullyIf the following message occurs while running the backup play of the playbook, then the Plan and Backup Ansible playbook was unable to verify that the backup completed successfully:
57
The backup job failed to complete!
Note: The Plan and Backup Ansible playbook looks for the word ‘complete’ in the output from the backup plug-in to the sas-viya CLI. The playbook uses the backup plug-in SHOW command with the backup job ID that results from the START command to get the status of the backup job.
To resolve, do the following:
1 Use the backup plug-in to the sas-viya CLI to get the status of the backup job and review any error messages. See Backup and Restore: How To (CLI) in the SAS Viya 3.5 Administration Guide for more information.
2 Before rerunning the backup play of the Plan and Backup Ansible playbook, delete the contents of the incomplete SAS Viya 3.X migration package from the SAS_BACKUP_ID location of the viya-plan-backup-vars.yml file.
The Storage Location for the SAS Viya 3.X Migration Package Ran Out of SpaceIf you receive a message about inadequate space while running the backup play of the playbook, then you might have run out of space in the location specified for the SAS Viya 3.X migration package.
To resolve, you must allocate more space on the location specified in the MIGRATIONPACKAGELOCATION parameter in the viya-plan-backup-vars.yml file or specify a new location. Then run the backup play of the playbook again.
After Restore
Cannot Verify That CAS Migration SucceededSearch the CAS controller log on page 46 for messages about the items that were restored.
For example, you might search for these messages in the log.
n Migration content will be restored.
n migration_complete* breadcrumb does not exist...we haven't migrated yet
n Migration source permstore found
n running sas-inventory-cli restore...
n sas-inventory-cli restore complete!
n Copy over product content if present
n Create product directories
n [INFO] - Starting Cloud Analytic Services...
58
In a successful CAS migration, these messages appear in the log in this order. If for example, there was no Migration source permstore found message in the log, you might suspect that there was some problem with the source permstore path.
Cannot Restore Caslib Based on an NFS MountMake sure that the mount has been created in the Kubernetes target environment.
Watch for a pair of messages that matches this pattern:
Extracting /vol/IT_testing/users/users1/users1_testing /census_data.csv
open /vol/IT_testing/users/users1/users1_testing /census_data.csv: no such file or directory
Make sure that the mount exists in the Kubernetes target environment.
Ran Out of Disk Space during RestoreMake sure that the Kubernetes volumes are sized adequately.
SAS® and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. in the USA and other countries. ® indicates USA registration. Other brand and product names are trademarks of their respective companies. Copyright © 2020, SAS Institute Inc., Cary, NC, USA. All Rights Reserved. February 2021 v_008-P1:calmigration
59
60
