Talos/README.md

# 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**:
   ```bash
   nix-shell
   ```

2. **Bootstrap the cluster**:
   ```bash
   ./bootstrap-cluster.sh
   ```

3. **Verify cluster health**:
   ```bash
   kubectl get nodes
   talosctl health
   ```

4. **Install storage provisioner**:
   ```bash
   ./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

```bash
# 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://&lt;node-ip&gt;:30300
- **SSH**: 10.0.1.10:22 or &lt;node-ip&gt;: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

```bash
# Check cluster health
talosctl health

# Get cluster nodes
kubectl get nodes

# Check all resources
kubectl get all -A
```

### FluxCD Operations

```bash
# Check Flux status
flux get all

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

# View Flux logs
flux logs --follow
```

### Gitea Management

```bash
# 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](CLAUDE.md) for detailed development guidance, including:
- Cluster bootstrap procedures
- Storage setup
- Talos and Kubernetes commands
- Troubleshooting guides

See [APP_DEPLOYMENT.md](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

```bash
# 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

```bash
# 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

```bash
# 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.