Computer Science Wiki - User contributions [en]

CS Launch MariaDB

2025-10-28T13:02:55Z

Carnold:

== Introduction ==
Instructions for deploying a simple MariaDB database service on CS Launch using Docker official images: https://hub.docker.com/u/library

== Create Project and Namespace ==
You will need a project and namespace on CS Launch to deploy your database. See [[HowTo:CS_Launch]] for instructions on doing this.

== Create Persistence Storage ==
Your database will need a Persistent Volume Claim to store the data so that it is not lost between restarts.

* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Storage''''' from the menu on the left
* '''Click on ''PersistentVolumeClaims''''' underneath ''Storage''
* '''Click on the ''Create'' button'''
* Fill in '''Name''' with a namespace unique name, example: <code>mariadb-pvc</code>
* Change '''Request Storage''' to the size of your storage requirements, example: <code>1 GiB</code>
* '''Click on the ''Create'' button'''

== Create Passwords Secret ==
A secret is a secure way to store your deployments password information.

* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Storage''''' from the menu on the left
* '''Click on ''Secrets''''' underneath ''Storage''
* '''Click on the ''Create'' button'''
* '''Select the ''Opaque'' tile''' as this type of secret is suited for storing passwords
* Fill in '''Name''' with namespace unique name, example: <code>mariadb-secret</code>
* Fill in '''Key''' with <code>MARIADB_ROOT_PASSWORD</code>
* Fill in '''Value''' with what you want to use as the root password, for example: <code>ChangeMe</code>
* Fill in additional '''Keys''':
** <code>MARIADB_DATABASE</code> = <code>test-db</code>
** <code>MARIADB_USER</code> = <code>test</code>
** <code>MARIADB_PASSWORD</code> = <code>Insecure</code>
* '''Click on the ''Create'' button'''
[[File:launch-mariadb-secret.png]]

== Create Custom Configurations ==
You can use a ConfigMap to storage custom configuration options.
* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Storage''''' from the menu on the left
* '''Click on ''ConfigMaps''''' underneath ''Storage''
* '''Click on the ''Create'' button'''
* Fill in '''Name''' with namespace unique name, example: <code>mariadb-config</code>
* Fill in '''Key''' with <code>my.cnf</code>
* Fill in '''Value''' with your custom configuration options:
<pre>
[mariadb]
### Put custom mariadb configurations here
</pre>
* '''Click on the ''Create'' button'''
[[File:launch-mariadb-config.png]]

== Create the Deployment ==
Now you have all the components created, you can create the deployment itself. We will create it as a "Deployment" to make it easier. You can create as a StatefulSet to get a consistent pod name, but it is more work set up initially.
* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Workloads''''' from the menu on the left
* '''Click on ''Deployments''''' underneath ''Workloads''
* '''Click on the ''Create'' button'''
* Fill in '''Name''' with the hostname you want other workloads to access the service by, example: <code>mariadb</code>
* Fill in '''Container Image''' with the version of mariadb docker image you want, example: <code>mariadb:lts</code> or use a specific version that you want
* Click on '''Add Port or Service''' button
* Select <code>Cluster IP</code> from the '''Service Type''' drop down list
* Fill in service '''Name''' with a port name example: <code>mariadb</code>
* Fill in '''Private Container Port''' with the database port: <code>3306</code>
* Click on '''Add Variable''' under '''Environment Variables'''
* Select <code>Secret</code> from the '''Type''' drop down list
* Select <code>mariadb-secret</code> from the '''Secret''' drop down list
[[File:launch-mariadb-deployment.png]]
* Click on the '''Deployment''' tab
* Click on '''Scaling and Upgrade Policy''' under the '''Deployment''' tab
* Select '''Recreate: kill ALL pods, then start new pods''' checkbox
** This tells the cluster to remove pods before restarting because multiple pods can not mount the PVC
[[File:launch-mariadb-upgrade.png]]
* Click on the '''Pod''' tab
* Click on '''Storage''' under the '''Pod''' tab
* Select '''ConfigMap''' from the '''Add Volume''' drop down list
* Change '''VolumeName''' to <code>configuration</code>
* Select <code>mariadb-config</code> under the '''ConfigMap''' drop down list
* Select '''Persistent Volume Claim''' from the '''Add Volume''' drop down list
* Change '''VolumeName''' to <code>data</code>
* Select <code>mariadb-pvc</code> from the '''Persistent Volume Claim''' drop down list
[[File:launch-mariadb-storage.png]]
* Click on '''container-0''' tab
* Click on '''Storage''' under the '''container-0''' tab
* Select <code>configuration</code> from the '''Select Volume''' drop down list
* Fill in '''Mount Point''' with <code>/etc/mysql/conf.d</code>
* Select <code>data</code> from the '''Select Volume''' drop down list
* Fill in '''Mount Point''' with <code>/var/lib/mysql</code>
[[File:launch-mariadb-mount.png]]
* Click on '''Health Check''' under the '''container-0''' tab
* Select '''Command run inside the container exits with status 0''' from the '''Type''' drop down list under '''Readiness Check'''
* Change '''Initial Delay''' to <code>30 Sec.</code>
* Change '''Timeout''' to <code>5 Sec.</code>
* Fill in '''Command to run''' with <code>bash -c 'healthcheck.sh --connect --innodb_initialized'</code>
* Select '''Command run inside the container exists with status 0''' from the '''Type''' drop down list under '''Liveness Check'''
* Change '''Initial Delay''' to <code>120 Sec.</code>
* Change '''Timeout''' to <code>5 Sec.</code>
* Fill in '''Command to run''' with <code>bash -c 'healthcheck.sh --connect --innodb_initialized'</code>
* Select '''Command run inside the container exists with status 0''' from the '''Type''' drop down list under '''Startup Check'''
* Change '''Initial Delay''' to <code>10 Sec.</code>
* Change '''Timeout''' to <code>5 Sec.</code>
* Fill in '''Command to run''' with <code>bash -c 'healthcheck.sh --connect --innodb_initialized'</code>
* Change '''Failure Threshold''' to <code>30</code>
[[File:launch-mariadb-health.png]]
* Finally, click on the '''Create''' button to start your deployment

