Wallaroo Community Install Guides

• 1: Wallaroo Community Simple Install Guide
• 2: Wallaroo Community GitHub Codespaces Install Guide
• 3: Wallaroo Community Comprehensive Install Guide

1 - Wallaroo Community Simple Install Guide

The following guide details how to set up Wallaroo Community in a prepared environment. For a comprehensive guide for the entire process including sample scripts for setting up a cloud environment, see the Wallaroo Community Comprehensive Install Guide

Install Wallaroo Community

Wallaroo Community can be installed into a Kubernetes cloud environment, or into a Kubernetes environment that meets the Wallaroo Prerequisites Guide. Organizations that use the Wallaroo Community AWS EC2 Setup procedure do not have to set up a Kubernetes environment, as it is already configured for them.

This video demonstrates that procedure:

The procedure assumes at least a basic knowledge of Kubernetes and how to use the kubectl and kots version 1.91.3 applications.

The procedure involves the following major steps:

• Install Wallaroo Community
  • Prerequisites
    • Local Software Requirements
  • Install Wallaroo
    • Initial Configuration and License Upload Procedure

Prerequisites

Local Software Requirements

Before starting, verify that all local system requirements are complete as detailed in the Wallaroo Community Local System Prerequisites guide:

• kubectl: This interfaces with the Kubernetes server created in the Wallaroo environment.
• For Kots based installs:
  • kots Version 1.91.3

• Cloud Kubernetes environment has been prepared.
• You have downloaded your Wallaroo Community License file.

Install Wallaroo

The environment is ready, the tools are installed - let’s install Wallaroo! The following will use kubectl and kots through the following procedure:

1. Install the Wallaroo Community Edition using kots install wallaroo/ce, specifying the namespace to install. For example, if wallaroo is the namespace, then the command is:

   kubectl kots install wallaroo/ce --namespace wallaroo
   

2. Wallaroo Community Edition will be downloaded and installed into your Kubernetes environment in the namespace specified. When prompted, set the default password for the Wallaroo environment. When complete, Wallaroo Community Edition will display the URL for the Admin Console, and how to end the Admin Console from running.

   • Deploying Admin Console
   • Creating namespace ✓
   • Waiting for datastore to be ready ✓
       Enter a new password to be used for the Admin Console: •••••••••••••
     • Waiting for Admin Console to be ready ✓
   
   • Press Ctrl+C to exit
   • Go to http://localhost:8800 to access the Admin Console
   

Wallaroo Community edition will continue to run until terminated. To relaunch in the future, use the following command:

kubectl-kots admin-console --namespace wallaroo

Initial Configuration and License Upload Procedure

Once Wallaroo Community edition has been installed for the first time, we can perform initial configuration and load our Wallaroo Community license file through the following process:

1. If Wallaroo Community Edition has not started, launch it with the following command:

   ❯ kubectl-kots admin-console --namespace wallaroo
     • Press Ctrl+C to exit
     • Go to http://localhost:8800 to access the Admin Console
   

2. Enter the Wallaroo Community Admin Console address into a browser. You will be prompted for the default password as set in the step above. Enter it and select Log in.

   

3. Upload your license file.

   

4. The Configure Wallaroo Community page will be displayed which allows you to customize your Wallaroo environment. For now, scroll to the bottom and select Continue. These settings can be customized at a later date.

5. The Wallaroo Community Admin Console will run the preflight checks to verify that all of the minimum requirements are not met. This may take a few minutes. If there are any issues, Wallaroo can still be launched but may not function properly. When ready, select Continue.

   

6. The Wallaroo Community Dashboard will be displayed. There may be additional background processes that are completing their setup procedures, so there may be a few minute wait until those are complete. If everything is ready, then the Wallaroo Dashboard will show a green Ready.

   

7. Under the license information is the DNS entry for your Wallaroo instance. This is where you and other users of your Wallaroo instance can log in. In this example, the URL will be https://beautiful-horse-9537.wallaroo.community. Note that it may take a few minutes for the DNS entries to propagate and this URL to be available.

   

8. You will receive an email invitation for the email address connected to this URL with a temporary password and a link to this Wallaroo instance’s URL. Either enter the URL for your Wallaroo instance or use the link in the email.

9. To login to your new Wallaroo instance, enter the email address and temporary password associated with the license.

   

With that, Wallaroo Community edition is launched and ready for use! You can end the Admin Console from your terminal session above. From this point on you can just use the Wallaroo instance URL.

2 - Wallaroo Community GitHub Codespaces Install Guide

The following details how to set up Wallaroo Community using GitHub Codespaces. This provides a quick method of setting up Wallaroo Community with just a few commands. You get the free license from the Wallaroo Community Portal site, and the rest of the process is handled by GitHub and Wallaroo.

Prerequisites

• GitHub Account: A GitHub account.
• GitHub Codespaces: Free for individual use for up to 60 hours a month to start withwith simple, pay-as-you-go pricing afterwards. See the GitHub Codespaces Cost Calculator for details on services costs.
• Wallaroo Community License: Available for free from the Wallaroo Community Portal page.

