reorder and clean repo
This commit is contained in:
gilgamezh
@@ -0,0 +1,380 @@
|
|||||||
|
# CLAUDE.md
|
||||||
|
|
||||||
|
This file provides guidance to LLM agents like Claude, codex or cursor-cli when working with code in this repository.
|
||||||
|
|
||||||
|
## Repository Overview
|
||||||
|
|
||||||
|
This repository contains Kubernetes configuration files for a K3s homelab cluster running on TuringPi hardware. It includes Helm charts, values files, and manifests for deploying various self-hosted applications.
|
||||||
|
|
||||||
|
## Cluster Architecture
|
||||||
|
|
||||||
|
### Hardware Setup
|
||||||
|
- **turing1**: Control plane + worker (master node, IP: 192.168.222.237)
|
||||||
|
- **turing2**: Worker node (currently SchedulingDisabled)
|
||||||
|
- **turing3**: Worker node (also serves as NFS server at turing3.lan)
|
||||||
|
- **turing4**: Worker node
|
||||||
|
- **beelink**: Additional worker node
|
||||||
|
|
||||||
|
### Core Infrastructure
|
||||||
|
- **K3s version**: v1.31.6+k3s1
|
||||||
|
- **Storage**: NFS-backed persistent volumes from turing3.lan:/mnt/ssd
|
||||||
|
- **Load Balancer**: MetalLB for bare metal LoadBalancer services
|
||||||
|
- **SSL**: cert-manager with Let's Encrypt (staging/production cluster issuers)
|
||||||
|
- **Ingress**: Traefik (K3s default) with LAN-only restrictions
|
||||||
|
|
||||||
|
## Application Stack
|
||||||
|
|
||||||
|
### Media Services
|
||||||
|
- **Plex**: kube-plex (Kubernetes-native with dynamic transcoding pods)
|
||||||
|
- **Jellyfin**: Alternative media server
|
||||||
|
- **Sonarr/Radarr**: TV/Movie management (Bananaspliff charts)
|
||||||
|
- **Prowlarr**: Indexer management (custom chart)
|
||||||
|
- **Transmission**: BitTorrent client with OpenVPN
|
||||||
|
- **FlareSolverr**: Captcha solver service
|
||||||
|
|
||||||
|
### Other Applications
|
||||||
|
- **Actual Budget**: Personal finance (custom chart: my-actual-server/)
|
||||||
|
- **Home Assistant Voice LLMs**: AI voice integration (custom chart)
|
||||||
|
- **Ollama**: Local LLM inference
|
||||||
|
- **Prometheus**: Monitoring stack
|
||||||
|
- **PostgreSQL**: Database backend
|
||||||
|
|
||||||
|
## Common Helm Operations
|
||||||
|
|
||||||
|
### Repository Management
|
||||||
|
```bash
|
||||||
|
# Key repositories used
|
||||||
|
helm repo add metallb https://metallb.github.io/metallb
|
||||||
|
helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
|
||||||
|
helm repo add jetstack https://charts.jetstack.io
|
||||||
|
helm repo add bitnami https://charts.bitnami.com/bitnami
|
||||||
|
helm repo add bananaspliff https://bananaspliff.github.io/geek-charts
|
||||||
|
helm repo add k8s-at-home https://k8s-at-home.com/charts/
|
||||||
|
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
||||||
|
helm repo add jellyfin https://jellyfin.github.io/jellyfin-helm
|
||||||
|
helm repo add ollama-helm https://otwld.github.io/ollama-helm/
|
||||||
|
helm repo update
|
||||||
|
```
|
||||||
|
|
||||||
|
### Application Deployment Pattern
|
||||||
|
```bash
|
||||||
|
# Standard deployment with values file
|
||||||
|
helm upgrade <release-name> <chart> -f <app>_values.yaml -i
|
||||||
|
|
||||||
|
# Examples from history:
|
||||||
|
helm upgrade actual my-actual-server -f actual_values.yaml -i
|
||||||
|
helm upgrade plex kube-plex/charts/kube-plex --values plex_values.yml
|
||||||
|
helm upgrade radarr bananaspliff/radarr -f radarr_values.yaml
|
||||||
|
helm upgrade sonarr bananaspliff/sonarr -f sonarr_values.yaml
|
||||||
|
helm upgrade prowlarr prowlarr -f prowlarr_values.yml
|
||||||
|
```
|
||||||
|
|
||||||
|
### Development Workflow
|
||||||
|
```bash
|
||||||
|
# Chart development
|
||||||
|
helm create <chart-name>
|
||||||
|
helm lint <chart-path>
|
||||||
|
helm template <chart> -f <values> | vim -
|
||||||
|
|
||||||
|
# Values inspection
|
||||||
|
helm show values <chart> > <app>_values.yaml
|
||||||
|
helm get values <release-name>
|
||||||
|
helm get manifest <release-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
## File Structure Patterns
|
||||||
|
|
||||||
|
- `<app>_values.yaml` - Helm values overrides for each application
|
||||||
|
- Custom charts in subdirectories (my-actual-server/, home-assistant-voice-llms/, prowlarr/)
|
||||||
|
- `*_persistent_volume.yml` - PV definitions for applications requiring storage
|
||||||
|
- Infrastructure manifests: metallb.yml, ingress.yaml, cluster-issuer-*.yaml
|
||||||
|
|
||||||
|
## Storage Configuration
|
||||||
|
|
||||||
|
- **NFS Server**: turing3.lan serving /mnt/ssd
|
||||||
|
- **StorageClass**: nfs-client (via nfs-subdir-external-provisioner)
|
||||||
|
- **Access Mode**: ReadWriteMany for shared media access
|
||||||
|
- **PVC Pattern**: Applications create their own PVCs or reference pre-existing ones
|
||||||
|
|
||||||
|
## Network Setup
|
||||||
|
|
||||||
|
- **Pod Network**: Cluster subnet requires allowlisting in Plex for transcoding
|
||||||
|
- **Ingress**: LAN-only access enforced via limit_ingress_to_lan.yaml
|
||||||
|
- **Load Balancer**: MetalLB provides external IPs for services
|
||||||
|
- **DNS**: .lan domain for internal services
|
||||||
|
|
||||||
|
## Kube-Plex Specifics
|
||||||
|
|
||||||
|
The kube-plex/ directory contains a Go application that replaces the standard Plex transcoder:
|
||||||
|
- Creates Kubernetes pods for each transcode job
|
||||||
|
- Requires AMD64 nodes (configured via nodeSelector)
|
||||||
|
- Mounts shared NFS volumes for media access
|
||||||
|
- Environment variables: DATA_PVC, CONFIG_PVC, TRANSCODE_PVC, PMS_IMAGE, PMS_INTERNAL_ADDRESS
|
||||||
|
|
||||||
|
## ArgoCD Migration Guidelines
|
||||||
|
|
||||||
|
### Agent Workflow Defaults
|
||||||
|
When migrating or adding an ArgoCD Application, always:
|
||||||
|
- Create/update the Application manifest and any `helm-values/` files.
|
||||||
|
- Git add, commit, and push the changes to the tracked branch.
|
||||||
|
- Use the ArgoCD CLI to sync the app and wait for healthy status.
|
||||||
|
|
||||||
|
### Critical Configuration Preservation Rules
|
||||||
|
When migrating applications from direct Helm deployment to ArgoCD GitOps:
|
||||||
|
|
||||||
|
1. **NEVER change working configurations** - If an application was working with specific values files and service configurations, maintain those exact settings
|
||||||
|
2. **NO PATCHES OR WORKAROUNDS** - Do not create additional PVCs, port forwards, or other patches to "fix" configuration mismatches
|
||||||
|
3. **Root Cause Analysis Required** - Always identify why a configuration that worked before is now failing after ArgoCD migration
|
||||||
|
4. **Preserve Original Service Ports** - Applications should maintain their original service port configurations (e.g., Radarr:7878, Sonarr:8989)
|
||||||
|
5. **Respect Existing PVC Structure** - Use the existing PVC and storage configuration patterns, don't create compatibility layers
|
||||||
|
|
||||||
|
### Troubleshooting Process
|
||||||
|
1. Compare working Helm values with ArgoCD application configuration
|
||||||
|
2. Verify that Helm chart sources and versions match original deployments
|
||||||
|
3. Ensure service definitions in ArgoCD match original working services
|
||||||
|
4. Check that ingress configurations align with actual service ports
|
||||||
|
5. Fix the root configuration issue, don't patch around it
|
||||||
|
|
||||||
|
### Common Migration Pitfalls
|
||||||
|
- Creating unnecessary "myvolume" PVCs for chart compatibility - instead fix the chart values
|
||||||
|
- Changing service ports to match ingress instead of fixing ingress to match services
|
||||||
|
- Using generic chart defaults instead of preserving working custom configurations
|
||||||
|
|
||||||
|
## ArgoCD GitOps Implementation Lessons
|
||||||
|
|
||||||
|
### Successfully Migrated Applications
|
||||||
|
- **Plex**: Multi-source setup (kube-plex chart + turingpi values)
|
||||||
|
- **Radarr**: Bananaspliff chart with custom volume configuration
|
||||||
|
- **Sonarr**: Bananaspliff chart with custom volume configuration
|
||||||
|
|
||||||
|
### Critical ArgoCD Configuration Patterns
|
||||||
|
|
||||||
|
#### Multi-Source Application Structure
|
||||||
|
For applications requiring custom values from Git repository:
|
||||||
|
```yaml
|
||||||
|
spec:
|
||||||
|
project: default
|
||||||
|
sources:
|
||||||
|
- repoURL: https://chart-repository.com/charts
|
||||||
|
chart: app-name
|
||||||
|
targetRevision: "*"
|
||||||
|
ref: charts
|
||||||
|
helm:
|
||||||
|
releaseName: app-name
|
||||||
|
valueFiles:
|
||||||
|
- $values/helm-values/app_values.yaml
|
||||||
|
- repoURL: http://gitea-http.gitea.svc.cluster.local:3000/admin/turingpi.git
|
||||||
|
targetRevision: HEAD
|
||||||
|
ref: values
|
||||||
|
```
|
||||||
|
|
||||||
|
**CRITICAL**: Never use both `source:` and `sources:` sections - this creates conflicts where `source:` overrides `sources:` configuration.
|
||||||
|
|
||||||
|
#### Image Auto-Update Configuration
|
||||||
|
For applications using "latest" tags with automatic updates:
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
annotations:
|
||||||
|
argocd-image-updater.argoproj.io/image-list: app=registry/image:latest
|
||||||
|
argocd-image-updater.argoproj.io/app.update-strategy: digest
|
||||||
|
argocd-image-updater.argoproj.io/write-back-method: git
|
||||||
|
argocd-image-updater.argoproj.io/git-branch: master
|
||||||
|
argocd-image-updater.argoproj.io/git-commit-user: argocd-image-updater
|
||||||
|
argocd-image-updater.argoproj.io/git-commit-email: argocd@turing.lan
|
||||||
|
```
|
||||||
|
|
||||||
|
### Chart-Specific Configuration Requirements
|
||||||
|
|
||||||
|
#### Bananaspliff Charts (Radarr/Sonarr)
|
||||||
|
These charts require specific volume configuration syntax:
|
||||||
|
```yaml
|
||||||
|
# CORRECT: Direct volumes/volumeMounts (working configuration)
|
||||||
|
volumes:
|
||||||
|
- name: "plex-data"
|
||||||
|
persistentVolumeClaim:
|
||||||
|
claimName: "plex-data"
|
||||||
|
|
||||||
|
volumeMounts:
|
||||||
|
- name: "plex-data"
|
||||||
|
mountPath: "/config"
|
||||||
|
subPath: "configs/app-name"
|
||||||
|
- name: "plex-data"
|
||||||
|
mountPath: "/nfs"
|
||||||
|
|
||||||
|
# INCORRECT: persistence syntax (doesn't work with these charts)
|
||||||
|
persistence:
|
||||||
|
config:
|
||||||
|
enabled: true
|
||||||
|
existingClaim: "plex-data"
|
||||||
|
subPath: "configs/app-name"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Service Port Configuration
|
||||||
|
Bananaspliff charts use simple service structure:
|
||||||
|
```yaml
|
||||||
|
service:
|
||||||
|
type: ClusterIP
|
||||||
|
port: 7878 # Direct port specification
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ingress Controller Configuration
|
||||||
|
|
||||||
|
#### K3s Default Setup
|
||||||
|
- **Default Controller**: Traefik (not Nginx)
|
||||||
|
- **Ingress Class**: Use `kubernetes.io/ingress.class: traefik`
|
||||||
|
- **Common Mistake**: Using `nginx` class when Traefik is the active controller
|
||||||
|
|
||||||
|
#### Verification Commands
|
||||||
|
```bash
|
||||||
|
# Check active ingress controller
|
||||||
|
kubectl get pods -A | grep traefik
|
||||||
|
kubectl get pods -A | grep ingress
|
||||||
|
|
||||||
|
# Verify ingress class in configurations
|
||||||
|
kubectl get ingress -o yaml | grep "ingress.class"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pre-Migration Checklist
|
||||||
|
Before migrating any application to ArgoCD:
|
||||||
|
|
||||||
|
1. **Capture Current Configuration**:
|
||||||
|
```bash
|
||||||
|
helm get values <release-name> > original_values.yaml
|
||||||
|
helm get manifest <release-name> > original_manifest.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Document Volume Mounts**:
|
||||||
|
```bash
|
||||||
|
kubectl describe deployment <app-name> | grep -A 10 "Mounts:"
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Verify Service Configuration**:
|
||||||
|
```bash
|
||||||
|
kubectl get svc <app-name> -o yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Test Chart Template Locally**:
|
||||||
|
```bash
|
||||||
|
helm template <app-name> <chart> --values <values-file> | grep -A 20 "kind: Service"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Commit & Push + ArgoCD CLI Checks
|
||||||
|
After adding a new ArgoCD Application and values files:
|
||||||
|
|
||||||
|
1. Commit and push the changes:
|
||||||
|
```bash
|
||||||
|
git add applications/<app>.yaml helm-values/<app>_values.*
|
||||||
|
git commit -m "feat(argocd): add <app> application"
|
||||||
|
git push # or: git push gitea master
|
||||||
|
```
|
||||||
|
|
||||||
|
2. ArgoCD CLI login (if not already authenticated):
|
||||||
|
```bash
|
||||||
|
# Example options; adjust for your environment
|
||||||
|
# Get admin password if needed
|
||||||
|
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d; echo
|
||||||
|
|
||||||
|
# Login (use your server/credentials)
|
||||||
|
argocd login argocd-server.argocd.svc.cluster.local --username admin --password <password> --insecure
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Sync and wait for health:
|
||||||
|
```bash
|
||||||
|
argocd app sync <app>
|
||||||
|
argocd app wait <app> --sync --health --timeout 300
|
||||||
|
argocd app get <app>
|
||||||
|
argocd app list | grep <app>
|
||||||
|
```
|
||||||
|
|
||||||
|
4. If sync fails, inspect details and events:
|
||||||
|
```bash
|
||||||
|
argocd app history <app> --refresh
|
||||||
|
argocd app get <app> --refresh
|
||||||
|
kubectl -n default describe deploy/<app> || true
|
||||||
|
kubectl -n default get events --sort-by=.lastTimestamp | tail -n 50
|
||||||
|
```
|
||||||
|
|
||||||
|
### Post-Migration Verification
|
||||||
|
|
||||||
|
1. **Check Volume Mounts Match Original**:
|
||||||
|
```bash
|
||||||
|
kubectl describe pod -l app=<app-name> | grep -A 10 "Mounts:"
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Verify Service Ports**:
|
||||||
|
```bash
|
||||||
|
kubectl get svc <app-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Test Application Access**:
|
||||||
|
```bash
|
||||||
|
curl -I http://<app-domain>
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Confirm Configuration Persistence**:
|
||||||
|
```bash
|
||||||
|
kubectl exec -it deployment/<app-name> -- ls -la /config
|
||||||
|
```
|
||||||
|
|
||||||
|
### ArgoCD Image-Updater Multi-Source Application Issues
|
||||||
|
|
||||||
|
#### Problem: Credential Errors with Multi-Source Applications
|
||||||
|
When using ArgoCD image-updater with multi-source applications (chart from external repo + values from Git), the image-updater may fail with credential errors like:
|
||||||
|
```
|
||||||
|
Could not update application spec: could not get creds for repo 'https://chart-repository.com': credentials for 'https://chart-repository.com' are not configured in Argo CD settings
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Root Cause Analysis
|
||||||
|
1. **Multi-Source Confusion**: Image-updater tries to write back changes to the chart repository instead of the values repository
|
||||||
|
2. **Git Write-Back Limitations**: The `git` write-back method doesn't handle multi-source applications properly
|
||||||
|
3. **Repository Credentials**: External chart repositories (like Bananaspliff) don't have write credentials configured
|
||||||
|
|
||||||
|
#### Solution: Use ArgoCD API Write-Back Method
|
||||||
|
Instead of using `git` write-back method, use the `argocd` API method for multi-source applications:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
metadata:
|
||||||
|
annotations:
|
||||||
|
argocd-image-updater.argoproj.io/image-list: app=registry/image:latest
|
||||||
|
argocd-image-updater.argoproj.io/app.update-strategy: digest
|
||||||
|
argocd-image-updater.argoproj.io/write-back-method: argocd # Use ArgoCD API instead of git
|
||||||
|
argocd-image-updater.argoproj.io/write-back-target: http://git-repo.local/values.git # Optional: specify target repo
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Implementation Steps
|
||||||
|
1. **Update Image-Updater Configuration**:
|
||||||
|
```bash
|
||||||
|
kubectl patch configmap argocd-image-updater-config -n argocd --patch '{"data":{"git.user":"argocd-image-updater","git.email":"argocd@turing.lan"}}'
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Change Application Write-Back Method**:
|
||||||
|
```bash
|
||||||
|
kubectl patch application <app-name> -n argocd --type='merge' --patch='{"metadata":{"annotations":{"argocd-image-updater.argoproj.io/write-back-method":"argocd"}}}'
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Restart Image-Updater**:
|
||||||
|
```bash
|
||||||
|
kubectl rollout restart deployment argocd-image-updater -n argocd
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Verification Commands
|
||||||
|
```bash
|
||||||
|
# Check image-updater logs for success
|
||||||
|
kubectl logs -n argocd deployment/argocd-image-updater --tail=20
|
||||||
|
|
||||||
|
# Look for these success indicators:
|
||||||
|
# - "Successfully updated the live application spec"
|
||||||
|
# - "Processing results: applications=X images_considered=X images_skipped=0 images_updated=X errors=0"
|
||||||
|
|
||||||
|
# Verify applications remain healthy
|
||||||
|
argocd app list
|
||||||
|
|
||||||
|
# Check that pods are updated with new images
|
||||||
|
kubectl get pods -l app=<app-name>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Key Learnings
|
||||||
|
- **ArgoCD API Method**: Works better than Git write-back for multi-source applications
|
||||||
|
- **No Repository Credentials Needed**: ArgoCD API method doesn't require external repository write credentials
|
||||||
|
- **Application Spec Updates**: Changes are applied directly to ArgoCD application specs, not Git files
|
||||||
|
- **Multi-Source Compatibility**: This approach handles complex application configurations properly
|
||||||
@@ -1,380 +0,0 @@
|
|||||||
# CLAUDE.md
|
|
||||||
|
|
||||||
This file provides guidance to LLM agents like Claude, codex or cursor-cli when working with code in this repository.
|
|
||||||
|
|
||||||
## Repository Overview
|
|
||||||
|
|
||||||
This repository contains Kubernetes configuration files for a K3s homelab cluster running on TuringPi hardware. It includes Helm charts, values files, and manifests for deploying various self-hosted applications.
|
|
||||||
|
|
||||||
## Cluster Architecture
|
|
||||||
|
|
||||||
### Hardware Setup
|
|
||||||
- **turing1**: Control plane + worker (master node, IP: 192.168.222.237)
|
|
||||||
- **turing2**: Worker node (currently SchedulingDisabled)
|
|
||||||
- **turing3**: Worker node (also serves as NFS server at turing3.lan)
|
|
||||||
- **turing4**: Worker node
|
|
||||||
- **beelink**: Additional worker node
|
|
||||||
|
|
||||||
### Core Infrastructure
|
|
||||||
- **K3s version**: v1.31.6+k3s1
|
|
||||||
- **Storage**: NFS-backed persistent volumes from turing3.lan:/mnt/ssd
|
|
||||||
- **Load Balancer**: MetalLB for bare metal LoadBalancer services
|
|
||||||
- **SSL**: cert-manager with Let's Encrypt (staging/production cluster issuers)
|
|
||||||
- **Ingress**: Traefik (K3s default) with LAN-only restrictions
|
|
||||||
|
|
||||||
## Application Stack
|
|
||||||
|
|
||||||
### Media Services
|
|
||||||
- **Plex**: kube-plex (Kubernetes-native with dynamic transcoding pods)
|
|
||||||
- **Jellyfin**: Alternative media server
|
|
||||||
- **Sonarr/Radarr**: TV/Movie management (Bananaspliff charts)
|
|
||||||
- **Prowlarr**: Indexer management (custom chart)
|
|
||||||
- **Transmission**: BitTorrent client with OpenVPN
|
|
||||||
- **FlareSolverr**: Captcha solver service
|
|
||||||
|
|
||||||
### Other Applications
|
|
||||||
- **Actual Budget**: Personal finance (custom chart: my-actual-server/)
|
|
||||||
- **Home Assistant Voice LLMs**: AI voice integration (custom chart)
|
|
||||||
- **Ollama**: Local LLM inference
|
|
||||||
- **Prometheus**: Monitoring stack
|
|
||||||
- **PostgreSQL**: Database backend
|
|
||||||
|
|
||||||
## Common Helm Operations
|
|
||||||
|
|
||||||
### Repository Management
|
|
||||||
```bash
|
|
||||||
# Key repositories used
|
|
||||||
helm repo add metallb https://metallb.github.io/metallb
|
|
||||||
helm repo add nfs-subdir-external-provisioner https://kubernetes-sigs.github.io/nfs-subdir-external-provisioner
|
|
||||||
helm repo add jetstack https://charts.jetstack.io
|
|
||||||
helm repo add bitnami https://charts.bitnami.com/bitnami
|
|
||||||
helm repo add bananaspliff https://bananaspliff.github.io/geek-charts
|
|
||||||
helm repo add k8s-at-home https://k8s-at-home.com/charts/
|
|
||||||
helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
|
|
||||||
helm repo add jellyfin https://jellyfin.github.io/jellyfin-helm
|
|
||||||
helm repo add ollama-helm https://otwld.github.io/ollama-helm/
|
|
||||||
helm repo update
|
|
||||||
```
|
|
||||||
|
|
||||||
### Application Deployment Pattern
|
|
||||||
```bash
|
|
||||||
# Standard deployment with values file
|
|
||||||
helm upgrade <release-name> <chart> -f <app>_values.yaml -i
|
|
||||||
|
|
||||||
# Examples from history:
|
|
||||||
helm upgrade actual my-actual-server -f actual_values.yaml -i
|
|
||||||
helm upgrade plex kube-plex/charts/kube-plex --values plex_values.yml
|
|
||||||
helm upgrade radarr bananaspliff/radarr -f radarr_values.yaml
|
|
||||||
helm upgrade sonarr bananaspliff/sonarr -f sonarr_values.yaml
|
|
||||||
helm upgrade prowlarr prowlarr -f prowlarr_values.yml
|
|
||||||
```
|
|
||||||
|
|
||||||
### Development Workflow
|
|
||||||
```bash
|
|
||||||
# Chart development
|
|
||||||
helm create <chart-name>
|
|
||||||
helm lint <chart-path>
|
|
||||||
helm template <chart> -f <values> | vim -
|
|
||||||
|
|
||||||
# Values inspection
|
|
||||||
helm show values <chart> > <app>_values.yaml
|
|
||||||
helm get values <release-name>
|
|
||||||
helm get manifest <release-name>
|
|
||||||
```
|
|
||||||
|
|
||||||
## File Structure Patterns
|
|
||||||
|
|
||||||
- `<app>_values.yaml` - Helm values overrides for each application
|
|
||||||
- Custom charts in subdirectories (my-actual-server/, home-assistant-voice-llms/, prowlarr/)
|
|
||||||
- `*_persistent_volume.yml` - PV definitions for applications requiring storage
|
|
||||||
- Infrastructure manifests: metallb.yml, ingress.yaml, cluster-issuer-*.yaml
|
|
||||||
|
|
||||||
## Storage Configuration
|
|
||||||
|
|
||||||
- **NFS Server**: turing3.lan serving /mnt/ssd
|
|
||||||
- **StorageClass**: nfs-client (via nfs-subdir-external-provisioner)
|
|
||||||
- **Access Mode**: ReadWriteMany for shared media access
|
|
||||||
- **PVC Pattern**: Applications create their own PVCs or reference pre-existing ones
|
|
||||||
|
|
||||||
## Network Setup
|
|
||||||
|
|
||||||
- **Pod Network**: Cluster subnet requires allowlisting in Plex for transcoding
|
|
||||||
- **Ingress**: LAN-only access enforced via limit_ingress_to_lan.yaml
|
|
||||||
- **Load Balancer**: MetalLB provides external IPs for services
|
|
||||||
- **DNS**: .lan domain for internal services
|
|
||||||
|
|
||||||
## Kube-Plex Specifics
|
|
||||||
|
|
||||||
The kube-plex/ directory contains a Go application that replaces the standard Plex transcoder:
|
|
||||||
- Creates Kubernetes pods for each transcode job
|
|
||||||
- Requires AMD64 nodes (configured via nodeSelector)
|
|
||||||
- Mounts shared NFS volumes for media access
|
|
||||||
- Environment variables: DATA_PVC, CONFIG_PVC, TRANSCODE_PVC, PMS_IMAGE, PMS_INTERNAL_ADDRESS
|
|
||||||
|
|
||||||
## ArgoCD Migration Guidelines
|
|
||||||
|
|
||||||
### Agent Workflow Defaults
|
|
||||||
When migrating or adding an ArgoCD Application, always:
|
|
||||||
- Create/update the Application manifest and any `helm-values/` files.
|
|
||||||
- Git add, commit, and push the changes to the tracked branch.
|
|
||||||
- Use the ArgoCD CLI to sync the app and wait for healthy status.
|
|
||||||
|
|
||||||
### Critical Configuration Preservation Rules
|
|
||||||
When migrating applications from direct Helm deployment to ArgoCD GitOps:
|
|
||||||
|
|
||||||
1. **NEVER change working configurations** - If an application was working with specific values files and service configurations, maintain those exact settings
|
|
||||||
2. **NO PATCHES OR WORKAROUNDS** - Do not create additional PVCs, port forwards, or other patches to "fix" configuration mismatches
|
|
||||||
3. **Root Cause Analysis Required** - Always identify why a configuration that worked before is now failing after ArgoCD migration
|
|
||||||
4. **Preserve Original Service Ports** - Applications should maintain their original service port configurations (e.g., Radarr:7878, Sonarr:8989)
|
|
||||||
5. **Respect Existing PVC Structure** - Use the existing PVC and storage configuration patterns, don't create compatibility layers
|
|
||||||
|
|
||||||
### Troubleshooting Process
|
|
||||||
1. Compare working Helm values with ArgoCD application configuration
|
|
||||||
2. Verify that Helm chart sources and versions match original deployments
|
|
||||||
3. Ensure service definitions in ArgoCD match original working services
|
|
||||||
4. Check that ingress configurations align with actual service ports
|
|
||||||
5. Fix the root configuration issue, don't patch around it
|
|
||||||
|
|
||||||
### Common Migration Pitfalls
|
|
||||||
- Creating unnecessary "myvolume" PVCs for chart compatibility - instead fix the chart values
|
|
||||||
- Changing service ports to match ingress instead of fixing ingress to match services
|
|
||||||
- Using generic chart defaults instead of preserving working custom configurations
|
|
||||||
|
|
||||||
## ArgoCD GitOps Implementation Lessons
|
|
||||||
|
|
||||||
### Successfully Migrated Applications
|
|
||||||
- **Plex**: Multi-source setup (kube-plex chart + turingpi values)
|
|
||||||
- **Radarr**: Bananaspliff chart with custom volume configuration
|
|
||||||
- **Sonarr**: Bananaspliff chart with custom volume configuration
|
|
||||||
|
|
||||||
### Critical ArgoCD Configuration Patterns
|
|
||||||
|
|
||||||
#### Multi-Source Application Structure
|
|
||||||
For applications requiring custom values from Git repository:
|
|
||||||
```yaml
|
|
||||||
spec:
|
|
||||||
project: default
|
|
||||||
sources:
|
|
||||||
- repoURL: https://chart-repository.com/charts
|
|
||||||
chart: app-name
|
|
||||||
targetRevision: "*"
|
|
||||||
ref: charts
|
|
||||||
helm:
|
|
||||||
releaseName: app-name
|
|
||||||
valueFiles:
|
|
||||||
- $values/helm-values/app_values.yaml
|
|
||||||
- repoURL: http://gitea-http.gitea.svc.cluster.local:3000/admin/turingpi.git
|
|
||||||
targetRevision: HEAD
|
|
||||||
ref: values
|
|
||||||
```
|
|
||||||
|
|
||||||
**CRITICAL**: Never use both `source:` and `sources:` sections - this creates conflicts where `source:` overrides `sources:` configuration.
|
|
||||||
|
|
||||||
#### Image Auto-Update Configuration
|
|
||||||
For applications using "latest" tags with automatic updates:
|
|
||||||
```yaml
|
|
||||||
metadata:
|
|
||||||
annotations:
|
|
||||||
argocd-image-updater.argoproj.io/image-list: app=registry/image:latest
|
|
||||||
argocd-image-updater.argoproj.io/app.update-strategy: digest
|
|
||||||
argocd-image-updater.argoproj.io/write-back-method: git
|
|
||||||
argocd-image-updater.argoproj.io/git-branch: master
|
|
||||||
argocd-image-updater.argoproj.io/git-commit-user: argocd-image-updater
|
|
||||||
argocd-image-updater.argoproj.io/git-commit-email: argocd@turing.lan
|
|
||||||
```
|
|
||||||
|
|
||||||
### Chart-Specific Configuration Requirements
|
|
||||||
|
|
||||||
#### Bananaspliff Charts (Radarr/Sonarr)
|
|
||||||
These charts require specific volume configuration syntax:
|
|
||||||
```yaml
|
|
||||||
# CORRECT: Direct volumes/volumeMounts (working configuration)
|
|
||||||
volumes:
|
|
||||||
- name: "plex-data"
|
|
||||||
persistentVolumeClaim:
|
|
||||||
claimName: "plex-data"
|
|
||||||
|
|
||||||
volumeMounts:
|
|
||||||
- name: "plex-data"
|
|
||||||
mountPath: "/config"
|
|
||||||
subPath: "configs/app-name"
|
|
||||||
- name: "plex-data"
|
|
||||||
mountPath: "/nfs"
|
|
||||||
|
|
||||||
# INCORRECT: persistence syntax (doesn't work with these charts)
|
|
||||||
persistence:
|
|
||||||
config:
|
|
||||||
enabled: true
|
|
||||||
existingClaim: "plex-data"
|
|
||||||
subPath: "configs/app-name"
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Service Port Configuration
|
|
||||||
Bananaspliff charts use simple service structure:
|
|
||||||
```yaml
|
|
||||||
service:
|
|
||||||
type: ClusterIP
|
|
||||||
port: 7878 # Direct port specification
|
|
||||||
```
|
|
||||||
|
|
||||||
### Ingress Controller Configuration
|
|
||||||
|
|
||||||
#### K3s Default Setup
|
|
||||||
- **Default Controller**: Traefik (not Nginx)
|
|
||||||
- **Ingress Class**: Use `kubernetes.io/ingress.class: traefik`
|
|
||||||
- **Common Mistake**: Using `nginx` class when Traefik is the active controller
|
|
||||||
|
|
||||||
#### Verification Commands
|
|
||||||
```bash
|
|
||||||
# Check active ingress controller
|
|
||||||
kubectl get pods -A | grep traefik
|
|
||||||
kubectl get pods -A | grep ingress
|
|
||||||
|
|
||||||
# Verify ingress class in configurations
|
|
||||||
kubectl get ingress -o yaml | grep "ingress.class"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Pre-Migration Checklist
|
|
||||||
Before migrating any application to ArgoCD:
|
|
||||||
|
|
||||||
1. **Capture Current Configuration**:
|
|
||||||
```bash
|
|
||||||
helm get values <release-name> > original_values.yaml
|
|
||||||
helm get manifest <release-name> > original_manifest.yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Document Volume Mounts**:
|
|
||||||
```bash
|
|
||||||
kubectl describe deployment <app-name> | grep -A 10 "Mounts:"
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Verify Service Configuration**:
|
|
||||||
```bash
|
|
||||||
kubectl get svc <app-name> -o yaml
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Test Chart Template Locally**:
|
|
||||||
```bash
|
|
||||||
helm template <app-name> <chart> --values <values-file> | grep -A 20 "kind: Service"
|
|
||||||
```
|
|
||||||
|
|
||||||
### Commit & Push + ArgoCD CLI Checks
|
|
||||||
After adding a new ArgoCD Application and values files:
|
|
||||||
|
|
||||||
1. Commit and push the changes:
|
|
||||||
```bash
|
|
||||||
git add applications/<app>.yaml helm-values/<app>_values.*
|
|
||||||
git commit -m "feat(argocd): add <app> application"
|
|
||||||
git push # or: git push gitea master
|
|
||||||
```
|
|
||||||
|
|
||||||
2. ArgoCD CLI login (if not already authenticated):
|
|
||||||
```bash
|
|
||||||
# Example options; adjust for your environment
|
|
||||||
# Get admin password if needed
|
|
||||||
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath='{.data.password}' | base64 -d; echo
|
|
||||||
|
|
||||||
# Login (use your server/credentials)
|
|
||||||
argocd login argocd-server.argocd.svc.cluster.local --username admin --password <password> --insecure
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Sync and wait for health:
|
|
||||||
```bash
|
|
||||||
argocd app sync <app>
|
|
||||||
argocd app wait <app> --sync --health --timeout 300
|
|
||||||
argocd app get <app>
|
|
||||||
argocd app list | grep <app>
|
|
||||||
```
|
|
||||||
|
|
||||||
4. If sync fails, inspect details and events:
|
|
||||||
```bash
|
|
||||||
argocd app history <app> --refresh
|
|
||||||
argocd app get <app> --refresh
|
|
||||||
kubectl -n default describe deploy/<app> || true
|
|
||||||
kubectl -n default get events --sort-by=.lastTimestamp | tail -n 50
|
|
||||||
```
|
|
||||||
|
|
||||||
### Post-Migration Verification
|
|
||||||
|
|
||||||
1. **Check Volume Mounts Match Original**:
|
|
||||||
```bash
|
|
||||||
kubectl describe pod -l app=<app-name> | grep -A 10 "Mounts:"
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Verify Service Ports**:
|
|
||||||
```bash
|
|
||||||
kubectl get svc <app-name>
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Test Application Access**:
|
|
||||||
```bash
|
|
||||||
curl -I http://<app-domain>
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Confirm Configuration Persistence**:
|
|
||||||
```bash
|
|
||||||
kubectl exec -it deployment/<app-name> -- ls -la /config
|
|
||||||
```
|
|
||||||
|
|
||||||
### ArgoCD Image-Updater Multi-Source Application Issues
|
|
||||||
|
|
||||||
#### Problem: Credential Errors with Multi-Source Applications
|
|
||||||
When using ArgoCD image-updater with multi-source applications (chart from external repo + values from Git), the image-updater may fail with credential errors like:
|
|
||||||
```
|
|
||||||
Could not update application spec: could not get creds for repo 'https://chart-repository.com': credentials for 'https://chart-repository.com' are not configured in Argo CD settings
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Root Cause Analysis
|
|
||||||
1. **Multi-Source Confusion**: Image-updater tries to write back changes to the chart repository instead of the values repository
|
|
||||||
2. **Git Write-Back Limitations**: The `git` write-back method doesn't handle multi-source applications properly
|
|
||||||
3. **Repository Credentials**: External chart repositories (like Bananaspliff) don't have write credentials configured
|
|
||||||
|
|
||||||
#### Solution: Use ArgoCD API Write-Back Method
|
|
||||||
Instead of using `git` write-back method, use the `argocd` API method for multi-source applications:
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
metadata:
|
|
||||||
annotations:
|
|
||||||
argocd-image-updater.argoproj.io/image-list: app=registry/image:latest
|
|
||||||
argocd-image-updater.argoproj.io/app.update-strategy: digest
|
|
||||||
argocd-image-updater.argoproj.io/write-back-method: argocd # Use ArgoCD API instead of git
|
|
||||||
argocd-image-updater.argoproj.io/write-back-target: http://git-repo.local/values.git # Optional: specify target repo
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Implementation Steps
|
|
||||||
1. **Update Image-Updater Configuration**:
|
|
||||||
```bash
|
|
||||||
kubectl patch configmap argocd-image-updater-config -n argocd --patch '{"data":{"git.user":"argocd-image-updater","git.email":"argocd@turing.lan"}}'
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Change Application Write-Back Method**:
|
|
||||||
```bash
|
|
||||||
kubectl patch application <app-name> -n argocd --type='merge' --patch='{"metadata":{"annotations":{"argocd-image-updater.argoproj.io/write-back-method":"argocd"}}}'
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Restart Image-Updater**:
|
|
||||||
```bash
|
|
||||||
kubectl rollout restart deployment argocd-image-updater -n argocd
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Verification Commands
|
|
||||||
```bash
|
|
||||||
# Check image-updater logs for success
|
|
||||||
kubectl logs -n argocd deployment/argocd-image-updater --tail=20
|
|
||||||
|
|
||||||
# Look for these success indicators:
|
|
||||||
# - "Successfully updated the live application spec"
|
|
||||||
# - "Processing results: applications=X images_considered=X images_skipped=0 images_updated=X errors=0"
|
|
||||||
|
|
||||||
# Verify applications remain healthy
|
|
||||||
argocd app list
|
|
||||||
|
|
||||||
# Check that pods are updated with new images
|
|
||||||
kubectl get pods -l app=<app-name>
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Key Learnings
|
|
||||||
- **ArgoCD API Method**: Works better than Git write-back for multi-source applications
|
|
||||||
- **No Repository Credentials Needed**: ArgoCD API method doesn't require external repository write credentials
|
|
||||||
- **Application Spec Updates**: Changes are applied directly to ArgoCD application specs, not Git files
|
|
||||||
- **Multi-Source Compatibility**: This approach handles complex application configurations properly
|
|
||||||
@@ -79,6 +79,15 @@ Run the provided script to update all nodes:
|
|||||||
./update.sh
|
./update.sh
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
Old way:
|
||||||
|
```bash
|
||||||
|
master: curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false sh -s - --write-kubeconfig-mode 644 --disable servicelb --token torino --node-ip 192.168.222.237 --disable-cloud-controller --disable local-storage
|
||||||
|
|
||||||
|
nodes: curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false K3S_URL=https://192.168.222.237:6443 K3S_TOKEN=torino sh -
|
||||||
|
|
||||||
|
````
|
||||||
|
|
||||||
### Manual Update Process
|
### Manual Update Process
|
||||||
|
|
||||||
#### 1. Update Master Node (turing1)
|
#### 1. Update Master Node (turing1)
|
||||||
@@ -141,4 +150,4 @@ helm template <chart> -f <values> | kubectl apply --dry-run=client -f -
|
|||||||
### Storage Requirements
|
### Storage Requirements
|
||||||
- NFS server must be running on turing3.lan
|
- NFS server must be running on turing3.lan
|
||||||
- Applications require ReadWriteMany access for shared media
|
- Applications require ReadWriteMany access for shared media
|
||||||
- Persistent volumes are dynamically provisioned via nfs-subdir-external-provisioner
|
- Persistent volumes are dynamically provisioned via nfs-subdir-external-provisioner
|
||||||
|
|||||||
@@ -1,35 +0,0 @@
|
|||||||
apiVersion: argoproj.io/v1alpha1
|
|
||||||
kind: Application
|
|
||||||
metadata:
|
|
||||||
name: flaresolverr
|
|
||||||
namespace: argocd
|
|
||||||
annotations:
|
|
||||||
argocd-image-updater.argoproj.io/image-list: flaresolverr=ghcr.io/flaresolverr/flaresolverr:latest
|
|
||||||
argocd-image-updater.argoproj.io/flaresolverr.update-strategy: digest
|
|
||||||
argocd-image-updater.argoproj.io/write-back-method: argocd
|
|
||||||
argocd-image-updater.argoproj.io/flaresolverr.helm.image-name: image.repository
|
|
||||||
argocd-image-updater.argoproj.io/flaresolverr.helm.image-tag: image.tag
|
|
||||||
spec:
|
|
||||||
project: default
|
|
||||||
sources:
|
|
||||||
- repoURL: https://k8s-at-home.com/charts/
|
|
||||||
chart: flaresolverr
|
|
||||||
targetRevision: "*"
|
|
||||||
ref: charts
|
|
||||||
helm:
|
|
||||||
releaseName: flaresolverr
|
|
||||||
valueFiles:
|
|
||||||
- $values/helm-values/flaresolverr_values.yaml
|
|
||||||
- repoURL: http://gitea-http.gitea.svc.cluster.local:3000/admin/turingpi.git
|
|
||||||
targetRevision: HEAD
|
|
||||||
ref: values
|
|
||||||
destination:
|
|
||||||
server: https://kubernetes.default.svc
|
|
||||||
namespace: default
|
|
||||||
syncPolicy:
|
|
||||||
automated:
|
|
||||||
prune: true
|
|
||||||
selfHeal: true
|
|
||||||
syncOptions:
|
|
||||||
- CreateNamespace=true
|
|
||||||
- ServerSideApply=true
|
|
||||||
@@ -1,17 +0,0 @@
|
|||||||
apiVersion: v1
|
|
||||||
kind: ConfigMap
|
|
||||||
metadata:
|
|
||||||
name: argocd-image-updater-config
|
|
||||||
namespace: argocd
|
|
||||||
labels:
|
|
||||||
app.kubernetes.io/name: argocd-image-updater-config
|
|
||||||
app.kubernetes.io/part-of: argocd-image-updater
|
|
||||||
data:
|
|
||||||
# Force image-updater to use the ArgoCD API for write-back to avoid multi-source git issues.
|
|
||||||
write-back-method: argocd
|
|
||||||
# Keep git identity in case git mode is explicitly used for single-source apps later.
|
|
||||||
git.user: argocd-image-updater
|
|
||||||
git.email: argocd@turing.lan
|
|
||||||
argocd.server_addr: argocd-server.argocd.svc.cluster.local
|
|
||||||
argocd.plaintext: "true"
|
|
||||||
argocd.insecure: "true"
|
|
||||||
@@ -1,114 +0,0 @@
|
|||||||
# 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!
|
|
||||||
|
Before Width: | Height: | Size: 49 KiB After Width: | Height: | Size: 49 KiB |
@@ -1,78 +0,0 @@
|
|||||||
# TuringPi GitOps Deployment Summary
|
|
||||||
|
|
||||||
## ✅ Successfully Deployed
|
|
||||||
|
|
||||||
### ArgoCD GitOps Platform
|
|
||||||
- **URL**: http://192.168.222.25
|
|
||||||
- **Username**: admin
|
|
||||||
- **Password**: fJ3diddVd2yson3W
|
|
||||||
- **Features**: GitOps CD, Image auto-updates, Helm support
|
|
||||||
|
|
||||||
### Gitea Self-Hosted Git Server
|
|
||||||
- **URL**: http://192.168.222.27:3000
|
|
||||||
- **Username**: admin
|
|
||||||
- **Password**: gitea-admin-pass
|
|
||||||
- **SSH**: git@192.168.222.26
|
|
||||||
- **Features**: PostgreSQL backend, NFS storage, SSH access
|
|
||||||
|
|
||||||
## 🚀 Repository Status
|
|
||||||
|
|
||||||
**Local Repository**: `/home/gilgamezh/code/turingpi`
|
|
||||||
**Gitea Repository**: http://192.168.222.27:3000/admin/turingpi
|
|
||||||
**SSH Clone URL**: `git@192.168.222.26:admin/turingpi.git`
|
|
||||||
|
|
||||||
### Latest Commit
|
|
||||||
```
|
|
||||||
45dfbfc Add ArgoCD and Gitea for GitOps workflow implementation
|
|
||||||
```
|
|
||||||
|
|
||||||
**Includes:**
|
|
||||||
- ArgoCD configuration (`argocd_values.yaml`)
|
|
||||||
- Gitea configuration (`gitea_values.yaml`)
|
|
||||||
- Example ArgoCD Application with auto-updates
|
|
||||||
- Migration guides and documentation
|
|
||||||
- All existing Helm configurations
|
|
||||||
|
|
||||||
## 🔧 What's Working
|
|
||||||
|
|
||||||
✅ **ArgoCD Web UI** - Access at http://192.168.222.25
|
|
||||||
✅ **Gitea Web UI** - Access at http://192.168.222.27:3000
|
|
||||||
✅ **Repository Push** - Code successfully pushed to Gitea
|
|
||||||
✅ **Image Auto-Updates** - ArgoCD Image Updater configured for "latest" tags
|
|
||||||
✅ **LAN Security** - IP whitelisting enforced on both services
|
|
||||||
✅ **NFS Storage** - Persistent data on your existing NFS setup
|
|
||||||
✅ **LoadBalancer** - MetalLB providing external IPs
|
|
||||||
|
|
||||||
## 📋 Next Steps
|
|
||||||
|
|
||||||
1. **Access ArgoCD UI** and explore the interface
|
|
||||||
2. **Create first ArgoCD Application** pointing to your Gitea repo
|
|
||||||
3. **Test GitOps workflow**:
|
|
||||||
```bash
|
|
||||||
# Make a change to values file
|
|
||||||
git add changed-file.yaml
|
|
||||||
git commit -m "Update application config"
|
|
||||||
git push gitea master
|
|
||||||
# Watch ArgoCD auto-sync the changes
|
|
||||||
```
|
|
||||||
4. **Migrate existing applications** from manual Helm to GitOps
|
|
||||||
5. **Set up SSH key properly** for passwordless Git operations
|
|
||||||
|
|
||||||
## 🔐 SSH Setup Note
|
|
||||||
|
|
||||||
Your SSH key has been added to Gitea, but there may be a key mismatch. To fix:
|
|
||||||
|
|
||||||
1. Check which SSH key is being used: `ssh-add -l`
|
|
||||||
2. Test connection: `ssh -T git@192.168.222.26`
|
|
||||||
3. If issues persist, regenerate SSH key or use HTTPS for now
|
|
||||||
|
|
||||||
## 🎯 GitOps Benefits Achieved
|
|
||||||
|
|
||||||
- **Version Control**: All configs in Git with full history
|
|
||||||
- **Automated Deployments**: ArgoCD syncs Git changes automatically
|
|
||||||
- **Image Updates**: Latest container images pulled automatically
|
|
||||||
- **Rollback Capability**: Easy revert to any previous state
|
|
||||||
- **Self-Hosted**: No external dependencies, full control
|
|
||||||
- **Enterprise Features**: On your homelab hardware
|
|
||||||
|
|
||||||
Your TuringPi cluster now has production-grade GitOps capabilities! 🎉
|
|
||||||
@@ -1,159 +0,0 @@
|
|||||||
# 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
|
|
||||||
@@ -1,2 +0,0 @@
|
|||||||
ID: e464f256-841f-4ba6-a489-b72b0530f9ec
|
|
||||||
Key: 5a81e9238d361cce4393f56b8db8f4be2f23b0e9d571667c4a5625a7ca844a528195496d571dabf81b51a2480d07ac8ef0397b05f8cd7393984e4f74b516c6f9
|
|
||||||
@@ -1,20 +0,0 @@
|
|||||||
---
|
|
||||||
image:
|
|
||||||
repository: ghcr.io/flaresolverr/flaresolverr
|
|
||||||
pullPolicy: IfNotPresent
|
|
||||||
tag: "latest@sha256:f104ee51e5124d83cf3be9b37480649355d223f7d8f9e453d0d5ef06c6e3b31b"
|
|
||||||
|
|
||||||
env:
|
|
||||||
TZ: UTC
|
|
||||||
|
|
||||||
service:
|
|
||||||
main:
|
|
||||||
ports:
|
|
||||||
http:
|
|
||||||
port: 8191
|
|
||||||
|
|
||||||
ingress:
|
|
||||||
# -- Enable and configure ingress settings for the chart under this key.
|
|
||||||
# @default -- See values.yaml
|
|
||||||
main:
|
|
||||||
enabled: false
|
|
||||||
@@ -1,3 +0,0 @@
|
|||||||
master: curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false sh -s - --write-kubeconfig-mode 644 --disable servicelb --token torino --node-ip 192.168.222.237 --disable-cloud-controller --disable local-storage
|
|
||||||
|
|
||||||
nodes: curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_DOWNLOAD=false K3S_URL=https://192.168.222.237:6443 K3S_TOKEN=torino sh -
|
|
||||||
@@ -1,45 +0,0 @@
|
|||||||
---
|
|
||||||
image:
|
|
||||||
repository: docker.io/jellyfin/jellyfin
|
|
||||||
tag: "latest@sha256:96b09723b22fdde74283274bdc1f63b9b76768afd6045dd80d4a4559fc4bb7f3"
|
|
||||||
pullPolicy: Always
|
|
||||||
|
|
||||||
service:
|
|
||||||
type: LoadBalancer
|
|
||||||
port: 8096
|
|
||||||
|
|
||||||
persistence:
|
|
||||||
config:
|
|
||||||
existingClaim: "plex-config"
|
|
||||||
media:
|
|
||||||
existingClaim: "plex-data"
|
|
||||||
|
|
||||||
resources:
|
|
||||||
requests:
|
|
||||||
memory: "2Gi"
|
|
||||||
cpu: "1"
|
|
||||||
ephemeral-storage: "50Mi"
|
|
||||||
limits:
|
|
||||||
memory: "6Gi"
|
|
||||||
cpu: "1"
|
|
||||||
ephemeral-storage: "1Gi"
|
|
||||||
|
|
||||||
nodeSelector:
|
|
||||||
kubernetes.io/arch: amd64
|
|
||||||
|
|
||||||
securityContext:
|
|
||||||
capabilities:
|
|
||||||
add:
|
|
||||||
- "SYS_ADMIN"
|
|
||||||
drop:
|
|
||||||
- "ALL"
|
|
||||||
privileged: false
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
- name: hwa
|
|
||||||
hostPath:
|
|
||||||
path: /dev/dri
|
|
||||||
|
|
||||||
volumeMounts:
|
|
||||||
- name: hwa
|
|
||||||
mountPath: /dev/dri
|
|
||||||
@@ -1,15 +0,0 @@
|
|||||||
prometheus:
|
|
||||||
prometheusSpec:
|
|
||||||
storageSpec:
|
|
||||||
volumeClaimTemplate:
|
|
||||||
spec:
|
|
||||||
storageClassName: nfs-client
|
|
||||||
accessModes: ["ReadWriteOnce"]
|
|
||||||
resources:
|
|
||||||
requests:
|
|
||||||
storage: 50Gi # You can adjust the size as needed
|
|
||||||
|
|
||||||
grafana:
|
|
||||||
service:
|
|
||||||
type: LoadBalancer
|
|
||||||
port: 80
|
|
||||||
@@ -1,8 +0,0 @@
|
|||||||
helm:
|
|
||||||
parameters:
|
|
||||||
- name: image.repository
|
|
||||||
value: lscr.io/linuxserver/prowlarr
|
|
||||||
forcestring: true
|
|
||||||
- name: image.tag
|
|
||||||
value: latest@sha256:964485823771c102427a0c1cd896cf6b576add6f21bd041498b92cb040ee7270
|
|
||||||
forcestring: true
|
|
||||||
@@ -1,21 +0,0 @@
|
|||||||
resources:
|
|
||||||
- apiVersion: v1
|
|
||||||
kind: Deployment
|
|
||||||
metadata:
|
|
||||||
name: flaresolverr
|
|
||||||
spec:
|
|
||||||
replicas: 1
|
|
||||||
selector:
|
|
||||||
matchLabels:
|
|
||||||
app: flaresolverr
|
|
||||||
template:
|
|
||||||
metadata:
|
|
||||||
labels:
|
|
||||||
app: flaresolverr
|
|
||||||
spec:
|
|
||||||
containers:
|
|
||||||
- name: flaresolverr
|
|
||||||
image: flaresolverr/flaresolverr:latest
|
|
||||||
ports:
|
|
||||||
- containerPort: 8191
|
|
||||||
|
|
||||||
Reference in New Issue
Block a user