From 45dfbfcfbbba743e44e706e5422e92a958ac9b3f Mon Sep 17 00:00:00 2001 From: gilgamezh Date: Fri, 15 Aug 2025 16:52:10 +0200 Subject: [PATCH] Add ArgoCD and Gitea for GitOps workflow implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Deploy ArgoCD with Helm for GitOps continuous delivery * Configure LoadBalancer and Ingress access on LAN * Enable ArgoCD Image Updater for automatic "latest" tag updates * Simplified RBAC for single-user homelab environment - Deploy Gitea as self-hosted Git server for local repositories * PostgreSQL backend with NFS persistent storage * SSH and HTTP access via MetalLB LoadBalancer * Integration guides for ArgoCD GitOps workflows - Add example ArgoCD Application with auto-image updates - Include comprehensive migration guides from Helm to GitOps - Maintain compatibility with existing Helm-based deployments 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- argocd-example-app.yaml | 40 ++++++++++ argocd-migration-guide.md | 114 +++++++++++++++++++++++++++ argocd_values.yaml | 66 ++++++++++++++++ gitea-argocd-setup.md | 159 ++++++++++++++++++++++++++++++++++++++ gitea_values.yaml | 117 ++++++++++++++++++++++++++++ 5 files changed, 496 insertions(+) create mode 100644 argocd-example-app.yaml create mode 100644 argocd-migration-guide.md create mode 100644 argocd_values.yaml create mode 100644 gitea-argocd-setup.md create mode 100644 gitea_values.yaml diff --git a/argocd-example-app.yaml b/argocd-example-app.yaml new file mode 100644 index 0000000..0fbda1b --- /dev/null +++ b/argocd-example-app.yaml @@ -0,0 +1,40 @@ +# Example ArgoCD Application with Image Auto-Update +# This demonstrates how to set up your existing Helm applications in ArgoCD +# with automatic "latest" tag updates + +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: plex-example + namespace: argocd + annotations: + # Enable automatic image updates for Plex + argocd-image-updater.argoproj.io/image-list: plex=ghcr.io/k8s-at-home/plex:latest + # Use 'newest-build' strategy for latest images + argocd-image-updater.argoproj.io/plex.update-strategy: newest-build + # Write back to ArgoCD (for testing - production should use git method) + argocd-image-updater.argoproj.io/write-back-method: argocd +spec: + project: default + source: + # Point to your repository (replace with your actual Git repo) + repoURL: https://github.com/munnerz/kube-plex + path: charts/kube-plex + targetRevision: HEAD + helm: + valueFiles: + # This would reference your existing plex_values.yml + # For now, this is just an example structure + - values.yaml + parameters: + - name: image.tag + value: latest + destination: + server: https://kubernetes.default.svc + namespace: plex + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true \ No newline at end of file diff --git a/argocd-migration-guide.md b/argocd-migration-guide.md new file mode 100644 index 0000000..26e2ea0 --- /dev/null +++ b/argocd-migration-guide.md @@ -0,0 +1,114 @@ +# ArgoCD Migration Guide for TuringPi Cluster + +## ArgoCD Access Information + +**Web UI Access:** +- URL: http://192.168.222.25 (LoadBalancer IP) +- Alternative: http://argocd.turing.lan (if you add to your hosts file) +- Username: `admin` +- Password: `fJ3diddVd2yson3W` + +## Migration Strategy + +Your existing Helm-based applications can be migrated to ArgoCD gradually. Here's how: + +### Option 1: Keep Existing Helm + Add GitOps Overlay +1. Keep your current `*_values.yaml` files +2. Create ArgoCD Applications that reference the same charts +3. ArgoCD manages the lifecycle, you keep the familiar structure + +### Option 2: Git-First Approach (Recommended for Production) +1. Commit your values files to a Git repository +2. Use ArgoCD's Git source with `argocd-image-updater` writing back to Git +3. Full GitOps workflow with audit trail + +## Adding Image Auto-Updates to Your Applications + +For any application, add these annotations to the ArgoCD Application manifest: + +```yaml +metadata: + annotations: + # Define which images to track + argocd-image-updater.argoproj.io/image-list: myapp=myregistry/myapp:latest + + # Use newest-build strategy for "latest" tags + argocd-image-updater.argoproj.io/myapp.update-strategy: newest-build + + # Write method: 'argocd' for testing, 'git' for production + argocd-image-updater.argoproj.io/write-back-method: argocd +``` + +## Example: Converting Your Plex Deployment + +Your current command: +```bash +helm upgrade plex kube-plex/charts/kube-plex --values plex_values.yml +``` + +Becomes this ArgoCD Application: +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: plex + namespace: argocd + annotations: + argocd-image-updater.argoproj.io/image-list: plex=ghcr.io/k8s-at-home/plex:latest + argocd-image-updater.argoproj.io/plex.update-strategy: newest-build + argocd-image-updater.argoproj.io/write-back-method: argocd +spec: + project: default + source: + repoURL: https://github.com/munnerz/kube-plex # or your fork + path: charts/kube-plex + targetRevision: HEAD + helm: + valueFiles: + - ../../plex_values.yml # Reference your existing values + destination: + server: https://kubernetes.default.svc + namespace: plex + syncPolicy: + automated: + prune: true + selfHeal: true +``` + +## Quick Start Commands + +1. **Access ArgoCD UI**: Visit http://192.168.222.25 with admin/fJ3diddVd2yson3W + +2. **Create your first application via CLI**: +```bash +# Install ArgoCD CLI (optional) +curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64 +sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd + +# Login (using the LoadBalancer IP) +argocd login 192.168.222.25 --insecure --username admin --password fJ3diddVd2yson3W +``` + +3. **Apply the example application**: +```bash +kubectl apply -f argocd-example-app.yaml +``` + +## Benefits You Get Immediately + +✅ **Keep using Helm** - ArgoCD manages Helm releases +✅ **Auto image updates** - Latest tags update automatically +✅ **Visual UI** - See deployment status, sync state, rollback easily +✅ **GitOps ready** - When you want to commit values to Git +✅ **Rollback capability** - Easy rollback to previous versions +✅ **Multi-environment** - Can manage dev/staging/prod from one place + +## Next Steps + +1. Access the ArgoCD UI and familiarize yourself with it +2. Create ArgoCD Applications for 1-2 of your existing services +3. Test the image auto-update functionality +4. Once comfortable, migrate more applications +5. Consider setting up a Git repository for full GitOps workflow + +Your existing Helm workflow continues to work while you gain GitOps benefits! \ No newline at end of file diff --git a/argocd_values.yaml b/argocd_values.yaml new file mode 100644 index 0000000..cc61432 --- /dev/null +++ b/argocd_values.yaml @@ -0,0 +1,66 @@ +# ArgoCD configuration for TuringPi K3s cluster +# Simplified setup - no RBAC restrictions for single-user environment + +global: + # Set domain for your LAN access + domain: argocd.turing.lan + +# Server configuration +server: + # Enable ingress for web UI access + ingress: + enabled: true + controller: generic + ingressClassName: nginx + hostname: argocd.turing.lan + annotations: + nginx.ingress.kubernetes.io/force-ssl-redirect: "true" + nginx.ingress.kubernetes.io/ssl-passthrough: "true" + # Restrict to LAN access (matching your existing pattern) + nginx.ingress.kubernetes.io/whitelist-source-range: "192.168.0.0/16,10.0.0.0/8,172.16.0.0/12" + + # Use LoadBalancer service for direct access via MetalLB + service: + type: LoadBalancer + servicePortHttp: 80 + servicePortHttps: 443 + + # Enable insecure mode since this is a homelab (simpler setup) + extraArgs: + - --insecure + +# ApplicationSet controller (for managing multiple apps) +applicationSet: + enabled: true + +# Image updater will be installed separately +# This is just the base ArgoCD installation + +# Disable HA components for single-node simplicity +redis-ha: + enabled: false + +# Use single Redis instance +redis: + enabled: true + +# Disable RBAC since you're the only user +rbac: + create: true + # Allow admin access without restrictions + policy.default: role:admin + +# No authentication complexity needed for homelab +configs: + secret: + createSecret: true + +# Storage for repo data (using your NFS setup) +repoServer: + volumes: + - name: custom-tools + emptyDir: {} + +# Monitoring (since you have Prometheus) +prometheus: + enabled: false # Set to true if you want ArgoCD metrics in Prometheus \ No newline at end of file diff --git a/gitea-argocd-setup.md b/gitea-argocd-setup.md new file mode 100644 index 0000000..5bde464 --- /dev/null +++ b/gitea-argocd-setup.md @@ -0,0 +1,159 @@ +# Gitea + ArgoCD Setup Guide + +## Gitea Access Information + +**Web UI Access:** +- **LoadBalancer URL**: http://192.168.222.27:3000 +- **Ingress URL**: http://gitea.turing.lan (add to your hosts file: `192.168.222.27 gitea.turing.lan`) +- **SSH Clone URL**: `git@192.168.222.26:username/repo.git` + +**Admin Credentials:** +- **Username**: `admin` +- **Password**: `gitea-admin-pass` +- **Email**: `admin@turing.lan` + +## Initial Gitea Setup + +1. **Access Gitea**: Visit http://192.168.222.27:3000 +2. **Login**: Use admin credentials above +3. **Create Organization**: Create an org for your homelab projects (e.g., "turingpi") +4. **Create Repository**: Create your first repo for ArgoCD manifests + +## Setting Up Your First Repository + +### Create a Repository for ArgoCD Applications + +1. **Create new repo**: `turingpi-argocd-apps` +2. **Clone locally**: +```bash +git clone http://192.168.222.27:3000/admin/turingpi-argocd-apps.git +cd turingpi-argocd-apps +``` + +3. **Copy your existing values files**: +```bash +# Copy your existing values files to the repo +cp /home/gilgamezh/code/turingpi/*_values.yaml ./helm-values/ +mkdir -p apps/ +``` + +4. **Create directory structure**: +``` +turingpi-argocd-apps/ +├── apps/ # ArgoCD Application manifests +├── helm-values/ # Your existing *_values.yaml files +├── manifests/ # Raw Kubernetes manifests +└── README.md +``` + +## Migrating Plex to GitOps + +### Step 1: Create ArgoCD Application + +Create `apps/plex.yaml`: +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: plex + namespace: argocd + annotations: + # Enable automatic image updates + argocd-image-updater.argoproj.io/image-list: plex=ghcr.io/k8s-at-home/plex:latest + argocd-image-updater.argoproj.io/plex.update-strategy: newest-build + argocd-image-updater.argoproj.io/write-back-method: git +spec: + project: default + source: + repoURL: http://gitea-http.gitea.svc.cluster.local:3000/admin/turingpi-argocd-apps.git + path: helm-values + targetRevision: HEAD + helm: + valueFiles: + - plex_values.yml + destination: + server: https://kubernetes.default.svc + namespace: plex + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` + +### Step 2: Configure ArgoCD to Access Gitea + +Add Gitea as a repository in ArgoCD: + +1. **Via ArgoCD UI**: + - Go to Settings → Repositories → Connect Repo + - URL: `http://gitea-http.gitea.svc.cluster.local:3000/admin/turingpi-argocd-apps.git` + - Username: `admin` + - Password: `gitea-admin-pass` + +2. **Via CLI**: +```bash +argocd repo add http://gitea-http.gitea.svc.cluster.local:3000/admin/turingpi-argocd-apps.git \ + --username admin --password gitea-admin-pass +``` + +## Benefits of This Setup + +✅ **Version Control**: All your configurations are in Git +✅ **Automatic Updates**: Images update when "latest" tags change +✅ **Audit Trail**: See what changed and when +✅ **Easy Rollbacks**: Git history = deployment history +✅ **Local Control**: No external dependencies +✅ **Team Collaboration**: Others can contribute via Git + +## Migration Strategy + +1. **Start Small**: Migrate 1-2 applications first +2. **Test Process**: Verify auto-updates work as expected +3. **Bulk Migration**: Move remaining applications +4. **Cleanup**: Remove manual Helm commands once confident + +## Git Workflow Examples + +### Adding a New Application +```bash +# Create new app manifest +cat > apps/new-app.yaml << EOF +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: new-app + namespace: argocd +spec: + # ... configuration +EOF + +# Commit and push +git add apps/new-app.yaml +git commit -m "Add new application: new-app" +git push origin main +``` + +### Updating Values +```bash +# Edit your values file +vim helm-values/plex_values.yml + +# Commit changes +git add helm-values/plex_values.yml +git commit -m "Update Plex CPU limits" +git push origin main + +# ArgoCD will auto-sync the changes +``` + +Your homelab now has enterprise-grade GitOps capabilities while staying completely self-hosted! 🏠✨ + +## Next Steps + +1. **Access Gitea** and create your first repository +2. **Copy your values files** to the new repo +3. **Create your first ArgoCD application** pointing to Gitea +4. **Test the workflow** with a simple change +5. **Migrate more applications** gradually \ No newline at end of file diff --git a/gitea_values.yaml b/gitea_values.yaml new file mode 100644 index 0000000..2264137 --- /dev/null +++ b/gitea_values.yaml @@ -0,0 +1,117 @@ +# Gitea configuration for TuringPi K3s cluster +# Self-hosted Git server for ArgoCD integration + +# Single replica for homelab +replicaCount: 1 + +# Service configuration - LoadBalancer for direct access +service: + http: + type: LoadBalancer + port: 3000 + # MetalLB will assign an IP + ssh: + type: LoadBalancer + port: 22 + # For git SSH access + +# Ingress for web access +ingress: + enabled: true + className: nginx + pathType: Prefix + annotations: + nginx.ingress.kubernetes.io/proxy-body-size: "0" + # Restrict to LAN access (matching your existing pattern) + nginx.ingress.kubernetes.io/whitelist-source-range: "192.168.0.0/16,10.0.0.0/8,172.16.0.0/12" + hosts: + - host: gitea.turing.lan + paths: + - path: / + pathType: Prefix + +# Storage using your NFS setup +persistence: + enabled: true + create: true + storageClass: "nfs-client" # Your existing NFS storage class + size: 20Gi + accessModes: + - ReadWriteOnce + +# Database - use PostgreSQL for production-ready setup +postgresql: + enabled: true + auth: + username: gitea + database: gitea + # Password will be auto-generated + primary: + persistence: + enabled: true + storageClass: "nfs-client" + size: 10Gi + +# Disable PostgreSQL HA (since we're enabling regular postgresql) +postgresql-ha: + enabled: false + +# Disable Valkey cluster (Redis alternative) - not needed for homelab +valkey-cluster: + enabled: false + +# Gitea configuration +gitea: + cache: + enabled: false + admin: + username: admin + password: "gitea-admin-pass" # Change this! + email: "admin@turing.lan" + + config: + APP_NAME: "TuringPi Gitea" + RUN_MODE: prod + + server: + DOMAIN: gitea.turing.lan + SSH_DOMAIN: gitea.turing.lan + ROOT_URL: http://gitea.turing.lan + DISABLE_SSH: false + SSH_PORT: 22 + LFS_START_SERVER: true + + database: + DB_TYPE: postgres + + security: + INSTALL_LOCK: true + + service: + DISABLE_REGISTRATION: false # Allow user registration + REQUIRE_SIGNIN_VIEW: false # Allow anonymous viewing of public repos + + ui: + DEFAULT_THEME: auto + + repository: + DEFAULT_PRIVATE: false # Public repos by default for easier ArgoCD access + +# Resource limits (adjust based on your node capacity) +resources: + limits: + cpu: 1000m + memory: 1Gi + requests: + cpu: 100m + memory: 256Mi + +# Node affinity (prefer worker nodes, avoid control plane) +affinity: + nodeAffinity: + preferredDuringSchedulingIgnoredDuringExecution: + - weight: 100 + preference: + matchExpressions: + - key: node-role.kubernetes.io/control-plane + operator: DoesNotExist \ No newline at end of file