0xWheatyz/Talos
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update all documentation to reflect Gitea and FluxCD

Browse Source 
Replace all GitLab references with Gitea and add comprehensive
FluxCD GitOps workflow documentation.

Major changes:
- CLAUDE.md: Replace GitLab sections with Gitea management
- CLAUDE.md: Add FluxCD operations and troubleshooting
- CLAUDE.md: Update repository structure and GitOps workflow
- CLAUDE.md: Add Gitea Actions runner configuration guide
- APP_DEPLOYMENT.md: Replace GitLab examples with Gitea
- APP_DEPLOYMENT.md: Add FluxCD deployment workflow
- APP_DEPLOYMENT.md: Include Gitea Actions CI/CD examples
- README.md: Complete rewrite with project overview
- README.md: Add GitOps workflow explanation
- README.md: Include architecture and common commands

Removed:
- All GitLab-specific commands and examples
- References to removed scripts (redeploy-gitlab.sh)

Added:
- Gitea Actions runner setup and configuration
- FluxCD sync monitoring and troubleshooting
- GitOps best practices and workflow guides

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
0xWheatyz 2026-03-04 02:20:10 +00:00
parent f8e5b20381
commit f8870e59f4
3 changed files with 613 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

293
APP_DEPLOYMENT.md
View File

