Revert "*: update docs for hackdoc"
This reverts commit cc8c69c8974f7ce415641121cedb01d7e6aa9e17.
Reason for revert: <INSERT REASONING HERE>
Change-Id: I1315e930e2ef69db3188eda05e4aa0b12db24274
diff --git a/README.md b/README.md
index cab3853..11a05a7 100644
--- a/README.md
+++ b/README.md
@@ -26,9 +26,9 @@
What now?
---------
-If you want to use our Kubernetes cluster to run some stuff, see [//cluster/doc/user.md](cluster/doc/user.md).
+If you want to use our Kubernetes cluster to run some stuff, see [//cluster/doc/user](cluster/doc/user).
-If you're looking for administrative docs about cluster maintenance, see [//cluster/doc/admin.md](cluster/doc/admin.md).
+If you're looking for administrative docs about cluster maintenance, see [//cluster/doc/admin](cluster/doc/admin).
If you want to browse the source of `hscloud` in a web browser, use [gerrit's gitiles](https://gerrit.hackerspace.pl/plugins/gitiles/hscloud/+/refs/heads/master/).
diff --git a/cluster/doc/admin.md b/cluster/README.md
similarity index 77%
rename from cluster/doc/admin.md
rename to cluster/README.md
index 27b30ca..0120859 100644
--- a/cluster/doc/admin.md
+++ b/cluster/README.md
@@ -1,10 +1,23 @@
HSCloud Clusters
================
-Admin documentation. For user documentation, see [//cluster/doc/user.md](/cluster/doc/user.md).
-
Current cluster: `k0.hswaw.net`
+Accessing via kubectl
+---------------------
+
+ prodaccess # get a short-lived certificate for your use via SSO
+ # if youre local username is not the same as your HSWAW SSO
+ # username, pass `-username foo`
+ kubectl version
+ kubectl top nodes
+
+Every user gets a `personal-$username` namespace. Feel free to use it for your own purposes, but watch out for resource usage!
+
+ kubectl run -n personal-$username run --image=alpine:latest -it foo
+
+To proceed further you should be somewhat familiar with Kubernetes. Otherwise the rest of terminology might not make sense. We recommend going through the original Kubernetes tutorials.
+
Persistent Storage (waw2)
-------------------------
@@ -51,10 +64,9 @@
We run Ceph via Rook. The Rook operator is running in the `ceph-rook-system` namespace. To debug Ceph issues, start by looking at its logs.
-A dashboard is available at https://ceph-waw2.hswaw.net/ and https://ceph-waw3.hswaw.net, to get the admin password run:
+A dashboard is available at https://ceph-waw2.hswaw.net/, to get the admin password run:
kubectl -n ceph-waw2 get secret rook-ceph-dashboard-password -o yaml | grep "password:" | awk '{print $2}' | base64 --decode ; echo
- kubectl -n ceph-waw2 get secret rook-ceph-dashboard-password -o yaml | grep "password:" | awk '{print $2}' | base64 --decode ; echo
Ceph - Backups
@@ -63,7 +75,6 @@
Kubernetes PVs backed in Ceph RBDs get backed up using Benji. An hourly cronjob runs in every Ceph cluster. You can also manually trigger a run by doing:
kubectl -n ceph-waw2 create job --from=cronjob/ceph-waw2-benji ceph-waw2-benji-manual-$(date +%s)
- kubectl -n ceph-waw3 create job --from=cronjob/ceph-waw3-benji ceph-waw3-benji-manual-$(date +%s)
Ceph ObjectStorage pools (RADOSGW) are _not_ backed up yet!
@@ -72,7 +83,8 @@
To create an object store user consult rook.io manual (https://rook.io/docs/rook/v0.9/ceph-object-store-user-crd.html)
User authentication secret is generated in ceph cluster namespace (`ceph-waw2`),
-thus may need to be manually copied into application namespace. (see `app/registry/prod.jsonnet` comment)
+thus may need to be manually copied into application namespace. (see
+`app/registry/prod.jsonnet` comment)
`tools/rook-s3cmd-config` can be used to generate test configuration file for s3cmd.
Remember to append `:default-placement` to your region name (ie. `waw-hdd-redundant-1-object:default-placement`)
diff --git a/cluster/doc/index.md b/cluster/doc/index.md
deleted file mode 100644
index afd04e4..0000000
--- a/cluster/doc/index.md
+++ /dev/null
@@ -1,6 +0,0 @@
-Warsaw Hackerspace Kubernetes Cluster
-=====================================
-
-**User documentation**: [user.md](user.md).
-
-**Admin documentation**: [admin.md](admin.md).
diff --git a/cluster/doc/user.md b/cluster/doc/user.md
deleted file mode 100644
index 6dd6938..0000000
--- a/cluster/doc/user.md
+++ /dev/null
@@ -1,58 +0,0 @@
-Warsaw Hackerspace Kubernetes Clusters
-======================================
-
-End-user^Whacker documentation.
-
-Intro
------
-
-We run Kubernetes, a cluster system on our production machines. This allows you to schedule software to run without having to worry about traditional deployment, or where your particular piece of code is actually running. This document will not teach you how to use Kubernetes, but will give you a short hands-on example on how to access it, and then point you in the right direction for general documentation to follow.
-
-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.
-
-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:
- Good evening professor. I see you have driven here in your Ferrari.
-
-If `prodaccess` is not on your $PATH, ensure you have sourced `env.sh` from the root of hscloud and ran `tools/install.sh`.
-
-By default, `prodaccess` will use your local user name to authenticate as `<user>@hackerspce.pl`. If your Hackerspace SSO name is different, specify it using the `-u` flag to prodaccess, eg. `prodaccess -u informatic`.
-
-You can now check that you indeed have access to Kubernetes:
-
- $ kubectl version # show version of Kubernetes
- $ kubectl top nodes # show node (machine/server) statistics
-
-You are now fully set up to schedule your own jobs on `k0.hswaw.net`, our currently only Kubernetes cluster.
-
-Running Stuff
--------------
-
-We have a fairly extensive role-based access control system set up to provide a level of multi-tenancy of our Kubernetes cluster. What this means is that you will not be able to modify other people's stuff. Indeed, by default, you barely have any access. So as you can experiment with Kubernetes, we automatically provision you a personal namespace (`personal-$USER`) in Kubernetes. This acts as your own playground, where you can run anything you want, as long as it doesn't eat into our resources too much.
-
-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.
-
-Once you're done, delete the Deployment:
-
- kubectl -n personal-$USER delete deployment foo
-
-Pod Security
-------------
-
-Apart from the RBAC (role based access control) that prevents you from poling at things that you shouldn't over the API, we have one more security measure in place. Throught a Kubernetes mechanism called 'PodSecurityPolicy' we limit what pods (ie. containers) can do. Notably, pods will by default not be able to access any host data, run in privileged mode, or even setuid to a different uid. The most notable side effect of this is that some basic system tools within pods will not work: ie., apt on Ubuntu.
-
-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 :).
diff --git a/devtools/hackdoc/README.md b/devtools/hackdoc/README.md
index 3226cf2..45d4486 100644
--- a/devtools/hackdoc/README.md
+++ b/devtools/hackdoc/README.md
@@ -18,6 +18,6 @@
To run hackdoc locally on a filesystem checkout (ie. when working on docs, templates, or hackdoc itself), run:
- bazel run //devtools/hackdoc -- -hspki_disable -docroot /path/to/hscloud
+ bazel run //devtools/hackdoc:local
The output log should tell you where hackdoc just started listening at. Currently this is `127.0.0.1:8080` by default. You can change this by passing a `-listen` flag, eg. `-listen 127.0.0.1:4242`.
diff --git a/devtools/hackdoc/main.go b/devtools/hackdoc/main.go
index 413a129..558268b 100644
--- a/devtools/hackdoc/main.go
+++ b/devtools/hackdoc/main.go
@@ -111,6 +111,7 @@
return
}
+ glog.Infof("%+v", r.URL.Query())
ref := r.URL.Query().Get("ref")
if ref == "" {
ref = flagGitwebDefaultBranch
@@ -205,8 +206,7 @@
}
if file {
- http.Redirect(r.w, r.r, "/"+fpath, 302)
- //r.handleMarkdown(fpath, cfg)
+ r.handleMarkdown(fpath, cfg)
return
}
}
@@ -238,11 +238,6 @@
if file {
parts := strings.Split(r.rpath, "/")
dirpath := strings.Join(parts[:(len(parts)-1)], "/")
- // TODO(q3k): figure out this hack, hopefully by implementing a real path type
- if dirpath == "/" {
- dirpath = "//"
- }
-
cfg, err := config.ForPath(r.ctx, r.source, dirpath)
if err != nil {
glog.Errorf("could not get config for path %q: %w", dirpath, err)
diff --git a/devtools/hackdoc/markdown.go b/devtools/hackdoc/markdown.go
index d20f9e3..911c2c0 100644
--- a/devtools/hackdoc/markdown.go
+++ b/devtools/hackdoc/markdown.go
@@ -31,7 +31,6 @@
q["ref"] = []string{ref}
u.RawQuery = q.Encode()
node.Destination = []byte(u.String())
- glog.Infof("link fix %q -> %q", dest, u.String())
}
}
return r.RenderNode(&buf, node, entering)
@@ -39,11 +38,6 @@
return buf.Bytes()
}
-type pathPart struct {
- Label string
- Path string
-}
-
func (r *request) handleMarkdown(path string, cfg *config.Config) {
data, err := r.source.ReadFile(r.ctx, path)
if err != nil {
@@ -66,26 +60,11 @@
}
pathInDepot := strings.TrimPrefix(path, "//")
- pathParts := []pathPart{
- {Label: "//", Path: "/"},
- }
- parts := strings.Split(pathInDepot, "/")
- fullPath := ""
- for i, p := range parts {
- label := p
- if i != len(parts)-1 {
- label = label + "/"
- }
- fullPath += "/" + p
- pathParts = append(pathParts, pathPart{Label: label, Path: fullPath})
- }
-
vars := map[string]interface{}{
"Rendered": template.HTML(rendered),
"Title": path,
"Path": path,
"PathInDepot": pathInDepot,
- "PathParts": pathParts,
"HackdocURL": flagHackdocURL,
"WebLinks": r.source.WebLinks(pathInDepot),
}
diff --git a/devtools/hackdoc/tpl/default.html b/devtools/hackdoc/tpl/default.html
index a6c1d42..7120962 100644
--- a/devtools/hackdoc/tpl/default.html
+++ b/devtools/hackdoc/tpl/default.html
@@ -58,7 +58,7 @@
}
.column {
- width: 80em;
+ max-width: 80em;
padding: 1rem 0 1rem 0;
}
@@ -85,16 +85,8 @@
color: #b30014;
}
-.header span.part {
+.header span.muted {
color: #666;
- padding-left: 0.2em;
-}
-
-.header span.part a {
- color: rgb(27, 106, 203);
-}
-.header span.part a:visited {
- color: rgb(27, 106, 203);
}
.footer {
@@ -106,14 +98,6 @@
text-align: right;
}
-.footer .left {
- float: left;
-}
-
-.footer .right {
- float: right;
-}
-
.footer a {
color: #bbb;
}
@@ -180,20 +164,15 @@
<div class="column">
<div class="page">
<div class="header">
- <span class="red">hackdoc:</span>
- {{ range .PathParts }}<span class="part"><a href="{{ .Path }}">{{ .Label }}</a></span>{{ end }}
- <span class="red" style="margin-left: 1em;">shortcuts:</span> <a href="/">root</a>, <a href="/cluster/doc">cluster docs</a>, <a href="/doc/codelabs">codelabs</a>
- </div>
- {{ .Rendered }}
- </div>
- <div class="footer">
- <div class="left">
- View in:
+ <span class="red">hackdoc:</span><span>{{ .Path }}</span>
{{ range .WebLinks }}
<span class="muted">[{{ .Kind }} <a href="{{ .LinkURL }}">{{ .LinkLabel }}</a>]</span>
{{ end }}
</div>
- <div class="right">Generated by <a href="{{ .HackdocURL }}/devtools/hackdoc">hackdoc</a>.</div>
+ {{ .Rendered }}
+ </div>
+ <div class="footer">
+ Generated by <a href="{{ .HackdocURL }}/devtools/hackdoc">hackdoc</a>.
</div>
</div>
</div>