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