Installation Steps

1. From the Wallaroo Community Portal page, follow the registration instructions. If a Wallaroo Community license already exists for this account, enter the same name and email address to retrieve the registration link.

2. Download the Wallaroo Community license. This provides both the Wallaroo Community license in YAML format and the base64 encoded version. Store both in a secure location. The base64 ended version will be used in this process.

3. From the License Download page:

   1. Select Download license file. This provides two files: The YAML version of the license file, and an encoded base 64 version of the license file.
   2. Select Github Codespaces, then select Click to install Wallaroo in your GitHub Codespaces.

4. From the Create codespace GitHub page for Wallaroo Community, set the following:

   

   1. Dev container configuration: Set to Wallaroo Codespaces Data Science.
   2. Region: Select the region where the codespace will run. This should be the region geographically closest to the end user.
      1. Europe West
      2. Southeast Asia
      3. US West
      4. US East
   3. Machine Type: Set the number of CPUs to use. Leave as 16-cores - anything less the containers will not run.
   4. Wallaroo Community License: Provide the base64 version of the Wallaroo license here.

5. When complete, select Create Codespace. Wait until the process is complete - this usually takes about 15 minutes.

To see the installation process in action, use one of the following options:

• Enter either Control-Shift-P or Command-Shift-P (for MacOS systems) and select Codespaces: View Creation Log.
• Select from the lower left corner Codespaces and then View Creation Log.

Once the entry “Finished configuring codespace” is displayed, the Wallaroo Community installation is complete.

Wallaroo Community First Login

If this is your first login, you will receive an email invitation for the email address connected to this URL with a temporary password. Follow the link provided in the email. If not already logged into GitHub, a prompt will appear for you to login to GitHub to manage the port forwarding required to connect to the Wallaroo Community instance through your browser.

To login to your new Wallaroo instance, enter the email address and temporary password associated with the license. Enter a new password twice to set a new permanent password, and you will be logged into the Wallaroo Community instance.

Subsequent logins will are performed through the same URL.

Stopping and Starting Wallaroo Community

To start and stop the Wallaroo Community codespace:

• To stop the current Wallaroo Community codespace:
  • From the Wallaroo Community Codespace page, from the bottom left select Codespaces, then select the action Stop Current Codespace.
  • The other option is to press F1 and select Stop Current Codespace.
• To start a Wallaroo Community codespace:
  • Access your GitHub Codespaces page from GitHub by selecting your user profile icon in the upper right corner, then selecting My Codespaces.
  • From your GitHub Codespaces page, select your Wallaroo Community code space.
  • From the menu list on the right side, select Open In…, then Open in Browser to launch the Wallaroo Community Codespace page. This will launch the Wallaroo Community containers and make them available once they are done starting up.

See Setting your timeout period for GitHub Codespaces for information on timeout settings.

Additional GitHub Codespaces Options

Update the Wallaroo Community License

When Wallaroo Community is installed through GitHub Codespaces, the base64 hash of the Wallaroo license used in the installation process is stored in GitHub.

To update this license:

1. Select your GitHub user profile, then Settings.

2. Select Codespaces, then Codespaces secrets. The Wallaroo Community license is listed as WALLAROO_LICENSE. Use Update to update the license or Delete to remove if it is no longer needed.

   

Open Ports for Multiple Users

To provide for multiple users, the following ports must be set from private to public. This step is not required for users who will be the only one accessing Wallaroo Community though their codespace.

• keycloak: Port 8080, used for authentication to the Wallaroo service.
• hub: Port 8081, used for the JupyterHub service.
• dashboard: Port 8443, used for the Wallaroo Dashboard.

To update the network settings:

1. Access the Wallaroo Community codespace settings by entering either Control-Shift-P or Command-Shift-P (for MacOS systems) and select View: Toggle Terminal.
2. Right click keycloak, hub, and dashboard and set Port Visibility to Public.

3 - Wallaroo Community Comprehensive Install Guide

This guide is targeted towards system administrators and data scientists who want to work with the easiest, fastest, and free method of running your own machine learning models.

A typical installation of Wallaroo Community follows this process:

Register Your Wallaroo Community Account

The first step to installing Wallaroo CE is to set up your Wallaroo Community Account at the web site https://portal.wallaroo.community. This process typically takes about 5 minutes.

Once you’ve submitted your credentials, you’ll be sent an email with a link to your license file.

Follow the link and download your license file. Store it in a secure location.

Redownload License

If your license is misplaced or otherwise lost, it can be downloaded again later from the same link, or by following the registration steps again to be provided with a link to your license file.

Setup Environments

The following setup guides are used to set up the environment that will host the Wallaroo instance. Verify that the environment is prepared and meets the Wallaroo Prerequisites Guide.

• Environments:
• Amazon VM
• Amazon EKS
• Azure
• GCP

