The SAS® Viya® Deployment as a Code (DAC) project does not perform updates


The SAS Viya Deployment as Code (DAC), also known as the viya4-deployment project, does not perform SAS Viya updates. You should not use the DAC project to update SAS Viya from one version to another. 

SAS Viya requires manual steps to perform updates, which include completing the pre-update checklist, reading Deployment Notes, and acting upon them in a specific way. Because the DAC project does not perform these manual steps, the DAC does not directly support updates. 

The project previously provided the following disclaimer at https://github.com/sassoftware/viya4-deployment. 

Updating SAS Viya Manually 

Manual steps are required by the SAS software to update a SAS deployment in an existing cluster. As a result, viya4-deployment does not perform updates. The viya4-deployment tools can perform subsequent viya install tasks if you are simply reapplying the same software order into the cluster. 

If you have an existing deployment that you performed with the viya4-deployment project, take the following steps in order to update the SAS Viya platform: 

    • Follow the instructions in Updating Software in the SAS Viya Platform Operations Guide.
    • You are expected to modify the steps that are described in the SAS Viya Platform Operations Guide to accommodate the slightly different directory structure 

In addition, the project was updated to provide the following information in the README:

  • Use this project for only patch updates that use the exact same manifest as the existing deployment.
  • Updating to a new SAS Viya platform version, cadence, or a new software offering is not supported using this project.
  • For more information about updating your software, see SAS KB0041450, "The SAS Viya Deployment as a Code project does not perform updates."

Therefore, before performing updates, it is recommended that you change deployment methods from the DAC to another method (such as the SAS Deployment Operator, the sas-orchestration Command, or Kubernetes commands). Also, in the future, when performing new deployments, SAS Technical Support encourages you to consider the alternative options for deployment unless there is a compelling reason for using the viya4-deployment project. Alternative options for deployment are summarized here.

Note that changing from the DAC to another method is not covered in the SAS® Viya® Platform Operations documentation.

This SAS KB article provides guidance and tips based on the experiences in SAS Technical Support. However, due to the customizations present in every SAS Viya deployment, it is impossible to provide step-by-step guidance. This SAS KB article assumes basic knowledge of SAS Viya deployment techniques. If that level of knowledge is not available, contact SAS Professional Services or your SAS Account Team.  

Table of Contents


Overview: Moving from the DAC to Another Deployment Method

Note: All links to the documentation from this SAS KB article default to the newest stable. When you open the links, change the document version to your target SAS Viya version.  

General Tips

  • Any run books that you used to deploy SAS Viya originally would not be applicable to a SAS Viya update because the steps are different. The DAC cannot perform the manual steps in the documentation, which is why the DAC disclaims performing updates. 
  • By default, the DAC uses the Deployment Operator method. If you previously set V4_DEPLOYMENT_OPERATOR_ENABLED=false in Ansible vars, the sas-orchestration Command was used to deploy SAS Viya.
  • You can change from the DAC to any other method (such as the SAS Deployment Operator, the sas-orchestration Command, or Kubernetes commands). See Change Deployment Methods for more information.
    • When changing methods, make a copy of your $deploy directory that was generated when you did the DAC deployment. Use this new directory to make your changes. Note that you do not need to copy the sasdeployment.yaml and uninstall.yaml files.
  • All Deployment Methods noted in this SAS KB article include the following steps:
    • Pre-update checklist (complete the checklist first), which includes things to check to ensure a successful outcome.
    • Replace $deploy/sas-bases with the new assets that you download from my.sas.com. 
    • Review all applicable Deployment Notes (which have Before Deployment and After Deployment commands).
  • Additional steps required to transition from the DAC to your specific Deployment Method are not covered in the SAS documentation. Refer to this SAS KB article for additional information.

Directory Structure Differences Between the DAC and SAS Documentation

Here are some differences in the directory structure between the DAC and SAS documentation:

  • The DAC uses a slightly different directory structure than the documentation for the $deploy/site-config directory. Some of the paths might look different from those listed in the documentation because the DAC code organizes them differently. 
  • The documentation provides suggestions on different Directory Structure approaches.
  • After you stop using the DAC, you need to manage the files and directories under $deploy/site-config. 
  • You can choose to organize files under $deploy/site-config however you want, but you will need to update the corresponding file path references in kustomization.yaml. 

