add docs for k8s

master
Max Erenberg 10 months ago
parent bfa78ef0be
commit dc3db8ad03
  1. 4
      docs/index.md
  2. 116
      docs/kubernetes.md
  3. 30
      docs/vhosts.md
  4. 1
      mkdocs.yml

@ -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

@ -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.

@ -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

@ -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

Loading…
Cancel
Save