• Wallaroo Community AWS EC2 Setup Instructions

The following instructions are made to assist users set up their Amazon Web Services (AWS) environment for running Wallaroo using AWS virtual servers with EC2. This allows organizations to stand a single virtual machine and used a pre-made Amazon Machine Images (AMIs) to quickly stand up an environment that can be used to install Wallaroo.

• AWS Prerequisites

To install Wallaroo in your AWS environment based on these instructions, the following prerequisites must be met:

• Register an AWS account: https://aws.amazon.com/ and assign the proper permissions according to your organization’s needs. This must be a paid AWS account - Wallaroo will not operate on the free tier level of virtual machines.

• Steps

  • Create the EC2 VM

To create your Wallaroo instance using a pre-made AMI:

1. Log into AWS cloud console.

2. Set the region to N. Virginia. Other regions will be added over time.

   

3. Select Services -> EC2.

   

4. Select Instances, then from the upper right hand section Launch Instances->Launch Instances.

   

5. Set the Name and any additional tags.

6. In Application and OS Images, enter Wallaroo Install and press Enter.

7. From the search results, select Community AMIs and select Wallaroo Installer 3a.

   

8. Set the Instance Type as c6i.8xlarge or c6a.8xlarge as the minimum machine type. This provides 32 cores with 60 GB memory.

   

9. For Key pair (login) select one of the following:

   

   1. Select an existing Key pair name
   2. Select Create new key pair and set the following:
      1. Name: The name of the new key pair.
      2. Key pair type: Select either RSA or ED25519.
      3. Private key file format: Select either .pem or .ppk. These instructions are based on the .pem file.
      4. Select Create key pair when complete.

10. Set the following for Network settings:

    

    1. Firewall: Select Create security group or select from an existing one that best fits your organization.
    2. Allow SSH traffic from: Set to Enabled and Anywhere 0.0.0.0/0.
    3. Allow HTTPs traffic from the internet: Set to Enabled.

11. Set the following for Configure Storage:

    1. Set Root volume to at least 400 GiB, type standard.

12. Review the Summary and verify the following:

    1. Number of instances: 1
    2. Virtual server type: Matches the minimum requirement listed above.
    3. Verify the other settings are accurate.

13. Select Launch Instance.

It is recommended to give the instance time to complete its setup process. This typically takes 20 minutes.

• Verify the Setup

To verify the environment is setup for Wallaroo:

1. From the EC2 Dashboard, select the virtual machine created for your Wallaroo instance.

2. Note the Public IPv4 DNS address.

   

3. From a terminal, run ssh to connect to your virtual machine. The installation requires access to port 8800 and the private key selected or created in the instructions above.

   The ssh command format for connecting to your virtual machine uses the following format, replacing the $keyfile, $VM_DNS with your private key file and the DNS address to your Amazon VM:

   ssh -i "$keyfile" ubuntu@$VM_DNS -L8800:localhost:8800
   

   For example, a $keyfile of Doc Sample Key.pem and $VM_DNS of ec2-54-160-227-100.compute-1.amazonaws.com would be as follows:

   ssh -i "Doc Sample Key.pem" ubuntu@ec2-54-160-227-100.compute-1.amazonaws.com -L8800:localhost:8800
   

4. If the Kubernetes setup is still installing, wait until complete and when prompted select EXIT to complete the process. This process may take up to 20 to 30 minutes.

   

• Cost Saving Tips The following tips can be used to save costs on your AWS EC2 instance.
  • Stop Instances When Not In Use

One cost saving measure is to stop instances when not in use. If you intend to stop an instance, register it with static IP address so when it is turned back on your services will continue to function without interruption.

Reference: How do I associate a static public IP address with my EC2 Windows or Linux instance?.

• Troubleshooting
  • I keep seeing the errors such as connect failed. Is this a problem?
    • Sometimes you may see an error such as channel 3: open failed: connect failed: Connection refused. This is the ssh port forwarding attempting to connect to port 8800 during the installation, and can be ignored.
  • When Launching JupyterHub, I get a Server 500 error.

    • If you shut down and restart a Wallaroo instance in a new environment or change the IP address, some settings may not be updated. Run the following command to restart the deployment process and update the settings to match the current environment:

      kubectl rollout restart deployment hub
      

• Setup AWS EKS Environment for Wallaroo

The following instructions are made to assist users set up their Amazon Web Services (AWS) environment for running Wallaroo using AWS Elastic Kubernetes Service (EKS).

These represent a recommended setup, but can be modified to fit your specific needs.

If the prerequisites are already met, skip ahead to Install Wallaroo.

The following video demonstrates this process:

• AWS Prerequisites

To install Wallaroo in your AWS environment based on these instructions, the following prerequisites must be met:

