Talos Kubernetes Cluster

A GitOps-managed Talos Kubernetes cluster with automated deployments using FluxCD and Gitea.

Overview

This repository contains the complete configuration and manifests for a Talos Kubernetes cluster, including:

• Talos Linux: Immutable Kubernetes OS
• FluxCD: GitOps continuous delivery
• Gitea: Self-hosted Git service with Actions (CI/CD)
• MetalLB: Bare metal load balancer
• Storage: NFS and local-path provisioners

Quick Start

Prerequisites

• Nix package manager (for development shell)
• 3 nodes for Talos cluster (control planes)
• Network access to nodes: 10.0.1.3, 10.0.1.4, 10.0.1.5

Initial Setup

1. Enter development environment:

   nix-shell
   

2. Bootstrap the cluster:

   ./bootstrap-cluster.sh
   

3. Verify cluster health:

   kubectl get nodes
   talosctl health
   

4. Install storage provisioner:

   ./install-local-path-storage.sh
   

GitOps Workflow

This cluster uses FluxCD for automated deployments from Gitea.

How It Works

1. You push changes to the main branch in Gitea
2. FluxCD detects changes within 1 minute
3. Changes are automatically applied to the cluster within 5 minutes
4. Resources deleted from Git are pruned from the cluster

Making Changes

# Edit Kubernetes manifests
nano testing1/first-cluster/apps/<app-name>/deployment.yaml

# Commit and push
git add .
git commit -m "feat: update deployment"
git push origin main

# Monitor deployment
flux get kustomizations -w
kubectl get all -n <namespace> -w

Repository Structure

.
├── testing1/                          # Active cluster configuration
│   ├── first-cluster/                 # Kubernetes manifests (GitOps)
│   │   ├── cluster/                   # Cluster infrastructure
│   │   │   ├── base/                  # Namespaces, RBAC
│   │   │   ├── flux/                  # FluxCD configuration
│   │   │   ├── metallb/               # Load balancer
│   │   │   └── nfs-provisioner/       # NFS storage
│   │   └── apps/                      # Applications
│   │       ├── demo/                  # Nginx demo
│   │       └── gitea/                 # Gitea + CI/CD runner
│   ├── .talosconfig                   # Talos client config
│   ├── kubeconfig                     # Kubernetes client config
│   └── secrets.yaml                   # Cluster secrets (do not commit!)
├── shell.nix                          # Nix development environment
├── bootstrap-cluster.sh               # Cluster bootstrap script
├── CLAUDE.md                          # Development guide
└── APP_DEPLOYMENT.md                  # Application deployment guide

Deployed Applications

Gitea

Self-hosted Git service with Actions for CI/CD.

• Access: http://10.0.1.10 or http://<node-ip>:30300
• SSH: 10.0.1.10:22 or <node-ip>:30222
• Storage: 50Gi PVC for Git repositories and artifacts

FluxCD

GitOps continuous delivery operator.

• Repository: ssh://git@10.0.1.10/0xWheatyz/Talos
• Branch: main
• Sync Path: testing1/first-cluster/
• Interval: 1m (git poll), 5m (reconciliation)

Common Commands

Cluster Management

# Check cluster health
talosctl health

# Get cluster nodes
kubectl get nodes

# Check all resources
kubectl get all -A

FluxCD Operations

# Check Flux status
flux get all

# Force immediate sync
flux reconcile kustomization cluster-sync --with-source

# View Flux logs
flux logs --follow

Gitea Management

# Check Gitea status
kubectl get all -n gitea

# View Gitea logs
kubectl logs -n gitea deployment/gitea -f

# Check Actions runner
kubectl logs -n gitea deployment/gitea-runner -c runner -f

Development

See CLAUDE.md for detailed development guidance, including:

• Cluster bootstrap procedures
• Storage setup
• Talos and Kubernetes commands
• Troubleshooting guides

See APP_DEPLOYMENT.md for application deployment examples and best practices.

Architecture

• Kubernetes: 1.33.0
• Talos Linux: Latest
• Control Planes: 3 nodes (10.0.1.3, 10.0.1.4, 10.0.1.5)
• GitOps: FluxCD v2.7.3
• Load Balancer: MetalLB (10.0.1.10-10.0.1.20)
• Storage: Local-path and NFS provisioners

Troubleshooting

Cluster Issues

# Check cluster status
./check-cluster-status.sh

# View Talos logs
talosctl logs --tail

# Check Kubernetes events
kubectl get events -A --sort-by='.lastTimestamp'

Storage Issues

# Diagnose storage
./diagnose-storage.sh

# Check storage class
kubectl get storageclass

# View provisioner logs
kubectl logs -n local-path-storage deployment/local-path-provisioner

FluxCD Issues

# Check Git sync status
flux get sources git

# Check Kustomization status
flux get kustomizations

# View error logs
flux logs --level=error

Security Notes

• secrets.yaml: Contains cluster secrets, never commit to public repositories
• SSH keys: Flux uses SSH key authentication (stored in gitea-ssh secret)
• Runner tokens: Gitea runner registration token stored in runner-secret

License

MIT

Contributing

This is a personal cluster management repository. Feel free to use it as a template for your own Talos clusters.