HowTo:CS Launch

Introduction

This is a quick start guide for using the CS Launch website and kubernetes resources. It will walk you through setting up a basic website with database support. There is a separate guide that describes how to do all these steps using a command line terminal at HowTo:CS Launch Terminal

Clusters

The https://launch.cs.vt.edu site manages multiple clusters. Here is a list of clusters available for use by Computer Science members:

Endeavour
- This cluster is meant for long term teaching projects, and specialty projects that require GPU resources.
- Creation of projects on this cluster is limited to CS Faculty and Staff.
- Projects can be shared with any CS member, including students.
- Ingress: *.endeavour.cs.vt.edu
Discovery
- This cluster is meant for general teaching projects.
- Creation of projects on this cluster is limited to CS Faculty, Staff, graduate students, and CS majors.
- Projects can be shared with any VT member with a CS account, including non-CS students.
- Ingress: *.discovery.cs.vt.edu
- Ingresses on this cluster are limited to campus and VPN IPs by default, but can be opened further using annotations. See: CS Launch Ingress

Create a New Project

Access to CS Launch is made through projects. A project is a collection of kubernetes namespaces and resources. You can have access to multiple projects. Projects can be shared with other CS members.

Go to CS Launch website: https://launch.cs.vt.edu
Click the login button to use your CS username and password to log in
The main screen will show a list of kubernetes clusters you have access to, if the list is blank then you don't have access to any clusters
Click on the cluster name where you want to create the new project
This is your Cluster Dashboard
From the menu on the left Click on Projects/Namespaces
Click on the Create Project button
Fill in the Name field with a cluster unique name for your project Example: test-project
You add additional project members now or later after the project is created
Click on the Create button

Create a New Namespace

Kubernetes uses namespaces to separate resources. The CS Launch resources groups namespaces into projects for access control. A project can contain multiple namespaces. At least one namespace is required before resources can be created in a project. To access a namespace you must be a member of the project the namespace is associated with. A namespace can only be associated with a single project.

Navigate to the list of projects
- Click on Projects/Namespaces from the cluster dashboard
Click on the Create Namespace button that is associated with the project you want to assign the namespace to
Fill in the Name field with a cluster unique name. Example: test-namespace The namespace name can be the same as the project name as long as it follows the naming rules and is not already in use. Kubernetes namespace names must following DNS name rules: https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names
Click on the Create button

Launching a Database Using Helm

Kubernetes supports Helm charts to automate deployment of software. There are existing Helm charts for many popular software projects, such as databases. Using a Helm chart can make setting up and updating complex software much easier. This guide will walk you through deploying MariaDB using a Helm chart from Bitnami.

Navigate to your Cluster Dashboard
Click on Apps from the menu on the left
We need to add the helm chart repository:
- Click on Repositories underneath Apps
- Click on the Create button
- Fill in Name with bitnami
- Fill in Index URL with https://charts.bitnami.com/bitnami
- Click on the Create button
Click on Charts underneath Apps
We need to find the MariaDB chart
- Make sure to select Bitnami in the first drop down list
- Select Database from the catagories drop down list
- Click on the MariaDB tile
Click on the Install button
Select the namespace from the drop down list where you want the database deployed to
Click on the Next button
You will be presented with a long list of options and their default values in yaml format
For our example, change the following options:

auth:
  database: test-db
  username: test
  password: Insecure
primary:
  persistence:
    size: 1Gi

Click on the Install button
It will take a minute or two for the deployment to complete. The site will give you a window to watch the progress, and report any errors that might occur.
You should now have a running database, but no real way to access it yet
Other pods in the same namespace will be able to connect to this database using the hostname mariadb

Launch an App Using a Public Image

Next we will launch a web app called Adminer that will allow us to interact with our running database, and assign it a URL.

