Homelab GitOps Repository

Video Tutorial

Watch the complete homelab setup walkthrough on YouTube.

GitOps Kubernetes cluster with ArgoCD and External Secrets Operator (ESO) using Bitwarden Secrets Manager. Bootstrap installs core services, ArgoCD handles everything else.

Setup

Clone the repository and ensure you have access to your Kubernetes cluster.

git clone https://github.com/decodersam/homelab && cd homelab
# Ensure kubeconfig is available (either in ~/.kube/config or ./kubeconfig)
export KUBECONFIG=./kubeconfig  # if using local kubeconfig

Bootstrap

Deploy the core infrastructure components using Terraform. This sets up ArgoCD and essential operators.

Fresh install

terraform init && terraform apply

Required files

• kubeconfig - Required
• Bitwarden Secrets Manager credentials (configured after bootstrap)

Access

Service endpoints are available via LoadBalancer IPs. Use these commands to get the URLs:

# Get ArgoCD URL
kubectl get svc -n argocd argocd-server -o jsonpath='http://{.status.loadBalancer.ingress[0].ip}'

# Get Homepage URL
kubectl get svc -n homepage homepage -o jsonpath='http://{.status.loadBalancer.ingress[0].ip}'

Operations

Common commands for managing and monitoring your GitOps deployment.

just --list              # Show all commands
just launch_argo         # Open ArgoCD UI
kubectl get app -n argocd  # Check app status

Image Updates

ArgoCD Image Updater automatically tracks and updates container images using semantic versioning.

Requirements:

• Application must use Kustomize or Helm source type (not Directory)
• Current image tag must be semver-compliant (e.g., 1.0.0, not latest)
• Tags must match the configured regex pattern

Example annotations:

argocd-image-updater.argoproj.io/image-list: myapp=docker.io/user/image
argocd-image-updater.argoproj.io/myapp.update-strategy: semver
argocd-image-updater.argoproj.io/myapp.allow-tags: regexp:^[0-9]+\.[0-9]+\.[0-9]+$
argocd-image-updater.argoproj.io/write-back-method: git
argocd-image-updater.argoproj.io/git-branch: main

Secrets

External Secrets Operator with Bitwarden provider.

Bitwarden setup

After deployment, configure Bitwarden Secrets Manager credentials from environment:

export BITWARDEN_ORG_ID=your-org-id
export BITWARDEN_PROJECT_ID=your-project-id
export BITWARDEN_MACHINE_ACCOUNT_TOKEN=your-token
just patch-bitwarden

Troubleshooting

Quick fixes for common issues you might encounter.

• Jobs disappear quickly: kube-cleanup-operator deletes after 15min
• ESO not syncing: Check Bitwarden credentials and secret paths in ExternalSecrets