== Updates ==
Version updates to your manual deployment will have to be made manually. If you use the '''lts''' tag <code>mariadb:lts</code> then anytime the pod is restarted then the newest version of the long term support image is pulled and ran. If you a specific a version number tag, then you will need to manually change the version number to update.

== Accessing ==
* By design, access to your database workload is limited to the internal network between your other workloads
* You can access the database through the command prompt on the running database pod
* You can create another workload with a database client installed
* You can use a web based database client and create an ingress to access it from external hosts. See: [[HowTo:CS_Launch#Launch_an_App_Using_a_Public_Image]]

HowTo:CS Stash

2025-10-14T14:55:06Z

Carnold: /* Introduction */

== Introduction ==
CS Stash is a shared departmental storage system designed for sharing files to Linux based servers and workstations. The service is based on Ceph, and more specifically CephFS: https://docs.ceph.com/en/reef/cephfs/ The goal of the service is to provide fault tolerant, secure, high-speed file sharing to Linux machines in the department.

== How it Works ==
The service uses CephFS to share files primarily to Linux based hosts. It works like an NFS share in that it allows multiple hosts to mount R/W at the same time. File permissions also work similar to NFS or a locally mounted file system on the host.

== Creating an Allocation ==
All allocations are created by Techstaff. [[Contact Techstaff]] to make your request for storage space.

== Ansible Script ==
The techstaff have provided an ansible script to install and setup your central storage allocation at: https://version.cs.vt.edu/techstaff/ansible/-/tree/main/roles/csCentralStorage

You can also install manually following the instructions below.

== Installing Ceph Client ==
To mount your allocation, you will need to install the ceph client, if it is not already installed. You will need root level access to install ceph. See: https://docs.ceph.com/en/latest/install/ for more details and the latest information on installing ceph. Here are some brief instructions, using the <code>cephadm</code> tool that should work on any supported Linux system (Redhat, Rocky, CentOS, Ubuntu, Debian, Alma, Etc.).

* Download the cephadm tool
** <code>curl --silent --remote-name --location https://download.ceph.com/rpm-reef/el9/noarch/cephadm</code>
* Make the tool executable
** <code>chmod +x cephadm</code>
* Install the ''reef'' ceph repo ('''Note:''' Older OSs might have to go down the ''quincy'' release, for example Rocky Linux 8)
** <code>sudo ./cephadm add-repo --release reef</code>
* Install the ceph client
** <code>sudo ./cephadm install ceph-common</code>

== Mounting Your Allocation ==
When your allocation is created, you will be given the following information needed to mount your filesystem:
* <username>
* <secret_key>
* <path>
You need to save the contents of the <secret_key> into a file, and secure the file. For example, in the file <code>/etc/.<username>.secret</code> with chmod mode 0600.

You can have the filesystem automatically mounted on boot by adding an entry to your <code>/etc/fstab</code> file, substitute your information as needed. You can optionally mount a sub-path of your top level path.
* <code><username>@.cephfs=<path>[/<sub-path] <mount_location> ceph mon_addr=stash.cs.vt.edu:3300,secretfile=<path_to_secret_file>,_netdev,noatime,rbytes,ms_mode=secure 0 0</code>

Now you can mount the storage immediately, run <code>sudo mount <mount_location></code>
* You may get notices about files in your /etc/ceph directory, but they can be ignored.

== Mounting Your Allocation on CS Launch ==
[[Contact Techstaff]] to have your storage allocation added to your [[HowTo:CS_Launch|CS Launch]] project. This has the advantage of being R/W from multiple containers on CS Launch versus the built-in CS Launch storage.

== Security ==
* Your <secret_key> should be kept secret, anyone with access to the <username> and <secret_key> can mount, and have full access to your filesystem
* The CephFS mount works like a locally mounted POSIX filesystem with ACLs enabled. You can change file ownership and permissions like you would a local filesystem.
* All data is stored encrypted at rest
* If you use the "ms_mode=secure" mount option, then the data will also be encrypted on wire. This is the recommended option.

== Resizing ==
Your storage allocation can be resized quickly and easily without the need to unmount and remount the share. A resize will be need to done by [[Contact Techstaff|Techstaff]]

== Quotas ==
CephFS supports quotas. You can set a specific quota on any individual directory that effects that directory and any sub-directories. For full details, see: https://docs.ceph.com/en/latest/cephfs/quota/
Here is a quick example of setting a 1GB quota on a directory of your mount:
* <code>setfattr -n ceph.quota.max_bytes -v $(numfmt --from=iec 1G) /mnt/ceph/test</code>

The command uses the value as bytes. The ''numfmt'' command is just a convenient way to convert larger values into bytes.

== Performance ==
My benchmarks test show that performance from a 1Gbit network connection is about equivalent to a single local spindle drive. Performance from a 10Gbit network connection is much greater than a single local spindle drive.

== Backups ==
Techstaff currently does not do any automatic backups of the data on the CS Stash service.
* The service is fault tolerant to hardware failures
* CephFS offers snapshot support that can help mitigate data loss due to accidental deletion. See: https://docs.ceph.com/en/reef/dev/cephfs-snapshots/ for more details.
* Here is a brief example of creating a snapshot of a subdirectory in your allocation:
<pre>
user@localhost:/# cd /mnt/ceph/test
user@localhost:/mnt/ceph/test# echo "Version 1" > version.txt
user@localhost:/mnt/ceph/test# cd .snap
user@localhost:/mnt/ceph/test/.snap# mkdir my_snapshot
user@localhost:/mnt/ceph/test/.snap# cd ..
user@localhost:/mnt/ceph/test# echo "Version 2" > version.txt
user@localhost:/mnt/ceph/test# cat version.txt
Version 2
user@localhost:/mnt/ceph/test# cat .snap/my_snapshot/version.txt
Version 1
user@localhost:/mnt/ceph/test#
</pre>
* Here is a very simple bash script that would keep a one week rolling list of snaphots for a directory
<pre>
#!/bin/bash

DIR=/mnt/ceph/test
NAME=$(date +%A)

rmdir "$DIR/.snap/$NAME"
mkdir "$DIR/.snap/$NAME"
</pre>
* If off-site backup is a priority, then an outside solution will need to be implemented

== Benchmarking ==
* I used the program '''fio''' to benchmark
** ''small io'' Options: <code>fio --randrepeat=1 --ioengine=libaio --direct=1 --gtod_reduce=1 --name=test --bs=4k --iodepth=64 --readwrite=randrw --rwmixread=75 --size=4G --filename=/mnt/ceph/testfile</code>
*** This creates a 4 GB file. It performs 4 KB reads and writes using a 75%/25% split in the file, with 64 operations running at a time.
** ''large_io'' Options: <code>fio --randrepeat=1 --ioengine=libaio --direct=1 --gtod_reduce=1 --name=test --bs=1M --iodepth=8 --readwrite=randrw --rwmixread=75 --size=4G --filename=/mnt/ceph/testfile</code>

=== Reference ===
* Results from running on a local spindle disk with xfs filesystem
** ''small io'' results:
*** Read: 618 IOPs, 2.5 MB/s
*** Write: 204 IOPs, 819 KB/s
** ''large io'' results:
*** Read: 94 IOPs, 94.7 MB/s
*** Write: 32 IOPs, 32.6 MB/s
* Results from running on a local SSD disk with xfs filesystem
** ''small io'' results:
*** Read: 32.8k IOPs, 128 MB/s
*** Write: 11k IOPs, 42.9 MB/s
** ''large io'' results:
*** Read: 142 IOPs, 142 MB/s
*** Write: 49 IOPs, 49.0 MB/s
* '''Conclusion''' on reference: SSD drive outperforms a spindle drive on small IO operations. Actual read and write speeds are similar.

=== From 1 gigabit networking connection ===
* ''small io'' results '''no encryption on wire''':
** Read: 1912 IOPs, 7.7 MB/s
** Write: 639 IOPs, 2.6 MB/s
* ''large io'' results '''no encryption on wire''':
** Read: 91 IOPs, 91.5 MB/s
** Write: 31 IOPs, 31.5 MB/s
* ''small io'' results '''encrypted on wire''':
** Read: 1929 IOPs, 7.7 MB/s
** Write: 644 IOPs, 2.6 MB/s
* ''large io'' results '''encrypted on wire''':
** Read: 91 IOPs, 91.5 MB/s
** Write: 31 IOPs, 33.1 MB/s
* '''Conclusion''': Faster than a local spindle drive for small IO operations and almost identical performance to a local spindle drive for large IO and is network speed limited. Encryption on wire seemed to make very little difference in performance.

=== From 10 gigabit networking connection ===
* ''small io'' results '''no encryption on wire''':
** Read: 1958 IOPs, 7.8 MB/s
** Write: 654 IOPs, 2.6 MB/s
* ''large io'' results '''no encryption on wire''':
** Read: 358 IOPs, 376 MB/s
** Write: 123 IOPs, 130 MB/s
* ''small io'' results '''encrypted on wire''':
** Read: 2168 IOPs, 8.7 MB/s
** Write: 724 IOPs, 2.9 MB/s
* ''large io'' results '''encrypted on wire''':
** Read: 321 IOPs, 337 MB/s
** Write: 110 IOPs, 111 MB/s
* '''Conclusion''': No real change in performance for small IO operations from 1gig connection, but huge gain in large IO operations. Encrypted was actually faster for small IO operations, not sure why it could be that it is forcing the use of v2 protocol instead of v1.

CS Launch MariaDB

2025-10-02T17:50:21Z

Carnold:

HowTo:CS Launch

2025-10-02T17:47:58Z

Carnold: /* Launching a Database Using Helm */

== Video Demo ==
Link to a CS Launch demo created by Computer Science TA Wyatt Sweat: https://www.youtube.com/watch?v=BNmQfneAEzc&ab_channel=WyattSweat

== Introduction ==
This is a quick start guide for using the CS Launch (formerly CS cloud) 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]]

