A collection of recipes and other resources for building containers that include SAS Viya software.
Branch: master
Clone or download

README.md

SAS® Viya® Container Recipes

SAS Containers Icon

Framework to build SAS Viya Docker images and create deployments using Kubernetes.

SAS Viya Version Docker Version Kubernetes Version Ansible Container Version



Container deployments are more lightweight and don't have as much overhead as traditional virtual machines. By running a SAS engine inside a container, you can provision resources more efficiently to address a wide variety of SAS workloads. Select a base SAS recipe and create custom containers with specific products or configurations – e.g, access to data sources, in-database code and scoring accelerators, or specific analytic capabilities. For more information see SAS for Containers.



Quick Start

Use the instructions on this page to quickly build and launch SAS Viya containers. For more extensive infomation about building and launching SAS Viya containers, see the GitHub Project Wiki Page

  1. Locate your SAS Viya for Linux Software Order Email (SOE) and retrieve the SAS_Viya_deployment_data.zip file from it. Not sure if your organization purchased SAS Software? Contact Us or get SAS License Assistance. If you have not purchased SAS Software but would like to give it a try, please check out our Free Software Trials.

  2. Download the latest Latest Release or git clone git@github.com:sassoftware/sas-container-recipes.git

  3. Choose your flavor and follow the recipe to build, test, and deploy your container(s).

    a. If you are looking for an environment tailored towards individual data scientists and developers, you will be interested in a SAS programming-only deployment running on a Single Container.

    b. If you would like an environment suitable for collaborative data science work, then you may be interested in a SAS programming-only deployment or a SAS Viya full deployment on Multiple Containers.

Other Resources

GitHub Project Wiki Page for all documentation.

GitHub Project Issues Page for questions and project improvements.

Official Kubernetes Documentation for general Kubernetes help.

Official Docker Documentation for general Docker help.




For a Single User - SAS® Viya® programming-only deployment running on a Single Container

Use these instructions to create a SAS Viya programming-only deployment in a single container for an independent data scientist or developer to execute SAS code. All code and data should be stored in a persistent location outside the container. This deployment includes SAS Studio, SAS Workspace Server, and a CAS server, which provides in-memory analytics for Symmetric Multi Processing (SMP).

A supported version of Docker-ce (community edition) is required.

Build the Container

Run the following to create a user 'sasdemo' with the password 'sasdemo' for product evaluation. A non-root user is recommended for all build commands.

  ./build.sh --zip ~/my/path/to/SAS_Viya_deployment_data.zip --addons "addons/auth-demo"

You can use addons found in the addons/ directory to enhance the base SAS Viya image with SAS/ACCESS, LDAP configuration, and more. For each addon that will be included with the build, review the readme associated with the addon for important information and any possible prerequisite requirements.

Run the Container

After the container is built then instructions for how to run the image will be printed out.


  docker run --detach --rm --hostname sas-viya-programming \
    --env CASENV_CAS_VIRTUAL_HOST=<my_host_address> \
    --env CASENV_CAS_VIRTUAL_PORT=8081 \
    --publish-all \
    --publish 8081:80 \
    --name sas-viya-programming \
    sas-viya-programming:<VERSION-TAG>

    

Use the docker images command to see what images were built and what the most recent tag is (example: tag 19.0.1-20190109112555-48f98d8). Once the docker run command is completed, use docker ps to list the running container.
Finally go to the address http://<myhostname>:8081 and start using SAS Studio!

For more info see the GitHub Project Wiki Page.




For one or more users - SAS® Viya® programming-only or SAS® Viya® full deployment running on multiple containers

Use these instructions to build multiple Docker images and then use the images to create a SAS Viya programming-only or a SAS Viya full deployment in Kubernetes. These deployments can have SMP or MPP (Massive Parallel Processing) CAS servers, which provide in-memory analytics, and can be used by one or more users.

A programming-only deployment supports data scientists and programmers who use SAS Studio or direct programming interfaces such as Python or REST APIs. Understand that this type of deployment does not include SAS Drive, SAS Environment Manager, and the complete suite of services that are included with a full deployment. Therefore, make sure that you are providing your users with the features that they require.

Prerequisites

  • A supported version of Docker-ce (community edition) on Linux must be installed on the build machine
  • Python2 with python-pip2 and virtualenv or Python3 and python-pip3 must be installed on the build machine
  • java-1.8.0-openjdk or another Java Runtime Environment (1.8.x) must be installed on the build machine
  • Access to a Docker registry: The build process will push built Docker images automatically to the Docker registry. Before running build.sh do a docker login docker.registry.company.com and make sure that the $HOME/.docker/config.json is filled in correctly.
  • Access to a Kubernetes environment and kubectl installed: required for the deployment step but not required for the build step.
  • Strongly recommended: A local mirror of the SAS software. Here's why.

Required build.sh Arguments

