Initial monorepo scaffold

Turborepo + pnpm monorepo for k3s homelab cluster on Intel NUCs. - Apps: Next.js web frontend, Express API (TypeScript, Dockerfiles, k8s manifests) - Packages: shared UI, ESLint config, TypeScript config, Drizzle DB schemas - Infra/Ansible: bare-metal provisioning with roles for common, k3s-server, k3s-agent, hardening - Infra/Kubernetes: ArgoCD GitOps (app-of-apps + ApplicationSets), platform components (cert-manager, Traefik, CloudNativePG, Valkey, Longhorn, Sealed Secrets), namespaces - Observability: kube-prometheus-stack, Loki, Promtail as ArgoCD Applications - CI/CD: GitHub Actions for PR builds, preview deploys, production deploys - DX: Taskfile, utility scripts, copier templates, Ubiquiti network docs
2026-03-19 22:24:56 +00:00
commit 96e3f32f28
118 changed files with 2681 additions and 0 deletions
--- a/infra/ansible/ansible.cfg
+++ b/infra/ansible/ansible.cfg
@@ -0,0 +1,14 @@
+[defaults]
+inventory = inventory/hosts.yaml
+roles_path = roles
+remote_user = julia
+private_key_file = ~/.ssh/homelab
+host_key_checking = False
+retry_files_enabled = False
+stdout_callback = yaml
+callbacks_enabled = profile_tasks
+
+[privilege_escalation]
+become = True
+become_method = sudo
+become_user = root
--- a/infra/ansible/inventory/group_vars/agents.yaml
+++ b/infra/ansible/inventory/group_vars/agents.yaml
@@ -0,0 +1,3 @@
+---
+k3s_agent_args: >-
+  --node-label=node-role.kubernetes.io/worker=true
--- a/infra/ansible/inventory/group_vars/all.yaml
+++ b/infra/ansible/inventory/group_vars/all.yaml
@@ -0,0 +1,37 @@
+---
+# Timezone
+timezone: America/New_York
+
+# NTP
+ntp_servers:
+  - 0.ubuntu.pool.ntp.org
+  - 1.ubuntu.pool.ntp.org
+
+# k3s
+k3s_version: v1.31.4+k3s1
+k3s_server_url: "https://{{ hostvars['nuc01']['ansible_host'] }}:6443"
+k3s_token: "{{ vault_k3s_token }}"
+
+# System packages
+common_packages:
+  - curl
+  - wget
+  - git
+  - htop
+  - iotop
+  - net-tools
+  - unzip
+  - jq
+  - open-iscsi
+  - nfs-common
+  - cryptsetup
+
+# Container runtime
+containerd_config:
+  max_container_log_size: 10M
+  max_container_log_files: 3
+
+# Network
+cluster_cidr: 10.42.0.0/16
+service_cidr: 10.43.0.0/16
+cluster_dns: 10.43.0.10
--- a/infra/ansible/inventory/group_vars/servers.yaml
+++ b/infra/ansible/inventory/group_vars/servers.yaml
@@ -0,0 +1,12 @@
+---
+k3s_server_args: >-
+  --cluster-cidr={{ cluster_cidr }}
+  --service-cidr={{ service_cidr }}
+  --cluster-dns={{ cluster_dns }}
+  --disable=servicelb
+  --write-kubeconfig-mode=644
+  --tls-san={{ ansible_host }}
+  --tls-san=k3s.homelab.local
+  --kube-apiserver-arg=audit-log-maxage=30
+  --kube-apiserver-arg=audit-log-maxbackup=10
+  --kube-apiserver-arg=audit-log-maxsize=100
--- a/infra/ansible/inventory/host_vars/nuc01.yaml
+++ b/infra/ansible/inventory/host_vars/nuc01.yaml
@@ -0,0 +1,4 @@
+---
+node_labels:
+  - topology.kubernetes.io/zone=rack1
+  - node.kubernetes.io/instance-type=nuc
--- a/infra/ansible/inventory/hosts.yaml
+++ b/infra/ansible/inventory/hosts.yaml
@@ -0,0 +1,18 @@
+---
+all:
+  children:
+    k3s_cluster:
+      children:
+        servers:
+          hosts:
+            nuc01:
+              ansible_host: 10.0.10.11
+              k3s_role: server
+        agents:
+          hosts:
+            nuc02:
+              ansible_host: 10.0.10.12
+              k3s_role: agent
+            nuc03:
+              ansible_host: 10.0.10.13
+              k3s_role: agent
--- a/infra/ansible/playbooks/bootstrap.yaml
+++ b/infra/ansible/playbooks/bootstrap.yaml
@@ -0,0 +1,7 @@
+---
+- name: Bootstrap all nodes
+  hosts: k3s_cluster
+  become: true
+  roles:
+    - common
+    - hardening
--- a/infra/ansible/playbooks/k3s-agent.yaml
+++ b/infra/ansible/playbooks/k3s-agent.yaml
@@ -0,0 +1,6 @@
+---
+- name: Install k3s agent nodes
+  hosts: agents
+  become: true
+  roles:
+    - k3s-agent
--- a/infra/ansible/playbooks/k3s-server.yaml
+++ b/infra/ansible/playbooks/k3s-server.yaml
@@ -0,0 +1,6 @@
+---
+- name: Install k3s server nodes
+  hosts: servers
+  become: true
+  roles:
+    - k3s-server
--- a/infra/ansible/playbooks/k3s-upgrade.yaml
+++ b/infra/ansible/playbooks/k3s-upgrade.yaml
@@ -0,0 +1,49 @@
+---
+- name: Upgrade k3s cluster
+  hosts: k3s_cluster
+  become: true
+  serial: 1
+  vars:
+    k3s_upgrade_version: "{{ k3s_version }}"
+  tasks:
+    - name: Cordon node
+      ansible.builtin.command:
+        cmd: k3s kubectl cordon {{ inventory_hostname }}
+      delegate_to: "{{ groups['servers'][0] }}"
+      changed_when: true
+
+    - name: Drain node
+      ansible.builtin.command:
+        cmd: >-
+          k3s kubectl drain {{ inventory_hostname }}
+          --ignore-daemonsets
+          --delete-emptydir-data
+          --timeout=120s
+      delegate_to: "{{ groups['servers'][0] }}"
+      changed_when: true
+
+    - name: Upgrade k3s
+      ansible.builtin.command:
+        cmd: /tmp/k3s-install.sh
+      environment:
+        INSTALL_K3S_VERSION: "{{ k3s_upgrade_version }}"
+        K3S_TOKEN: "{{ k3s_token }}"
+        INSTALL_K3S_EXEC: "{{ 'server ' + k3s_server_args if k3s_role == 'server' else 'agent ' + k3s_agent_args }}"
+        K3S_URL: "{{ '' if k3s_role == 'server' else k3s_server_url }}"
+      changed_when: true
+
+    - name: Wait for node to be ready
+      ansible.builtin.command:
+        cmd: k3s kubectl get node {{ inventory_hostname }} -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
+      delegate_to: "{{ groups['servers'][0] }}"
+      register: node_ready
+      retries: 30
+      delay: 10
+      until: node_ready.stdout == "True"
+      changed_when: false
+
+    - name: Uncordon node
+      ansible.builtin.command:
+        cmd: k3s kubectl uncordon {{ inventory_hostname }}
+      delegate_to: "{{ groups['servers'][0] }}"
+      changed_when: true
--- a/infra/ansible/playbooks/reset.yaml
+++ b/infra/ansible/playbooks/reset.yaml
@@ -0,0 +1,38 @@
+---
+- name: Reset k3s cluster (DESTRUCTIVE)
+  hosts: k3s_cluster
+  become: true
+  tasks:
+    - name: Confirm reset
+      ansible.builtin.pause:
+        prompt: "This will DESTROY the k3s cluster. Type 'yes' to continue"
+      register: confirm
+      run_once: true
+
+    - name: Abort if not confirmed
+      ansible.builtin.fail:
+        msg: "Reset aborted"
+      when: confirm.user_input != "yes"
+      run_once: true
+
+    - name: Uninstall k3s agent
+      ansible.builtin.command:
+        cmd: /usr/local/bin/k3s-agent-uninstall.sh
+      when: k3s_role == 'agent'
+      ignore_errors: true
+      changed_when: true
+
+    - name: Uninstall k3s server
+      ansible.builtin.command:
+        cmd: /usr/local/bin/k3s-uninstall.sh
+      when: k3s_role == 'server'
+      ignore_errors: true
+      changed_when: true
+
+    - name: Clean up data directories
+      ansible.builtin.file:
+        path: "{{ item }}"
+        state: absent
+      loop:
+        - /var/lib/rancher
+        - /etc/rancher
--- a/infra/ansible/playbooks/site.yaml
+++ b/infra/ansible/playbooks/site.yaml
@@ -0,0 +1,9 @@
+---
+- name: Full cluster deployment
+  ansible.builtin.import_playbook: bootstrap.yaml
+
+- name: Install k3s servers
+  ansible.builtin.import_playbook: k3s-server.yaml
+
+- name: Install k3s agents
+  ansible.builtin.import_playbook: k3s-agent.yaml
--- a/infra/ansible/requirements.yaml
+++ b/infra/ansible/requirements.yaml
@@ -0,0 +1,8 @@
+---
+collections:
+  - name: ansible.posix
+    version: ">=1.5.0"
+  - name: community.general
+    version: ">=9.0.0"
+  - name: kubernetes.core
+    version: ">=4.0.0"
--- a/infra/ansible/roles/common/handlers/main.yaml
+++ b/infra/ansible/roles/common/handlers/main.yaml
@@ -0,0 +1,6 @@
+---
+- name: restart timesyncd
+  ansible.builtin.systemd:
+    name: systemd-timesyncd
+    state: restarted
+    enabled: true
--- a/infra/ansible/roles/common/tasks/main.yaml
+++ b/infra/ansible/roles/common/tasks/main.yaml
@@ -0,0 +1,55 @@
+---
+- name: Set timezone
+  community.general.timezone:
+    name: "{{ timezone }}"
+
+- name: Configure NTP
+  ansible.builtin.template:
+    src: timesyncd.conf.j2
+    dest: /etc/systemd/timesyncd.conf
+    mode: "0644"
+  notify: restart timesyncd
+
+- name: Update apt cache
+  ansible.builtin.apt:
+    update_cache: true
+    cache_valid_time: 3600
+
+- name: Install common packages
+  ansible.builtin.apt:
+    name: "{{ common_packages }}"
+    state: present
+
+- name: Configure sysctl for k8s
+  ansible.posix.sysctl:
+    name: "{{ item.key }}"
+    value: "{{ item.value }}"
+    sysctl_set: true
+    reload: true
+  loop:
+    - { key: net.bridge.bridge-nf-call-iptables, value: "1" }
+    - { key: net.bridge.bridge-nf-call-ip6tables, value: "1" }
+    - { key: net.ipv4.ip_forward, value: "1" }
+    - { key: fs.inotify.max_user_instances, value: "512" }
+    - { key: fs.inotify.max_user_watches, value: "524288" }
+
+- name: Load br_netfilter module
+  community.general.modprobe:
+    name: br_netfilter
+    persistent: present
+
+- name: Disable swap
+  ansible.builtin.command: swapoff -a
+  changed_when: false
+
+- name: Remove swap from fstab
+  ansible.builtin.lineinfile:
+    path: /etc/fstab
+    regexp: '\sswap\s'
+    state: absent
+
+- name: Enable iscsid service (for Longhorn)
+  ansible.builtin.systemd:
+    name: iscsid
+    enabled: true
+    state: started
--- a/infra/ansible/roles/common/templates/timesyncd.conf.j2
+++ b/infra/ansible/roles/common/templates/timesyncd.conf.j2
@@ -0,0 +1,5 @@
+[Time]
+{% for server in ntp_servers %}
+NTP={{ server }}
+{% endfor %}
+FallbackNTP=ntp.ubuntu.com
--- a/infra/ansible/roles/hardening/handlers/main.yaml
+++ b/infra/ansible/roles/hardening/handlers/main.yaml
@@ -0,0 +1,5 @@
+---
+- name: restart sshd
+  ansible.builtin.systemd:
+    name: sshd
+    state: restarted
--- a/infra/ansible/roles/hardening/tasks/main.yaml
+++ b/infra/ansible/roles/hardening/tasks/main.yaml
@@ -0,0 +1,81 @@
+---
+- name: Ensure SSH password authentication is disabled
+  ansible.builtin.lineinfile:
+    path: /etc/ssh/sshd_config
+    regexp: "^#?PasswordAuthentication"
+    line: "PasswordAuthentication no"
+  notify: restart sshd
+
+- name: Disable root SSH login
+  ansible.builtin.lineinfile:
+    path: /etc/ssh/sshd_config
+    regexp: "^#?PermitRootLogin"
+    line: "PermitRootLogin no"
+  notify: restart sshd
+
+- name: Install and configure UFW
+  ansible.builtin.apt:
+    name: ufw
+    state: present
+
+- name: Set UFW default deny incoming
+  community.general.ufw:
+    direction: incoming
+    default: deny
+
+- name: Set UFW default allow outgoing
+  community.general.ufw:
+    direction: outgoing
+    default: allow
+
+- name: Allow SSH
+  community.general.ufw:
+    rule: allow
+    port: "22"
+    proto: tcp
+
+- name: Allow k3s API server (servers only)
+  community.general.ufw:
+    rule: allow
+    port: "6443"
+    proto: tcp
+  when: k3s_role == 'server'
+
+- name: Allow k3s flannel VXLAN
+  community.general.ufw:
+    rule: allow
+    port: "8472"
+    proto: udp
+
+- name: Allow kubelet metrics
+  community.general.ufw:
+    rule: allow
+    port: "10250"
+    proto: tcp
+
+- name: Allow HTTP/HTTPS (for Traefik ingress)
+  community.general.ufw:
+    rule: allow
+    port: "{{ item }}"
+    proto: tcp
+  loop:
+    - "80"
+    - "443"
+
+- name: Enable UFW
+  community.general.ufw:
+    state: enabled
+
+- name: Configure automatic security updates
+  ansible.builtin.apt:
+    name: unattended-upgrades
+    state: present
+
+- name: Enable automatic security updates
+  ansible.builtin.copy:
+    dest: /etc/apt/apt.conf.d/20auto-upgrades
+    content: |
+      APT::Periodic::Update-Package-Lists "1";
+      APT::Periodic::Unattended-Upgrade "1";
+      APT::Periodic::AutocleanInterval "7";
+    mode: "0644"
--- a/infra/ansible/roles/k3s-agent/tasks/main.yaml
+++ b/infra/ansible/roles/k3s-agent/tasks/main.yaml
@@ -0,0 +1,29 @@
+---
+- name: Check if k3s-agent is installed
+  ansible.builtin.stat:
+    path: /usr/local/bin/k3s
+  register: k3s_binary
+
+- name: Download k3s installer
+  ansible.builtin.get_url:
+    url: https://get.k3s.io
+    dest: /tmp/k3s-install.sh
+    mode: "0755"
+  when: not k3s_binary.stat.exists
+
+- name: Install k3s agent
+  ansible.builtin.command:
+    cmd: /tmp/k3s-install.sh
+  environment:
+    INSTALL_K3S_VERSION: "{{ k3s_version }}"
+    K3S_URL: "{{ k3s_server_url }}"
+    K3S_TOKEN: "{{ k3s_token }}"
+    INSTALL_K3S_EXEC: "agent {{ k3s_agent_args }}"
+  when: not k3s_binary.stat.exists
+  changed_when: true
+
+- name: Wait for k3s-agent to be ready
+  ansible.builtin.systemd:
+    name: k3s-agent
+    state: started
+    enabled: true
--- a/infra/ansible/roles/k3s-server/tasks/main.yaml
+++ b/infra/ansible/roles/k3s-server/tasks/main.yaml
@@ -0,0 +1,47 @@
+---
+- name: Check if k3s is installed
+  ansible.builtin.stat:
+    path: /usr/local/bin/k3s
+  register: k3s_binary
+
+- name: Download k3s installer
+  ansible.builtin.get_url:
+    url: https://get.k3s.io
+    dest: /tmp/k3s-install.sh
+    mode: "0755"
+  when: not k3s_binary.stat.exists
+
+- name: Install k3s server
+  ansible.builtin.command:
+    cmd: /tmp/k3s-install.sh
+  environment:
+    INSTALL_K3S_VERSION: "{{ k3s_version }}"
+    K3S_TOKEN: "{{ k3s_token }}"
+    INSTALL_K3S_EXEC: "server {{ k3s_server_args }}"
+  when: not k3s_binary.stat.exists
+  changed_when: true
+
+- name: Wait for k3s to be ready
+  ansible.builtin.command:
+    cmd: k3s kubectl get nodes
+  register: k3s_ready
+  retries: 30
+  delay: 10
+  until: k3s_ready.rc == 0
+  changed_when: false
+
+- name: Fetch kubeconfig
+  ansible.builtin.fetch:
+    src: /etc/rancher/k3s/k3s.yaml
+    dest: "{{ playbook_dir }}/../../kubeconfig"
+    flat: true
+  run_once: true
+
+- name: Update kubeconfig server URL
+  ansible.builtin.lineinfile:
+    path: "{{ playbook_dir }}/../../kubeconfig"
+    regexp: "server: https://127.0.0.1:6443"
+    line: "    server: https://{{ ansible_host }}:6443"
+  delegate_to: localhost
+  become: false
+  run_once: true
--- a/infra/kubernetes/argocd/app-of-apps.yaml
+++ b/infra/kubernetes/argocd/app-of-apps.yaml
@@ -0,0 +1,22 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: app-of-apps
+  namespace: argocd
+  finalizers:
+    - resources-finalizer.argocd.argoproj.io
+spec:
+  project: default
+  source:
+    repoURL: https://github.com/OWNER/homelab.git
+    targetRevision: main
+    path: infra/kubernetes/argocd
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: argocd
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
--- a/infra/kubernetes/argocd/appsets/apps.yaml
+++ b/infra/kubernetes/argocd/appsets/apps.yaml
@@ -0,0 +1,30 @@
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: apps-production
+  namespace: argocd
+spec:
+  goTemplate: true
+  goTemplateOptions: ["missingkey=error"]
+  generators:
+    - git:
+        repoURL: https://github.com/OWNER/homelab.git
+        revision: main
+        directories:
+          - path: apps/*/k8s/overlays/production
+  template:
+    metadata:
+      name: "{{ index .path.segments 1 }}-production"
+    spec:
+      project: default
+      source:
+        repoURL: https://github.com/OWNER/homelab.git
+        targetRevision: main
+        path: "{{ .path.path }}"
+      destination:
+        server: https://kubernetes.default.svc
+        namespace: apps
+      syncPolicy:
+        automated:
+          prune: true
+          selfHeal: true
--- a/infra/kubernetes/argocd/appsets/platform.yaml
+++ b/infra/kubernetes/argocd/appsets/platform.yaml
@@ -0,0 +1,32 @@
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: platform
+  namespace: argocd
+spec:
+  goTemplate: true
+  goTemplateOptions: ["missingkey=error"]
+  generators:
+    - git:
+        repoURL: https://github.com/OWNER/homelab.git
+        revision: main
+        directories:
+          - path: infra/kubernetes/platform/*
+  template:
+    metadata:
+      name: "platform-{{ .path.basename }}"
+    spec:
+      project: default
+      source:
+        repoURL: https://github.com/OWNER/homelab.git
+        targetRevision: main
+        path: "{{ .path.path }}"
+      destination:
+        server: https://kubernetes.default.svc
+        namespace: platform
+      syncPolicy:
+        automated:
+          prune: true
+          selfHeal: true
+        syncOptions:
+          - CreateNamespace=true
--- a/infra/kubernetes/argocd/appsets/previews.yaml
+++ b/infra/kubernetes/argocd/appsets/previews.yaml
@@ -0,0 +1,34 @@
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: apps-preview
+  namespace: argocd
+spec:
+  goTemplate: true
+  goTemplateOptions: ["missingkey=error"]
+  generators:
+    - pullRequest:
+        github:
+          owner: OWNER
+          repo: homelab
+        requeueAfterSeconds: 60
+  template:
+    metadata:
+      name: "preview-{{ .number }}"
+    spec:
+      project: default
+      source:
+        repoURL: https://github.com/OWNER/homelab.git
+        targetRevision: "{{ .branch }}"
+        path: apps/*/k8s/overlays/preview
+        kustomize:
+          nameSuffix: "-pr{{ .number }}"
+      destination:
+        server: https://kubernetes.default.svc
+        namespace: "preview-{{ .number }}"
+      syncPolicy:
+        automated:
+          prune: true
+          selfHeal: true
+        syncOptions:
+          - CreateNamespace=true
--- a/infra/kubernetes/argocd/install.yaml
+++ b/infra/kubernetes/argocd/install.yaml
@@ -0,0 +1,2 @@
+# ArgoCD is installed via Kustomize remote base.
+# See kustomization.yaml for the version-pinned reference.
--- a/infra/kubernetes/argocd/kustomization.yaml
+++ b/infra/kubernetes/argocd/kustomization.yaml
@@ -0,0 +1,22 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+namespace: argocd
+resources:
+  - namespace.yaml
+  - https://raw.githubusercontent.com/argoproj/argo-cd/v2.13.3/manifests/install.yaml
+  - app-of-apps.yaml
+  - appsets/platform.yaml
+  - appsets/apps.yaml
+  - appsets/previews.yaml
+patches:
+  - target:
+      kind: ConfigMap
+      name: argocd-cm
+    patch: |
+      apiVersion: v1
+      kind: ConfigMap
+      metadata:
+        name: argocd-cm
+      data:
+        url: https://argocd.homelab.local
+        application.resourceTrackingMethod: annotation
--- a/infra/kubernetes/argocd/namespace.yaml
+++ b/infra/kubernetes/argocd/namespace.yaml
@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: argocd
--- a/infra/kubernetes/namespaces/apps.yaml
+++ b/infra/kubernetes/namespaces/apps.yaml
@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: apps
+  labels:
+    managed-by: argocd
--- a/infra/kubernetes/namespaces/kustomization.yaml
+++ b/infra/kubernetes/namespaces/kustomization.yaml
@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - apps.yaml
+  - platform.yaml
+  - observability.yaml
--- a/infra/kubernetes/namespaces/observability.yaml
+++ b/infra/kubernetes/namespaces/observability.yaml
@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: observability
+  labels:
+    managed-by: argocd
--- a/infra/kubernetes/namespaces/platform.yaml
+++ b/infra/kubernetes/namespaces/platform.yaml
@@ -0,0 +1,6 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: platform
+  labels:
+    managed-by: argocd
--- a/infra/kubernetes/observability/kube-prometheus-stack/application.yaml
+++ b/infra/kubernetes/observability/kube-prometheus-stack/application.yaml
@@ -0,0 +1,95 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: kube-prometheus-stack
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://prometheus-community.github.io/helm-charts
+    chart: kube-prometheus-stack
+    targetRevision: 67.9.0
+    helm:
+      valuesObject:
+        prometheus:
+          prometheusSpec:
+            retention: 15d
+            resources:
+              requests:
+                memory: 512Mi
+                cpu: 250m
+              limits:
+                memory: 2Gi
+            storageSpec:
+              volumeClaimTemplate:
+                spec:
+                  storageClassName: longhorn
+                  accessModes: ["ReadWriteOnce"]
+                  resources:
+                    requests:
+                      storage: 20Gi
+            serviceMonitorSelectorNilUsesHelmValues: false
+            podMonitorSelectorNilUsesHelmValues: false
+
+        grafana:
+          adminPassword: "changeme"
+          ingress:
+            enabled: true
+            ingressClassName: traefik
+            annotations:
+              cert-manager.io/cluster-issuer: letsencrypt-production
+            hosts:
+              - grafana.homelab.local
+            tls:
+              - secretName: grafana-tls
+                hosts:
+                  - grafana.homelab.local
+          sidecar:
+            dashboards:
+              enabled: true
+              searchNamespace: ALL
+              label: grafana_dashboard
+            datasources:
+              enabled: true
+              searchNamespace: ALL
+              label: grafana_datasource
+          resources:
+            requests:
+              memory: 128Mi
+              cpu: 100m
+            limits:
+              memory: 512Mi
+
+        alertmanager:
+          alertmanagerSpec:
+            resources:
+              requests:
+                memory: 64Mi
+                cpu: 50m
+              limits:
+                memory: 256Mi
+            storage:
+              volumeClaimTemplate:
+                spec:
+                  storageClassName: longhorn
+                  accessModes: ["ReadWriteOnce"]
+                  resources:
+                    requests:
+                      storage: 5Gi
+
+        nodeExporter:
+          enabled: true
+
+        kubeStateMetrics:
+          enabled: true
+
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: observability
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
+      - ServerSideApply=true
--- a/infra/kubernetes/observability/kube-prometheus-stack/dashboards/cluster-overview.yaml
+++ b/infra/kubernetes/observability/kube-prometheus-stack/dashboards/cluster-overview.yaml
@@ -0,0 +1,69 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cluster-overview-dashboard
+  namespace: observability
+  labels:
+    grafana_dashboard: "1"
+data:
+  cluster-overview.json: |
+    {
+      "annotations": { "list": [] },
+      "editable": true,
+      "fiscalYearStartMonth": 0,
+      "graphTooltip": 1,
+      "id": null,
+      "links": [],
+      "panels": [
+        {
+          "title": "CPU Usage by Node",
+          "type": "timeseries",
+          "gridPos": { "h": 8, "w": 12, "x": 0, "y": 0 },
+          "targets": [
+            {
+              "expr": "100 - (avg by(instance) (rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) * 100)",
+              "legendFormat": "{{ instance }}"
+            }
+          ]
+        },
+        {
+          "title": "Memory Usage by Node",
+          "type": "timeseries",
+          "gridPos": { "h": 8, "w": 12, "x": 12, "y": 0 },
+          "targets": [
+            {
+              "expr": "(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100",
+              "legendFormat": "{{ instance }}"
+            }
+          ]
+        },
+        {
+          "title": "Disk Usage by Node",
+          "type": "timeseries",
+          "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
+          "targets": [
+            {
+              "expr": "(1 - (node_filesystem_avail_bytes{mountpoint=\"/\"} / node_filesystem_size_bytes{mountpoint=\"/\"})) * 100",
+              "legendFormat": "{{ instance }}"
+            }
+          ]
+        },
+        {
+          "title": "Pod Count by Namespace",
+          "type": "bargauge",
+          "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
+          "targets": [
+            {
+              "expr": "count by(namespace) (kube_pod_info)",
+              "legendFormat": "{{ namespace }}"
+            }
+          ]
+        }
+      ],
+      "schemaVersion": 39,
+      "tags": ["homelab", "cluster"],
+      "templating": { "list": [] },
+      "time": { "from": "now-6h", "to": "now" },
+      "title": "Cluster Overview",
+      "uid": "cluster-overview"
+    }
--- a/infra/kubernetes/observability/kube-prometheus-stack/grafana-datasources.yaml
+++ b/infra/kubernetes/observability/kube-prometheus-stack/grafana-datasources.yaml
@@ -0,0 +1,17 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: loki-datasource
+  namespace: observability
+  labels:
+    grafana_datasource: "1"
+data:
+  loki-datasource.yaml: |
+    apiVersion: 1
+    datasources:
+      - name: Loki
+        type: loki
+        access: proxy
+        url: http://loki.observability.svc:3100
+        jsonData:
+          maxLines: 1000
--- a/infra/kubernetes/observability/kube-prometheus-stack/kustomization.yaml
+++ b/infra/kubernetes/observability/kube-prometheus-stack/kustomization.yaml
@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - application.yaml
+  - grafana-datasources.yaml
+  - dashboards/cluster-overview.yaml
--- a/infra/kubernetes/observability/kustomization.yaml
+++ b/infra/kubernetes/observability/kustomization.yaml
@@ -0,0 +1,6 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - kube-prometheus-stack/
+  - loki/
+  - promtail/
--- a/infra/kubernetes/observability/loki/application.yaml
+++ b/infra/kubernetes/observability/loki/application.yaml
@@ -0,0 +1,71 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: loki
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://grafana.github.io/helm-charts
+    chart: loki
+    targetRevision: 6.24.0
+    helm:
+      valuesObject:
+        deploymentMode: SingleBinary
+        loki:
+          auth_enabled: false
+          commonConfig:
+            replication_factor: 1
+          storage:
+            type: filesystem
+          schemaConfig:
+            configs:
+              - from: "2024-01-01"
+                store: tsdb
+                object_store: filesystem
+                schema: v13
+                index:
+                  prefix: loki_index_
+                  period: 24h
+          limits_config:
+            retention_period: 168h
+            max_query_series: 500
+            max_query_parallelism: 2
+
+        singleBinary:
+          replicas: 1
+          resources:
+            requests:
+              memory: 256Mi
+              cpu: 100m
+            limits:
+              memory: 1Gi
+          persistence:
+            enabled: true
+            storageClass: longhorn
+            size: 10Gi
+
+        gateway:
+          enabled: false
+
+        backend:
+          replicas: 0
+        read:
+          replicas: 0
+        write:
+          replicas: 0
+
+        chunksCache:
+          enabled: false
+        resultsCache:
+          enabled: false
+
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: observability
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
+    syncOptions:
+      - CreateNamespace=true
--- a/infra/kubernetes/observability/loki/kustomization.yaml
+++ b/infra/kubernetes/observability/loki/kustomization.yaml
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - application.yaml
--- a/infra/kubernetes/observability/promtail/application.yaml
+++ b/infra/kubernetes/observability/promtail/application.yaml
@@ -0,0 +1,38 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: promtail
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: https://grafana.github.io/helm-charts
+    chart: promtail
+    targetRevision: 6.16.6
+    helm:
+      valuesObject:
+        config:
+          clients:
+            - url: http://loki.observability.svc:3100/loki/api/v1/push
+          snippets:
+            pipelineStages:
+              - cri: {}
+              - multiline:
+                  firstline: '^\d{4}-\d{2}-\d{2}'
+                  max_wait_time: 3s
+        resources:
+          requests:
+            memory: 64Mi
+            cpu: 50m
+          limits:
+            memory: 256Mi
+        tolerations:
+          - effect: NoSchedule
+            operator: Exists
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: observability
+  syncPolicy:
+    automated:
+      prune: true
+      selfHeal: true
--- a/infra/kubernetes/observability/promtail/kustomization.yaml
+++ b/infra/kubernetes/observability/promtail/kustomization.yaml
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - application.yaml
--- a/infra/kubernetes/platform/cert-manager/clusterissuer-letsencrypt.yaml
+++ b/infra/kubernetes/platform/cert-manager/clusterissuer-letsencrypt.yaml
@@ -0,0 +1,37 @@
+# Prerequisites: cert-manager must be installed via Helm first.
+# Install: helm install cert-manager jetstack/cert-manager --namespace cert-manager --set crds.enabled=true --version v1.16.3
+# This file configures the Let's Encrypt issuers after cert-manager is running.
+---
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-staging
+spec:
+  acme:
+    server: https://acme-staging-v02.api.letsencrypt.org/directory
+    email: admin@homelab.local
+    privateKeySecretRef:
+      name: letsencrypt-staging-key
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:
+              name: cloudflare-api-token
+              key: api-token
+---
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-production
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: admin@homelab.local
+    privateKeySecretRef:
+      name: letsencrypt-production-key
+    solvers:
+      - dns01:
+          cloudflare:
+            apiTokenSecretRef:
+              name: cloudflare-api-token
+              key: api-token
--- a/infra/kubernetes/platform/cert-manager/kustomization.yaml
+++ b/infra/kubernetes/platform/cert-manager/kustomization.yaml
@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - clusterissuer-letsencrypt.yaml
--- a/infra/kubernetes/platform/cert-manager/namespace.yaml
+++ b/infra/kubernetes/platform/cert-manager/namespace.yaml
@@ -0,0 +1,4 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: cert-manager
--- a/infra/kubernetes/platform/cloudnativepg/cluster.yaml
+++ b/infra/kubernetes/platform/cloudnativepg/cluster.yaml
@@ -0,0 +1,45 @@
+# Prerequisites: CloudNativePG operator must be installed first.
+# Install: helm install cnpg cloudnative-pg/cloudnative-pg --namespace cnpg-system --create-namespace
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: homelab-pg
+  namespace: platform
+spec:
+  instances: 2
+  primaryUpdateStrategy: unsupervised
+
+  storage:
+    storageClass: longhorn
+    size: 10Gi
+
+  postgresql:
+    parameters:
+      max_connections: "100"
+      shared_buffers: 256MB
+      effective_cache_size: 512MB
+      work_mem: 4MB
+
+  bootstrap:
+    initdb:
+      database: homelab
+      owner: homelab
+      secret:
+        name: homelab-pg-credentials
+
+  backup:
+    barmanObjectStore:
+      destinationPath: s3://homelab-pg-backups/
+      endpointURL: http://minio.platform.svc:9000
+      s3Credentials:
+        accessKeyId:
+          name: pg-backup-s3-credentials
+          key: ACCESS_KEY_ID
+        secretAccessKey:
+          name: pg-backup-s3-credentials
+          key: SECRET_ACCESS_KEY
+    retentionPolicy: "30d"
+
+  monitoring:
+    enablePodMonitor: true
--- a/infra/kubernetes/platform/cloudnativepg/kustomization.yaml
+++ b/infra/kubernetes/platform/cloudnativepg/kustomization.yaml
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - cluster.yaml
--- a/infra/kubernetes/platform/longhorn/kustomization.yaml
+++ b/infra/kubernetes/platform/longhorn/kustomization.yaml
@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
+  - storageclass.yaml
--- a/infra/kubernetes/platform/longhorn/namespace.yaml
+++ b/infra/kubernetes/platform/longhorn/namespace.yaml
@@ -0,0 +1,6 @@
+# Prerequisites: Longhorn must be installed via Helm first.
+# Install: helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace --version 1.7.2
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: longhorn-system
--- a/infra/kubernetes/platform/longhorn/storageclass.yaml
+++ b/infra/kubernetes/platform/longhorn/storageclass.yaml
@@ -0,0 +1,14 @@
+apiVersion: storage.k8s.io/v1
+kind: StorageClass
+metadata:
+  name: longhorn
+  annotations:
+    storageclass.kubernetes.io/is-default-class: "true"
+provisioner: driver.longhorn.io
+allowVolumeExpansion: true
+reclaimPolicy: Delete
+volumeBindingMode: Immediate
+parameters:
+  numberOfReplicas: "2"
+  staleReplicaTimeout: "2880"
+  dataLocality: best-effort
--- a/infra/kubernetes/platform/sealed-secrets/kustomization.yaml
+++ b/infra/kubernetes/platform/sealed-secrets/kustomization.yaml
@@ -0,0 +1,4 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - namespace.yaml
--- a/infra/kubernetes/platform/sealed-secrets/namespace.yaml
+++ b/infra/kubernetes/platform/sealed-secrets/namespace.yaml
@@ -0,0 +1,9 @@
+# Prerequisites: Sealed Secrets must be installed via Helm first.
+# Install: helm install sealed-secrets sealed-secrets/sealed-secrets --namespace kube-system --version 2.16.2
+# The controller runs in kube-system; this is just the config namespace.
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: sealed-secrets
+  labels:
+    managed-by: argocd
--- a/infra/kubernetes/platform/traefik/helmchartconfig.yaml
+++ b/infra/kubernetes/platform/traefik/helmchartconfig.yaml
@@ -0,0 +1,26 @@
+# HelmChartConfig customizes the k3s-bundled Traefik deployment
+apiVersion: helm.cattle.io/v1
+kind: HelmChartConfig
+metadata:
+  name: traefik
+  namespace: kube-system
+spec:
+  valuesContent: |-
+    ports:
+      web:
+        redirectTo:
+          port: websecure
+      websecure:
+        tls:
+          enabled: true
+    providers:
+      kubernetesCRD:
+        allowCrossNamespace: true
+    logs:
+      access:
+        enabled: true
+    metrics:
+      prometheus:
+        entryPoint: metrics
+    additionalArguments:
+      - "--entrypoints.websecure.http.tls.certresolver=letsencrypt"
--- a/infra/kubernetes/platform/traefik/kustomization.yaml
+++ b/infra/kubernetes/platform/traefik/kustomization.yaml
@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - helmchartconfig.yaml
+  - middleware-default-headers.yaml
--- a/infra/kubernetes/platform/traefik/middleware-default-headers.yaml
+++ b/infra/kubernetes/platform/traefik/middleware-default-headers.yaml
@@ -0,0 +1,16 @@
+apiVersion: traefik.io/v1alpha1
+kind: Middleware
+metadata:
+  name: default-headers
+  namespace: platform
+spec:
+  headers:
+    browserXssFilter: true
+    contentTypeNosniff: true
+    frameDeny: true
+    stsIncludeSubdomains: true
+    stsPreload: true
+    stsSeconds: 31536000
+    customFrameOptionsValue: SAMEORIGIN
+    customRequestHeaders:
+      X-Forwarded-Proto: https
--- a/infra/kubernetes/platform/valkey/deployment.yaml
+++ b/infra/kubernetes/platform/valkey/deployment.yaml
@@ -0,0 +1,71 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: valkey
+  namespace: platform
+  labels:
+    app: valkey
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: valkey
+  template:
+    metadata:
+      labels:
+        app: valkey
+    spec:
+      containers:
+        - name: valkey
+          image: valkey/valkey:8.0-alpine
+          ports:
+            - containerPort: 6379
+          args:
+            - "--requirepass"
+            - "$(VALKEY_PASSWORD)"
+            - "--maxmemory"
+            - "256mb"
+            - "--maxmemory-policy"
+            - "allkeys-lru"
+          env:
+            - name: VALKEY_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: valkey-credentials
+                  key: password
+          resources:
+            requests:
+              memory: 128Mi
+              cpu: 100m
+            limits:
+              memory: 512Mi
+          readinessProbe:
+            tcpSocket:
+              port: 6379
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            tcpSocket:
+              port: 6379
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          volumeMounts:
+            - name: data
+              mountPath: /data
+      volumes:
+        - name: data
+          persistentVolumeClaim:
+            claimName: valkey-data
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: valkey-data
+  namespace: platform
+spec:
+  accessModes:
+    - ReadWriteOnce
+  storageClassName: longhorn
+  resources:
+    requests:
+      storage: 2Gi
--- a/infra/kubernetes/platform/valkey/kustomization.yaml
+++ b/infra/kubernetes/platform/valkey/kustomization.yaml
@@ -0,0 +1,5 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+  - deployment.yaml
+  - service.yaml
--- a/infra/kubernetes/platform/valkey/service.yaml
+++ b/infra/kubernetes/platform/valkey/service.yaml
@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: valkey
+  namespace: platform
+  labels:
+    app: valkey
+spec:
+  type: ClusterIP
+  ports:
+    - port: 6379
+      targetPort: 6379
+      protocol: TCP
+  selector:
+    app: valkey
--- a/infra/ubiquiti/README.md
+++ b/infra/ubiquiti/README.md
@@ -0,0 +1,73 @@
+# Ubiquiti Cloud Gateway Configuration
+
+Documentation for the Ubiquiti Cloud Gateway (UCG) that manages network ingress for the homelab cluster.
+
+## Network Layout
+
+```
+Internet
+  │
+  ▼
+UCG (Ubiquiti Cloud Gateway)
+  │
+  ├── VLAN 1  - Management (10.0.1.0/24)
+  ├── VLAN 10 - Servers    (10.0.10.0/24)
+  ├── VLAN 20 - IoT        (10.0.20.0/24)
+  └── VLAN 99 - Guest      (10.0.99.0/24)
+```
+
+## VLAN Configuration
+
+| VLAN ID | Name       | Subnet          | Purpose                |
+|---------|------------|-----------------|------------------------|
+| 1       | Management | 10.0.1.0/24     | Network devices, admin |
+| 10      | Servers    | 10.0.10.0/24    | k3s cluster nodes      |
+| 20      | IoT        | 10.0.20.0/24    | IoT devices            |
+| 99      | Guest      | 10.0.99.0/24    | Guest WiFi             |
+
+## DHCP Reservations (VLAN 10 — Servers)
+
+| Hostname | IP Address  | MAC Address       | Role        |
+|----------|-------------|-------------------|-------------|
+| nuc01    | 10.0.10.11  | XX:XX:XX:XX:XX:01 | k3s server  |
+| nuc02    | 10.0.10.12  | XX:XX:XX:XX:XX:02 | k3s agent   |
+| nuc03    | 10.0.10.13  | XX:XX:XX:XX:XX:03 | k3s agent   |
+
+## Port Forwarding Rules
+
+| Name       | External Port | Internal IP  | Internal Port | Protocol |
+|------------|---------------|--------------|---------------|----------|
+| HTTP       | 80            | 10.0.10.11   | 80            | TCP      |
+| HTTPS      | 443           | 10.0.10.11   | 443           | TCP      |
+| k3s API    | 6443          | 10.0.10.11   | 6443          | TCP      |
+
+> **Note**: HTTP/HTTPS traffic routes to nuc01 where Traefik runs as the ingress controller.
+> k3s API port is only forwarded if external kubectl access is needed.
+
+## Firewall Rules
+
+### Inter-VLAN Rules
+- **Servers → Internet**: Allow all outbound
+- **Servers → Management**: Allow (for UCG API access)
+- **IoT → Servers**: Deny (isolate IoT from cluster)
+- **Guest → ***: Allow Internet only, block all local
+
+### Inbound Rules
+- Allow established/related connections
+- Allow HTTP (80) and HTTPS (443) to VLAN 10
+- Drop all other inbound
+
+## DNS Configuration
+
+- **Internal DNS**: Use UCG as DNS server for VLAN 10
+- **External DNS**: Cloudflare (1.1.1.1, 1.0.0.1)
+- **Local DNS entries**: Add `*.homelab.local` → 10.0.10.11 for internal access
+
+## Setup Steps
+
+1. **Create VLANs** in UniFi Network → Settings → Networks
+2. **Assign ports** on the switch to VLAN 10 for NUC connections
+3. **Create DHCP reservations** for each NUC (Settings → Networks → VLAN 10)
+4. **Add port forwarding rules** (Settings → Firewall & Security → Port Forwarding)
+5. **Configure firewall rules** (Settings → Firewall & Security → Firewall Rules)
+6. **Set local DNS** entries for *.homelab.local
--- a/infra/ubiquiti/network-diagram.md
+++ b/infra/ubiquiti/network-diagram.md
@@ -0,0 +1,37 @@
+# Network Diagram
+
+```
+                          ┌──────────────┐
+                          │   Internet   │
+                          └──────┬───────┘
+                                 │
+                          ┌──────┴───────┐
+                          │     UCG      │
+                          │  10.0.1.1    │
+                          └──────┬───────┘
+                                 │
+                    ┌────────────┼────────────┐
+                    │            │            │
+             ┌──────┴───┐ ┌─────┴────┐ ┌────┴──────┐
+             │ VLAN 10  │ │ VLAN 20  │ │ VLAN 99   │
+             │ Servers  │ │   IoT    │ │  Guest    │
+             └──────┬───┘ └──────────┘ └───────────┘
+                    │
+       ┌────────────┼────────────┐
+       │            │            │
+  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐
+  │  nuc01  │ │  nuc02  │ │  nuc03  │
+  │ .10.11  │ │ .10.12  │ │ .10.13  │
+  │ server  │ │  agent  │ │  agent  │
+  └─────────┘ └─────────┘ └─────────┘
+
+  Services on k3s cluster:
+  ┌─────────────────────────────────────┐
+  │  Traefik (Ingress) ← :80/:443      │
+  │  ArgoCD            ← :8080         │
+  │  Grafana           ← :3001         │
+  │  PostgreSQL (CNPG) ← :5432         │
+  │  Valkey            ← :6379         │
+  │  Longhorn UI       ← :8000         │
+  └─────────────────────────────────────┘
+```