• Register an AWS account: https://aws.amazon.com/ and assign the proper permissions according to your organization’s needs.
• The Kubernetes cluster must include the following minimum settings:
  • Nodes must be OS type Linux with using the containerd driver.
  • Role-based access control (RBAC) must be enabled.
  • Minimum of 4 nodes, each node with a minimum of 8 CPU cores and 16 GB RAM. 50 GB will be allocated per node for a total of 625 GB for the entire cluster.
  • RBAC is enabled.
  • Recommended Aws Machine type: c5.4xlarge. For more information, see the AWS Instance Types.
• Installed eksctl version 0.101.0 and above.
• If the cluster will utilize autoscaling, install the Cluster Autoscaler on AWS.

• AWS Cluster Recommendations

The following recommendations will assist in reducing the cost of a cloud based Kubernetes Wallaroo cluster.

• Turn off the cluster when not in use. An AWS EKS (Elastic Kubernetes Services) cluster can be turn off when not in use, then turned back on again when needed. If organizations adopt this process, be aware of the following issues:

  • IP Address Reassignment: The load balancer public IP address may be reassigned when the cluster is restarted by the cloud service unless a static IP address is assigned. For more information in Amazon Web Services see the Associate Elastic IP addresses with resources in your VPC user guide.

• Assign to a Single Availability Zone: Clusters that span multiple availability zones may have issues accessing persistent volumes that were provisioned in another availability zone from the node when the node is restarted. The simple solution is to assign the entire cluster into a single availability zone. For more information in Amazon Web Services see the Regions and Zones guide.

  The scripts and configuration files are set up to create the AWS environment for a Wallaroo instance are based on a single availability zone. Modify the script as required for your organization.

• Community Cluster Setup Instructions

The following is based on the requirements for Wallaroo Community. Note that Wallaroo Community does not use adaptive nodepools. Adapt the settings as required for your organization’s needs, as long as they meet the prerequisites listed above.

This sample YAML file can be downloaded from here:

wallaroo_community_aws_install.yaml

apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  # replace with the name of your server
  name: wallarooAWS
  # replace with your location
  region: us-east-1
  version: "1.25"

addons:
  - name: aws-ebs-csi-driver

iam:
  withOIDC: true

nodeGroups:
  - name: mainpool
    instanceType: m5.2xlarge
    desiredCapacity: 4
    containerRuntime: containerd
    amiFamily: AmazonLinux2
    availabilityZones:
      - us-east-1a

• Install AWS Command Line Tools

The following steps require the installation of the following Amazon Web Services command line tools:

• AWS CLI: Complete both the AWS Command Line Installation Guide and the AWS CLI Quick Setup Guide to authenticate to your AWS account.

• eksctl: A command line tool for managing Amazon EKS clusters from a configured YAML file. See the EKSCTL Install Guide for more details.

• kubectl: This interfaces with the Kubernetes server created in the Wallaroo environment.

• kots Version: Used to manage software installed in a Kubernetes environment.

• Create the Cluster

Create the cluster with the following command, which creates the environment and sets the correct Kubernetes version.

eksctl create cluster -f aws.yaml

During the process the Kuberntes credentials will be copied into the local environment. To verify the setup is complete, use the kubectl get nodes command to display the available nodes as in the following example:

kubectl get nodes

NAME                                           STATUS   ROLES    AGE     VERSION
ip-192-168-21-253.us-east-2.compute.internal   Ready    <none>   13m     v1.23.8-eks-9017834
ip-192-168-30-36.us-east-2.compute.internal    Ready    <none>   13m     v1.23.8-eks-9017834
ip-192-168-55-123.us-east-2.compute.internal   Ready    <none>   12m     v1.23.8-eks-9017834
ip-192-168-79-70.us-east-2.compute.internal    Ready    <none>   13m     v1.23.8-eks-9017834

• Setup Azure Environment for Wallaroo

The following instructions are made to assist users set up their Microsoft Azure Kubernetes environment for running Wallaroo Community. These represent a recommended setup, but can be modified to fit your specific needs.

If your prepared to install the environment now, skip to Setup Environment Steps.

There are two methods we’ve detailed here on how to setup your Kubernetes cloud environment in Azure:

• Quick Setup Script: Download a bash script to automatically set up the Azure environment through the Microsoft Azure command line interface az.
• Manual Setup Guide: A list of the az commands used to create the environment through manual commands.

The following video demonstrates the manual guide:

• Azure Prerequisites

To install Wallaroo in your Microsoft Azure environment, the following prerequisites must be met:

• Register a Microsoft Azure account: https://azure.microsoft.com/.
• Install the Microsoft Azure CLI and complete the Azure CLI Get Started Guide to connect your az application to your Microsoft Azure account.
• The Kubernetes cluster must include the following minimum settings:
  • Nodes must be OS type Linux the containerd driver as the default.
  • Role-based access control (RBAC) must be enabled.
  • Minimum of 4 nodes, each node with a minimum of 8 CPU cores and 16 GB RAM. 50 GB will be allocated per node for a total of 625 GB for the entire cluster.
  • RBAC is enabled.
  • Minimum machine type is set to to Standard_D8s_v4.