Navigate to your Cluster Dashboard.
Click on Workloads from the menu on the left.
Click on the Create button.
Select the Deployment tile as this type of deployment is best suited for our Adminer web app.
Make sure to select the same namespace as the database.
Fill in Name with a project unique name. Example: test-adminer The name must following DNS naming rules.
Fill in Container Image with the value adminer:latest This is a path to a docker image, and it resolves to the latest image from the adminer project on https://docker.io.
We need to tell kubernetes how this deployment will interact with the network by giving it a cluster IP.
- Click on the Add Port or Service button under Networking.
- Select ClusterIP under the Service Type drop down list
- Fill in Name with tcp8080 under Networking.
- Fill in Private Container Port with 8080. TCP port 8080 is the port that the Adminer web app listens to.
Many public docker images use environment variables to effect how the deployment runs. Adminer has several environment variables you can set. For our example, we will set some default values for convenience.
- Click on Add Variable under Environment Variables.
  - Fill in Variable Name with the value ADMINER_DEFAULT_SERVER
  - Fill in Value with the value mariadb
The rest of the options can be left on their default settings.
Click on the Create button.
The web app will start running, but we won't have a way to access it until we map a URL to the container, this is called an ingress in kubernetes.

Create Ingress to a Workload

Creating an ingress in kubernetes allows you to map an external URL to your running container so it can be accessed from anywhere on the Internet.

