Skip to main content

Getting Started: Homelab Cluster and GitOps Onboarding

This guide walks you through spinning up a Kubernetes homelab: provisioning VMs, bootstrapping the cluster, and deploying workloads using GitOps—all in under one hour.

info

For a minimal demo or test setup, see the quick‑start version.

Prerequisites​

  • Proxmox access (with SSH key set up on the hypervisor).
  • Installed tools:
  • terraform.tfvars file with your cluster's details (see below for example).
  • Access to this Git repository.

Overview of steps​

  1. Configure cluster variables.
  2. Launch and provision VMs with Talos.
  3. Retrieve cluster access configs.
  4. Bootstrap and verify ArgoCD.
  5. Confirm GitOps deployment and cluster health.

Prepare the configuration​

  1. Clone the repository: Download the required files and move into the working directory.

    git clone https://github.com/theepicsaxguy/homelab.git
    cd homelab

  2. Configure cluster variables: Edit or create the terraform.tfvars file to define your cluster nodes:

    # terraform.tfvars
    cluster_name     = "homelab"
    controlplane_ips = ["10.25.150.10", "10.25.150.11", "10.25.150.12"]
    worker_ips       = ["10.25.150.20", "10.25.150.21"]
    info

    Use secure storage for secrets, like 1Password or Bitwarden, and avoid committing sensitive files. For more information, see the Argo CD Secrets Management .

Apply and deploy the cluster​

  1. Initialize SSH agent and OpenTofu: Enable SSH access and initialize the environment.

    eval $(ssh-agent)
    ssh-add ~/.ssh/id_rsa
    tofu init

  2. Provision the VMs and Talos cluster: This step creates and configures all control-plane and worker nodes.

    tofu apply

  3. Retrieve Talos and Kubernetes configs: Fetch access configs and set secure permissions.

    tofu output -raw talos_config > ~/.talos/config
    tofu output -raw kube_config > ~/.kube/config
    chmod 600 ~/.talos/config ~/.kube/config

Bootstrap and verify ArgoCD​

  1. Check or install ArgoCD: ArgoCD is usually installed automatically. To verify or re-apply manually:

    kubectl get pods -n argocd
    # If ArgoCD pods aren't running, install with:
    kubectl apply -k k8s/infrastructure/controllers/argocd

  2. Monitor ApplicationSet synchronization: Use the ArgoCD CLI to confirm apps are recognized and syncing.

    argocd app list

Verify the setup​

  1. Check node and service health:

    talosctl health --talosconfig ~/.talos/config --nodes <control-plane-IP>

    All checks should report healthy.

  2. Confirm apps are synced in ArgoCD UI: All applications should show Synced / Healthy status.

  3. Inspect ArgoCD logs (optional troubleshooting):

    kubectl logs -n argocd deployment/argocd-server

    Look for messages indicating healthy reconciliation.

Pro tips and troubleshooting​

  • To recreate a node (e.g., after resizing a disk):

    tofu taint 'module.talos.proxmox_virtual_environment_vm.this["work-00"]'
    tofu apply

  • For common issues (API or etcd failures):

    talosctl etcd members

  • Back up your talosconfig and kubeconfig immediately after setup.

  • Document and save your network layout for future troubleshooting.

For further details on cluster architecture, networking, and recovery, see Cluster Details.