• Azure Cluster Recommendations

The following recommendations will assist in reducing the cost of a cloud based Kubernetes Wallaroo cluster.

• Turn off the cluster when not in use. An Azure Kubernetes Service (AKS) cluster can be turn off when not in use, then turned back on again when needed to save on costs. For more information on starting and stopping an AKS cluster, see the Stop and Start an Azure Kubernetes Service (AKS) cluster guide.

  If organizations adopt this process, be aware of the following issues:

  • IP Address Reassignment: The load balancer public IP address may be reassigned when the cluster is restarted by the cloud service unless a static IP address is assigned. For more information in Microsoft Azure see the Use a static public IP address and DNS label with the Azure Kubernetes Service (AKS) load balancer user guide.

• Assign to a Single Availability Zone: Clusters that span multiple availability zones may have issues accessing persistent volumes that were provisioned in another availability zone from the node when the cluster is restarted. The simple solution is to assign the entire cluster into a single availability zone. For more information in Microsoft Azure see the Create an Azure Kubernetes Service (AKS) cluster that uses availability zones guide.

  The scripts and configuration files are set up to create the Azure environment for a Wallaroo instance are based on a single availability zone. Modify the script as required for your organization.

• Setup Environment Steps

  • Standard Setup Variables

    The following variables are used in the Quick Setup Script and the Manual Setup Guide. Modify them as best fits your organization.

Variable Name	Default Value	Description
WALLAROO_RESOURCE_GROUP	wallaroocegroup	The Azure Resource Group used for the Kubernetes environment.
WALLAROO_GROUP_LOCATION	eastus	The region that the Kubernetes environment will be installed to.
WALLAROO_CONTAINER_REGISTRY	wallarooceacr	The Azure Container Registry used for the Kubernetes environment.
WALLAROO_CLUSTER	wallarooceaks	The name of the Kubernetes cluster that Wallaroo is installed to.
WALLAROO_SKU_TYPE	Base	The Azure Kubernetes Service SKU type.
WALLAROO_NODEPOOL	wallaroocepool	The main nodepool for the Kubernetes cluster.
WALLAROO_VM_SIZE	Standard_D8s_v4	The VM type used for the standard Wallaroo cluster nodes.
WALLAROO_CLUSTER_SIZE	4	The number of nodes in the cluster.

• Quick Setup Script

The following sample script creates an Azure Kubernetes environment ready for use with Wallaroo Community. This script requires the following prerequisites listed above.

Modify the installation file to fit for your organization. The only parts that require modification are the variables listed in the beginning as follows:

The following script is available for download: wallaroo_community_azure_install.bash

The following steps are geared towards a standard Linux or macOS system that supports the prerequisites listed above. Modify these steps based on your local environment.

1. Download the script above.

2. In a terminal window set the script status as execute with the command chmod +x wallaroo_community_azure_install.bash.

3. Modify the script variables listed above based on your requirements.

4. Run the script with either bash wallaroo_community_azure_install.bash or ./wallaroo_community_azure_install.bash from the same directory as the script.

   

• Manual Setup Guide

The following steps are guidelines to assist new users in setting up their Azure environment for Wallaroo. Feel free to replace these with commands with ones that match your needs.

See the Azure Command-Line Interface for full details on commands and settings.

The following are used for the example commands below. Replace them with your specific environment settings:

• Azure Resource Group: wallarooCEGroup
• Azure Resource Group Location: eastus
• Azure Container Registry: wallarooCEAcr
• Azure Kubernetes Cluster: wallarooCEAKS
• Azure Container SKU type: Base
• Azure Nodepool Name: wallarooCEPool

Setting up an Azure AKS environment is based on the Azure Kubernetes Service tutorial, streamlined to show the minimum steps in setting up your own Wallaroo environment in Azure.

This follows these major steps:

• Create an Azure Resource Group

• Create an Azure Container Registry

• Create the Azure Kubernetes Environment

• Set Variables

The following are the variables used in the environment setup process. Modify them as best fits your organization’s needs.

WALLAROO_RESOURCE_GROUP=wallaroocegroupdocs
WALLAROO_GROUP_LOCATION=eastus
WALLAROO_CONTAINER_REGISTRY=wallarooceacrdocs
WALLAROO_CLUSTER=wallarooceaksdocs
WALLAROO_SKU_TYPE=Base
WALLAROO_NODEPOOL=wallaroocepool
WALLAROO_VM_SIZE=Standard_D8s_v4
WALLAROO_CLUSTER_SIZE=4

• Create an Azure Resource Group

To create an Azure Resource Group for Wallaroo in Microsoft Azure, use the following template:

az group create --name $WALLAROO_RESOURCE_GROUP --location $WALLAROO_GROUP_LOCATION

(Optional): Set the default Resource Group to the one recently created. This allows other Azure commands to automatically select this group for commands such as az aks list, etc.