== Creating a Secret ==
Kubernetes uses secrets to store sensitive information, such as passwords, in a secure manner.
* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Storage''''' from the menu on the left
* '''Click on ''Secrets''''' underneath ''Storage''
* '''Click on the ''Create'' button'''
* '''Select the ''Opaque'' tile''' as this type of secret is suited for storing passwords
* Fill in '''Name''' with <code>my-secret</code>
* Fill in '''Key''' with <code>my-pass</code>
* Fill in '''Value''' with what you want to use as the password, for example: <code>ChangeMe</code>
* '''Click on the ''Create'' button'''

== Launching a Database Using Helm ==

'''UPDATE:''' These instructions used to show how to deploy an App using the Bitnami helm charts. Bitnami is now a paid product, so I have updated these instructions to use the groundhog2k helm charts which are currently community based. See our separate wiki page on Bitnami to see the old instructions and tips on migrating existing Bitnami deployments: [[CS Launch Bitnami]]

'''Alternative''' You can also choose to deploy a database manually using an official docker image, see [[CS_Launch_MariaDB]]

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 Groundhog2k.
* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Apps''''' from the menu on the left
* '''Click on ''Charts''''' underneath ''Apps''
* We need to find the MariaDB chart
** Make sure to '''select ''groundhog2k'' '''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
* Fill in '''Name''' with <code>mariadb</code> or a unique hostname you want to give your database
* '''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>
settings:
# bug in chart requires this for now:
allowEmptyRootPassword: true
rootPassword:
value: 'ChangeMe'
storage:
requestedSize: 1Gi
keepPvc: true
userDatabase:
name:
value: 'test-db'
user:
value: 'test'
password:
value: 'Insecure'
</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]]

File:Launch-mariadb-config.png

2025-10-02T17:46:03Z

Carnold:

File:Launch-mariadb-secret.png

2025-10-02T17:45:47Z

Carnold:

CS Launch MariaDB

2025-10-02T17:45:02Z

Carnold:

CS Launch MariaDB

2025-10-02T17:40:22Z

2025-10-02T17:23:28Z

Carnold: Created page with "== Introduction == Instructions for deploying a simple MariaDB database service on CS Launch using Docker official images: https://hub.docker.com/u/library == Create Project and Namespace == You will need a project and namespace on CS Launch to deploy your database. See HowTo:CS_Launch for instructions on doing this. == Create Persistence Storage == Your database will need a Persistent Volume Claim to store the data so that it is not lost between restarts. * Navi..."

CS Launch Bitnami

2025-10-02T16:27:38Z

Carnold:

== Introduction ==
We used to support an encourage users to use the Bitnami helm charts for installing CS Launch Apps. However, they have moved to a paid service so it is no longer feasible for us to use them. Currently, we suggest to use either:
* Manual deployment of Docker official images: https://hub.docker.com/u/library
** Example deployment: [[CS Launch MariaDB]]
* Groundhog2k helm charts (based on the Docker official images): https://github.com/groundhog2k/helm-charts
** Example deployment: [[HowTo:CS_Launch#Launching_a_Database_Using_Helm]]

== Migration Strategies ==
If you have an existing Bitnami deployment that you need to keep active, then here are some strategies to keep your deployment working.

=== Legacy Bitnami ===
The Bitnami crew are moving their images to a legacy repository. Support for this is likely to be short term, and updates are unlikely.
* You should be able to immediately switch your <code>bitnami...</code> images definitions to <code>bitnamilegacy...</code> to continue working

=== Full Replacement ===
Probably the best solution is to completely replace your Bitnami deployment to either a manual deployment of the Official Docker image or groundhog2k chart deployment. This would involve the following steps:
* Backup all current data and configurations
* Delete Bitnami deployment
* Deploy new instance using an currently supported method
* Import the backup data

=== In-Place Replacement ===
This method may require more work and intimate knowledge of how the deployment works. The idea is to replace the existing Bitnami docker image with an official docker image that is maintained. Some things to consider when trying this method:
* Make sure to make a backup of all data and configurations before attempting
* You will likely have to re-map existing configurations and secrets
* Data mounts might be different between the two images
* Make sure the application version is close to the same
* Future updates will have to be done manually instead of through the helm chart

== Detailed Migration ==
We might provide more details instructions for popular deployments such as MariaDB, if needed.

== Instructions Archive ==
Here is a copy of the old instructions using Bitnami for archive purposes. These instructions will no longer be supported.

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
* '''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
* Fill in '''Name''' with <code>mariadb</code> or a unique hostname you want to give your database
* '''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>

HowTo:CS Launch

2025-10-02T14:45:04Z

Carnold: /* Launching a Database Using Helm */

== Video Demo ==
Link to a CS Launch demo created by Computer Science TA Wyatt Sweat: https://www.youtube.com/watch?v=BNmQfneAEzc&ab_channel=WyattSweat

== Introduction ==
This is a quick start guide for using the CS Launch (formerly CS cloud) 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]]

== Creating a Secret ==
Kubernetes uses secrets to store sensitive information, such as passwords, in a secure manner.
* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Storage''''' from the menu on the left
* '''Click on ''Secrets''''' underneath ''Storage''
* '''Click on the ''Create'' button'''
* '''Select the ''Opaque'' tile''' as this type of secret is suited for storing passwords
* Fill in '''Name''' with <code>my-secret</code>
* Fill in '''Key''' with <code>my-pass</code>
* Fill in '''Value''' with what you want to use as the password, for example: <code>ChangeMe</code>
* '''Click on the ''Create'' button'''

