talos-cluster

个人自用的 Talos Kubernetes 集群仓库。

🚀 当前架构

• 操作系统：Talos Linux
• Kubernetes GitOps：Flux
• 网络：Cilium、Cloudflare Tunnel、Tailscale
• Secret 管理：SOPS + age、External Secrets、Bitwarden Connect
• 观测：kube-prometheus-stack、Grafana、Loki、Thanos、Gatus、Uptime Kuma
• 存储：Topolvm、Volsync、snapshot-controller、NFS CSI、local-path-provisioner

仓库里的应用已经按 namespace / domain 分组放在 kubernetes/apps/ 下，当前主要包括：

• kube-system：Cilium、CoreDNS、metrics-server、node-feature-discovery、system-upgrade
• flux-system：flux-operator、flux-instance
• network：cloudflare-tunnel、adguard-dns、k8s-gateway、smtp-relay、tailscale
• observability：Grafana、Prometheus、Loki、Thanos、Gatus、promtail
• storage：Topolvm、Volsync、NFS CSI、snapshot-controller、Nextcloud
• default：一批个人业务应用，例如 Gitea、Paperless、Navidrome、Jellyfin、qBittorrent、RSSHub、n8n、Ollama 等

🗂️ 目录说明

.
├── bootstrap/              # 集群首次引导时直接安装的 Helm charts
├── kubernetes/
│   ├── apps/               # Flux 管理的应用清单
│   ├── components/         # 通用组件与复用片段
│   └── flux/               # Flux cluster/meta kustomization
├── scripts/                # bootstrap 脚本
├── talos/
│   ├── talconfig.yaml      # Talhelper 主配置
│   ├── talenv.yaml         # Talos / Kubernetes 版本
│   ├── clusterconfig/      # 生成后的 talos 配置
│   └── patches/            # Talos 机器级 patch
├── .taskfiles/             # task 子命令定义
└── Taskfile.yaml           # 常用入口

🧰 本地依赖

仓库用 mise 管理工具链，见 .mise.toml。

初始化本地环境：

mise trust
mise install

常用 CLI：

• task
• talhelper
• talosctl
• kubectl
• flux
• helmfile
• sops
• age
• yq

mise 还会自动设置这些环境变量：

• KUBECONFIG=./kubeconfig
• TALOSCONFIG=./talos/clusterconfig/talosconfig
• SOPS_AGE_KEY_FILE=./age.key

🛠️ 引导流程

1. ⚙️ 准备 Talos 配置

当前仓库直接维护 talos/talconfig.yaml 和 talos/talenv.yaml，而不是依赖旧模版里的生成流程。

修改时通常关注：

• 节点定义、IP、VIP、磁盘选择器
• Talos / Kubernetes 版本
• machine patches
• 自定义 inline manifests

如果只想重新生成 Talos 配置：

task talos:generate-config

2. 🚧 引导 Talos 集群

首次安装：

task bootstrap:talos

这个任务会：

• 生成或复用 talos/talsecret.sops.yaml
• 运行 talhelper genconfig
• 将 machine config apply 到节点
• 执行 Talos bootstrap
• 导出 kubeconfig

3. 📦 引导基础组件

Talos 可用后，执行：

task bootstrap:apps

这个流程由 scripts/bootstrap-apps.sh 完成，主要会：

• 等待节点进入可继续安装的状态
• 创建所需 namespace
• 预先应用 SOPS secrets
• 安装必要 CRD
• 用 bootstrap/helmfile.yaml 同步首批 Helm releases

当前 bootstrap 阶段直接安装的核心组件有：

• Cilium
• CoreDNS
• cert-manager
• flux-operator
• flux-instance

之后由 Flux 持续接管 kubernetes/apps/ 下的资源。

🔧 日常运维

强制同步 Flux：

task reconcile

单节点重刷 Talos 配置：

task talos:apply-node IP=<node-ip>

升级单个节点 Talos：

task talos:upgrade-node IP=<node-ip>

按 talos/talenv.yaml 升级 Kubernetes：

task talos:upgrade-k8s

重置整个 Talos 集群：

task talos:reset

🔐 Secret 管理

仓库使用 SOPS + age：

• talos/*.sops.yaml：整文件加密
• bootstrap/、kubernetes/ 下的 *.sops.yaml：只加密 data / stringData

规则见 .sops.yaml。

修改 secret 后，提交前至少确认：

• 文件仍然是加密态
• age.key 与集群中的 sops-age secret 对应
• Flux 能正常解密 kubernetes/components/common/sops/ 下资源

📝 备注

• 项目最初通过 onedr0p/cluster-template 初始化。
• talos/patches/ 里的 patch 会被 talhelper 合并进最终 machine config。
• 仓库中包含不少强绑定个人环境的配置，复用时应先清理网络、域名、凭据和应用清单。