az configure --defaults group=$WALLAROO_RESOURCE_GROUP

• Create an Azure Container Registry

An Azure Container Registry(ACR) manages the container images for services includes Kubernetes. The template for setting up an Azure ACR that supports Wallaroo is the following:

az acr create -n $WALLAROO_CONTAINER_REGISTRY -g $WALLAROO_RESOURCE_GROUP --sku $WALLAROO_SKU_TYPE --location $WALLAROO_GROUP_LOCATION

• Create an Azure Kubernetes Services

And now we can create our Kubernetes service in Azure that will host our Wallaroo that meet the prerequisites. Modify the settings to meet your organization’s needs. This creates a 4 node cluster with a total of 32 cores.

az aks create \
--resource-group $WALLAROO_RESOURCE_GROUP \
--name $WALLAROO_CLUSTER \
--node-count $WALLAROO_CLUSTER_SIZE \
--generate-ssh-keys \
--vm-set-type VirtualMachineScaleSets \
--load-balancer-sku standard \
--node-vm-size $WALLAROO_VM_SIZE \
--nodepool-name $WALLAROO_NODEPOOL \
--nodepool-name mainpool \
--attach-acr $WALLAROO_CONTAINER_REGISTRY \
--kubernetes-version=1.23.8 \
--zones 1 \
--location $WALLAROO_GROUP_LOCATION

• Download Wallaroo Kubernetes Configuration

Once the Kubernetes environment is complete, associate it with the local Kubernetes configuration by importing the credentials through the following template command:

az aks get-credentials --resource-group $WALLAROO_RESOURCE_GROUP --name $WALLAROO_CLUSTER

Verify the cluster is available through the kubectl get nodes command.

kubectl get nodes

NAME                               STATUS   ROLES   AGE   VERSION
aks-mainpool-37402055-vmss000000   Ready    agent   81m   v1.23.8
aks-mainpool-37402055-vmss000001   Ready    agent   81m   v1.23.8
aks-mainpool-37402055-vmss000002   Ready    agent   81m   v1.23.8
aks-mainpool-37402055-vmss000003   Ready    agent   81m   v1.23.8

• Setup GCP Environment for Wallaroo

The following instructions are made to assist users set up their Google Cloud Platform (GCP) Kubernetes environment for running Wallaroo. These represent a recommended setup, but can be modified to fit your specific needs. In particular, these instructions will provision a GKE cluster with 32 CPUs in total. Please ensure that your project’s resource limits support that.

• Quick Setup Guide: Download a bash script to automatically set up the GCP environment through the Google Cloud Platform command line interface gcloud.
• Manual Setup Guide: A list of the gcloud commands used to create the environment through manual commands.

The following video demonstrates the manual guide:

• GCP Prerequisites

Organizations that wish to run Wallaroo in their Google Cloud Platform environment must complete the following prerequisites:

• Register a Google Cloud Account: https://cloud.google.com/
• Create a Google Cloud project: https://cloud.google.com/resource-manager/docs/creating-managing-projects
• Install gcloud and run gcloud init or gcloud init –console on the local system used to set up your environment: https://cloud.google.com/sdk/docs/install
• Enable the Google Compute Engine(GCE): https://cloud.google.com/endpoints/docs/openapi/enable-api
• Enable the Google Kubernetes Engine(GKE) on your project: https://console.cloud.google.com/apis/enableflow?apiid=container.googleapis.com
• Select a default Computer Engine region and zone: https://cloud.google.com/compute/docs/regions-zones.

• GCP Cluster Recommendations

The following recommendations will assist in reducing the cost of a cloud based Kubernetes Wallaroo cluster.

• Turn off the cluster when not in use. A GCP Google Kubernetes Engine (GKE) cluster can be turn off when not in use, then turned back on again when needed. If organizations adopt this process, be aware of the following issues:

  • IP Address Reassignment: The load balancer public IP address may be reassigned when the cluster is restarted by the cloud service unless a static IP address is assigned. For more information in Google Cloud Platform see the Configuring domain names with static IP addresses user guide.

• Assign to a Single Availability Zone: Clusters that span multiple availability zones may have issues accessing persistent volumes that were provisioned in another availability zone from the node when the cluster is restarted. The simple solution is to assign the entire cluster into a single availability zone. For more information in Google Cloud Platform see the Regions and zones guide.

  The scripts and configuration files are set up to create the GCP environment for a Wallaroo instance are based on a single availability zone. Modify the script as required for your organization.

• Standard Setup Variables

The following variables are used in the Quick Setup Script and the Manual Setup Guide. Modify them as best fits your organization.

