diff --git a/docs/index.md b/docs/index.md index bd3a120..d75af3f 100644 --- a/docs/index.md +++ b/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 diff --git a/docs/kubernetes.md b/docs/kubernetes.md new file mode 100644 index 0000000..2bc996f --- /dev/null +++ b/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. diff --git a/docs/vhosts.md b/docs/vhosts.md index bd306a8..cddb0f7 100644 --- a/docs/vhosts.md +++ b/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 -`.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 diff --git a/mkdocs.yml b/mkdocs.yml index 9e1a074..a52b135 100644 --- a/mkdocs.yml +++ b/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