A non-root user is recommended for all build commands.


        SAS Viya Programming example:
            ./build.sh --type multiple --zip /path/to/SAS_Viya_deployment_data.zip --docker-registry-namespace myuniquename --docker-registry-url myregistry.myhost.com --addons "addons/auth-demo"

        SAS Viya Full example: 
            ./build.sh --type full --docker-registry-namespace myuniquename --docker-registry-url myregistry.myhost.com --zip /my/path/to/SAS_Viya_deployment_data.zip
        

  -y|--type [ multiple | full ] 
                          The type of deployment.
                            multiple: SAS Viya Programming Multi-Container deployment with Kubernetes
                            full: SAS Visuals based deployment with Kubernetes.
                            single: One container for SAS Programming. See the "Single Container" guide section.

  -n|--docker-registry-namespace <value>
                          The namespace in the Docker registry where Docker images 
                          will be pushed to. Use a unique name to prevent collisions.
                            example: myuniquename

  -u|--docker-registry-url <value>
                          URL of the Docker registry where Docker images will be pushed to.
                          This is required for Kubernetes 
                            example: 10.12.13.14:5000 or myregistry.myhost.com

  -v|--virtual-host 
                          The Kubernetes Ingress path that defines the location of the HTTP endpoint.
                          For more details on Ingress see the official Kubernetes documentation at
                          https://kubernetes.io/docs/concepts/services-networking/ingress/
                          
                            example: user-myproject.mylocal.com

  -z|--zip <value>
                          Path to the SAS_Viya_deployment_data.zip file from your Software Order Email (SOE).
                            example: /my/path/to/SAS_Viya_deployment_data.zip
                            
                            SAS License Assistance: https://support.sas.com/en/technical-support/license-assistance.html
                            SAS Software Purchase: https://www.sas.com/en_us/software/how-to-buy.html
                            SAS Software Trial: https://www.sas.com/en_us/trials.html
                        
                            
   ** [ EITHER --zip OR --playbook-dir ]  **

  -l|--playbook-dir <value>
                          Path to the sas_viya_playbook directory. A playbook is used for existing BAREOS deployments
                          whereas new deployments utilize the above '--zip' argument. If this is passed in along with
                          the zip file then this playbook location will take precendence.
    
                               

Optional build.sh Arguments


  -a|--addons "[<value>] [<value>]"
                          A space separated list of layers to add on to the main SAS image.
                          See the 'addons' directory for more details on adding access engines and other tools.
                            example: --addons "addons/auth-sssd addons/access-postgres"

  -i|--baseimage <value>
                          The Docker image from which the SAS images will build on top of
                            Default: centos

  -t|--basetag <value>
                          The Docker tag for the base image that is being used
                            Default: latest

  -m|--mirror-url <value>
                          The location of the mirror URL. See the Mirror Manager guide at
                          https://support.sas.com/en/documentation/install-center/viya/deployment-tools/34/mirror-manager.html

  -p|--platform <value>
                          The type of distribution of the image defined by the \"baseimage\" option.
                            Options: [ redhat ]
                            Default: redhat

  -d|--skip-docker-url-validation
                          Skips validating the Docker registry URL

  -k|--skip-mirror-url-validation
                          Skips validating the mirror URL from the --mirror-url flag.

  -s|--sas-docker-tag
                          The tag to apply to the images before pushing to the Docker registry.
                            default: ${recipe_project_version}-${datetime}-${last_commit_sha1}
                            example: 18.12.0-20181209115304-b197206
  
  

After running build.sh

  • For a SAS Viya Programming deployment, the Kubernetes manifests are located at viya-programming/viya-multi-container/working/manifests/kubernetes
  • For a SAS Viya Full deployment, the Kubernetes manifests are located at viya-visuals/working/manifests/kubernetes/

Choose between Symmetric Multi Processing (SMP) or Massively Parallel Processing (MPP) and run a kubectl create --file or kubectl replace --file on the manifests inside the kubernetes directory.

  • Note: If you are running the build process process multiple times then use kubectl replace to add your new manifests instead of kubectl create.

Then add hosts to your Kubernetes Ingress for sas-viya-httpproxy and other services using kubectl edit ingress.


    - Kubernetes Ingress Example -

  apiVersion: extensions/v1beta1
  kind: Ingress
  metadata:
    namespace: <myuniquename>
    name: example ingress
  spec:
    rules:
    - host: sas-viya-http.<mycompany>.com
      http:
        paths:
        - backend:
            serviceName: sas-viya-httpproxy
            servicePort: 80
          
    - host: sas-viya-cas.<mycompany>.com
      http:
        paths:
        - backend:
            serviceName: sas-viya-sas-casserver-primary
            servicePort: 5570


For more details on Ingress Controllers see the official Kubernetes documentation.

Finally, go to the host address that's defined in your Kubernetes Ingress to view your SAS product(s). If there is no response from the host, then check the status of the containers by running kubectl get pods. There should be one or more sas-viya-<service> pods, depending on your software order. It may take several minutes to see a login screen, even with all pods showing a "Running" status. You may also need to correct the host name on your Ingress Controller and check your Kubernetes configurations.

SAS Logon Screen

For more info see the GitHub Project Wiki Page.




Copyright

Copyright 2018 SAS Institute Inc.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.