== Launching a Database Using Helm ==

'''UPDATE:''' These instructions used to show how to deploy an App using the Bitnami helm charts. Bitnami is now a paid product, so I have updated these instructions to use the groundhog2k helm charts which are currently community based. See our separate wiki page on Bitnami to see the old instructions and tips on migrating existing Bitnami deployments: [[CS Launch Bitnami]]

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 Groundhog2k.
* Navigate to your '''Cluster Dashboard'''
* '''Click on ''Apps''''' from the menu on the left
* '''Click on ''Charts''''' underneath ''Apps''
* We need to find the MariaDB chart
** Make sure to '''select ''groundhog2k'' '''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
* Fill in '''Name''' with <code>mariadb</code> or a unique hostname you want to give your database
* '''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>
settings:
# bug in chart requires this for now:
allowEmptyRootPassword: true
rootPassword:
value: 'ChangeMe'
storage:
requestedSize: 1Gi
keepPvc: true
userDatabase:
name:
value: 'test-db'
user:
value: 'test'
password:
value: 'Insecure'
</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]]

CS Launch Bitnami

2025-10-02T14:17:56Z

Carnold:

== Introduction ==
We used to support an encourage users to use the Bitnami helm charts for installing CS Launch Apps. However, they have moved to a paid service so it is no longer feasible for us to use them. Currently, we suggest to use either:
* Manual deployment of Docker official images: https://hub.docker.com/u/library
* Groundhog2k helm charts (based on the Docker official images): https://github.com/groundhog2k/helm-charts

== Migration Strategies ==
If you have an existing Bitnami deployment that you need to keep active, then here are some strategies to keep your deployment working.

=== Legacy Bitnami ===
The Bitnami crew are moving their images to a legacy repository. Support for this is likely to be short term, and updates are unlikely.
* You should be able to immediately switch your <code>bitnami...</code> images definitions to <code>bitnamilegacy...</code> to continue working

=== Full Replacement ===
Probably the best solution is to completely replace your Bitnami deployment to either a manual deployment of the Official Docker image or groundhog2k chart deployment. This would involve the following steps:
* Backup all current data and configurations
* Delete Bitnami deployment
* Deploy new instance using an currently supported method
* Import the backup data

=== In-Place Replacement ===
This method may require more work and intimate knowledge of how the deployment works. The idea is to replace the existing Bitnami docker image with an official docker image that is maintained. Some things to consider when trying this method:
* Make sure to make a backup of all data and configurations before attempting
* You will likely have to re-map existing configurations and secrets
* Data mounts might be different between the two images
* Make sure the application version is close to the same
* Future updates will have to be done manually instead of through the helm chart

== Detailed Migration ==
We might provide more details instructions for popular deployments such as MariaDB, if needed.

== Instructions Archive ==
Here is a copy of the old instructions using Bitnami for archive purposes. These instructions will no longer be supported.

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
* '''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
* Fill in '''Name''' with <code>mariadb</code> or a unique hostname you want to give your database
* '''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>

CS Launch Bitnami

2025-10-02T14:09:39Z

Carnold:

== Introduction ==
We used to support an encourage users to use the Bitnami helm charts for installing CS Launch Apps. However, they have moved to a paid service so it is no longer feasible for us to use them. Currently, we suggest to use either:
* Manual deployment of Docker official images: https://hub.docker.com/u/library
* Groundhog2k helm charts (based on the Docker official images): https://github.com/groundhog2k/helm-charts

== Migration Strategies ==
If you have an existing Bitnami deployment that you need to keep active, then here are some strategies to keep your deployment working.

=== Legacy Bitnami ===
The Bitnami crew are moving their images to a legacy repository. Support for this is likely to be short term, and updates are unlikely.
* You should be able to immediately switch your <code>bitnami...</code> images definitions to <code>bitnamilegacy...</code> to continue working

=== Full Replacement ===
Probably the best solution is to completely replace your Bitnami deployment to either a manual deployment of the Official Docker image or groundhog2k chart deployment. This would involve the following steps:
* Backup all current data and configurations
* Delete Bitnami deployment
* Deploy new instance using an currently supported method
* Import the backup data

=== In-Place Replacement ===
This method may require more work and intimate knowledge of how the deployment works. The idea is to replace the existing Bitnami docker image with an official docker image that is maintained. Some things to consider when trying this method:
* Make sure to make a backup of all data and configurations before attempting
* You will likely have to re-map existing configurations and secrets
* Data mounts might be different between the two images

== Detailed Migration ==
We might provide more details instructions for popular deployments such as MariaDB, if needed.

== Instructions Archive ==
Here is a copy of the old instructions using Bitnami for archive purposes. These instructions will no longer be supported.

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
* '''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
* Fill in '''Name''' with <code>mariadb</code> or a unique hostname you want to give your database
* '''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>

2024-10-23T11:37:26Z

Carnold: /* Use a Token to Access Registry */

== Introduction ==
This guide will walk you through creating a git repository which gives you a docker registry to host docker images, build a docker image, and push the image up to the registry. The image will be based on the official PHP docker image https://hub.docker.com/_/php , and a copy of ''Chatbot for College Students'' app installed https://github.com/AaravRajSIngh/Chatbot You will need access to workstation that has Docker installed. You can SSH to rlogin.cs.vt.edu and build docker images there. This example compliments the CS Launch walkthrough at [[HowTo:CS Launch]] which will walk you through hosting this docker image using Computer Science kubernetes cluster.

== Create Repository ==
Computer offers two Gitlab instances: https://git.cs.vt.edu and https://version.cs.vt.edu git.cs.vt.edu is geared toward academic use, and version.cs.vt.edu is for departmental or research use. We will use git.cs.vt.edu for this example.
* '''Log into https://git.cs.vt.edu''' using your CS username and password.
* '''Click on ''Projects''''' from the menu on the left.
* '''Click on the ''New Project'' button'''.
* '''Click on the ''Create blank project'' tile'''.
* '''Fill in ''Project name'' field''' with a unique name for your docker image project. Example: <code>chatbot</code>
* '''Fill in ''Project URL'' fields''' with your own sub path and project slug.
* '''Select ''Visibility Level''''' If your project is ''public'' then anyone on the Internet will be able to download and use your docker image given the correct URL. If your project is ''Private'' or ''Internal'' then to use your docker image you need to create and use a deployment token which will be discussed further in this walk through.
* '''Click on the ''Create project'' button'''.
* A docker image registry is automatically created with your git repository.
* '''Check your docker registry''':
** '''Select ''Deploy->Container Registry'' from the menu on the left
** '''Take note''' of the example docker commands it gives, this contains your '''Docker registry URL'''. Example: <code>container.cs.vt.edu/carnold/chatbot</code>
* Adding files to this git repository is optional, however you might find it a useful place to store versioned copies of your Docker image creation files.

== Create Docker Image ==
* '''SSH to rlogin.cs.vt.edu''' See [[Howto::Access_rlogin_service]] Alternatively, you can use any workstation that has Docker installed.
* '''Optional:''' Clone your git repository.
** Example: <code>git clone https://git.cs.vt.edu/carnold/chatbot.git</code>
** Change into the directory <code>cd chatbot</code>
* '''Use a text editor to create a new file called <code>Dockerfile</code>'''
** Example: <code>nano Dockerfile</code>
** Contents:
<pre>
# Start from Apache based PHP image
FROM php:apache

# Make sure git command is installed
RUN apt-get update && \
apt-get install vim git -y

# Install additional PHP modules
RUN docker-php-ext-install mysqli pdo pdo_mysql

# Download chatbot app
RUN cd /var/www/html && \
git clone https://github.com/AaravRajSIngh/Chatbot.git . && \
chmod 600 .git && \
cp -f homepage.php index.php
</pre>
* Build the docker image and give it a tag for easy identification.
** Example: <code>docker build . -t test-chatbot</code>
* If successful, your image will be built and store locally but is not yet accessible from your registry.
* '''Optional:''' You can run your docker image locally to make sure it works
** Example: <code>docker run -it test-chatbot /bin/bash</code>
* '''Optional:''' Commit and push your Dockerfile up to the git repository.
** Example: <code>git add --all</code>
** Example: <code>git commit -m init</code>
** Example: <code>git push origin main</code>

== Push Docker Image to Registry ==
At this point you should have a built and working docker image that is stored locally. You will need to push the image up to your docker registry to be able to access it from other hosts or clusters.
* '''Log into your docker registry using the docker command''' You need to give the docker command the hostname of the registry. If you are using https://git.cs.vt.edu then the hostname is <code>container.cs.vt.edu</code> If you are using https://version.cs.vt.edu then the hostname is <code>docker.cs.vt.edu</code>
** Example: <code>docker login container.cs.vt.edu</code>
* '''Tag your docker image''' with your ''Docker Registry URL'' from earlier.
** Example: <code>docker tag test-chatbot container.cs.vt.edu/carnold/chatbot</code>
* '''Push the image''' to your ''Docker Registry URL''
** Example: <code>docker push container.cs.vt.edu/carnold/chatbot</code>
** You can use ''tags'' to store multiple versions of your docker image by adding a <code>:<tag></code> to the end of your Docker Registry URL. Example: <code>container.cs.vt.edu/carnold/chatbot:latest</code>
* If successful, your docker image should be uploaded and ready to deploy.

== Use a Token to Access Registry ==
If your git repository that hosts your Docker Registry is set to ''Internal'' or ''Private'' visibility, then you will need to create and use a deployment token to download the images.
* '''Navigate to your git repository website''' such as https://git.cs.vt.edu/carnold/chatbot
* '''Select ''Settings -> Access Tokens''''' from the menu on the left.
* '''Click on the ''Add new token'' button'''
* '''Fill in ''Token name''''' with a unique name for your access token. '''Take note of the name''' that you give this token, as it will be used as the username in kubernetes. Example: <code>test-chatbot</code>
* '''Check the box for ''read_registry'''''
* '''Click on the ''Create project access token'' button'''
* It will display the contents of your access token, '''make a copy of the content''' as you will need to paste it into a secret resource in the kubernetes cluster.
* Refer to [[HowTo:CS_Launch#Create_a_Custom_Web_Application]] on how to import this token into kubernetes for hosting your docker images.