Homelab GitOps

This repository implements the ArgoCD App of Apps pattern for managing a homelab Kubernetes cluster using GitOps principles.

Overview

The App of Apps pattern allows you to manage multiple ArgoCD applications from a single repository. This approach provides:

• Centralized Management: All applications are defined in one place
• Version Control: Application configurations are versioned with Git
• Automated Deployment: Changes are automatically deployed to the cluster
• Consistency: Ensures all environments follow the same patterns

Repository Structure

homelab-gitops/
├── app-of-apps.yaml          # Main ArgoCD Application that manages all others
├── apps/                     # Individual ArgoCD Application manifests
│   ├── cert-manager.yaml    
│   ├── prometheus-stack.yaml
│   ├── homelab-services.yaml
│   ├── nfs-provisioner.yaml
│   ├── metallb.yaml
│   ├── velero.yaml
│   └── ingress-nginx.yaml
├── apps-disabled/            # Disabled applications (not deployed)
│   ├── nginx-ingress.yaml   # Legacy NGINX Ingress (disabled)
│   └── README.md
├── manifests/                # Kubernetes manifests for custom applications
│   ├── homelab-services/     # Custom application manifests
│   │   ├── whoami.yaml
│   │   ├── monitoring-ingress.yaml
│   │   └── argocd-ingress.yaml
│   ├── monitoring-namespace/ # Monitoring namespace with pod security
│   ├── metallb-namespace/    # MetalLB namespace with pod security
│   ├── metallb-ip-pool/      # MetalLB IP pool configuration
│   └── velero-namespace/     # Velero namespace with pod security
├── docs/                     # Documentation
│   └── ARGOCD-SETUP.md      # ArgoCD external proxy configuration
└── README.md

Getting Started

Prerequisites

1. A Kubernetes cluster (k3s, k8s, etc.)
2. ArgoCD installed in the cluster
3. This repository accessible from your cluster
4. On each Kubernetes node (workers), install the NFS client package so the cluster can mount NFS exports. On Ubuntu/Debian nodes:

sudo apt update
sudo apt install -y nfs-common

On RHEL/Fedora/CentOS nodes:

sudo dnf install -y nfs-utils   # or `yum install -y nfs-utils`

Installation

1. Clone this repository (if not already done):

   git clone https://github.com/jamilshaikh07/homelab-gitops.git
   cd homelab-gitops

2. Deploy the App of Apps:

   kubectl apply -f app-of-apps.yaml

3. Access ArgoCD UI:

   # Get ArgoCD admin password
   kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
   
   # Port forward to access UI
   kubectl port-forward svc/argocd-server -n argocd 8080:443

4. View in ArgoCD: Open https://localhost:8080 and login with admin credentials

Applications Included

Infrastructure Applications

• cert-manager: Automatic TLS certificate management
• prometheus-stack: Complete monitoring stack (Prometheus, Grafana, AlertManager)
• nfs-provisioner: NFS storage provisioner for persistent volumes
• metallb: Load balancer for bare metal Kubernetes clusters
• velero: Backup and disaster recovery solution with MinIO backend
• ingress-nginx: NGINX Ingress Controller for HTTP/HTTPS routing

Custom Applications

• homelab-services: Custom applications and services specific to your homelab

External Access

This setup includes NGINX Proxy Manager at 10.20.0.127 for external SSL termination:

• ArgoCD: https://argocd.devopsowl.com
• Grafana: https://grafana.devopsowl.com
• Prometheus: https://prometheus.devopsowl.com

All services use wildcard SSL certificates (*.devopsowl.com) managed by Let's Encrypt with DNS01 challenge.

Infrastructure Components

Storage

• NFS Provisioner: Provides persistent storage using NFS
• Default Storage Class: nfs-client for dynamic volume provisioning

Networking

• MetalLB: Load balancer with IP pool 10.20.0.81-10.20.0.99
• NGINX Ingress: HTTP/HTTPS routing to services
• External Proxy: NGINX Proxy Manager for SSL termination

Monitoring

• Prometheus: Metrics collection and alerting
• Grafana: Visualization and dashboards
• AlertManager: Alert routing and management
• Node Exporter: Host metrics collection

Backup & Recovery

• Velero: Cluster backup with MinIO S3 backend (10.20.0.163:9000)
• Node Agent: File-level backup for persistent volumes
• Scheduled Backups: Daily backup at 2 AM

Documentation

• ArgoCD External Proxy Setup - Detailed configuration for external proxy

Adding New Applications

Method 1: Helm Chart Application

Create a new file in the apps/ directory:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: your-app-name
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    namespace: your-namespace
    server: https://kubernetes.default.svc
  project: default
  source:
    chart: chart-name
    repoURL: https://helm-repo-url
    targetRevision: chart-version
    helm:
      values: |
        # Your helm values here
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Method 2: Git Repository Application

For custom Kubernetes manifests:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: your-app-name
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  destination:
    namespace: your-namespace
    server: https://kubernetes.default.svc
  project: default
  source:
    path: manifests/your-app-path
    repoURL: https://github.com/jamilshaikh07/homelab-gitops
    targetRevision: main
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

Managing Applications

Disabling Applications

To disable an application without deleting its configuration:

1. Move to disabled directory:

   mv apps/app-name.yaml apps-disabled/

2. Commit changes:

   git add apps-disabled/app-name.yaml
   git commit -m "Disable app-name"
   git push

Re-enabling Applications

To re-enable a disabled application:

1. Move back to apps directory:

   mv apps-disabled/app-name.yaml apps/

2. Commit changes:

   git add apps/app-name.yaml
   git commit -m "Re-enable app-name"
   git push

Configuration

Sync Policies

All applications are configured with automated sync policies:

• prune: true: Removes resources deleted from Git
• selfHeal: true: Corrects manual changes to match Git state
• CreateNamespace=true: Automatically creates target namespaces

Customization

To customize any application:

1. Edit the corresponding file in the apps/ directory
2. Commit and push changes
3. ArgoCD will automatically detect and apply changes

Monitoring

Monitor your applications through:

• ArgoCD UI: Application status and sync state
• Grafana: Metrics and dashboards (if prometheus-stack is enabled)
• kubectl: Direct cluster inspection

Troubleshooting

Common Issues

1. Application not syncing:

   argocd app sync <app-name>

2. Check application status:

   argocd app get <app-name>

3. View application logs:

   kubectl logs -n argocd deployment/argocd-application-controller

Manual Sync

If automatic sync is disabled or failing:

argocd app sync app-of-apps

Security Considerations

• Review all Helm values and manifests before deployment
• Use secrets management for sensitive data
• Regularly update application versions
• Monitor for security vulnerabilities

Contributing

1. Create a feature branch
2. Make your changes
3. Test in a development environment
4. Submit a pull request

References

• ArgoCD Documentation
• App of Apps Pattern
• GitOps Principles