# Talos Home Cluster

## Cluster Information

- **Cluster Name**: home-cluster
- **Kubernetes Version**: v1.36.1
- **Control Plane Nodes**: 3 (10.0.15.1-3)
- **Worker Nodes**: 4 (10.0.15.4-7)
- **Bare Metal Worker**: talos4 at 10.0.15.7 (HP t620)
- **API Endpoint**: https://10.0.15.1:6443

## Node Details

| Node Name | Role | IP | Proxmox Node | VMID |
|-----------|------|-----|--------------|------|
| talos-cp1 | Control Plane | 10.0.15.1 | node1 | 200 |
| talos-cp2 | Control Plane | 10.0.15.2 | node2 | 201 |
| talos-cp3 | Control Plane | 10.0.15.3 | node3 | 202 |
| talos-worker1 | Worker | 10.0.15.4 | node1 | 210 |
| talos-worker2 | Worker | 10.0.15.5 | node2 | 211 |
| talos-worker3 | Worker | 10.0.15.6 | node3 | 212 |
| talos4 | Worker | 10.0.15.7 | bare-metal (HP t620) | — |

## Configuration Files

- `secrets.yaml` - Cluster secrets (keep secure!)
- `controlplane.yaml` - Base control plane config (applied with per-node patches)
- `worker.yaml` - Base worker config (applied with per-node patches)
- `patches/*.yaml` - Per-node patches (hostname, disk overrides)
- `talosconfig` - Talosctl client configuration

## Using the Cluster

### Talosctl Commands

```bash
# Check cluster health
talosctl --talosconfig talosconfig health

# Get node list
talosctl --talosconfig talosconfig get members

# View logs from a node
talosctl --talosconfig talosconfig logs -f kubelet

# Check service status
talosctl --talosconfig talosconfig service

# Upgrade Talos (example)
talosctl --talosconfig talosconfig upgrade --image ghcr.io/siderolabs/installer:v1.13.3
```

### Kubectl Commands

The kubeconfig has been merged into your default kubectl config:

```bash
# View nodes
kubectl get nodes

# View all pods
kubectl get pods -A

# View cluster info
kubectl cluster-info
```

## Storage Configuration

VM boot disks are stored on local-lvm on each Proxmox node (no shared Ceph storage). For Kubernetes persistent storage, deploy a CSI provisioner (e.g. Rook-Ceph, OpenEBS, or cloud provider CSI).

## Networking

- **CNI**: Flannel (deployed by default)
- **Service CIDR**: Default Kubernetes range
- **Pod CIDR**: Default Kubernetes range

## Maintenance

### Adding a Node

1. Clone VM from template in Terraform
2. Create a per-node patch in `patches/` with the hostname
3. Apply base config with patch:
   ```bash
   talosctl --talosconfig talosconfig apply-config --insecure --nodes <NEW_NODE_IP> --file worker.yaml --config-patch @patches/<new-node>.yaml
   ```

### Removing a Node

```bash
# Drain node first
kubectl drain <node-name> --ignore-daemonsets --delete-emptydir-data

# Remove from cluster
kubectl delete node <node-name>

# Reset Talos on the node
talosctl --talosconfig talosconfig reset --nodes <NODE_IP>
```

### Upgrading Kubernetes

```bash
talosctl --talosconfig talosconfig upgrade-k8s --to 1.36.1
```

## Troubleshooting

### Node not joining cluster

```bash
# Check node logs
talosctl --talosconfig talosconfig logs -f kubelet --nodes <NODE_IP>

# Check etcd members
talosctl --talosconfig talosconfig etcd members
```

### Reset a Node

```bash
talosctl --talosconfig talosconfig reset --nodes <NODE_IP> --graceful=false
```

### Reboot a Node

```bash
talosctl --talosconfig talosconfig reboot --nodes <NODE_IP>
```

## Backup

Important files to backup:
- `secrets.yaml` - Required to add nodes or recover cluster
- `talosconfig` - Required for talosctl access
- `controlplane.yaml` and `worker.yaml` - Base node configs
- `patches/` directory - Per-node patches
- Kubeconfig is stored in `~/.kube/config`

Store these securely in a password manager or encrypted backup.