Mirror Registry

  • If you are using a mirror registry, take steps to ensure that the deployment assets match the container images in the mirror repository to avoid image pull failures.
  • When running mirrormgr to create a mirror repo, specify --deployment-assets and point to the new Deployment Assets archive that you downloaded. Per the documentation, "This uses data from the Deployment Assets archive that you downloaded with your software order to determine the cadence name, version, and release values." See Optional Flags for additional information. 
  • If you use methods other than the DAC, note the following:
    • If using the SAS Deployment Operator, the cadence-type, cadence-version-number, and cadence-release-number must match the --deployment-assets flag used when running mirrormgr to populate the mirror. See Create the SASDeployment Custom Resource for additional information.
    • If using the sas-orchestration Command, the cadence-type, cadence-version-number, and cadence-release-number must match the --deployment-assets flag used when running mirrormgr to populate the mirror. See Deployment Using the sas-orchestration Command for additional information.
    • If using Kubernetes Commands, you do not need to take any additional steps. 

Considerations when Choosing a Deployment Method

There are three deployment methods that you can choose when transitioning away from the DAC. When choosing a method, consider that when the DAC runs, the DAC uses the Deployment Operator method by default in the background. If you set V4_DEPLOYMENT_OPERATOR_ENABLED=false in Ansible vars, the DAC uses the sas-orchestration command.
 
You can think of the DAC as a code generator, which then calls either the SAS Deployment Operator or the sas-orchestration command. However, since the DAC does not perform updates, SAS Technical Support recommends that you change Deployment Methods from the DAC to another method and begin using that newly chosen method directly.

Deployment Operator Method

  • Follow the appropriate process depending on what method the DAC used:
    • If you were already using the SAS Deployment Operator with the DAC (the default), when copying files for the Deployment Operator, recommends naming the directory for the Deployment Operator as $operator-deploy. The recommended location of $operator-deploy is parallel to the $deploy directory. Parallel means $operator-deploy is not nested under $deploy. For a directory tree example, see Directories for the SAS Viya Platform Deployment Operator.
    • If you opted into using the sas-orchestration command with the DAC and now you want to change to the Deployment Operator, see Kubernetes Commands to SAS Viya Platform Deployment Operator. Despite the misleading title, this doc is applicable.
      • If you used a mirror registry (and if you opted into using the sas-orchestration command with the DAC and now you want to change to the Deployment Operator): 
        • Remove references to mirror.yaml from $deploy/kustomization.yaml. The file is not used by the Deployment Operator. 
        • When you follow Update to a New Version Using the Deployment Operator and Create the SASDeployment custom resource, add this option to your Docker command: --image-registry mirror-registry-location
        • mirror-registry-location is the URL for the docker image registry (for example, registry.example.com). For more syntax details see Command Format. This option modifies the internal build that occurs using Deployment Operator. It will build Deployment Assets, replacing cr.sas.com with the mirror host. 
  • If you are updating SAS Viya to a new version, consider updating the Deployment Operator first. For more information, see Update to a New Version Using the Deployment Operator.
  • Complete the deployment instructions at Update to a New Version Using the Deployment Operator. 

sas-orchestration Command Method

Kubernetes Commands Method

  • Follow the appropriate process depending on what method the DAC used:
  • The Kubernetes Commands method requires the Kustomize binary. The version of Kustomize depends on the SAS Viya version that you are updating to. Download the correct version of Kustomize. See Kubernetes Client Machine Requirements. Remember to change the document version to your target SAS Viya version.
  • Complete the deployment instructions at Update to a New Version Using Kubernetes Commands.
  • Other deployment methods (such as the SAS Deployment Operator and the sas-orchestration Command) provide the Kubernetes client machine requirements and do not require installing Kustomize. 

Preventing Future Problems with License Renewals

  • The DAC managed your license file automatically. Other methods do not. A universal suggestion when moving from the DAC to another deployment method is to comment out the license yaml reference in your kustomization.yaml file: site-config/vdm/generators/sas-license.yaml.
  • Commenting out the license yaml reference helps prevent future complications with license updates.
  • When following the How to Apply a New License documentation, note the following:
    • If the DAC license reference is still in your kustomization.yaml file, it will overwrite the new license and cause the license update to not work. 
    • If you choose the Kubernetes Commands Method, slight modifications to the documented steps are required to apply the license. The documentation tells you to add the secretGenerator block immediately before the configMapGenerator block. However, the DAC did not create a secretGenerator block nor a configMapGenerator block. You will need to add the secretGenerator block to the end of the kustomization.yaml file (unless you added it previously). Ensure that there is only one secretGenerator block in kustomization.yaml. 
  • When making a copy of your $license directory, the recommended location for $license is parallel to the $deploy directory (not nested under $deploy). For a directory tree example, see Directories for the SAS Viya Platform Deployment Operator.