Variable Name	Default Value	Description
WALLAROO_GCP_PROJECT	wallaroo-ce	The name of the Google Project used for the Wallaroo instance.
WALLAROO_CLUSTER	wallaroo-ce	The name of the Kubernetes cluster for the Wallaroo instance.
WALLAROO_GCP_REGION	us-central1	The region the Kubernetes environment is installed to. Update this to your GCP Computer Engine region.
WALLAROO_NODE_LOCATION	us-central1-f	The location the Kubernetes nodes are installed to. Update this to your GCP Compute Engine Zone.
WALLAROO_GCP_NETWORK_NAME	wallaroo-network	The Google network used with the Kubernetes environment.
WALLAROO_GCP_SUBNETWORK_NAME	wallaroo-subnet-1	The Google network subnet used with the Kubernetes environment.
WALLAROO_GCP_MACHINE_TYPE	e2-standard-8	Recommended VM size per GCP node.
WALLAROO_CLUSTER_SIZE	4	Number of nodes installed into the cluster. 4 nodes will create a 32 core cluster.

• Quick Setup Script

A sample script is available here, and creates a Google Kubernetes Engine cluster ready for use with Wallaroo Community. This script requires the prerequisites listed above, and uses the variables as listed in Standard Setup Variables.

The following script is available for download: wallaroo_community_gcp_install.bash

The following steps are geared towards a standard Linux or macOS system that supports the prerequisites listed above. Modify these steps based on your local environment.

1. Download the script above.

2. In a terminal window set the script status as execute with the command chmod +x bash wallaroo_community_gcp_install.bash.

3. Modify the script variables listed above based on your requirements.

4. Run the script with either bash wallaroo_community_gcp_install.bash or ./wallaroo_community_gcp_install.bash from the same directory as the script.

   

• Manual Setup Guide

The following steps are guidelines to assist new users in setting up their GCP environment for Wallaroo. Feel free to replace these with commands with ones that match your needs.

See the Google Cloud SDK for full details on commands and settings.

The commands below are set to meet the prerequisites listed above, and uses the variables as listed in Standard Setup Variables. Modify them as best fits your organization’s needs.

• Set Variables

The following are the variables used in the environment setup process. Modify them as best fits your organization’s needs.

WALLAROO_GCP_PROJECT=wallaroo-ce
WALLAROO_CLUSTER=wallaroo-ce
WALLAROO_GCP_REGION=us-central1
WALLAROO_NODE_LOCATION=us-central1-f
WALLAROO_GCP_NETWORK_NAME=wallaroo-network
WALLAROO_GCP_SUBNETWORK_NAME=wallaroo-subnet-1
WALLAROO_GCP_MACHINE_TYPE=e2-standard-8
WALLAROO_CLUSTER_SIZE=4

• Create a GCP Network

First create a GCP network that is used to connect to the cluster with the gcloud compute networks create command. For more information, see the gcloud compute networks create page.

gcloud compute networks \
create $WALLAROO_GCP_NETWORK_NAME \
--bgp-routing-mode regional \
--subnet-mode custom

Verify it’s creation by listing the GCP networks:

gcloud compute networks list

• Create the GCP Wallaroo Cluster

Once the network is created, the gcloud container clusters create command is used to create a cluster. For more information see the gcloud container clusters create page.

