Getting Started

Setting up your Account

Step 1: Creating your Nautilus Account

Go to the Nautilus Portal homepage and click logging in:

That will take you to this page, where you will select University of Missouri System:

This will then redirect you to the SSO for the University of Missouri, where you should enter your university-assigned pawprint and password.

Step 2: Requesting Namespace Access

Once you have created your Nautilus account by following the steps above, you need to request access to a namespace before you can start using the cluster. Namespaces are a mechanism in Kubernetes for creating groupings of containers and resources.

As of writing (Sep 10, 2022) the current practice is that each user will have their own namespace created and assigned, thus ensuring that your containers and data cannot be seen or deleted by other users of the cluster.

To request this be done for you (after you have created an account), send a message via Slack or Email to one of the admins, which at time of writing are Chenhan Zhao (czxrf@mail.missouri.edu), Anes Ouadou (aomqc@mail.missouri.edu), and Alex Hurt (jhurt@missouri.edu)

Step 3: Installing Kubernetes Command Line Tool

Now that you have requested access to a namespace in the cluster, you will need a command line tool to interact with the cluster.

Installing Locally

To install on a local machine where you have administrative access, go to the KubeCtl Install Tools webpage and install kubectl to your computer.

Installing without Admin

If you would like to install start and run K8s pods and jobs on existing resources, login to an NRP Jupyter instance, such as mizzou.nrp-nautilus.io with CILogon, and spawn a container with cURL installed, such as Stack Datascience.

Once you have entered Jupyter Lab, create a terminal from the launcher page and perform the following steps:

1. Download KubeCTL from K8s:

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

2. Verify the Installation:

curl -LO "https://dl.k8s.io/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256)  kubectl" | sha256sum --check

You should see kubectl: OK

3. Move KubeCTL to ~/.local/bin:

chmod +x kubectl
mkdir -p ~/.local/bin
mv ./kubectl ~/.local/bin/kubectl

4. Add ~/.local/bin to the $PATH:

export PATH=~/.local/bin:$PATH

Step 4: Downloading your Kubernetes Config

After you have logged into the Nautilus portal and been given access to a namespace, you will reach the home page seen here:

Click on Get config in the top right corner. After re-authenticating with your MU SSO credentials, your Kubernetes config file will download.

After you have downloaded your file, move it to ~/.kube/ so that kubectl is properly configured:

mkdir -p ~/.kube && mv [YOUR FILE HERE] ~/.kube/

Note: If you have installed KubeCTL to a Jupyter environment, you will need to upload your config to the Jupyter environment and then move it to ~/.kube similarly to above.

Step 5 (Optional): Creating your Gitlab Account

If you are planning to use a custom docker image on the Nautilus cluster, it is recommended to create an account on the Nautilus Gitlab instance.

This Gitlab will provide source control, CI/CD, and a container registry that can be easily integrated into the Nautilus cluster.

To create an account, go to the Nautilus GitLab homepage and click Register Now.

Accessing Nautilus Resources

To interact with the Nautilus cluster and access the resources available, you will be using the kubectl command line tool that you should have already installed. You also must have downloaded your kube config and copied it to ~/.kube.

The general syntax for using kubectl is:

kubectl [command] [TYPE] [NAME] [flags]

There are various resources for using kubectl, including the official reference documentation

In the subsections below, we discuss, briefly, some of the common kubectl commands that you will use most often:

Viewing Pods and Jobs

To view pods, jobs, or persistent volume claims (PVC) we can use get:

kubectl get pods
kubectl get jobs 
kubectl get pvc

Getting More Information on a Pod or Job

We can use describe to see more information about pods and jobs:

kubectl describe pod PODNAME
kubectl describe job JOBNAME

Checking Pod/Job Progress

To get the standard output and standard error of a job/pod, you can use the logs:

kubectl logs PODNAME

Note: This command can only be used on pods. To get job progress, you will need to run kubectl get pods and get the name of the pods associated with your job

Creating Pods and Jobs

To create pods and jobs, we will use the apply command with the path to a .yml spec file, which will define the resources and type of job/pod that should be run:

kubectl apply -f FILENAME.yml

Executing Code on Pods

To execute code on a pod, including attaching to a pod, we an use exec.

To get a remote shell to the pod:

kubectl exec -it PODNAME -- /bin/bash

To check the GPU utilization of a pod:

kubectl exec PODNAME -- nvidia-smi

Deleting Pods and Jobs

After a pod/job has either errored or you are finished using it, you should run delete to release the resources.

kubectl delete pod PODNAME
kubectl delete job JOBNAME

Note: This will remove all local storage on the pod/job. Be sure that all of the data you want to keep is copied/moved to a persistent volume.

Next Steps

There are pages in this wiki on building YML files for running pods and jobs, as well as how to use persistent storage, how to use a custom container, and how to train a neural network.