From 2a59555c3b5a787afb0038db0f95789dc483f2bf Mon Sep 17 00:00:00 2001 From: Lumpiasty Date: Mon, 2 Mar 2026 19:27:12 +0100 Subject: [PATCH] Add more README --- README.md | 33 +++++++++++++++++++++++++++++++++ docs/assets/cilium.svg | 16 ++++++++++++++++ docs/assets/flux.svg | 22 ++++++++++++++++++++++ docs/assets/openebs.svg | 1 + 4 files changed, 72 insertions(+) create mode 100644 docs/assets/cilium.svg create mode 100644 docs/assets/flux.svg create mode 100644 docs/assets/openebs.svg diff --git a/README.md b/README.md index 6073881..5b982d4 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,8 @@ Currently the k8s cluster consists of single node (hostname anapistula-delrosala The cluster itself is based on [Talos Linux](https://www.talos.dev/) (which is also a Kubernetes distribution) and uses [Cilium](https://cilium.io/) as CNI, IPAM, kube-proxy replacement, Load Balancer, and BGP control plane. Persistent volumes are managed by [OpenEBS LVM LocalPV](https://openebs.io/docs/user-guides/local-storage-user-guide/local-pv-lvm/lvm-overview). Applications are deployed using GitOps (this repo) and reconciled on cluster using [Flux](https://fluxcd.io/). Git repository is hosted on [Gitea](https://gitea.io/) running on a cluster itself. Secets are kept in [OpenBao](https://openbao.org/) (HashiCorp Vault fork) running on a cluster and synced to cluster objects using [Vault Secrets Operator](https://github.com/hashicorp/vault-secrets-operator). Deployments are kept up to date using self hosted [Renovate](https://www.mend.io/renovate/) bot updating manifests in the Git repository. Incoming HTTP traffic is routed to cluster using [Nginx Ingress Controller](https://kubernetes.github.io/ingress-nginx/) and certificates are issued by [cert-manager](https://cert-manager.io/) with [Let's Encrypt](https://letsencrypt.org/) ACME issuer with [cert-manager-webhook-ovh](https://github.com/aureq/cert-manager-webhook-ovh) resolving DNS-01 challanges. Cluster also runs [CloudNativePG](https://cloudnative-pg.io/) operator for managing PostgreSQL databases. High level core cluster software architecture is shown on the diagram below. +> Talos Linux is an immutable Linux distribution purpose-built for running Kubernetes. The OS is distributed as an OCI (Docker) image and does not contain any package manager, shell, SSH, or any other tools for managing the system. Instead, all operations are performed using API, which can be accessed using `talosctl` CLI tool. + ```mermaid flowchart TD router[MikroTik Router] @@ -189,6 +191,9 @@ flowchart TD | Logo | Name | Address | Description | |------|------|---------|-------------| +| Flux CD | Flux CD | | GitOps operator for reconciling cluster state with Git repository | +| Cilium | Cilium | | CNI, BGP control plane, kube-proxy replacement and Load Balancer for cluster networking | +| OpenEBS | OpenEBS LVM LocalPV | | Container Storage Interface for managing persistent volumes on local LVM pools | | Gitea | Gitea | https://gitea.lumpiasty.xyz/ | Private Git repository hosting and artifact storage (Docker, Helm charts) | | OpenBao | OpenBao | https://openbao.lumpiasty.xyz:8200/ | Secret storage (HashiCorp Vault compatible) | | Renovate | Renovate | | Bot for keeping dependencies up to date | @@ -201,3 +206,31 @@ flowchart TD | Open WebUI | Open WebUI | https://openwebui.lumpiasty.xyz/ | Web UI for chatting with LLMs running on the cluster | | Frigate | Frigate | https://frigate.lumpiasty.xyz/ | NVR for camera system with AI object detection and classification | + +## Development + +This repo leverages [devenv](https://devenv.sh/) for easy setup of a development environment. Install devenv, clone this repo and run `devenv shell` to make the tools and enviornment variables available in your shell. Alternatively, you can use direnv to automate enabling enviornment after entering directory in your shell. You can also install [direnv extension](https://marketplace.visualstudio.com/items?itemName=mkhl.direnv) in VSCode to automatically set up environment after opening workspace so all the fancy intellisense and extensions detect stuff correctly. + +### App deployment + +This repo is being watched by Flux running on cluster. To change config/add new app, simply commit to this repo and wait a while for cluster to reconcile changes. You can speed up this process by "notifying" Flux using `flux reconcile source git flux-system`. + +Flux watches 3 kustomizations in this repo: + +- flux-system - [cluster/flux-system](cluster/flux-system) directory, contains flux manifests +- infra - [infra](infra) directory, contains cluster infrastructure manifests like storage classes, network policies, monitoring etc. +- apps - [apps](apps) directory, contains manifests for applications deployed on cluster + +### Talos config changes + +Talos config in this repo is stored as yaml patches under [talos/patches](talos/patches) directory. Those patches can then be compiled into full Talos config files using `make gen-talos-config` command. Full config can then be applied to cluster using `make apply-talos-config` command, which applies config to all nodes in cluster. + +To compile config, you need to have secrets file, which contains certificates and keys for cluster. Those secrets are then incorporated into final config files. That is also why we can not store full config in repo. + +### Kube API access + +To generate kubeconfig for accessing cluster API, run `make get-kubeconfig` command, which will generate kubeconfig under `talos/generated/kubeconfig` path. Devenv automatically sets `KUBECONFIG` enviornment variable to point to this file, so you can start using `kubectl` right away. + +Like above, you need secrets file to generate kubeconfig. + + \ No newline at end of file diff --git a/docs/assets/cilium.svg b/docs/assets/cilium.svg new file mode 100644 index 0000000..bfeb664 --- /dev/null +++ b/docs/assets/cilium.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/docs/assets/flux.svg b/docs/assets/flux.svg new file mode 100644 index 0000000..36ad500 --- /dev/null +++ b/docs/assets/flux.svg @@ -0,0 +1,22 @@ + + + + flux-icon + Created with Sketch. + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/assets/openebs.svg b/docs/assets/openebs.svg new file mode 100644 index 0000000..9361bd9 --- /dev/null +++ b/docs/assets/openebs.svg @@ -0,0 +1 @@ + \ No newline at end of file