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. The first half showing using the web interface, and the second half shows how to do it through a command line interface.

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. The default kubernetes cluster Endeavour only allows Faculty and Staff to create projects. After a Faculty member creates a project, it can be shared with CS students.

• 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
• 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. 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.

• 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 Partners 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

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
• 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());
}