doc: improve cluster/user docs, make it more discoverable

Change-Id: Icbb348865a442a01a3ab191dad88662a88635007
Reviewed-on: https://gerrit.hackerspace.pl/c/hscloud/+/1565
Reviewed-by: q3k <q3k@hackerspace.pl>

cluster/README.md

@@ -5,3 +5,10 @@ Documentation relating to our Kubernetes cluster(s).
 
 For information about the physical DC infrastructure, see [//dc](/dc/).
 
+For all docs, see [hackdoc root](/).
+
+Cluster docs
+------------
+
+- [user (hacker) guide](./doc/user.md)
+- [admin guide](./doc/admin.md)

cluster/doc/user.md

@@ -11,14 +11,16 @@ We run Kubernetes, a cluster system on our production machines. This allows you
 Accessing Kubernetes
 --------------------
 
-Kubernetes is accessed fully via an API, for which there exists a standard command line tool: `kubectl`. If you've check out hscloud and followed the instructions in [//README.md]("/README.md"), you should have that tool built and available for you to use.
+Kubernetes is accessed fully via an API, for which there exists a standard command line tool: `kubectl`. If you've check out hscloud and followed the instructions in [//README.md](/), you should have that tool built and available for you to use.
 
 Before you can use `kubectl`, however, you will need to authenticate yourself. To do that, run `prodaccess`. This will issue you short-term (~hours) credentials that `kubectl` can then pass on to Kubernetes to authenticate itself.
 
     $ prodaccess
-    Enter SSO/LDAP password for q3k@hackerspace.pl: 
+    Enter SSO/LDAP password for q3k@hackerspace.pl:
     Good evening professor. I see you have driven here in your Ferrari.
 
+You might need to ping q3k on #hswaw-infra if you get a PermissionDenied error.
+
 If `prodaccess` is not on your $PATH:
 
     $ bazel run //tools:install
@@ -42,11 +44,11 @@ For example, to run an Alpine Linux Docker image in your own namespace:
 
     kubectl -n personal-$USER run --image=alpine:latest -it foo
 
-This will create a Kubernetes deployment named foo, running the `alpine:latest` Docker image, and drop you in an interactive shell in it. Naturally, replace `$USER` with your SSO username if it's different from your system username.
+This will create a Kubernetes pod named foo, running the `alpine:latest` Docker image, and drop you in an interactive shell in it. Naturally, replace `$USER` with your SSO username if it's different from your system username.
 
-Once you're done, delete the Deployment:
+Once you're done, delete the pod:
 
-    kubectl -n personal-$USER delete deployment foo
+    kubectl -n personal-$USER delete pod foo
 
 Pod Security
 ------------
@@ -58,4 +60,4 @@ More Kubernetes
 
 We highly recommend following the [Kubernetes Basics](https://kubernetes.io/docs/tutorials/kubernetes-basics/) tutorial as a first step in using Kubernetes for real world applications.
 
-For defining production jobs, we use a language called `Jsonnet` via a tool called `kubecfg`. This is to replace some more popular tools that other Kubernetes systems use, eg. Helm. For more information about that, ping q3k so that he writes a codelab about it :).
+For defining production jobs, we use a language called `Jsonnet` via a tool called `kubecfg`. This is to replace some more popular tools that other Kubernetes systems use, eg. Helm. For more information about that, ping q3k so that he writes a codelab about it :). Before he does, [see jsonnet documentation](https://jsonnet.org/learning/tutorial.html), and [basic (possibly outdated) `kubecfg` readme](https://github.com/q3k/kubecfg).

doc/codelabs/index.md

@@ -11,3 +11,8 @@ Getting started
 - [**Checking out hscloud**](getting-started/checking-out.md) - how to get a copy of hscloud, how to navigate around it, and what's what. This is nearly **mandatory** for anyone who wishes to interact with hscloud.
 - [**Your First Change**](getting-started/your-first-change.md) - how to use Gerrit and git to send your first change to hscloud, and an intro to personal directories. Using Gerrit can be somewhat confusing even (or especially) if you're used to Gitflow or GitHub.
 - [**Bazel & Go basics**](getting-started/bazel-go.md) - will (TODO) guide you through building some code using Bazel, and then writing a tiny bit of Go code of your own.
+
+See also
+--------
+
+- [**Cluster User Docs**](/cluster/doc/user.md) - getting started with our Kubernetes cluster (on hackdoc://cluster)