HowTo:CS Launch

2025-02-07T13:31:21Z

Bbradner: Added secondary examples about the discovery ingress as students are skipping the note at the top about the difference between the endeavour and discovery ingress formats

== 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: <code>test-project</code>
* You add additional project members now or later after the project is created
* '''Click on the ''Create'' button'''
[[Image:Project_create.png]]

== 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: <code>test-namespace</code> 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'''
[[Image:Create_namespace.png]]

== 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 <code>bitnami</code>
** Fill in '''Index URL''' with <code>https://charts.bitnami.com/bitnami</code>
** '''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''':
<pre>
auth:
database: test-db
username: test
password: Insecure
primary:
persistence:
size: 1Gi
</pre>
* '''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 <code>mariadb</code>

== 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: <code>test-adminer</code> The name must following DNS naming rules.
* '''Fill in ''Container Image''''' with the value <code>adminer:latest</code> 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 <code>tcp8080</code> under ''Networking''.
** '''Fill in ''Private Container Port''''' with <code>8080</code>. 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 <code>ADMINER_DEFAULT_SERVER</code>
*** '''Fill in ''Value'' with the value <code>mariadb</code>'''
* 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: <code>test-ingress</code> The name must follow DNS naming rules.
* '''Fill in ''Request Host''''' with the hostname of the URL you want to map to. Example: <code>testdb.endeavour.cs.vt.edu</code> The Endeavour cluster on CS Launch allows you to map any *.endeavour.cs.vt.edu hostname to your ingress. Example 2: <code>testdb.discovery.cs.vt.edu</code> The Discovery cluster on CS Launch allows you to map any *.discovery.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 <code>/</code> 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: <code>test-adminer</code>
* '''Select <code>8080</code> 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 <code>mariadb</code>
* 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: <code>test-regstry</code>
** '''Fill in the ''Registry Domain Name''''' field with the hostname of your Docker registry. Example: <code>container.cs.vt.edu</code>
** '''Fill in the ''Username'' field''' with the ''Name'' from when you created your access token. Example: <code>test-chatbot</code>
** '''Fill in the ''Password'' field''' with the ''contents of your access token'' Example: <code>glpat-FqgNwpWtZJT-sfapguRv</code>
** '''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: <code>test-config</code>
* '''Click on ''Binary Data''''' on the left.
* '''Fill in the ''Key'' field''' with the value <code>config.php</code>
* '''File in the ''Value'' field''' with contents:
<pre>
<?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());
}
</pre>
* '''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: <code>dbconfig</code>
* '''Select ''ConfigMap'' from the ''Add Volume'' drop down list'''.
* '''Select your custom ConfigMap from the ''ConfigMap'' drop down list'''. Example: <code>test-config</code>
* '''Click on the ''container-0'' tab'''.
* '''Fill in the ''Name'' field''' with a project unique name. The name must following DNS naming rules. Example: <code>test-chatbot</code>
* '''Fill in the ''Container Image'' field''' with your personal Docker image URL. Example: <code>container.cs.vt.edu/carnold/chatbot:latest</code>
* '''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: <code>http</code>
* '''Fill in the ''Private Container Port'' field''' under ''Networking'' with the value: <code>80</code>
* '''Click on the ''Storage''''' under the ''container-0'' tab.
* '''Select your pod volume from the ''Select Volume'' drop down list'''. Example: <code>dbconfig</code>
* '''Fill in ''Mount Point''''' with the value: <code>/var/www/html/dbconfig</code>
* '''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: <code>chatbot-ingress</code> The name must follow DNS naming rules.
* '''Fill in ''Request Host''''' with the hostname of the URL you want to map to. Example: <code>chatbot.endeavour.cs.vt.edu</code> The Endeavour cluster on CS Launch allows you to map any *.endeavour.cs.vt.edu hostname to your ingress. Example 2: <code>chatbot.discovery.cs.vt.edu</code> The Discovery cluster on CS Launch allows you to map any *.discovery.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 <code>/</code> 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: <code>test-chatbot</code>
* '''Select <code>80</code> 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]]

Contact Techstaff

2024-12-06T18:59:00Z

Bbradner: Updated Office Locations from KW II

== techstaff@cs.vt.edu ==

* The quickest and easiest way to contact us is through email to [mailto:techstaff@cs.vt.edu techstaff@cs.vt.edu]

== Individually ==

* '''Rich Charles (Technical lead)'''
** 4309 A Gilbert Place
** [mailto:rich08@cs.vt.edu rich08@cs.vt.edu]
** (540) 231-7227

* '''Mike Thompson (Desktop Support)'''
** 4309 Gilbert Place
** [mailto:miket@vt.edu miket@vt.edu]
**(540) 231-3167

* '''Chris Arnold (Dept/Teaching Resources)'''
** 4309 Gilbert Place
** [mailto:carnold@cs.vt.edu carnold@cs.vt.edu]
** (540) 231-5464

* '''Rob Hunter (Research Resources)'''
** 4309 Gilbert Place
** [mailto:rhunter@vt.edu rhunter@vt.edu]
** (540) 231-6470

* '''Ben Stein (DevOps)'''
** 4309 Gilbert Place
** [mailto:bbradner@vt.edu bbradner@vt.edu]
** (540) 231-0048

* '''Michael Davis (Inventory/Supplies)'''
** 4309 Gilbert Place
** [mailto:michd91@vt.edu michd91@vt.edu]
** (540) 231-7618

Poster Printing

2023-12-04T19:58:43Z

Bbradner: Told users to email their poster to us, so it can get printed

As a provided service the techstaff will print posters for departmental use at no charge.

'''NOTE: This service requires the approval of your professor.'''
==Specifications==
'''Paper Size:''' 24", 36" 42"
<br>As long as one of the edges of the poster shares a common length with these three paper sizes, the poster can be printed without any scaling or margins.

'''File Type:''' PDF & PPT

'''Lead Time:''' 24 Hours
<br>Your poster may be finished before this time but for best results the sooner you can have the finished poster to the techstaff the better. Printer issues and other projects may cause a delay.

'''How to Submit a Poster for Printing:'''
<br>Email techstaff@cs.vt.edu with your preferred paper size dimensions, the date you need the poster by, and attach your poster file (if sharing a google drive link or similar ensure anyone with a link can access).

'''Where & when can I pick up my poster?'''
<br> The TechStaff offices are located on the 4th floor of Gilbert place (Suite 4309). Your poster will be left in the hallway outside of our suite when completed. The building is open to the public between 8am-5pm, Monday - Friday. After 5pm building access requires authenticated Hokie passports.

Computer Science Wiki - User contributions [en]

HowTo:CS Launch

Contact Techstaff

Poster Printing