asbisen / sas-container-recipes

A collection of recipes and other resources for building containers that include SAS Viya software.

SAS^® Viya^® Container Recipes

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

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](http://support.sas.com/rnd/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 or git clone [e-mail]: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.

   c. For either single or multiple containers, addons found in the addons/ directory can enhance the base SAS Viya images with SAS/ACCESS, LDAP configuration, and more. For each addon, review the Appendix for important information and any possible prerequisite requirements.

---

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 Image

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"

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 massively parallel processing (MPP) 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 or Mac 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 run step but not required for the build step.
• Strongly recommended: A local mirror of the SAS software. Here's why.

Build Examples

Examples of running build.sh to build multiple containers are provided below. A non-root user is recommended for all build commands.

Example: Programming-Only Deployment, Mulitple Containers

  ./build.sh \
  --type multiple \
  --zip /path/to/SAS_Viya_deployment_data.zip \
  --docker-registry-namespace myuniquename \
  --docker-registry-url myregistry.myhost.com \
  --virtual-host user-myproject.mylocal.com \
  --addons "addons/auth-demo"

Example: Full Deployment, Multiple Containers

  ./build.sh \
  --type full \
  --zip /path/to/SAS_Viya_deployment_data.zip \
  --docker-registry-namespace myuniquename \
  --docker-registry-url myregistry.myhost.com \
  --virtual-host user-myproject.mylocal.com \
  --addons "addons/auth-sssd"

build.sh Arguments

# Required Arguments

  --type [multiple | full]
    sets the deployment type.
    multiple: SAS Viya programming-only deployment, multiple containers using Kubernetes
    full: SAS Viya full deployment, multiple containers using Kubernetes.

  --zip <value>
    specifies the path to the SAS_Viya_deployment_data.zip file, which is from your Software Order Email (SOE).
    Example: /my/path/to/SAS_Viya_deployment_data.zip
    
  --docker-registry-namespace <value>
    specifies the namespace in the Docker registry where the Docker images will be pushed. 
    Use a unique name to prevent collisions.
    Example: myuniquename

  --docker-registry-url <value>
    specifies the URL of the Docker registry where Docker the images will be pushed.
    Required for Kubernetes.
    Examples: 10.12.13.14:5000 or myregistry.myhost.com                  

# Optional Arguments 

  --virtual-host
    specifies the Kubernetes Ingress path that defines the location of the HTTP endpoint.
    For details about Ingress, see the official Kubernetes documentation at 
    https://kubernetes.io/docs/concepts/services-networking/ingress/.
    Example: user-myproject.mylocal.com

  --addons "[<value>] [<value>]"
    adds one or more software layers to the main SAS image.
    For more information about addons, see 'Appendix: Under the Hood' in the wiki at 
    https://github.com/sassoftware/sas-container-recipes/wiki/Appendix:-Under-the-Hood
    Example: --addons \"addons/auth-sssd addons/access-postgres\"

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

  --basetag <value>
    specifies the Docker tag for the base image that is being used.
    Default: latest

  --mirror-url <value>
    specifies 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

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

  --skip-docker-url-validation
    skips validating the Docker registry URL.

  --skip-mirror-url-validation
    skips validating the mirror URL from the --mirror-url flag.

  --sas-docker-tag
    specifies 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

Running Multiple Containers

The build process creates Kubernetes manifests that you use to run multiple containers.

• For a SAS Viya programming-only deployment, the Kubernetes manifests are located at $PWD/viya-programming/viya-multi-container/working/manifests
• For a SAS Viya full deployment, the Kubernetes manifests are located at $PWD/viya-visuals/working/manifests

For information about using the manifests, see Build and Run SAS Viya Multiple Containers.

Log on to SAS Studio

After the containers are running, users can sign on to SAS Studio.

• If you deployed a programming-only environment, then your environment contains SAS Studio 4.4.
• If you deployed a full environment, then your environment contains both SAS Studio 4.4 and SAS Studio 5.1. By default, you will log on to SAS Studio 5.1.

Here are some examples of how to log on:

• For SAS Studio 4.4 via Docker run without TLS:

  https://docker-host:8081/SASStudio

• For SAS Studio 4.4 via Kubernetes:

  https://ingress-path/SASStudio

• For SAS Studio 5.1:

  https://ingress-path/SASStudioV

---

Additional Resources

• Wiki: Documentation
• Issues: Questions and Project Improvements
• Kubernetes Documentation
• Docker Documentation
• SAS License Assistance
• SAS Software Purchase
• SAS Software Trial

---

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.