Cloud Quickstart

CS Cloud Quickstart Guide

This guide will give you an introduction to using the Computer Science cloud, instructions on starting a simple kubernetes pod, basic networking concepts, and how to use storage. We will show how to do things both in the web user interface and through command line access.

Introduction

The CS cloud is a container-as-a-service resource. It allows you to run Docker based containers on our hardware. Containers allow you to encapsulate your application with all it's needed dependencies and allows the containerized application to run just about anywhere. The CS cloud is based on Kubernetes cluster which is a open-source container orchestration system. We also use Rancher as a UI and proxy interface.

Accessing the Cloud

You access the CS cloud through https://cloud.cs.vt.edu By default, all users get access to the "testing" cluster. This cluster is available for users to play with kubernetes, develop their containerized applications, and Techstaff to test updates to the system. Critical services should not be run on this cluster, we will have other clusters available to actually run containerized user services. You can also use the Rancher UI to control your own kubernetes cluster(s) allowing you to share your personal cluster with others in the department. This can even work behind a private network.

API/Command line access

You can also access the CS cloud via a command line tool called kubectl.

• Install the kubectl binary on your machine https://kubernetes.io/docs/tasks/tools/install-kubectl/
• You will need a config file to tell kubectl how to connect to the CS cloud, download this file from the Web interface
• Log into https://cloud.cs.vt.edu
• Select the cluster you want to access from the top left menu
• Click on the Cluster menu item at the top, if you are not already there
• Click on the Kubeconfig File button
• You can either download the file or copy and paste the content into your kubectl config file (normally ~/.kube/config on Linux)
• You can also directly access kubectl command line directly from the web interface! Just click on the Launch kubectl button.

Creating a Project

When you first log into https://cloud.cs.vt.edu it will show you the clusters you have access to. Normally, this will only be the testing cluster. Also, you won't have any Projects unless someone has shared a Project with you. To get started, you will need to create a Project and a Namespace inside that project:

The Project will need to be created through the web interface.

• Select testing cluster by either clicking the name in the list, or selecting it from the top left menu (Global -> Cluster: testing).

• Select Projects/Namespaces on the top menu
• Click on the Add Project button to create a Project
• Project Name is the only required field, this is set at the cluster scope so the name can conflict with other users' project names. I suggest pre-appending your username to the project name, for example: mypid-project1
• After you create your project, it will take you to a screen that will allow you to add a namespace to your project.
• Namespaces allow you to group Pods and other resources together, this namespace translates to the Kubernetes namespace so again the names can conflict with other users. Example namespace name: mypid-project1-db for grouping all of project1's database pods together.
• Click on the Add Namespace button to create a Namespace
• Name is the only field needed
• Click on the Project's title or use the top left menu to select your new Project. This will take you to the Project's page.
• At this point you are ready to start a Pod

Starting a Deployment

Kubernetes groups containers into a Pod. A Pod can be thought of roughly as a single machine with a single IP on the Kubernetes network. Each container running in a Pod can communicate with each other via localhost. The simplest Pod is just a single container, which is what we will show you here. A Deployment is a kubernetes term for a Pod resource that can automatically scale out. For our example, we will only be starting a single Pod.

Example: Ubuntu shell

In this example, we will show how to start up a Ubuntu container and access it via a shell prompt.

Via Web Interface

• From the Your Project page, click on the "Deploy" button
• Give your deployment a Name, this name is unique to the Namespace
• Namespace should be automatically selected to the one you created earlier
• Docker Image can be any valid Docker URL, for this example: ubuntu:xenial
• You can leave the other options on the defaults for now, and click on Launch
• It will take a moment for the system to deploy your Workload, and it will give you a progress indicator that will turn solid green when ready.
• Click on the ... menu icon far right of your Workload to access the menu

• Select Execute Shell to get an in-browser command line shell into your Ubuntu container
• From here, you can run commands like you would on a Ubuntu machine

Via Command Line

• This example, assumes you have already installed and configured the kubectl command
• You can create and update resources in Kubernetes using manifests, manifests are text files that describe the resource and are in YAML format
• Here is an example manifest to create a simple deployment, in this case a single Ubuntu container. You will need to personalize metadata/namespace

apiVersion: v1
kind: Pod
metadata:
  name: ubuntu-shell
  namespace: peong-project1-web
  labels:
    app: ubuntu-shell
spec:
  containers:
  - name: ubuntu
    image: ubuntu:xenial

• Save this file as ubuntu-shell.yml
• Apply the manifest by running kubectl apply -f ubuntu-shell.yml
• You will need to wait for the Deployment to be ready, you can check the status by running kubectl get deployment -n <namespace>
• Once your deployment is ready, you can get a shell by running kubectl exec -it

Networking

Storage