turingpi/argocd-migration-guide.md

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:

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:

helm upgrade plex kube-plex/charts/kube-plex --values plex_values.yml

Becomes this ArgoCD Application:

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:

# 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:

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!