From 26fb573055d81553a25dfb6c5e0ab91e2d322be8 Mon Sep 17 00:00:00 2001 From: radex Date: Sat, 5 Aug 2023 21:37:25 +0200 Subject: [PATCH] doc: improve cluster/user docs, make it more discoverable Change-Id: Icbb348865a442a01a3ab191dad88662a88635007 Reviewed-on: https://gerrit.hackerspace.pl/c/hscloud/+/1565 Reviewed-by: q3k --- cluster/README.md | 7 +++++++ cluster/doc/user.md | 14 ++++++++------ doc/codelabs/index.md | 5 +++++ 3 files changed, 20 insertions(+), 6 deletions(-) diff --git a/cluster/README.md b/cluster/README.md index 40416b9c..586a07ab 100644 --- a/cluster/README.md +++ b/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) diff --git a/cluster/doc/user.md b/cluster/doc/user.md index 11ea9594..f7a521eb 100644 --- a/cluster/doc/user.md +++ b/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). diff --git a/doc/codelabs/index.md b/doc/codelabs/index.md index 70f1af2b..4908ef9c 100644 --- a/doc/codelabs/index.md +++ b/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)