diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..5eafdb261cd10cc1e1bacce62d996864bb8676bc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,124 @@
+# 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.
+
+On Ubuntu you can `sudo snap install kubectl`
+
+## 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](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#set-the-kubeconfig-environment-variable)
+
+## 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
+```
+