public/geek-cookbook
1
0
Fork 0
mirror of https://github.com/funkypenguin/geek-cookbook/ synced 2025-12-13 01:36:23 +00:00
Code Issues Releases Wiki Activity

"Sexify" the template

Browse Source
This commit is contained in:
David Young
2020-03-25 21:06:10 +13:00
parent 08a75ba31d
commit 701ee63ecd
4 changed files with 410 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
manuscript/images/kubernetes-dashboard.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 502 KiB

269
manuscript/recipes/kubernetes/kubernetes-dashboard.md Normal file
View File

@@ -0,0 +1,269 @@
# Kubernetes Dashboard
Yes, Kubernetes is complicated. There are lots of moving parts, and debugging _what's_ gone wrong and _why_, can be challenging.
Fortunately, to assist in day-to-day operation of our cluster, and in the occasional "how-did-that-ever-work" troubleshooting, we have available to us, the mighty **[Kubernetes Dashboard](https://github.com/kubernetes/dashboard)**:
![Kubernetes Dashboard Screenshot](/images/kubernetes-dashboard.png)
Using the dashboard, you can:
* Visual cluster load, pod distribution
* Examine Kubernetes objects, such as Deployments, Daemonsets, ConfigMaps, etc
* View logs
* Deploy new YAML manifests
* Lots more!
## Ingredients
1. A [Kubernetes Cluster](/kubernetes/design/), with
2. OIDC-enabled authentication
3. An Ingress Controller ([Traefik Ingress](/kubernetes/traefik/) or [NGinx Ingress](/kubernetes/nginx-ingress/))
4. A DNS name for your dashboard instance (*dashboard.example.com*, below) pointing to your [load balancer](/kubernetes/loadbalancer/), fronting your ingress controller
5. A [KeyCloak](/recipes/keycloak/) instance for authentication
6. A
## Preparation
### Prepare traefik for namespace
When you deployed [Traefik via the helm chart](/kubernetes/traefik/), you would have customized ```values.yml``` for your deployment. In ```values.yml``` is a list of namespaces which Traefik is permitted to access. Update ```values.yml``` to include the *kanboard* namespace, as illustrated below:
```
<snip>
kubernetes:
namespaces:
- kube-system
- nextcloud
- kanboard
- miniflux
<snip>
```
If you've updated ```values.yml```, upgrade your traefik deployment via helm, by running ```helm upgrade --values values.yml traefik stable/traefik --recreate-pods```
### Create data locations
Although we could simply bind-mount local volumes to a local Kubuernetes cluster, since we're targetting a cloud-based Kubernetes deployment, we only need a local path to store the YAML files which define the various aspects of our Kubernetes deployment.
```
mkdir /var/data/config/kanboard
```
### Create namespace
We use Kubernetes namespaces for service discovery and isolation between our stacks, so create a namespace for the kanboard stack with the following .yml:
```
cat <<EOF > /var/data/config/kanboard/namespace.yml
apiVersion: v1
kind: Namespace
metadata:
name: kanboard
EOF
kubectl create -f /var/data/config/kanboard/namespace.yaml
```
### Create persistent volume claim
Persistent volume claims are a streamlined way to create a persistent volume and assign it to a container in a pod. Create a claim for the kanboard app and plugin data:
```
cat <<EOF > /var/data/config/kanboard/persistent-volumeclaim.yml
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: kanboard-volumeclaim
namespace: kanboard
annotations:
backup.kubernetes.io/deltas: P1D P7D
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
EOF
kubectl create -f /var/data/config/kanboard/kanboard-volumeclaim.yaml
```
!!! question "What's that annotation about?"
The annotation is used by [k8s-snapshots](/kubernetes/snapshots/) to create daily incremental snapshots of your persistent volumes. In this case, our volume is snapshotted daily, and copies kept for 7 days.
### Create ConfigMap
Kanboard's configuration is all contained within ```config.php```, which needs to be presented to the container. We _could_ maintain ```config.php``` in the persistent volume we created above, but this would require manually accessing the pod every time we wanted to make a change.
Instead, we'll create ```config.php``` as a [ConfigMap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/), meaning it "lives" within the Kuberetes cluster and can be **presented** to our pod. When we want to make changes, we simply update the ConfigMap (*delete and recreate, to be accurate*), and relaunch the pod.
Grab a copy of [config.default.php](https://github.com/kanboard/kanboard/blob/master/config.default.php), save it to ```/var/data/config/kanboard/config.php```, and customize it per [the guide](https://docs.kanboard.org/en/latest/admin_guide/config_file.html).
At the very least, I'd suggest making the following changes:
```
define('PLUGIN_INSTALLER', true); // Yes, I want to install plugins using the UI
define('ENABLE_URL_REWRITE', false); // Yes, I want pretty URLs
```
Now create the configmap from config.php, by running ```kubectl create configmap -n kanboard kanboard-config --from-file=config.php```
## Serving
Now that we have a [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), a [persistent volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/), and a [configmap](https://kubernetes.io/docs/tasks/configure-pod-container/configure-pod-configmap/), we can create a [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), [service](https://kubernetes.io/docs/concepts/services-networking/service/), and [ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) for the kanboard [pod](https://kubernetes.io/docs/concepts/workloads/pods/pod-overview/).
### Create deployment
Create a deployment to tell Kubernetes about the desired state of the pod (*which it will then attempt to maintain*). Note below that we mount the persistent volume **twice**, to both ```/var/www/app/data``` and ```/var/www/app/plugins```, using the subPath value to differentiate them. This trick avoids us having to provision **two** persistent volumes just for data mounted in 2 separate locations.
!!! tip
I share (_with my [patreon patrons](https://www.patreon.com/funkypenguin)_) a private "_premix_" git repository, which includes necessary .yml files for all published recipes. This means that patrons can launch any recipe with just a ```git pull``` and a ```kubectl create -f *.yml``` 👍
```
cat <<EOF > /var/data/kanboard/deployment.yml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
namespace: kanboard
name: app
labels:
app: app
spec:
replicas: 1
selector:
matchLabels:
app: app
template:
metadata:
labels:
app: app
spec:
containers:
- image: kanboard/kanboard
name: app
volumeMounts:
- name: kanboard-config
mountPath: /var/www/app/config.php
subPath: config.php
- name: kanboard-app
mountPath: /var/www/app/data
subPath: data
- name: kanboard-app
mountPath: /var/www/app/plugins
subPath: plugins
volumes:
- name: kanboard-app
persistentVolumeClaim:
claimName: kanboard-app
- name: kanboard-config
configMap:
name: kanboard-config
EOF
kubectl create -f /var/data/kanboard/deployment.yml
```
Check that your deployment is running, with ```kubectl get pods -n kanboard```. After a minute or so, you should see a "Running" pod, as illustrated below:
```
[funkypenguin:~] % kubectl get pods -n kanboard
NAME READY STATUS RESTARTS AGE
app-79f97f7db6-hsmfg 1/1 Running 0 11d
[funkypenguin:~] %
```
### Create service
The service resource "advertises" the availability of TCP port 80 in your pod, to the rest of the cluster (*constrained within your namespace*). It seems a little like overkill coming from the Docker Swarm's automated "service discovery" model, but the Kubernetes design allows for load balancing, rolling upgrades, and health checks of individual pods, without impacting the rest of the cluster elements.
```
cat <<EOF > /var/data/kanboard/service.yml
kind: Service
apiVersion: v1
metadata:
name: app
namespace: kanboard
spec:
selector:
app: app
ports:
- protocol: TCP
port: 80
clusterIP: None
EOF
kubectl create -f /var/data/kanboard/service.yml
```
Check that your service is deployed, with ```kubectl get services -n kanboard```. You should see something like this:
```
[funkypenguin:~] % kubectl get service -n kanboard
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
app ClusterIP None <none> 80/TCP 38d
[funkypenguin:~] %
```
### Create ingress
The ingress resource tells Traefik what to forward inbound requests for *kanboard.example.com* to your service (defined above), which in turn passes the request to the "app" pod. Adjust the config below for your domain.
```
cat <<EOF > /var/data/kanboard/ingress.yml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
name: app
namespace: kanboard
annotations:
kubernetes.io/ingress.class: traefik
spec:
rules:
- host: kanboard.example.com
http:
paths:
- backend:
serviceName: app
servicePort: 80
EOF
kubectl create -f /var/data/kanboard/ingress.yml
```
Check that your service is deployed, with ```kubectl get ingress -n kanboard```. You should see something like this:
```
[funkypenguin:~] % kubectl get ingress -n kanboard
NAME HOSTS ADDRESS PORTS AGE
app kanboard.funkypenguin.co.nz 80 38d
[funkypenguin:~] %
```
### Access Kanboard
At this point, you should be able to access your instance on your chosen DNS name (*i.e. https://kanboard.example.com*)
### Updating config.php
Since ```config.php``` is a ConfigMap now, to update it, make your local changes, and then delete and recreate the ConfigMap, by running:
```
kubectl delete configmap -n kanboard kanboard-config
kubectl create configmap -n kanboard kanboard-config --from-file=config.php
```
Then, in the absense of any other changes to the deployement definition, force the pod to restart by issuing a "null patch", as follows:
```
kubectl patch -n kanboard deployment app -p "{\"spec\":{\"template\":{\"metadata\":{\"labels\":{\"date\":\"`date +'%s'`\"}}}}}"
```
### Troubleshooting
To look at the Kanboard pod's logs, run ```kubectl logs -n kanboard <name of pod per above> -f```. For further troubleshooting hints, see [Troubleshooting](/reference/kubernetes/troubleshooting/).
## Chef's Notes
1. The simplest deployment of Kanboard uses the default SQLite database backend, stored on the persistent volume. You can convert this to a "real" database running MySQL or PostgreSQL, and running an an additional database pod and service. Contact me if you'd like further details ;)
### Tip your waiter (support me) 👏
Did you receive excellent service? Want to make your waiter happy? (_..and support development of current and future recipes!_) See the [support](/support/) page for (_free or paid)_ ways to say thank you! 👏
### Your comments? 💬

274
mkdocs.yml
View File

@@ -25,138 +25,142 @@ plugins:
#theme_dir: mkdocs-material
nav:
- Home: index.md
- Introduction:
- README: README-UI.md
- Home:
- What is this: index.md
- About: whoami.md
- Sponsored Projects: sponsored-projects.md
- Support:
- Support: support.md
- Docker Swarm:
- Preparation:
- Design: ha-docker-swarm/design.md
- Nodes: ha-docker-swarm/nodes.md
- Shared Storage (Ceph): ha-docker-swarm/shared-storage-ceph.md
- Shared Storage (GlusterFS): ha-docker-swarm/shared-storage-gluster.md
- Keepalived: ha-docker-swarm/keepalived.md
- Docker Swarm Mode: ha-docker-swarm/docker-swarm-mode.md
- Traefik: ha-docker-swarm/traefik.md
- Traefik Forward Auth:
- Start: ha-docker-swarm/traefik-forward-auth.md
- KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md
- Registry: ha-docker-swarm/registry.md
- Mail Server: recipes/mail.md
- Duplicity: recipes/duplicity.md
- Chef's Favorites:
- Auto Pirate:
- Start: recipes/autopirate.md
- SABnzbd: recipes/autopirate/sabnzbd.md
- NZBGet: recipes/autopirate/nzbget.md
- Rtorrent: recipes/autopirate/rtorrent.md
- Sonarr: recipes/autopirate/sonarr.md
- Radarr: recipes/autopirate/radarr.md
- Mylar: recipes/autopirate/mylar.md
- Lazy Librarian: recipes/autopirate/lazylibrarian.md
- Headphones: recipes/autopirate/headphones.md
- Lidarr: recipes/autopirate/lidarr.md
- NZBHydra: recipes/autopirate/nzbhydra.md
- NZBHydra 2: recipes/autopirate/nzbhydra2.md
- Ombi: recipes/autopirate/ombi.md
- Jackett: recipes/autopirate/jackett.md
- Heimdall: recipes/autopirate/heimdall.md
- End: recipes/autopirate/end.md
- ElkarBackup: recipes/elkarbackup.md
- Emby: recipes/emby.md
- Home Assistant:
- Start: recipes/homeassistant.md
- iBeacon: recipes/homeassistant/ibeacon.md
- Huginn: recipes/huginn.md
- Kanboard: recipes/kanboard.md
- KeyCloak:
- Start: recipes/keycloak.md
- Users: recipes/keycloak/create-user.md
- OIDC Provider: recipes/keycloak/setup-oidc-provider.md
- OpenLDAP: recipes/keycloak/authenticate-against-openldap.md
- Miniflux: recipes/miniflux.md
- Munin: recipes/munin.md
- NextCloud: recipes/nextcloud.md
- OwnTracks: recipes/owntracks.md
- phpIPAM: recipes/phpipam.md
- Plex: recipes/plex.md
- PrivateBin: recipes/privatebin.md
- Swarmprom: recipes/swarmprom.md
- Turtle Pool: recipes/turtle-pool.md
- Recipes:
- Bitwarden: recipes/bitwarden.md
- Bookstack: recipes/bookstack.md
- CryptoMiner:
- Start: recipes/cryptominer.md
- Mining Rig: recipes/cryptominer/mining-rig.md
- AMD GPU: recipes/cryptominer/amd-gpu.md
- NVidia GPU: recipes/cryptominer/nvidia-gpu.md
- Mining Pools : recipes/cryptominer/mining-pool.md
- Wallets : recipes/cryptominer/wallet.md
- Exchanges: recipes/cryptominer/exchange.md
- Minerhotel: recipes/cryptominer/minerhotel.md
- Monitoring: recipes/cryptominer/monitor.md
- Profit!: recipes/cryptominer/profit.md
- Calibre-Web: recipes/calibre-web.md
- Collabora Online: recipes/collabora-online.md
- Ghost: recipes/ghost.md
- GitLab: recipes/gitlab.md
- GitLab Runner: recipes/gitlab-runner.md
- Gollum: recipes/gollum.md
- InstaPy: recipes/instapy.md
- KeyCloak:
- Start: recipes/keycloak.md
- Users: recipes/keycloak/create-user.md
- OIDC Provider: recipes/keycloak/setup-oidc-provider.md
- OpenLDAP: recipes/keycloak/authenticate-against-openldap.md
- Minio: recipes/minio.md
- OpenLDAP: recipes/openldap.md
- Piwik: recipes/piwik.md
- Portainer: recipes/portainer.md
- Realms: recipes/realms.md
- Tiny Tiny RSS: recipes/tiny-tiny-rss.md
- Traefik: ha-docker-swarm/traefik.md
- Traefik Forward Auth:
- Start: ha-docker-swarm/traefik-forward-auth.md
- KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md
- Wallabag: recipes/wallabag.md
- Wekan: recipes/wekan.md
- Wetty: recipes/wetty.md
- Reference:
- OAuth Proxy: reference/oauth_proxy.md
- Data Layout: reference/data_layout.md
- Networks: reference/networks.md
- Containers: reference/containers.md
- git-docker : reference/git-docker.md
- OpenVPN : reference/openvpn.md
- Troubleshooting: reference/troubleshooting.md
- Work-in-Progress:
# - MatterMost: recipes/mattermost.md
- IPFS Cluster: recipes/ipfs-cluster.md
- MQTT: recipes/mqtt.md
# - HackMD: recipes/hackmd.md
# - Mastodon: recipes/mastodon.md
# - Mayan EDMS: recipes/mayan-edms.md
# - Shaarli: recipes/shaarli.md
# - UniFi Controller: recipes/unifi-controller.md
# - CyberChef : recipes/cyberchef.md
- Kubernetes:
- Preparation:
- Start: kubernetes/start.md
- Design: kubernetes/design.md
- Cluster: kubernetes/cluster.md
- DIY Cluster: kubernetes/diycluster.md
- Load Balancer: kubernetes/loadbalancer.md
- Snapshots: kubernetes/snapshots.md
- Helm: kubernetes/helm.md
- Traefik: kubernetes/traefik.md
- Chef's Favorites:
- Kanboard: recipes/kubernetes/kanboard.md
# - Kubernetes Dashboard: recipes/kubernetes/kubernetes-dashboard.md
- Miniflux: recipes/kubernetes/miniflux.md
# - NextCloud: recipes/kubernetes/nextcloud.md
# - phpIPAM: recipes/kubernetes/phpipam.md
# - PrivateBin: recipes/kubernetes/privatebin.md
- CHANGELOG:
- CHANGELOG: CHANGELOG.md
- whoami: whoami.md
- Docker Swarm:
- Design: ha-docker-swarm/design.md
- Nodes: ha-docker-swarm/nodes.md
- Shared Storage (Ceph): ha-docker-swarm/shared-storage-ceph.md
- Shared Storage (GlusterFS): ha-docker-swarm/shared-storage-gluster.md
- Keepalived: ha-docker-swarm/keepalived.md
- Docker Swarm Mode: ha-docker-swarm/docker-swarm-mode.md
- Traefik: ha-docker-swarm/traefik.md
- Traefik Forward Auth:
- Start: ha-docker-swarm/traefik-forward-auth.md
- KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md
- Registry: ha-docker-swarm/registry.md
- Mail Server: recipes/mail.md
- Duplicity: recipes/duplicity.md
- Kubernetes Cluster:
- Start: kubernetes/start.md
- Design: kubernetes/design.md
- Cluster: kubernetes/cluster.md
- DIY Cluster: kubernetes/diycluster.md
- Load Balancer: kubernetes/loadbalancer.md
- Snapshots: kubernetes/snapshots.md
- Helm: kubernetes/helm.md
- Traefik: kubernetes/traefik.md
- Chef's Favorites (Docker):
- Auto Pirate:
- Start: recipes/autopirate.md
- SABnzbd: recipes/autopirate/sabnzbd.md
- NZBGet: recipes/autopirate/nzbget.md
- Rtorrent: recipes/autopirate/rtorrent.md
- Sonarr: recipes/autopirate/sonarr.md
- Radarr: recipes/autopirate/radarr.md
- Mylar: recipes/autopirate/mylar.md
- Lazy Librarian: recipes/autopirate/lazylibrarian.md
- Headphones: recipes/autopirate/headphones.md
- Lidarr: recipes/autopirate/lidarr.md
- NZBHydra: recipes/autopirate/nzbhydra.md
- NZBHydra 2: recipes/autopirate/nzbhydra2.md
- Ombi: recipes/autopirate/ombi.md
- Jackett: recipes/autopirate/jackett.md
- Heimdall: recipes/autopirate/heimdall.md
- End: recipes/autopirate/end.md
- ElkarBackup: recipes/elkarbackup.md
- Emby: recipes/emby.md
- Home Assistant:
- Start: recipes/homeassistant.md
- iBeacon: recipes/homeassistant/ibeacon.md
- Huginn: recipes/huginn.md
- Kanboard: recipes/kanboard.md
- KeyCloak:
- Start: recipes/keycloak.md
- Users: recipes/keycloak/create-user.md
- OIDC Provider: recipes/keycloak/setup-oidc-provider.md
- OpenLDAP: recipes/keycloak/authenticate-against-openldap.md
- Miniflux: recipes/miniflux.md
- Munin: recipes/munin.md
- NextCloud: recipes/nextcloud.md
- OwnTracks: recipes/owntracks.md
- phpIPAM: recipes/phpipam.md
- Plex: recipes/plex.md
- PrivateBin: recipes/privatebin.md
- Swarmprom: recipes/swarmprom.md
- Turtle Pool: recipes/turtle-pool.md
- Chef's Favorites (Kubernetes):
- Kanboard: recipes/kubernetes/kanboard.md
- Miniflux: recipes/kubernetes/miniflux.md
# - NextCloud: recipes/kubernetes/nextcloud.md
# - phpIPAM: recipes/kubernetes/phpipam.md
# - PrivateBin: recipes/kubernetes/privatebin.md
- Menu:
- Bitwarden: recipes/bitwarden.md
- Bookstack: recipes/bookstack.md
- CryptoMiner:
- Start: recipes/cryptominer.md
- Mining Rig: recipes/cryptominer/mining-rig.md
- AMD GPU: recipes/cryptominer/amd-gpu.md
- NVidia GPU: recipes/cryptominer/nvidia-gpu.md
- Mining Pools : recipes/cryptominer/mining-pool.md
- Wallets : recipes/cryptominer/wallet.md
- Exchanges: recipes/cryptominer/exchange.md
- Minerhotel: recipes/cryptominer/minerhotel.md
- Monitoring: recipes/cryptominer/monitor.md
- Profit!: recipes/cryptominer/profit.md
- Calibre-Web: recipes/calibre-web.md
- Collabora Online: recipes/collabora-online.md
- Ghost: recipes/ghost.md
- GitLab: recipes/gitlab.md
- GitLab Runner: recipes/gitlab-runner.md
- Gollum: recipes/gollum.md
- InstaPy: recipes/instapy.md
- KeyCloak:
- Start: recipes/keycloak.md
- Users: recipes/keycloak/create-user.md
- OIDC Provider: recipes/keycloak/setup-oidc-provider.md
- OpenLDAP: recipes/keycloak/authenticate-against-openldap.md
- Minio: recipes/minio.md
- OpenLDAP: recipes/openldap.md
- Piwik: recipes/piwik.md
- Portainer: recipes/portainer.md
- Realms: recipes/realms.md
- Tiny Tiny RSS: recipes/tiny-tiny-rss.md
- Traefik: ha-docker-swarm/traefik.md
- Traefik Forward Auth:
- Start: ha-docker-swarm/traefik-forward-auth.md
- KeyCloak: ha-docker-swarm/traefik-forward-auth/keycloak.md
- Wallabag: recipes/wallabag.md
- Wekan: recipes/wekan.md
- Wetty: recipes/wetty.md
- Work-in-Progress:
# - MatterMost: recipes/mattermost.md
- IPFS Cluster: recipes/ipfs-cluster.md
- MQTT: recipes/mqtt.md
# - HackMD: recipes/hackmd.md
# - Mastodon: recipes/mastodon.md
# - Mayan EDMS: recipes/mayan-edms.md
# - Shaarli: recipes/shaarli.md
# - UniFi Controller: recipes/unifi-controller.md
# - CyberChef : recipes/cyberchef.md
- Reference:
- OAuth Proxy: reference/oauth_proxy.md
- Data Layout: reference/data_layout.md
- Networks: reference/networks.md
- Containers: reference/containers.md
- git-docker : reference/git-docker.md
- OpenVPN : reference/openvpn.md
- Troubleshooting: reference/troubleshooting.md
- Support: support.md
- Sponsored Projects: sponsored-projects.md
theme:
name: 'material'
@@ -165,13 +169,13 @@ theme:
logo: 'images/site-logo.png'
favicon: 'images/favicon.ico'
feature:
tabs: false
tabs: true
palette:
primary: 'brown'
primary: 'black'
accent: 'indigo'
font:
text: 'Roboto'
code: 'Roboto Mono'
text: 'Ubuntu'
code: 'Ubuntu Mono'
social:
- type: 'github'
link: 'https://github.com/funkypenguin'

2
scripts/serve.sh Executable file
View File

@@ -0,0 +1,2 @@
#!/bin/bash
docker run --rm --name mkdocs-material -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material