add docs for k8s
This commit is contained in:
parent
bfa78ef0be
commit
dc3db8ad03
|
@ -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…
Reference in New Issue