add docs for k8s
This commit is contained in:
parent
bfa78ef0be
commit
dc3db8ad03
|
@ -6,8 +6,8 @@ available to CSC members.
|
||||||
## Available services
|
## Available services
|
||||||
|
|
||||||
* [CloudStack](cloudstack) - Virtual machines on demand.
|
* [CloudStack](cloudstack) - Virtual machines on demand.
|
||||||
* [Virtual hosting](vhosts) - Virtual domain name hosting for websites.
|
* [Virtual hosting](vhosts) - Domain name routing for websites.
|
||||||
* Kubernetes (coming soon!)
|
* [Kubernetes](kubernetes) - Easily deploy your Dockerized apps.
|
||||||
|
|
||||||
## Getting Started
|
## 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.
|
a vhost record for your VM.
|
||||||
|
|
||||||
## Domain limitations
|
## Domain limitations
|
||||||
Each member may create up to 10 vhosts whose domains end with
|
Each member may create up to 10 vhosts whose domains have the form
|
||||||
`<username>.csclub.cloud`.
|
`username.csclub.cloud` or end with `-username.csclub.cloud`.
|
||||||
|
|
||||||
For example, if your username is `ctdalek`, then the following vhost domains
|
For example, if your username is `ctdalek`, then the following vhost domains
|
||||||
are all valid:
|
are all valid:
|
||||||
|
|
||||||
* ctdalek.csclub.cloud
|
* ctdalek.csclub.cloud
|
||||||
* www.ctdalek.csclub.cloud
|
* app-ctdalek.csclub.cloud
|
||||||
* abc.def.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
|
## Creating a vhost record
|
||||||
Let's say your VM's IP address is 172.19.134.121 and you wish to use the domain
|
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
|
```sh
|
||||||
ceo cloud vhosts add ctdalek.csclub.cloud 172.19.134.121
|
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
|
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`.
|
website over HTTPS from your browser, e.g. `https://ctdalek.csclub.cloud`.
|
||||||
|
|
||||||
!!! warning
|
!!! warning
|
||||||
To avoid having to reload our web server too frequently, and to reduce the risk
|
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
|
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:
|
To view your vhost records, run the following:
|
||||||
```sh
|
```sh
|
||||||
|
@ -49,8 +61,8 @@ ceo cloud vhosts delete ctdalek.csclub.cloud
|
||||||
```
|
```
|
||||||
|
|
||||||
!!! info
|
!!! info
|
||||||
Multiple domain names can point to the same IP address, but a single domain name
|
If you run `ceo cloud vhost add` twice for the same domain, the second command
|
||||||
can only point to one IP address.
|
will effectively override the first (that is, the vhost will be replaced).
|
||||||
|
|
||||||
## Using a custom domain name
|
## Using a custom domain name
|
||||||
If you wish to use a custom domain name which you have purchased from an external
|
If you wish to use a custom domain name which you have purchased from an external
|
||||||
|
|
|
@ -4,6 +4,7 @@ nav:
|
||||||
- Home: index.md
|
- Home: index.md
|
||||||
- CloudStack: cloudstack.md
|
- CloudStack: cloudstack.md
|
||||||
- Virtual Hosting: vhosts.md
|
- Virtual Hosting: vhosts.md
|
||||||
|
- Kubernetes: kubernetes.md
|
||||||
- SSH Tricks: ssh-tricks.md
|
- SSH Tricks: ssh-tricks.md
|
||||||
|
|
||||||
# pip install pymdown-extensions
|
# pip install pymdown-extensions
|
||||||
|
|
Loading…
Reference in New Issue