Get started with k8s!

This is a quick-n-dirty getting started guide to start using the k8s cluster. Just a summary of the steps and the commands to run.

Note: these steps assume a Linux environemnt (bash and curl commands available).

Clone this repo

Start by cloning this repo to your local machine and work in that dir.

Install kubectl

You need the kubectl command to control k8s. Install it according to your platform requirements.

Note from: You must use a kubectl version that is within one minor version difference of your cluster. For example, a v1.27 client can communicate with v1.26, v1.27, and v1.28 control planes. Using the latest compatible version of kubectl helps avoid unforeseen issues.

We are currently on version 1.24

• On Ubuntu you can sudo snap install kubectl (How to install specific version of a snap?)

• Install v1.24 kubectl on Mac w/ Apple Silicon. For Intel Macs, replace arch="arm64" with arch="amd64"

  ver="1.24"
  arch="arm64"
  curl -LO "https://dl.k8s.io/release/v${ver}.0/bin/darwin/${arch}/kubectl"
  chmod +x kubectl
  curl -LO "https://dl.k8s.io/release/v${ver}.0/bin/darwin/${arch}/kubectl.sha256"
  echo "$(cat kubectl.sha256)  kubectl" | shasum -a 256 --check

Copy the example kube config

cp kube-config.example kube-config

Point your environment to your kube-config

export KUBECONFIG=kube-config

Take a look at your config

This is just a sanity check to make sure kubectl sees your config. The output should be the same the content of your kube-config file, except the data is ommitted.

kubectl config view

Get an application credential

Log into https://dashboard.k8s.rc.uab.edu and select "UAB Single Sign-On" from the dropdown and Sign In.

Once you are logged in, ignore the permission denied message you see on the dashboard. It is irrelevent.

Click the Identity dropdown on the left and select Application Credentials.

Click the Create Application Credential button and on the form that pops up, file in a name. This name will be part of the file name you download in the next step. A good choice is a name that reflects the purpose of the creditial, like your username.

A good habit is to make your credential expire after some time. For now a 30-day timeframe can be good. You select the "Expiration Date" drop-down and pick the same day one month ahead. It is not required to set an expiration date.

Leave all the rest of the fields as the default and click Create.

Select the "Download openrc file" and save it with your browser. If you saved it to your Downloads dir then it will be a file named ~/Downloads/app-cred-[cred-name-above]-openrc.sh.

Move the application credential to your project dir

This just makes it easy to use your app credential.

mv ~/Downloads/app-cred-[cred-name-above]-openrc.sh .

Source the application credtials to load them into your environment

. app-cred-[cred-name-above]-openrc.sh

Run your first kubectl command to see whats in the default namespace

By default the only namespace you can use is "default". All users share it so don't store any important work here. Anyone can delete it or access it!

The main thing to do here is just confirm you have a working kubectl against the cluster. You can run a command to list the pods:

kubectl get pods

Request your own namespace to have a private space for your k8s objects

You need to ask support to create a namespace. Once it's ready you'll have the namespace name and want to set it up as your default context in your kube-config file.

Run this command to add a context to your kube-config and set it as the default. Replace YOURNAMESPACE with the namespace provided to you.

kubectl config set-context YOURNAMESPACE --cluster=k8s-rc --namespace=YOURNAMESPACE --user=username

Set this as your default context.

kubectl config use-context YOURNAMESPACE

Use your namespace to explore k8s

Your personal namespace is now ready to use. You can list the pods there but you won't have any until you create some.

kubectl get pods

Remember to set your KUBECONFIG to point at your kube-config file whenever you start a new shell to use kubectl in.

More advanced config scenarios are documented here

Admins: how to create a namespace

When someone requests a namespace, run these commands to create one based on their blazerid. Namespaces have to follow DNS naming conventions, so only alphanums and dashes with alphanums at start and end.

user=USERID
kubectl create namespace $user
kubectl create rolebinding $user@uab.edu-admin-binding --clusterrole=admin --user=$user@uab.edu --namespace=$user