Note that three nodes are created by default, so one more is added with the --num-nodes setting to meet the Wallaroo prerequisites. For Google GKE, containerd is enabled by default and so does not need to be specified during the setup procedure: (https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd)[https://cloud.google.com/kubernetes-engine/docs/concepts/using-containerd].

gcloud container clusters \
create $WALLAROO_CLUSTER \
--region $WALLAROO_GCP_REGION \
--node-locations $WALLAROO_NODE_LOCATION \
--machine-type $WALLAROO_GCP_MACHINE_TYPE \
--num-nodes $WALLAROO_CLUSTER_SIZE \
--network $WALLAROO_GCP_NETWORK_NAME \
--create-subnetwork name=$WALLAROO_GCP_SUBNETWORK_NAME \
--enable-ip-alias \
--cluster-version=1.23

The command can take several minutes to complete based on the size and complexity of the clusters. Verify the process is complete with the clusters list command:

gcloud container clusters list

• Retrieving Kubernetes Credentials

Once the GCP cluster is complete, the Kubernetes credentials can be installed into the local administrative system with the the gcloud container clusters get-credentials (https://cloud.google.com/sdk/gcloud/reference/container/clusters/get-credentials) command:

gcloud container clusters \
get-credentials $WALLAROO_CLUSTER \
--region $WALLAROO_GCP_REGION

To verify the Kubernetes credentials for your cluster have been installed locally, use the kubectl get nodes command. This will display the nodes in the cluster as demonstrated below:

kubectl get nodes

NAME                                         STATUS   ROLES    AGE   VERSION
gke-wallaroo-ce-default-pool-863f02db-7xd4   Ready    <none>   39m   v1.21.6-gke.1503
gke-wallaroo-ce-default-pool-863f02db-8j2d   Ready    <none>   39m   v1.21.6-gke.1503
gke-wallaroo-ce-default-pool-863f02db-hn06   Ready    <none>   39m   v1.21.6-gke.1503
gke-wallaroo-ce-default-pool-3946eaca-4l3s   Ready    <none>   39m   v1.21.6-gke.1503

• Troubleshooting
  • What does the error ‘Insufficient project quota to satisfy request: resource “CPUS_ALL_REGIONS”’ mean?

Make sure that the Compute Engine Zone and Region are properly set based on your organization’s requirements. The instructions above default to us-central1, so change that zone to install your Wallaroo instance in the correct location.

In the case of the script, this would mean changing the region and location from:

WALLAROO_GCP_REGION=us-central1
WALLAROO_NODE_LOCATION=us-central1-f

WALLAROO_GCP_REGION={Your Region}
WALLAROO_NODE_LOCATION={Your Location}

Install Wallaroo Community

Wallaroo Community can be installed into a Kubernetes cloud environment, or into a Kubernetes environment that meets the Wallaroo Prerequisites Guide. Organizations that use the Wallaroo Community AWS EC2 Setup procedure do not have to set up a Kubernetes environment, as it is already configured for them.

If the prerequisites are already configured, jump to Install Wallaroo to start installing.

This video demonstrates that procedure:

The procedure assumes at least a basic knowledge of Kubernetes and how to use the kubectl and kots version 1.91.3 applications.

The procedure involves the following major steps:

• Prerequisites
• Download License File: This is detailed above in the process Register Your Wallaroo Community Account above.
• Install Wallaroo

Prerequisites

Local Software Requirements

Before starting, verify that all local system requirements are complete as detailed in the Wallaroo Community Local System Prerequisites guide:

• kubectl: This interfaces with the Kubernetes server created in the Wallaroo environment.
• For Kots based installs:
  • kots Version 1.91.3

• Cloud Kubernetes environment has been prepared.
• You have downloaded your Wallaroo Community License file.

Install Wallaroo

The environment is ready, the tools are installed - let’s install Wallaroo! The following will use kubectl and kots through the following procedure:

1. Install the Wallaroo Community Edition using kots install wallaroo/ce, specifying the namespace to install. For example, if wallaroo is the namespace, then the command is:

   kubectl kots install wallaroo/ce --namespace wallaroo
   

2. Wallaroo Community Edition will be downloaded and installed into your Kubernetes environment in the namespace specified. When prompted, set the default password for the Wallaroo environment. When complete, Wallaroo Community Edition will display the URL for the Admin Console, and how to end the Admin Console from running.

   • Deploying Admin Console
   • Creating namespace ✓
   • Waiting for datastore to be ready ✓
       Enter a new password to be used for the Admin Console: •••••••••••••
     • Waiting for Admin Console to be ready ✓
   
   • Press Ctrl+C to exit
   • Go to http://localhost:8800 to access the Admin Console
   

Wallaroo Community edition will continue to run until terminated. To relaunch in the future, use the following command:

kubectl-kots admin-console --namespace wallaroo

Initial Configuration and License Upload Procedure

Once Wallaroo Community edition has been installed for the first time, we can perform initial configuration and load our Wallaroo Community license file through the following process:

1. If Wallaroo Community Edition has not started, launch it with the following command:

   ❯ kubectl-kots admin-console --namespace wallaroo
     • Press Ctrl+C to exit
     • Go to http://localhost:8800 to access the Admin Console
   

2. Enter the Wallaroo Community Admin Console address into a browser. You will be prompted for the default password as set in the step above. Enter it and select Log in.

   

3. Upload your license file.

   

4. The Configure Wallaroo Community page will be displayed which allows you to customize your Wallaroo environment. For now, scroll to the bottom and select Continue. These settings can be customized at a later date.

5. The Wallaroo Community Admin Console will run the preflight checks to verify that all of the minimum requirements are not met. This may take a few minutes. If there are any issues, Wallaroo can still be launched but may not function properly. When ready, select Continue.

   

6. The Wallaroo Community Dashboard will be displayed. There may be additional background processes that are completing their setup procedures, so there may be a few minute wait until those are complete. If everything is ready, then the Wallaroo Dashboard will show a green Ready.

   

7. Under the license information is the DNS entry for your Wallaroo instance. This is where you and other users of your Wallaroo instance can log in. In this example, the URL will be https://beautiful-horse-9537.wallaroo.community. Note that it may take a few minutes for the DNS entries to propagate and this URL to be available.

   

8. You will receive an email invitation for the email address connected to this URL with a temporary password and a link to this Wallaroo instance’s URL. Either enter the URL for your Wallaroo instance or use the link in the email.

9. To login to your new Wallaroo instance, enter the email address and temporary password associated with the license.

   

With that, Wallaroo Community edition is launched and ready for use! You can end the Admin Console from your terminal session above. From this point on you can just use the Wallaroo instance URL.

Now that your Wallaroo Community edition has been installed, let’s work with some sample models to show off what you can do. Check out either the Wallaroo 101 if this is your first time using Wallaroo, or for more examples of how to use Wallaroo see the Wallaroo Tutorials.

Troubleshooting