add docs for k8s

docs/index.md

@@ -6,8 +6,8 @@ available to CSC members.
 ## Available services
 
 * [CloudStack](cloudstack) - Virtual machines on demand.
-* [Virtual hosting](vhosts) - Virtual domain name hosting for websites.
-* Kubernetes (coming soon!)
+* [Virtual hosting](vhosts) - Domain name routing for websites.
+* [Kubernetes](kubernetes) - Easily deploy your Dockerized apps.
 
 ## Getting Started
 

docs/kubernetes.md

@@ -0,0 +1,116 @@
+# Kubernetes
+
+We are running a [Kubernetes](https://k8s.io) cluster on top of CloudStack.
+Each member gets their own namespace in which they can deploy their applications.
+
+!!! info
+    If you wish to learn about how to operate a Kubernetes cluster, you may
+    create your own cluster from the CloudStack UI. If all you want to do is
+    run some containerized apps, then we suggest that you use our cluster
+    instead, since it has far more resources.
+
+## Account resource limits
+As of this writing, the per-namespace Kubernetes resource limits for each member are:
+
+* 40 pods
+* 10 jobs
+* 10 cron jobs
+* 25 GB of Persistent Volume Claims
+* 5 NodePort services
+
+If you wish to acquire more resources, please send an email to the Systems Committee
+with a brief justification.
+
+!!! info
+    LoadBalancer services are disabled because we are running our own load balancer
+    (NGINX) outside of Kubernetes which we manage ourselves.
+    See [Exposing your app](#exposing-your-app), below.
+
+
+## Create a new namespace
+
+Log into a general-use machine and run the following:
+```sh
+ceo k8s account activate
+```
+
+This will create a new Kubernetes namespace whose name has the format `csc-username`.
+A new kubeconfig file will be placed into `~/.kube/config`. To verify that everything
+is working properly, run the following command:
+```sh
+kubectl cluster-info
+```
+
+The output should look something like this:
+```
+Kubernetes control plane is running at https://172.19.134.149:6443
+CoreDNS is running at https://172.19.134.149:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
+
+To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
+```
+
+## Quickstart
+
+So, let's say you've created a Dockerized app, and the image is available on some publicly available
+registry such as [Docker Hub](https://hub.docker.com) or [Quay.io](https://quay.io). Here is the bare
+minimum which you need to do get your app running in our Kubernetes cluster.
+
+First, create a Deployment:
+```sh
+kubectl create deployment demo --image=ctdalek/myapp --port=80
+```
+Replace the values of `--image` and `--port` as necessary.
+
+If your app does not need to be publicly exposed, then you are done; otherwise, you need to create
+a Service to expose your Deployment:
+```sh
+kubectl expose deployment demo
+```
+
+Finally, create an Ingress which exposes the Service to the outside world:
+```sh
+kubectl create ingress demo --rule='ctdalek.k8s.csclub.cloud/*=demo:80'
+```
+
+You should now be able to access your app at e.g. `https://ctdalek.k8s.csclub.cloud`.
+
+To see what kind of Ingress domains you may create, see [Ingress domains](#ingress-domains)
+below.
+
+## Not-so-quick start
+
+At this point I am going to take the lazy way out and direct you to the official
+Kubernetes documentation:
+
+* [https://kubernetes.io/docs/home/](https://kubernetes.io/docs/home/)
+* [https://kubernetes.io/docs/tutorials/](https://kubernetes.io/docs/tutorials/)
+* [https://kubectl.docs.kubernetes.io/guides/](https://kubectl.docs.kubernetes.io/guides/)
+
+You may also contact the [Systems Committee](mailto:syscom@csclub.uwaterloo.ca) for
+assistance if something is not working the way you think it should.
+
+## Exposing your app
+
+If your app is running in our Kuberenetes cluster, you have two options for exposing
+it to the outside world: an [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)
+(preferred), or a [NodePort](https://kubernetes.io/docs/concepts/services-networking/service/#type-nodeport).
+We generally recommend using an Ingress if your program is a web application; for
+non-web apps, you will need to use a NodePort instead. Since our Kubernetes cluster
+is not publicly accessible, the NodePort will only be directly accessible from on-campus.
+
+### Ingress domains
+
+By default, you may only create Ingress rules of the form `username.k8s.csclub.cloud`
+or `*-username.k8s.csclub.cloud`. If you wish to use a custom domain, please
+contact the [Systems Committee](mailto:syscom@csclub.uwaterloo.ca).
+
+If you decide to create a multi-level subdomain (e.g. `app.ctdalek.k8s.csclub.cloud`),
+then you will also need to create a corresponding virtual host (see
+[Virtual Hosting](../vhosts)) which points to `k8s`. For example:
+```sh
+ceo cloud vhosts add app.ctdalek.k8s.csclub.cloud k8s
+```
+
+We strongly encourage you to use single-level subdomains instead
+(e.g. `app-ctdalek.k8s.csclub.cloud`) since this does not require us to obtain a
+new SSL certificate.

docs/vhosts.md

@@ -8,15 +8,22 @@ and you would like it to be publically accessible, you will need to create
 a vhost record for your VM.
 
 ## Domain limitations
-Each member may create up to 10 vhosts whose domains end with
-`<username>.csclub.cloud`.
+Each member may create up to 10 vhosts whose domains have the form
+`username.csclub.cloud` or end with `-username.csclub.cloud`.
 
 For example, if your username is `ctdalek`, then the following vhost domains
 are all valid:
 
 * ctdalek.csclub.cloud
-* www.ctdalek.csclub.cloud
-* abc.def.ctdalek.csclub.cloud
+* app-ctdalek.csclub.cloud
+* abc-def-ctdalek.csclub.cloud
+
+!!! note "Multi-level subdomains"
+    While you are allowed to create multi-level subdomains of csclub.cloud
+    (e.g. app.ctdalek.csclub.cloud), we strongly ask that you do not do this
+    unless you have a very good reason, because it is easier for us to use our
+    existing wildcard SSL certificate which is valid for *.csclub.cloud (one
+    level only).
 
 ## Creating a vhost record
 Let's say your VM's IP address is 172.19.134.121 and you wish to use the domain
@@ -28,15 +35,20 @@ and run the following:
 ```sh
 ceo cloud vhosts add ctdalek.csclub.cloud 172.19.134.121
 ```
-In addition to creating the vhost record, this command will also provision a TLS
+
+!!! tip
+    You can also append a port number to the IP address, e.g. `172.19.134.121:8000`.
+
+If you specified a multi-level subdomain, this command will also provision a TLS
 certificate for your website (from either [ZeroSSL](https://zerossl.com/) or
-[Let's Encrypt](https://letsencrypt.org/)). You should now be able to visit your
+[Let's Encrypt](https://letsencrypt.org/)); otherwise, our existing wildcard
+certificate will be used. You should now be able to visit your
 website over HTTPS from your browser, e.g. `https://ctdalek.csclub.cloud`.
 
 !!! warning
     To avoid having to reload our web server too frequently, and to reduce the risk
     of getting banned by our ACME service provider, we have set a rate limit on the
-    command above for **once every five minutes**. We apologize for the inconvnience.
+    command above for **once every three minutes**. We apologize for the inconvenience.
 
 To view your vhost records, run the following:
 ```sh
@@ -49,8 +61,8 @@ ceo cloud vhosts delete ctdalek.csclub.cloud
 ```
 
 !!! info
-    Multiple domain names can point to the same IP address, but a single domain name
-    can only point to one IP address.
+    If you run `ceo cloud vhost add` twice for the same domain, the second command
+    will effectively override the first (that is, the vhost will be replaced).
 
 ## Using a custom domain name
 If you wish to use a custom domain name which you have purchased from an external

mkdocs.yml

@@ -4,6 +4,7 @@ nav:
   - Home: index.md
   - CloudStack: cloudstack.md
   - Virtual Hosting: vhosts.md
+  - Kubernetes: kubernetes.md
   - SSH Tricks: ssh-tricks.md
 
 # pip install pymdown-extensions