@ -1,48 +1,72 @@
# Application Deployment Guide
This guide explains how to deploy applications to your Talos Kubernetes cluster following the GitOps structure used in this repository.
This guide explains how to deploy applications to your Talos Kubernetes cluster using the GitOps workflow with FluxCD.
## Directory Structure
Applications are organized in the `testing1/first-cluster/apps/` directory:
Applications are organized in the `testing1/first-cluster/` directory:
```
testing1/first-cluster/
├── cluster/
│ └── base/ # Cluster-level resources (namespaces, RBAC, etc.)
│ ├── base/ # Cluster-level resources (namespaces, RBAC, etc.)
│ ├── flux/ # FluxCD GitOps configuration
│ ├── metallb/ # MetalLB load balancer
│ └── nfs-provisioner/ # NFS storage provisioner
└── apps/
├── demo/ # Example nginx app
│ ├── nginx-deployment.yaml
│ └── nginx-service.yaml
└── gitlab/ # GitLab with Container Registry
└── gitea/ # Gitea with CI/CD Runner
├── namespace.yaml
├── pvc.yaml
├── configmap.yaml
├── deployment.yaml
├── service.yaml
├── runner-secret.yaml
├── runner-configmap.yaml
├── runner-deployment.yaml
└── kustomization.yaml
```
## Deploying Applications
### Method 1: Direct kubectl apply
**IMPORTANT**: This cluster uses FluxCD for GitOps automation. All changes committed to the `main` branch in Gitea are automatically deployed to the cluster.
Apply individual app manifests:
### Method 1: GitOps (Recommended)
This is the preferred method for all deployments:
1. Add or modify manifests in `testing1/first-cluster/apps/<app-name>/`
2. Commit and push to Gitea:
```bash
git add testing1/first-cluster/apps/<app-name>/
git commit -m "feat: deploy <app-name>"
git push origin main
```
3. Flux automatically applies changes within 1-5 minutes
4. Monitor deployment:
```bash
flux get kustomizations
kubectl get all -n <namespace> -w
```
### Method 2: Manual kubectl apply (For Testing Only)
For testing changes before committing to Git:
```bash
# Deploy a specific app
kubectl apply -f testing1/first-cluster/apps/gitlab/
kubectl apply -f testing1/first-cluster/apps/<app-name>/
# Or use kustomize
kubectl apply -k testing1/first-cluster/apps/gitlab/
kubectl apply -k testing1/first-cluster/apps/<app-name>/
```
### Method 2: Using kustomize (Recommended)
**Remember**: Manual changes will be overwritten when Flux next reconciles. Always commit working configurations to Git.
Each app directory can contain a `kustomization.yaml` file that lists all resources:
### Using Kustomize
Each app directory should contain a `kustomization.yaml` file that lists all resources:
```yaml
apiVersion: kustomize.config.k8s.io/v1beta1
@ -54,11 +78,6 @@ resources:
- service.yaml
```
Deploy with:
```bash
kubectl apply -k testing1/first-cluster/apps/<app-name>/
```
## Adding a New Application
Follow these steps to add a new application to your cluster:
@ -217,7 +236,7 @@ kubectl apply -k testing1/first-cluster/apps/<app-name>/
kubectl get all -n <app-name>
```
## GitLab Deployment Example
## Gitea Deployment Example
### Prerequisites
@ -236,85 +255,152 @@ kubectl get all -n <app-name>
./install-local-path-storage.sh
```
Without a storage provisioner, GitLab's PersistentVolumeClaims will remain in Pending state and pods won't start.
Without a storage provisioner, Gitea's PersistentVolumeClaims will remain in Pending state and pods won't start.
### Deploy GitLab
### Deploy Gitea (GitOps Method)
1. **Update the runner registration token** in `testing1/first-cluster/apps/gitlab/runner-secret.yaml`:
1. **Verify Gitea manifests** in `testing1/first-cluster/apps/gitea/`:
- `namespace.yaml` - Gitea namespace
- `pvc.yaml` - Persistent storage for Git data
- `deployment.yaml` - Gitea application
- `service.yaml` - LoadBalancer service
- `runner-secret.yaml` - Runner registration token (update after Gitea is running)
- `runner-deployment.yaml` - Gitea Actions runner
- `kustomization.yaml` - Kustomize configuration
After GitLab is running, get the registration token from:
- GitLab UI: `Admin Area > CI/CD > Runners > Register an instance runner`
- Or for project runners: `Settings > CI/CD > Runners > New project runner`
2. **Deploy GitLab and Runner**:
2. **Commit and push** (if not already in Git):
```bash
kubectl apply -k testing1/first-cluster/apps/gitlab/
git add testing1/first-cluster/apps/gitea/
git commit -m "feat: deploy Gitea with Actions runner"
git push origin main
```
3. **Wait for GitLab to be ready** (this can take 5-10 minutes):
3. **Monitor deployment** (Flux will auto-deploy):
```bash
kubectl get pods -n gitlab -w
# Watch Flux sync
flux get kustomizations -w
# Watch pods come up
kubectl get pods -n gitea -w
```
4. **Access GitLab**:
- GitLab UI: `http://<any-node-ip>:30080`
- SSH: `<any-node-ip>:30022`
- Container Registry: `http://<any-node-ip>:30500`
4. **Access Gitea** (after pods are ready):
- Gitea UI: `http://10.0.1.10` (via MetalLB) or `http://<node-ip>:30300`
- SSH: `10.0.1.10:22` or `<node-ip>:30222`
5. **Get initial root password**:
5. **Complete Gitea Installation**:
- Access the UI
- Complete the installation wizard (use SQLite for simplicity)
- Create an admin account
- Create your first repository
6. **Enable Gitea Actions**:
- Go to: Site Administration > Configuration
- Find "Actions" section
- Enable Actions
- Save configuration
### Configure Gitea Actions Runner
1. **Get Runner Registration Token**:
- Go to Gitea UI: Site Administration > Actions > Runners
- Click "Create new Runner"
- Copy the registration token
2. **Update Runner Secret** (GitOps method):
```bash
kubectl exec -n gitlab deployment/gitlab -- grep 'Password:' /etc/gitlab/initial_root_password
# Edit the secret file
nano testing1/first-cluster/apps/gitea/runner-secret.yaml
# Replace REPLACE_WITH_GITEA_RUNNER_TOKEN with your actual token
# Then commit and push
git add testing1/first-cluster/apps/gitea/runner-secret.yaml
git commit -m "chore: update Gitea runner token"
git push origin main
# Or update directly (non-GitOps):
kubectl create secret generic runner-secret \
--from-literal=token='YOUR_TOKEN' \
-n gitea --dry-run=client -o yaml | kubectl apply -f -
```
6. **Configure GitLab Runner**:
- Login to GitLab
- Get the runner registration token
- Update `runner-secret.yaml` with the token
- Re-apply the secret:
```bash
kubectl apply -f testing1/first-cluster/apps/gitlab/runner-secret.yaml
```
- Restart the runner:
```bash
kubectl rollout restart deployment/gitlab-runner -n gitlab
```
### Using the Container Registry
1. **Login to the registry**:
3. **Restart Runner** (to register with token):
```bash
docker login <node-ip>:30500
kubectl rollout restart deployment/gitea-runner -n gitea
```
2. **Tag and push images**:
4. **Verify Runner Registration**:
```bash
docker tag myapp:latest <node-ip>:30500/mygroup/myapp:latest
docker push <node-ip>:30500/mygroup/myapp:latest
# Check runner logs
kubectl logs -n gitea deployment/gitea-runner -c runner -f
# Check Gitea UI
# Go to: Site Administration > Actions > Runners
# Should see "kubernetes-runner" with status "Idle"
```
3. **Example `.gitlab-ci.yml` for building Docker images**:
```yaml
stages:
- build
- push
### Using Gitea Actions for CI/CD
variables:
DOCKER_DRIVER: overlay2
DOCKER_TLS_CERTDIR: ""
IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
Gitea Actions uses GitHub Actions-compatible workflow syntax. Create `.gitea/workflows/` in your repository.
build:
stage: build
image: docker:24-dind
services:
- docker:24-dind
tags:
- docker
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $IMAGE_TAG .
- docker push $IMAGE_TAG
```
**Example workflow** `.gitea/workflows/build.yaml`:
```yaml
name: Build and Test
on:
push:
branches:
- main
pull_request:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm install
- name: Run tests
run: npm test
- name: Build application
run: npm run build
```
**Example Docker build workflow** `.gitea/workflows/docker.yaml`:
```yaml
name: Build Docker Image
on:
push:
branches:
- main
jobs:
docker-build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Build Docker image
run: |
docker build -t myapp:${{ gitea.sha }} .
docker tag myapp:${{ gitea.sha }} myapp:latest
- name: Save image
run: docker save myapp:latest -o myapp.tar
```
## Resource Sizing Guidelines
@ -425,10 +511,6 @@ kubectl top pods -n <namespace>
./install-local-path-storage.sh
```
- Check PVC events: `kubectl describe pvc <pvc-name> -n <namespace>`
- For GitLab specifically, use the redeploy script:
```bash
./redeploy-gitlab.sh
```
- Verify storage is available on nodes
5. **Storage Provisioner Issues**
@ -436,10 +518,61 @@ kubectl top pods -n <namespace>
- Check provisioner pods: `kubectl get pods -n local-path-storage`
- View provisioner logs: `kubectl logs -n local-path-storage deployment/local-path-provisioner`
6. **FluxCD Not Syncing Changes**
- Check Flux status: `flux get all`
- Check GitRepository status: `flux get sources git`
- Force reconciliation: `flux reconcile kustomization cluster-sync --with-source`
- View Flux logs: `flux logs --level=error`
- Verify Git connectivity: `kubectl describe gitrepository talos-gitops -n flux-system`
7. **Gitea Actions Runner Not Registering**
- Check runner logs: `kubectl logs -n gitea deployment/gitea-runner -c runner -f`
- Verify runner token is correct in secret: `kubectl get secret runner-secret -n gitea -o yaml`
- Ensure Gitea Actions is enabled in Gitea UI
- Check Docker daemon in runner pod: `kubectl logs -n gitea deployment/gitea-runner -c daemon`
## FluxCD GitOps Workflow
This cluster uses FluxCD for automated deployments:
1. **Making Changes**:
- Edit manifests in `testing1/first-cluster/`
- Commit and push to `main` branch in Gitea
- Flux detects changes within 1 minute
- Changes applied within 5 minutes
2. **Monitoring Deployments**:
```bash
# Overall Flux status
flux get all
# Watch for reconciliation
flux get kustomizations -w
# Check specific resources
kubectl get all -n <namespace>
```
3. **Force Immediate Sync**:
```bash
flux reconcile source git talos-gitops
flux reconcile kustomization cluster-sync
```
4. **Troubleshooting Flux**:
```bash
# Check Flux logs
flux logs
# Check specific controller logs
kubectl logs -n flux-system deployment/source-controller
kubectl logs -n flux-system deployment/kustomize-controller
```
## Next Steps
- Set up FluxCD for GitOps automation
- Configure ingress controller for HTTP/HTTPS routing
- Set up monitoring with Prometheus and Grafana
- Implement backup solutions for persistent data
- Configure network policies for security
- Set up SSL/TLS certificates with cert-manager

274
CLAUDE.md
View File

@ -166,42 +166,79 @@ kubectl apply -f testing1/first-cluster/cluster/base/
kubectl apply -f testing1/first-cluster/apps/demo/
# Deploy applications using kustomize
kubectl apply -k testing1/first-cluster/apps/gitlab/
kubectl apply -k testing1/first-cluster/apps/gitea/
kubectl apply -k testing1/first-cluster/apps/<app-name>/
```
### GitLab Management
### FluxCD GitOps Management
FluxCD automatically syncs the cluster with the Git repository. Changes pushed to the `main` branch are automatically applied.
```bash
# Check Flux status
flux get all
# Check GitRepository sync status
flux get sources git
# Check Kustomization status
flux get kustomizations
# Force immediate reconciliation
flux reconcile kustomization cluster-sync --with-source
# View Flux logs
flux logs
# Suspend/resume automatic sync (for maintenance)
flux suspend kustomization cluster-sync
flux resume kustomization cluster-sync
```
### Gitea Management
**Prerequisites**: Storage provisioner must be installed first (see Storage Setup section)
```bash
# Deploy GitLab with Container Registry and Runner
kubectl apply -k testing1/first-cluster/apps/gitlab/
# Deploy Gitea with CI/CD Runner
kubectl apply -k testing1/first-cluster/apps/gitea/
# Check GitLab status
kubectl get pods -n gitlab -w
# Check Gitea status
kubectl get pods -n gitea -w
# Check PVC status (should be Bound)
kubectl get pvc -n gitlab
kubectl get pvc -n gitea
# Get initial root password
kubectl exec -n gitlab deployment/gitlab -- grep 'Password:' /etc/gitlab/initial_root_password
# Access Gitea
# - Gitea UI: http://10.0.1.10 or http://<node-ip>:30300
# - SSH: 10.0.1.10:22 or <node-ip>:30222
# Access GitLab services
# - GitLab UI: http://<node-ip>:30080
# - SSH: <node-ip>:30022
# - Container Registry: http://<node-ip>:30500
# Initial Gitea setup
# 1. Access the UI and complete the installation wizard
# 2. Create an admin account
# 3. Create a repository
# Restart GitLab Runner after updating registration token
kubectl rollout restart deployment/gitlab-runner -n gitlab
# Configure Gitea Runner
# 1. In Gitea UI, go to Site Administration > Actions > Runners
# 2. Create a new runner registration token
# 3. Update the runner secret:
kubectl create secret generic runner-secret \
--from-literal=token='YOUR_RUNNER_TOKEN' \
-n gitea --dry-run=client -o yaml | kubectl apply -f -
# 4. Restart the runner to register with new token
kubectl rollout restart deployment/gitea-runner -n gitea
# Check runner logs
kubectl logs -n gitlab deployment/gitlab-runner -f
kubectl logs -n gitea deployment/gitea-runner -c runner -f
# Check runner status in Gitea UI
# Go to: Site Administration > Actions > Runners
```
### GitLab Troubleshooting
### Gitea Troubleshooting
If GitLab pods are stuck in Pending:
If Gitea pods are stuck in Pending:
```bash
# Check storage issues
@ -209,9 +246,31 @@ If GitLab pods are stuck in Pending:
# If no storage provisioner, install it
./install-local-path-storage.sh
```
# Redeploy GitLab with storage
./redeploy-gitlab.sh
### Flux Troubleshooting
If Flux is not syncing changes:
```bash
# Check GitRepository status
flux get sources git
# Check for authentication issues
kubectl describe gitrepository talos-gitops -n flux-system
# Verify SSH key secret exists
kubectl get secret gitea-ssh -n flux-system
# Check Kustomization status
flux get kustomizations
# View recent reconciliation errors
flux logs --level=error
# Force reconciliation
flux reconcile source git talos-gitops
flux reconcile kustomization cluster-sync
```
## Architecture
@ -221,14 +280,18 @@ If GitLab pods are stuck in Pending:
This is a Talos Kubernetes cluster management repository with the following structure:
- **testing1/** - Active testing cluster configuration
- **controlplane.yaml** - Talos config for control plane nodes (Kubernetes 1.33.0)
- **worker.yaml** - Talos config for worker nodes
- **controlplane-\*.yaml** - Per-node Talos configs for control plane nodes
- **worker.yaml** - Talos config for worker nodes (if applicable)
- **.talosconfig** - Talos client configuration
- **kubeconfig** - Kubernetes client configuration
- **secrets.yaml** - Cluster secrets (keep secure!)
- **first-cluster/** - Kubernetes manifests in GitOps structure
- **cluster/base/** - Cluster-level resources (namespaces, etc.)
- **cluster/flux/** - FluxCD GitOps configuration
- **cluster/metallb/** - MetalLB load balancer configuration
- **cluster/nfs-provisioner/** - NFS storage provisioner
- **apps/demo/** - Application deployments (nginx demo)
- **apps/gitlab/** - GitLab CE with Container Registry and CI/CD Runner
- **apps/gitea/** - Gitea with CI/CD Runner
- **prod1/** - Production cluster placeholder (currently empty)
@ -237,8 +300,8 @@ This is a Talos Kubernetes cluster management repository with the following stru
- **check-cluster-status.sh** - Cluster status diagnostic tool
- **install-local-path-storage.sh** - Install storage provisioner
- **diagnose-storage.sh** - Storage diagnostic tool
- **redeploy-gitlab.sh** - GitLab cleanup and redeployment
- **APP_DEPLOYMENT.md** - Comprehensive guide for deploying applications
- **CLAUDE.md** - This file - development guidance
### Cluster Configuration
@ -250,76 +313,155 @@ The Talos cluster uses:
### GitOps Structure
Kubernetes manifests in `testing1/first-cluster/` follow a GitOps-friendly layout:
This repository uses FluxCD for GitOps automation. Kubernetes manifests in `testing1/first-cluster/` are automatically synced to the cluster.
**Directory Layout:**
- **cluster/** - Cluster infrastructure and base resources
- **flux/** - FluxCD configuration (GitRepository, Kustomization)
- **base/** - Namespaces and cluster-wide resources
- **metallb/** - Load balancer configuration
- **nfs-provisioner/** - Storage provisioner
- **apps/** - Application workloads organized by app name
Each app in `apps/` contains its own deployment and service definitions.
**How FluxCD Works:**
1. FluxCD monitors the Gitea repository at `ssh://git@10.0.1.10/0xWheatyz/Talos`
2. Every 1 minute, it checks for new commits on the `main` branch
3. When changes are detected, Flux applies them to the cluster within 5 minutes
4. Prune is enabled - resources deleted from Git are automatically removed from the cluster
**Making Changes:**
1. Edit manifests in `testing1/first-cluster/`
2. Commit and push to the `main` branch in Gitea
3. Flux automatically applies the changes to the cluster
4. Monitor sync status with `flux get all`
## Configuration Files
When modifying Talos configurations:
1. Edit `testing1/controlplane.yaml` for control plane changes
### Modifying Talos Configurations
When modifying Talos configurations (NOT managed by Flux):
1. Edit `testing1/controlplane-<ip>.yaml` for specific control plane node changes
2. Edit `testing1/worker.yaml` for worker node changes
3. Apply changes using `talosctl apply-config` with the appropriate node IPs
4. Always specify `--nodes` flag to target specific nodes
When adding Kubernetes workloads:
1. Place cluster-level resources in `testing1/first-cluster/cluster/base/`
### Adding/Modifying Kubernetes Workloads (GitOps Workflow)
**Important**: Kubernetes manifests are managed by FluxCD. Changes are automatically synced from Git.
1. Place cluster-level resources in `testing1/first-cluster/cluster/<component>/`
2. Place application manifests in `testing1/first-cluster/apps/<app-name>/`
3. Create a `kustomization.yaml` file to organize resources
4. Apply using `kubectl apply -k testing1/first-cluster/apps/<app-name>/`
5. See `APP_DEPLOYMENT.md` for detailed guide on adding new applications
4. **Commit and push to Git** - Flux will automatically apply changes
5. Monitor deployment: `flux get kustomizations` and `kubectl get all -n <namespace>`
6. See `APP_DEPLOYMENT.md` for detailed guide on adding new applications
**Manual Apply (for testing)**:
If you need to test changes before committing:
```bash
kubectl apply -k testing1/first-cluster/apps/<app-name>/
```
**GitOps Best Practices**:
- Always commit working configurations to Git
- Use feature branches for major changes
- Test changes before pushing to `main`
- Monitor Flux logs when deploying: `flux logs --follow`
## Deployed Applications
### GitLab (testing1/first-cluster/apps/gitlab/)
### Gitea (testing1/first-cluster/apps/gitea/)
GitLab CE deployment with integrated Container Registry and CI/CD runner.
Gitea deployment with integrated CI/CD runner using Gitea Actions (compatible with GitHub Actions).
**Components:**
- **GitLab CE 16.11.1**: Main GitLab instance
- **Container Registry**: Docker image registry (port 5005/30500)
- **GitLab Runner**: CI/CD runner with Docker-in-Docker support
- **Gitea**: Lightweight self-hosted Git service
- **Gitea Act Runner**: CI/CD runner with Docker-in-Docker support for running Actions workflows
**Access:**
- UI: `http://<node-ip>:30080`
- SSH: `<node-ip>:30022`
- Registry: `http://<node-ip>:30500`
- UI: `http://10.0.1.10` (via MetalLB) or `http://<node-ip>:30300`
- SSH: `10.0.1.10:22` (via MetalLB) or `<node-ip>:30222`
**Storage:**
- `gitlab-data`: 50Gi - Git repositories, artifacts, uploads
- `gitlab-config`: 5Gi - Configuration files
- `gitlab-logs`: 5Gi - Application logs
- `gitea-data`: 50Gi - Git repositories, attachments, LFS objects, Actions artifacts
**Initial Setup:**
1. Deploy: `kubectl apply -k testing1/first-cluster/apps/gitlab/`
2. Wait for pods to be ready (5-10 minutes)
3. Get root password: `kubectl exec -n gitlab deployment/gitlab -- grep 'Password:' /etc/gitlab/initial_root_password`
4. Access UI and configure runner registration token
5. Update `testing1/first-cluster/apps/gitlab/runner-secret.yaml` with token
6. Restart runner: `kubectl rollout restart deployment/gitlab-runner -n gitlab`
1. Deploy: `kubectl apply -k testing1/first-cluster/apps/gitea/` (or push to Git - Flux will deploy)
2. Wait for pods to be ready (2-5 minutes)
3. Access the UI and complete the installation wizard
4. Create an admin account
5. Enable Actions: Site Administration > Configuration > Actions > Enable
**CI/CD Configuration:**
**Configuring Gitea Actions Runner:**
1. **Generate Runner Registration Token:**
- Go to Gitea UI: Site Administration > Actions > Runners
- Click "Create new Runner"
- Copy the registration token
2. **Update Runner Secret:**
```bash
# Update the token in the secret
kubectl create secret generic runner-secret \
--from-literal=token='YOUR_REGISTRATION_TOKEN' \
-n gitea --dry-run=client -o yaml | kubectl apply -f -
# Or edit the file and commit to Git (recommended for GitOps):
# Edit testing1/first-cluster/apps/gitea/runner-secret.yaml
# Replace REPLACE_WITH_GITEA_RUNNER_TOKEN with your token
# git add, commit, and push - Flux will update the secret
```
3. **Restart Runner:**
```bash
kubectl rollout restart deployment/gitea-runner -n gitea
```
4. **Verify Runner Registration:**
- Check logs: `kubectl logs -n gitea deployment/gitea-runner -c runner -f`
- Check Gitea UI: Site Administration > Actions > Runners
- You should see "kubernetes-runner" with status "Idle"
**CI/CD Configuration (Gitea Actions):**
The runner is configured for building Docker images with:
- Executor: Docker
- Privileged mode enabled
- Access to host Docker socket
- Tags: `docker`, `kubernetes`, `dind`
- Docker-in-Docker (DinD) support
- Labels: `ubuntu-latest`, `ubuntu-22.04`
- Base image: `node:20-bullseye`
Example `.gitlab-ci.yml` for building container images:
Example `.gitea/workflows/build.yaml` for building container images:
```yaml
stages:
- build
name: Build Docker Image
build-image:
stage: build
image: docker:24-dind
tags:
- docker
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG .
- docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Build Docker image
run: |
docker build -t myapp:${{ gitea.sha }} .
docker tag myapp:${{ gitea.sha }} myapp:latest
- name: Push to registry
run: |
echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login -u "${{ secrets.REGISTRY_USER }}" --password-stdin registry.example.com
docker push myapp:${{ gitea.sha }}
docker push myapp:latest
```
**Runner Labels Configured:**
- `ubuntu-latest` → `docker://node:20-bullseye`
- `ubuntu-22.04` → `docker://node:20-bullseye`
You can customize these labels in `testing1/first-cluster/apps/gitea/runner-deployment.yaml` under `GITEA_RUNNER_LABELS`.

249
README.md
View File

@ -1,93 +1,228 @@
# talos
# Talos Kubernetes Cluster
A GitOps-managed Talos Kubernetes cluster with automated deployments using FluxCD and Gitea.
## Overview
## Getting started
This repository contains the complete configuration and manifests for a Talos Kubernetes cluster, including:
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
- **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
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
## Quick Start
## Add your files
### Prerequisites
- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
- [ ] [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
- 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
```
cd existing_repo
git remote add origin http://git/0xWheatyz/talos.git
git branch -M main
git push -uf origin main
### 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
```
## Integrate with your tools
## Repository Structure
- [ ] [Set up project integrations](http://git/0xWheatyz/talos/-/settings/integrations)
```
.
├── 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
```
## Collaborate with your team
## Deployed Applications
- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
- [ ] [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
### Gitea
## Test and Deploy
Self-hosted Git service with Actions for CI/CD.
Use the built-in continuous integration in GitLab.
- **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
- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/)
- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
### FluxCD
***
GitOps continuous delivery operator.
# Editing this README
- **Repository**: ssh://git@10.0.1.10/0xWheatyz/Talos
- **Branch**: main
- **Sync Path**: testing1/first-cluster/
- **Interval**: 1m (git poll), 5m (reconciliation)
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
## Common Commands
## Suggestions for a good README
### Cluster Management
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
```bash
# Check cluster health
talosctl health
## Name
Choose a self-explaining name for your project.
# Get cluster nodes
kubectl get nodes
## Description
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
# Check all resources
kubectl get all -A
```
## Badges
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
### FluxCD Operations
## Visuals
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
```bash
# Check Flux status
flux get all
## Installation
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
# Force immediate sync
flux reconcile kustomization cluster-sync --with-source
## Usage
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
# View Flux logs
flux logs --follow
```
## Support
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
### Gitea Management
## Roadmap
If you have ideas for releases in the future, it is a good idea to list them in the README.
```bash
# Check Gitea status
kubectl get all -n gitea
## Contributing
State if you are open to contributions and what your requirements are for accepting them.
# View Gitea logs
kubectl logs -n gitea deployment/gitea -f
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
# Check Actions runner
kubectl logs -n gitea deployment/gitea-runner -c runner -f
```
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
## Development
## Authors and acknowledgment
Show your appreciation to those who have contributed to the project.
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
For open source projects, say how it is licensed.
## Project status
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
MIT
## Contributing
This is a personal cluster management repository. Feel free to use it as a template for your own Talos clusters.