Navigate to your Cluster Dashboard.
Click on Service Discovery from the menu on the left.
Click on Ingresses from the sub-menu on the left.
Click on the Create button.
Make sure to select the same namespace as the web app.
Fill in Name with a project unique name. Example: test-ingress The name must follow DNS naming rules.
Fill in Request Host with the hostname of the URL you want to map to. Example: testdb.endeavour.cs.vt.edu The Endeavour cluster on CS Launch allows you to map any *.endeavour.cs.vt.edu hostname to your ingress. Additionally, a TLS certificate is used to automatically encrypt your ingress traffic.
Fill in Path with Prefix value of / Using / will map the top level path, and all sub-paths of the URL to this deployment. You can create multiple sub-paths to the same hostname to different deployments allowing you to flesh out a URL running as multiple containers. Example: mapping /api/* to a deployment that runs the backend of your website.
Select your application deployment from the Target Service drop down list. Example: test-adminer
Select 8080 from the Port drop down list.
Click on the Create button.
Once created you should have a working URL to your web application, and a link on the Ingresses tabs.
For our example, you should be able to go to the URL and login using the password set earlier in the database deployment. Server name is mariadb
See CS Launch Ingress for additional information about CS Launch Ingresses

Create a Custom Web Application

You can do more than just launch pre-built docker images on CS Launch. You can create your own custom docker images allowing you to host just about any kind of app on kubernetes. This will walk you through an example of that process.

Build your custom docker image Refer to HowTo:Docker for an example of building and hosting your own custom docker image.
Optional: If your docker image is not public, then you will need to import an access token to be able to download and use your custom docker image.
- Refer to HowTo:Docker#Use_a_Token_to_Access_Registry to create an access token for your registry.
- Copy the contents of your access token
- Navigate to your Cluster Dashboard
- Click on Storage from the menu on the left.
- Click on Secrets from the sub-menu on the left.
- Click on the Create button.
- Make sure to select the same namespace as the web app.
- Select the Registry tile.
- Fill in the Name field with a project unique name. Example: test-regstry
- Fill in the Registry Domain Name field with the hostname of your Docker registry. Example: container.cs.vt.edu
- Fill in the Username field with the Name from when you created your access token. Example: test-chatbot
- Fill in the Password field with the contents of your access token Example: glpat-FqgNwpWtZJT-sfapguRv
- Click on the Create button.

Create a ConfigMap

Kubernetes has a special storage option called a ConfigMap. ConfigMaps can be used to create custom config files that can be directly mounted into the Docker image to localize your deployment. For example, use a ConfigMap to create a database configuration file instead of embedding that config inside of the docker image itself. For this example, we will create a config.php ConfigMap file and mount it under the /var/www/html/dbconfig directory inside the running container.

Navigate to your Cluster Dashboard.
Click on Storage from the menu on the left.
Click on ConfigMaps from the sub-menu on the left.
Click on the Create button.
Make sure to select the same namespace as the web app.
Fill in the Name field with a project unique name. The name must following DNS naming rules. Example: test-config
Click on Binary Data on the left.
Fill in the Key field with the value config.php
File in the Value field with contents:

<?php
declare(strict_types=1);

define("HOST", "mariadb");
define("DB_NAME", "test-db");
define("DB_USER", "test");
define("PASS", "Insecure");

$host = HOST;
$db_name = DB_NAME;

$dsn = "mysql:host=$host;dbname=$db_name";

try {
	$db = new PDO ($dsn, DB_USER, PASS);
	$db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
} catch (PDOException $e) {
	throw new PDOException($e->getMessage());
}

Click on the Create button.

Create Database Tables

Most dynamic web apps will require a database to be created before use. For our example, you need to import a SQL dump to create tables and data.

Navigate to your Adminer Ingress URL
Log in using your database credentials
Download the database dump from https://raw.githubusercontent.com/AaravRajSIngh/Chatbot/main/database.sql
Click on the Import button to the left.
Click on the Browse... button and locate the downloaded sql dump.
Click on the Execute button.

Launch a Custom Application using a ConfigMap

We are ready to launch the custom built web app.

Navigate to your Cluster Dashboard.
Click on Workloads from the menu on the left.
Click on the Create button.
Click on the Deployment tile.
Make sure to select the same namespace as the database.
Click on the Pod tab.
Click on the Storage menu under the Pod tab.
Fill in the Volume Name field with a pod unique name. Example: dbconfig
Select ConfigMap from the Add Volume drop down list.
Select your custom ConfigMap from the ConfigMap drop down list. Example: test-config
Click on the container-0 tab.
Fill in the Name field with a project unique name. The name must following DNS naming rules. Example: test-chatbot
Fill in the Container Image field with your personal Docker image URL. Example: container.cs.vt.edu/carnold/chatbot:latest
Click on the Add Port or Service button.
Select ClusterIP from the Service Type drop down list
Fill in the Name field under Networking with the value: http
Fill in the Private Container Port field under Networking with the value: 80
Click on the Storage under the container-0 tab.
Select your pod volume from the Select Volume drop down list. Example: dbconfig
Fill in Mount Point with the value: /var/www/html/dbconfig
Click on the Create button.

Create an Ingress to a Custom Application

We need to create another ingress to access this new web application.

Navigate to your Cluster Dashboard.
Click on Service Discovery from the menu on the left.
Click on Ingresses from the sub-menu on the left.
Click on the Create button.
Make sure to select the same namespace as the web app.
Fill in Name with a project unique name. Example: chatbot-ingress The name must follow DNS naming rules.
Fill in Request Host with the hostname of the URL you want to map to. Example: chatbot.endeavour.cs.vt.edu The Endeavour cluster on CS Launch allows you to map any *.endeavour.cs.vt.edu hostname to your ingress. Additionally, a TLS certificate is used to automatically encrypt your ingress traffic.
Fill in Path with Prefix value of / Using / will map the top level path, and all sub-paths of the URL to this deployment. You can create multiple sub-paths to the same hostname to different deployments allowing you to flesh out a URL running as multiple containers. Example: mapping /api/* to a deployment that runs the backend of your website.
Select your application deployment from the Target Service drop down list. Example: test-chatbot
Select 80 from the Port drop down list.
Click on the Create button.
Once created you should have a working URL to your web application, and a link on the Ingresses tabs.

Notes on Storage

Persistent volumes (PVs) can be used for storage on your workloads
PVs can be created on demand using the default storage class
The default storage class PVs can only be mounted on a single pod at a time
If you need larger storage (> 1TB) or read/write from multiple pods, then consider using the CS central storage service: HowTo:CS_Stash

Advanced

Using GPU enabled containers on Endeavour cluster see HowTo:CS_Launch_GPU

HowTo:CS Launch

Contents

Introduction

Clusters

Create a New Project

Create a New Namespace

Launching a Database Using Helm

Launch an App Using a Public Image

Create Ingress to a Workload

Create a Custom Web Application

Create a ConfigMap

Create Database Tables

Launch a Custom Application using a ConfigMap

Create an Ingress to a Custom Application

Notes on Storage

Advanced

Navigation menu

HowTo:CS Launch

Introduction

Clusters

Create a New Project

Create a New Namespace

Launching a Database Using Helm

Launch an App Using a Public Image

Create Ingress to a Workload

Create a Custom Web Application

Create a ConfigMap

Create Database Tables

Launch a Custom Application using a ConfigMap

Create an Ingress to a Custom Application

Notes on Storage

Advanced

Navigation menu

Search