From 322b8e3c0e47fdf50acbdebd301feaf5bc38f4a0 Mon Sep 17 00:00:00 2001 From: Azuna <36605286+azunaVT@users.noreply.github.com> Date: Tue, 10 Mar 2026 09:09:29 -0400 Subject: [PATCH] Restructure repo to documentation-first homelab platform --- .github/ISSUE_TEMPLATE/decision.yml | 33 ++++++++ .github/ISSUE_TEMPLATE/epic.yml | 34 ++++++++ .github/ISSUE_TEMPLATE/task.yml | 36 +++++++++ .github/pull_request_template.md | 26 ++++++ README.md | 79 +++++++++++++++++++ ai/README.md | 5 ++ argocd/README.md | 5 ++ automation/README.md | 5 ++ docs/README.md | 9 +++ docs/architecture/media-platform.md | 26 ++++++ docs/architecture/network-topology.md | 21 +++++ docs/architecture/proxmox-k8s-strategy.md | 23 ++++++ docs/architecture/security-model.md | 21 +++++ docs/architecture/target-architecture.md | 21 +++++ docs/archive/README.md | 5 ++ .../legacy-baremetal-talos-pxe/README.md | 17 ++++ .../infra}/README.md | 0 .../infra}/live/dev/.gitkeep | 0 .../infra}/live/prod/.terraform.lock.hcl | 0 .../infra}/live/prod/main.tf | 0 .../infra}/live/prod/providers.tf | 0 .../infra/live/prod/terraform.auto.tfvars | 27 +++++++ .../infra}/live/prod/variables.tf | 0 .../infra}/modules/baremetal/main.tf | 0 .../infra}/modules/baremetal/outputs.tf | 0 .../infra}/modules/baremetal/providers.tf | 0 .../infra}/modules/baremetal/variables.tf | 0 .../infra}/modules/cluster/main.tf | 0 .../infra}/modules/cluster/outputs.tf | 0 .../infra}/modules/cluster/providers.tf | 0 .../infra}/modules/cluster/variables.tf | 0 .../infra}/modules/config/main.tf | 0 .../infra}/modules/config/outputs.tf | 0 .../infra}/modules/config/providers.tf | 0 .../infra}/modules/config/variables.tf | 0 .../infra}/modules/flux/main.tf | 0 .../infra}/modules/flux/providers.tf | 0 .../modules/flux/values/components.yaml | 0 .../infra}/modules/flux/variables.tf | 0 .../infra}/modules/github_deploy_key/main.tf | 0 .../modules/github_deploy_key/outputs.tf | 0 .../modules/github_deploy_key/providers.tf | 0 .../modules/github_deploy_key/variables.tf | 0 .../infra}/modules/node/main.tf | 0 .../infra}/modules/node/providers.tf | 0 .../node/templates/cilium-install.yaml.tftpl | 0 .../node/templates/controlplane.yaml.tftpl | 0 .../modules/node/templates/worker.yaml.tftpl | 0 .../infra}/modules/node/variables.tf | 0 docs/decisions/ADR-001-proxmox-first.md | 21 +++++ docs/decisions/ADR-002-k8s-inside-proxmox.md | 21 +++++ docs/decisions/ADR-003-argocd-over-flux.md | 21 +++++ docs/decisions/ADR-004-truenas-separate.md | 21 +++++ ...a-platform-stays-separate-from-core-lab.md | 21 +++++ docs/inventory/current-media-stack.md | 48 +++++++++++ docs/inventory/hardware-inventory.md | 17 ++++ docs/inventory/network-inventory.md | 20 +++++ docs/inventory/service-inventory.md | 18 +++++ docs/roadmap/backlog.md | 30 +++++++ docs/roadmap/current-phase.md | 18 +++++ docs/roadmap/media-migration.md | 28 +++++++ docs/roadmap/milestones.md | 46 +++++++++++ docs/runbooks/bootstrap-sequence.md | 32 ++++++++ docs/vision/homelab-vision.md | 25 ++++++ infra/live/prod/terraform.auto.tfvars | 41 ---------- kubernetes/README.md | 5 ++ proxmox/README.md | 5 ++ scripts/README.md | 8 ++ 68 files changed, 798 insertions(+), 41 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/decision.yml create mode 100644 .github/ISSUE_TEMPLATE/epic.yml create mode 100644 .github/ISSUE_TEMPLATE/task.yml create mode 100644 .github/pull_request_template.md create mode 100644 README.md create mode 100644 ai/README.md create mode 100644 argocd/README.md create mode 100644 automation/README.md create mode 100644 docs/README.md create mode 100644 docs/architecture/media-platform.md create mode 100644 docs/architecture/network-topology.md create mode 100644 docs/architecture/proxmox-k8s-strategy.md create mode 100644 docs/architecture/security-model.md create mode 100644 docs/architecture/target-architecture.md create mode 100644 docs/archive/README.md create mode 100644 docs/archive/legacy-baremetal-talos-pxe/README.md rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/README.md (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/live/dev/.gitkeep (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/live/prod/.terraform.lock.hcl (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/live/prod/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/live/prod/providers.tf (100%) create mode 100644 docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/terraform.auto.tfvars rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/live/prod/variables.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/baremetal/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/baremetal/outputs.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/baremetal/providers.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/baremetal/variables.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/cluster/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/cluster/outputs.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/cluster/providers.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/cluster/variables.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/config/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/config/outputs.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/config/providers.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/config/variables.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/flux/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/flux/providers.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/flux/values/components.yaml (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/flux/variables.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/github_deploy_key/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/github_deploy_key/outputs.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/github_deploy_key/providers.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/github_deploy_key/variables.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/node/main.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/node/providers.tf (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/node/templates/cilium-install.yaml.tftpl (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/node/templates/controlplane.yaml.tftpl (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/node/templates/worker.yaml.tftpl (100%) rename {infra => docs/archive/legacy-baremetal-talos-pxe/infra}/modules/node/variables.tf (100%) create mode 100644 docs/decisions/ADR-001-proxmox-first.md create mode 100644 docs/decisions/ADR-002-k8s-inside-proxmox.md create mode 100644 docs/decisions/ADR-003-argocd-over-flux.md create mode 100644 docs/decisions/ADR-004-truenas-separate.md create mode 100644 docs/decisions/ADR-005-media-platform-stays-separate-from-core-lab.md create mode 100644 docs/inventory/current-media-stack.md create mode 100644 docs/inventory/hardware-inventory.md create mode 100644 docs/inventory/network-inventory.md create mode 100644 docs/inventory/service-inventory.md create mode 100644 docs/roadmap/backlog.md create mode 100644 docs/roadmap/current-phase.md create mode 100644 docs/roadmap/media-migration.md create mode 100644 docs/roadmap/milestones.md create mode 100644 docs/runbooks/bootstrap-sequence.md create mode 100644 docs/vision/homelab-vision.md delete mode 100644 infra/live/prod/terraform.auto.tfvars create mode 100644 kubernetes/README.md create mode 100644 proxmox/README.md create mode 100644 scripts/README.md diff --git a/.github/ISSUE_TEMPLATE/decision.yml b/.github/ISSUE_TEMPLATE/decision.yml new file mode 100644 index 0000000..de883b1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/decision.yml @@ -0,0 +1,33 @@ +name: Decision +description: Propose a significant architecture or process decision. +title: "decision: " +labels: + - decision +body: + - type: textarea + id: context + attributes: + label: Context + description: What context drives this decision? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed decision + description: What do you propose and why? + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + - type: textarea + id: consequences + attributes: + label: Consequences + - type: input + id: adr_link + attributes: + label: ADR link (if created) + placeholder: docs/decisions/ADR-xxx-...md diff --git a/.github/ISSUE_TEMPLATE/epic.yml b/.github/ISSUE_TEMPLATE/epic.yml new file mode 100644 index 0000000..8c8efb9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/epic.yml @@ -0,0 +1,34 @@ +name: Epic +description: Track a multi-task initiative. +title: "epic: " +labels: + - epic +body: + - type: textarea + id: objective + attributes: + label: Objective + description: What outcome does this epic deliver? + validations: + required: true + - type: textarea + id: problem + attributes: + label: Problem statement + description: Why this work matters now. + - type: textarea + id: milestones + attributes: + label: Milestones + placeholder: | + - Mx: ... + - type: textarea + id: child_tasks + attributes: + label: Child tasks + placeholder: | + - [ ] #123 ... + - type: textarea + id: risks + attributes: + label: Risks and unknowns diff --git a/.github/ISSUE_TEMPLATE/task.yml b/.github/ISSUE_TEMPLATE/task.yml new file mode 100644 index 0000000..02423d2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.yml @@ -0,0 +1,36 @@ +name: Task +description: Track a focused implementation or documentation task. +title: "task: " +labels: + - task +body: + - type: textarea + id: summary + attributes: + label: Summary + description: What needs to be done? + validations: + required: true + - type: textarea + id: scope + attributes: + label: Scope + description: In-scope and out-of-scope boundaries. + - type: textarea + id: acceptance + attributes: + label: Acceptance criteria + description: Define done. + placeholder: | + - [ ] ... + - [ ] ... + validations: + required: true + - type: textarea + id: dependencies + attributes: + label: Dependencies / blockers + - type: textarea + id: notes + attributes: + label: Notes diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..b9d530e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,26 @@ +## Summary + +- What changed? +- Why was it needed? + +## What to review first + +- Primary entry points for reviewers: + - + +## Restructuring and archive notes + +- What was restructured: +- What legacy content was archived: +- Any redactions performed for safety: + +## TODOs intentionally left open + +- TODO: +- TODO: + +## Validation + +- [ ] Documentation paths and links checked +- [ ] No secrets/credentials added +- [ ] ADR/backlog/roadmap updates included if needed diff --git a/README.md b/README.md new file mode 100644 index 0000000..84d38b7 --- /dev/null +++ b/README.md @@ -0,0 +1,79 @@ +# Homelab Infrastructure (Documentation-First) + +This repository is the planning and execution hub for a homelab/platform build centered on: + +- **Proxmox-first virtualization** +- **Virtualized Kubernetes inside Proxmox** +- **Argo CD for GitOps** +- **TrueNAS as a separate storage anchor** +- A path toward **self-hosted AI/agent platform capabilities** + +The previous bare-metal Talos/PXE implementation is preserved in `docs/archive/legacy-baremetal-talos-pxe/` for historical reference and is **not** the current primary direction. + +## Current architecture direction + +- Main compute: 3x Minisforum MS-A2 (96 GB RAM each, 10GbE) +- Core platform direction: Proxmox cluster first, then Kubernetes as VMs +- GitOps direction: Argo CD preferred over Flux +- Storage: separate TrueNAS system +- Network foundation: Ubiquiti stack (Cloud Gateway Fiber, Pro XG 8 PoE, Lite 16 PoE) + +Where details are not finalized, this repository uses explicit `TODO` markers rather than assumptions. + +## Repository structure + +```text +docs/ + vision/ # North-star goals and intent + inventory/ # Hardware, network, and service inventory + architecture/ # Target architecture and security/network models + decisions/ # ADRs (architecture decision records) + runbooks/ # Operational procedures + roadmap/ # Milestones, backlog, current phase + archive/ # Legacy direction and historical references +proxmox/ # Proxmox planning/implementation docs and artifacts +kubernetes/ # Kubernetes cluster design and implementation docs +argocd/ # Argo CD bootstrap and app-of-apps patterns +automation/ # Automation plans/scripts conventions +ai/ # Future AI platform direction and experiments +scripts/ # Safe utility scripts (no secrets) +.github/ # GitHub issue/PR templates and project workflow docs +``` + +## Current phase + +See: `docs/roadmap/current-phase.md`. + +At time of this restructuring, the project is in **Foundation / Repository Realignment**. + +## How decisions are recorded + +Architectural decisions are documented as ADRs in `docs/decisions/`. + +Each ADR follows: +- Title +- Status +- Context +- Decision +- Alternatives considered +- Consequences + +## How work is tracked + +- Use GitHub Issues with templates in `.github/ISSUE_TEMPLATE/` +- Track larger streams via epics and milestones +- Use pull requests with `.github/pull_request_template.md` + +## How to navigate docs + +1. Start with `docs/vision/homelab-vision.md` +2. Review current state in `docs/inventory/` +3. Read target direction in `docs/architecture/` +4. Check ADRs in `docs/decisions/` +5. Use `docs/runbooks/bootstrap-sequence.md` for sequencing +6. Follow execution in `docs/roadmap/` + +## Notes on sensitive data + +Do not commit live secrets, tokens, credentials, private domains, or operationally sensitive values. +Use redacted examples with `TODO` placeholders where needed. diff --git a/ai/README.md b/ai/README.md new file mode 100644 index 0000000..71a0466 --- /dev/null +++ b/ai/README.md @@ -0,0 +1,5 @@ +# AI Platform + +Future-facing workstream for self-hosted AI and agent platform capabilities. + +TODO: Define requirements, constraints, and initial pilot architecture. diff --git a/argocd/README.md b/argocd/README.md new file mode 100644 index 0000000..b16ad49 --- /dev/null +++ b/argocd/README.md @@ -0,0 +1,5 @@ +# Argo CD + +GitOps bootstrap and application management patterns for Kubernetes environments. + +TODO: Add bootstrap sequence, repo layout conventions, and access model. diff --git a/automation/README.md b/automation/README.md new file mode 100644 index 0000000..7d947eb --- /dev/null +++ b/automation/README.md @@ -0,0 +1,5 @@ +# Automation + +Automation conventions and implementation plans. + +Keep scripts deterministic, documented, and free of secrets. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7752324 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,9 @@ +# Documentation Index + +- `vision/`: project direction and principles +- `inventory/`: current known hardware/network/service/media state +- `architecture/`: target design drafts and constraints +- `decisions/`: ADRs +- `runbooks/`: operational sequencing +- `roadmap/`: milestones, backlog, current phase +- `archive/`: legacy/superseded materials diff --git a/docs/architecture/media-platform.md b/docs/architecture/media-platform.md new file mode 100644 index 0000000..e988eca --- /dev/null +++ b/docs/architecture/media-platform.md @@ -0,0 +1,26 @@ +# Media Platform Architecture + +## Current state + +- Docker Compose media stack runs in a Proxmox VM. +- Storage is NFS-backed from TrueNAS. +- Plex currently uses NVIDIA-backed transcoding. + +## Future state (under evaluation) + +The final media platform design remains open. +Current evaluation tracks: + +1. Plex vs Jellyfin vs Emby +2. Media workloads on TrueNAS vs dedicated media VM +3. Operational and backup model for media services + +## Design guardrail + +Keep media platform evolution separate from core lab control-plane reliability work. + +## TODOs + +- TODO: Define migration criteria (downtime tolerance, performance, maintainability). +- TODO: Define decision timeline and ADR trigger points. +- TODO: Define target observability for media workloads. diff --git a/docs/architecture/network-topology.md b/docs/architecture/network-topology.md new file mode 100644 index 0000000..4a2b149 --- /dev/null +++ b/docs/architecture/network-topology.md @@ -0,0 +1,21 @@ +# Network Topology (Draft) + +## Known topology anchors + +- Ubiquiti Cloud Gateway Fiber (gateway/routing role) +- Ubiquiti Pro XG 8 PoE and Lite 16 PoE (switching fabric) +- 10GbE-capable Proxmox compute nodes +- Separate TrueNAS system + +## Target segmentation intent + +- Separate management/control traffic from workload traffic. +- Ensure storage access paths are explicit and observable. +- Keep externally exposed services constrained and auditable. + +## TODOs + +- TODO: Define VLAN layout and naming. +- TODO: Define subnet and addressing model. +- TODO: Define north-south ingress model for Kubernetes services. +- TODO: Define east-west policy posture between major service zones. diff --git a/docs/architecture/proxmox-k8s-strategy.md b/docs/architecture/proxmox-k8s-strategy.md new file mode 100644 index 0000000..e7ce933 --- /dev/null +++ b/docs/architecture/proxmox-k8s-strategy.md @@ -0,0 +1,23 @@ +# Proxmox + Kubernetes Strategy + +## Strategy statement + +Build and stabilize Proxmox first, then deploy an initial Kubernetes cluster as VMs to accelerate platform learning while retaining infrastructure flexibility. + +## Why this approach + +- Faster iteration than immediate bare-metal Kubernetes rebuild. +- Better isolation between host virtualization and guest orchestration concerns. +- Easier phased migration of workloads and operational practices. + +## Implementation themes + +- Standardized VM templates for Kubernetes nodes. +- Repeatable cluster bootstrap process (document first, automate next). +- Clear separation of management, workload, and storage networking (details TODO). + +## TODOs + +- TODO: Define Kubernetes distro selection criteria. +- TODO: Define control-plane and worker VM sizing profile. +- TODO: Define day-2 operations model (upgrade cadence, patch windows). diff --git a/docs/architecture/security-model.md b/docs/architecture/security-model.md new file mode 100644 index 0000000..49d58c0 --- /dev/null +++ b/docs/architecture/security-model.md @@ -0,0 +1,21 @@ +# Security Model (Baseline) + +## Principles + +- Least privilege for identities, credentials, and network access. +- Secret hygiene: no live secrets in repo. +- Explicit trust boundaries between host, cluster, storage, and edge access. + +## Baseline controls + +- Git-based change review via pull requests. +- ADR-backed architectural changes. +- Segmented networks (details pending). +- Prefer short-lived credentials and secure secret delivery patterns. + +## TODOs + +- TODO: Define secret management strategy for Proxmox/Kubernetes/Argo CD. +- TODO: Define identity provider and RBAC model. +- TODO: Define backup encryption and key handling practices. +- TODO: Define minimum logging/auditing standards. diff --git a/docs/architecture/target-architecture.md b/docs/architecture/target-architecture.md new file mode 100644 index 0000000..f262b9d --- /dev/null +++ b/docs/architecture/target-architecture.md @@ -0,0 +1,21 @@ +# Target Architecture (Working Draft) + +## High-level model + +1. Proxmox cluster provides virtualization and lifecycle management. +2. Kubernetes runs inside Proxmox-hosted VMs. +3. Argo CD manages Kubernetes desired state from Git. +4. TrueNAS remains a separate storage/media anchor. +5. Media platform remains logically separate from core platform control services. + +## Design constraints + +- Prefer incremental migration over all-at-once rebuilds. +- Keep storage and media concerns decoupled from cluster control plane. +- Use documentation and ADRs to reduce architectural drift. + +## TODOs + +- TODO: Define availability goals for each platform layer. +- TODO: Define backup and disaster recovery boundaries. +- TODO: Define observability baseline (metrics/logs/traces/events). diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..1edef27 --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,5 @@ +# Archive + +This directory stores historical or superseded materials kept for reference. + +Archived content is not the active implementation path unless explicitly re-adopted via ADR. diff --git a/docs/archive/legacy-baremetal-talos-pxe/README.md b/docs/archive/legacy-baremetal-talos-pxe/README.md new file mode 100644 index 0000000..08e7471 --- /dev/null +++ b/docs/archive/legacy-baremetal-talos-pxe/README.md @@ -0,0 +1,17 @@ +# Legacy: Bare-Metal Talos/PXE Direction + +This directory captures a **previous platform direction** focused on bare-metal Talos cluster deployment via PXE/Terraform-style workflows. + +## Archive intent + +- Preserved for historical/reference purposes. +- Useful for extracting reusable ideas, patterns, or scripts. +- **Not** the current primary architecture direction for this repository. + +## Current primary direction + +See top-level `README.md` and `docs/architecture/` for the active Proxmox-first, virtualized-Kubernetes approach. + +## Safety note + +Some legacy files may have been redacted during archival to avoid retaining environment-specific sensitive values. diff --git a/infra/README.md b/docs/archive/legacy-baremetal-talos-pxe/infra/README.md similarity index 100% rename from infra/README.md rename to docs/archive/legacy-baremetal-talos-pxe/infra/README.md diff --git a/infra/live/dev/.gitkeep b/docs/archive/legacy-baremetal-talos-pxe/infra/live/dev/.gitkeep similarity index 100% rename from infra/live/dev/.gitkeep rename to docs/archive/legacy-baremetal-talos-pxe/infra/live/dev/.gitkeep diff --git a/infra/live/prod/.terraform.lock.hcl b/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/.terraform.lock.hcl similarity index 100% rename from infra/live/prod/.terraform.lock.hcl rename to docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/.terraform.lock.hcl diff --git a/infra/live/prod/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/main.tf similarity index 100% rename from infra/live/prod/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/main.tf diff --git a/infra/live/prod/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/providers.tf similarity index 100% rename from infra/live/prod/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/providers.tf diff --git a/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/terraform.auto.tfvars b/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/terraform.auto.tfvars new file mode 100644 index 0000000..74a6a4a --- /dev/null +++ b/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/terraform.auto.tfvars @@ -0,0 +1,27 @@ +# Redacted archival sample. +# Original hostnames, IPs, MAC addresses, and organization-specific values were removed +# during the documentation-first repository pivot. + +cluster_nodes = { + node0 = { + hostname = "TODO.example.internal" + ip = "TODO" + mac_address = "TODO" + wake_on_lan_mac = "TODO" + install_disk = "/dev/TODO" + role = "controlplane" + bootstrap = true + } +} + +cluster_info = { + name = "TODO-cluster-name" + nameservers = ["TODO"] + virtual_ip = "TODO" + endpoint = "https://TODO:6443" +} + +k8s_version = "TODO" + +github_organization = "TODO" +github_repository = "TODO" diff --git a/infra/live/prod/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/variables.tf similarity index 100% rename from infra/live/prod/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/live/prod/variables.tf diff --git a/infra/modules/baremetal/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/main.tf similarity index 100% rename from infra/modules/baremetal/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/main.tf diff --git a/infra/modules/baremetal/outputs.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/outputs.tf similarity index 100% rename from infra/modules/baremetal/outputs.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/outputs.tf diff --git a/infra/modules/baremetal/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/providers.tf similarity index 100% rename from infra/modules/baremetal/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/providers.tf diff --git a/infra/modules/baremetal/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/variables.tf similarity index 100% rename from infra/modules/baremetal/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/baremetal/variables.tf diff --git a/infra/modules/cluster/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/main.tf similarity index 100% rename from infra/modules/cluster/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/main.tf diff --git a/infra/modules/cluster/outputs.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/outputs.tf similarity index 100% rename from infra/modules/cluster/outputs.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/outputs.tf diff --git a/infra/modules/cluster/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/providers.tf similarity index 100% rename from infra/modules/cluster/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/providers.tf diff --git a/infra/modules/cluster/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/variables.tf similarity index 100% rename from infra/modules/cluster/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/cluster/variables.tf diff --git a/infra/modules/config/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/main.tf similarity index 100% rename from infra/modules/config/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/main.tf diff --git a/infra/modules/config/outputs.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/outputs.tf similarity index 100% rename from infra/modules/config/outputs.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/outputs.tf diff --git a/infra/modules/config/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/providers.tf similarity index 100% rename from infra/modules/config/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/providers.tf diff --git a/infra/modules/config/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/variables.tf similarity index 100% rename from infra/modules/config/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/config/variables.tf diff --git a/infra/modules/flux/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/main.tf similarity index 100% rename from infra/modules/flux/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/main.tf diff --git a/infra/modules/flux/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/providers.tf similarity index 100% rename from infra/modules/flux/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/providers.tf diff --git a/infra/modules/flux/values/components.yaml b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/values/components.yaml similarity index 100% rename from infra/modules/flux/values/components.yaml rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/values/components.yaml diff --git a/infra/modules/flux/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/variables.tf similarity index 100% rename from infra/modules/flux/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/flux/variables.tf diff --git a/infra/modules/github_deploy_key/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/main.tf similarity index 100% rename from infra/modules/github_deploy_key/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/main.tf diff --git a/infra/modules/github_deploy_key/outputs.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/outputs.tf similarity index 100% rename from infra/modules/github_deploy_key/outputs.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/outputs.tf diff --git a/infra/modules/github_deploy_key/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/providers.tf similarity index 100% rename from infra/modules/github_deploy_key/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/providers.tf diff --git a/infra/modules/github_deploy_key/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/variables.tf similarity index 100% rename from infra/modules/github_deploy_key/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/github_deploy_key/variables.tf diff --git a/infra/modules/node/main.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/main.tf similarity index 100% rename from infra/modules/node/main.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/main.tf diff --git a/infra/modules/node/providers.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/providers.tf similarity index 100% rename from infra/modules/node/providers.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/providers.tf diff --git a/infra/modules/node/templates/cilium-install.yaml.tftpl b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/cilium-install.yaml.tftpl similarity index 100% rename from infra/modules/node/templates/cilium-install.yaml.tftpl rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/cilium-install.yaml.tftpl diff --git a/infra/modules/node/templates/controlplane.yaml.tftpl b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/controlplane.yaml.tftpl similarity index 100% rename from infra/modules/node/templates/controlplane.yaml.tftpl rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/controlplane.yaml.tftpl diff --git a/infra/modules/node/templates/worker.yaml.tftpl b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/worker.yaml.tftpl similarity index 100% rename from infra/modules/node/templates/worker.yaml.tftpl rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/templates/worker.yaml.tftpl diff --git a/infra/modules/node/variables.tf b/docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/variables.tf similarity index 100% rename from infra/modules/node/variables.tf rename to docs/archive/legacy-baremetal-talos-pxe/infra/modules/node/variables.tf diff --git a/docs/decisions/ADR-001-proxmox-first.md b/docs/decisions/ADR-001-proxmox-first.md new file mode 100644 index 0000000..eda82a6 --- /dev/null +++ b/docs/decisions/ADR-001-proxmox-first.md @@ -0,0 +1,21 @@ +# ADR-001: Proxmox-First Platform Direction + +## Status +Accepted + +## Context +The repository previously focused on bare-metal Talos/PXE workflows. The current platform direction prioritizes virtualization-first operations and documentation-driven execution. + +## Decision +Adopt Proxmox as the primary infrastructure substrate for the next phase of homelab/platform development. + +## Alternatives considered + +- Continue bare-metal Talos/PXE as primary path +- Hybrid immediate split across bare metal and Proxmox + +## Consequences + +- Improves near-term flexibility for workload placement. +- Requires clear host/guest operational boundary documentation. +- Legacy bare-metal content is retained as archived reference. diff --git a/docs/decisions/ADR-002-k8s-inside-proxmox.md b/docs/decisions/ADR-002-k8s-inside-proxmox.md new file mode 100644 index 0000000..9e27c75 --- /dev/null +++ b/docs/decisions/ADR-002-k8s-inside-proxmox.md @@ -0,0 +1,21 @@ +# ADR-002: Kubernetes Initially Runs Inside Proxmox + +## Status +Accepted + +## Context +The immediate goal is to stand up a manageable Kubernetes environment while minimizing infrastructure risk during platform transition. + +## Decision +Run the first Kubernetes cluster as virtual machines inside Proxmox. + +## Alternatives considered + +- Immediate return to bare-metal Kubernetes +- Postpone Kubernetes until full physical architecture redesign is complete + +## Consequences + +- Enables phased adoption of Kubernetes and GitOps practices. +- Adds VM-layer considerations for performance and operations. +- Keeps migration path open for future architecture changes. diff --git a/docs/decisions/ADR-003-argocd-over-flux.md b/docs/decisions/ADR-003-argocd-over-flux.md new file mode 100644 index 0000000..3abdb6c --- /dev/null +++ b/docs/decisions/ADR-003-argocd-over-flux.md @@ -0,0 +1,21 @@ +# ADR-003: Argo CD Preferred Over Flux for GitOps + +## Status +Accepted + +## Context +A GitOps control plane is required for Kubernetes workload lifecycle management. The team currently prefers Argo CD for usability and workflow alignment. + +## Decision +Use Argo CD as the primary GitOps controller for Kubernetes environments. + +## Alternatives considered + +- Flux as primary GitOps controller +- Manual kubectl-first operations without a GitOps controller + +## Consequences + +- Standardizes GitOps workflow around Argo CD patterns. +- Requires Argo CD bootstrap, access, and operational runbooks. +- Existing Flux-oriented legacy references are archive-only unless re-adopted. diff --git a/docs/decisions/ADR-004-truenas-separate.md b/docs/decisions/ADR-004-truenas-separate.md new file mode 100644 index 0000000..5cf62ba --- /dev/null +++ b/docs/decisions/ADR-004-truenas-separate.md @@ -0,0 +1,21 @@ +# ADR-004: TrueNAS Remains a Separate Storage Anchor + +## Status +Accepted + +## Context +The environment already uses a separate TrueNAS system for storage and media anchoring. + +## Decision +Retain TrueNAS as an independent storage anchor rather than collapsing storage into the core compute cluster. + +## Alternatives considered + +- Collapse storage into Proxmox/Kubernetes nodes +- Immediate migration to a fully new storage platform + +## Consequences + +- Preserves existing storage investment and operational patterns. +- Requires explicit network and access boundary design. +- Keeps storage lifecycle partially decoupled from compute lifecycle. diff --git a/docs/decisions/ADR-005-media-platform-stays-separate-from-core-lab.md b/docs/decisions/ADR-005-media-platform-stays-separate-from-core-lab.md new file mode 100644 index 0000000..e2790a4 --- /dev/null +++ b/docs/decisions/ADR-005-media-platform-stays-separate-from-core-lab.md @@ -0,0 +1,21 @@ +# ADR-005: Media Platform Stays Operationally Separate from Core Lab Platform + +## Status +Accepted + +## Context +The media stack is currently substantial and production-adjacent for household usage. Core platform modernization should not destabilize media reliability. + +## Decision +Treat media platform evolution as a dedicated workstream that remains operationally separate from core platform control-plane work. + +## Alternatives considered + +- Fold media services directly into early core platform migration +- Freeze media platform changes indefinitely + +## Consequences + +- Reduces blast radius during core platform transition. +- Supports measured media redesign (platform choice still open). +- Requires explicit integration points for storage/network/shared services. diff --git a/docs/inventory/current-media-stack.md b/docs/inventory/current-media-stack.md new file mode 100644 index 0000000..2a7db1e --- /dev/null +++ b/docs/inventory/current-media-stack.md @@ -0,0 +1,48 @@ +# Current Media Stack (As-Is) + +## Summary + +The current media platform runs as a **Docker Compose stack inside a VM on Proxmox**. +It is broader than Plex alone and includes supporting media-management and access services. + +## Known components + +- Plex +- Tautulli +- nginx reverse proxy +- ACME companion +- Cloudflare tunnel +- Cloudflare DDNS +- Radarr +- Sonarr +- Bazarr +- Prowlarr +- Overseerr +- Homepage +- Recyclarr +- FlareSolverr +- Torrent/VPN-related services + +## Storage and compute characteristics + +- Media storage is mounted over **NFS from TrueNAS**. +- Current Plex deployment uses **NVIDIA-backed transcoding access** within the Docker stack. + +## Migration intent + +The media platform will be redesigned, but the final architecture is not decided. +Open evaluation areas: + +- Plex vs Jellyfin vs Emby +- Media apps directly on TrueNAS vs dedicated media VM + +## Guardrails + +- Do not commit live credentials, tokens, domains, or private operational values. +- Track unknowns and decisions as TODOs + ADRs. + +## TODOs + +- TODO: Document current backup/restore approach for media services. +- TODO: Document current GPU pass-through/runtime configuration at high level. +- TODO: Capture data-path and failure-domain assumptions for redesign planning. diff --git a/docs/inventory/hardware-inventory.md b/docs/inventory/hardware-inventory.md new file mode 100644 index 0000000..6a20097 --- /dev/null +++ b/docs/inventory/hardware-inventory.md @@ -0,0 +1,17 @@ +# Hardware Inventory + +## Confirmed assets + +| Role | System | Quantity | Known details | Notes | +|---|---|---:|---|---| +| Main compute nodes | Minisforum MS-A2 | 3 | 96 GB RAM each, 10GbE | Primary homelab compute pool | +| Storage anchor | TrueNAS box | 1 | Separate system | Media + storage anchor | +| Primary desktop | Workstation | 1 | Not part of core hosting | Treated as client/admin endpoint | +| Older rack hardware | Mixed legacy systems | TODO | Deferred | Revisit later | + +## TODOs + +- TODO: Capture CPU model per Minisforum node. +- TODO: Capture local storage device layout per node. +- TODO: Capture firmware/BIOS baseline versions. +- TODO: Capture out-of-band management capabilities (if any). diff --git a/docs/inventory/network-inventory.md b/docs/inventory/network-inventory.md new file mode 100644 index 0000000..f47af8f --- /dev/null +++ b/docs/inventory/network-inventory.md @@ -0,0 +1,20 @@ +# Network Inventory + +## Confirmed network hardware + +- Ubiquiti Cloud Gateway Fiber +- Ubiquiti Pro XG 8 PoE +- Ubiquiti Lite 16 PoE + +## Current state (known) + +- The homelab uses Ubiquiti networking as the core switching/routing foundation. +- The main compute nodes are 10GbE-capable. + +## TODOs + +- TODO: Document VLAN strategy and IDs. +- TODO: Document IP plan/subnets and DHCP/static boundaries. +- TODO: Document management network segmentation approach. +- TODO: Document firewall policy model and inter-VLAN rules. +- TODO: Document external access model (VPN, tunnel, reverse proxy boundaries). diff --git a/docs/inventory/service-inventory.md b/docs/inventory/service-inventory.md new file mode 100644 index 0000000..b06fba1 --- /dev/null +++ b/docs/inventory/service-inventory.md @@ -0,0 +1,18 @@ +# Service Inventory + +## Core platform services (target direction) + +- Proxmox cluster management plane +- Virtualized Kubernetes cluster +- Argo CD GitOps control plane +- Shared storage integrations with TrueNAS + +## Current known services + +- Media platform stack running in a VM on Proxmox (see `current-media-stack.md`) + +## TODOs + +- TODO: Inventory current non-media supporting services (DNS, monitoring, logging, backups). +- TODO: Identify which services are core platform vs optional workloads. +- TODO: Define service ownership and operational criticality tiers. diff --git a/docs/roadmap/backlog.md b/docs/roadmap/backlog.md new file mode 100644 index 0000000..b7182bf --- /dev/null +++ b/docs/roadmap/backlog.md @@ -0,0 +1,30 @@ +# Backlog (Starter) + +## Foundation +- [ ] Finalize hardware inventory details (CPU, storage, firmware) +- [ ] Finalize network inventory details +- [ ] Document current platform and supporting services + +## Proxmox + Network +- [ ] Document Proxmox cluster install/plan approach +- [ ] Define VLAN/IP strategy (management/workload/storage) +- [ ] Document host networking standards + +## Storage +- [ ] Document TrueNAS role for platform and media +- [ ] Define storage access and permission model (high-level) + +## Media platform +- [ ] Complete as-is media stack documentation +- [ ] Define media migration options matrix (Plex/Jellyfin/Emby) +- [ ] Define placement options (TrueNAS apps vs media VM) + +## Kubernetes + GitOps +- [ ] Define Kubernetes VM node approach +- [ ] Define cluster bootstrap and lifecycle approach +- [ ] Define Argo CD bootstrap approach + +## Operational excellence +- [ ] Define backup and recovery expectations by service tier +- [ ] Define observability baseline and ownership +- [ ] Define local CI/doc linting workflow diff --git a/docs/roadmap/current-phase.md b/docs/roadmap/current-phase.md new file mode 100644 index 0000000..8479358 --- /dev/null +++ b/docs/roadmap/current-phase.md @@ -0,0 +1,18 @@ +# Current Phase + +## Active phase + +**Foundation / Repository Realignment** + +## Phase goals + +- Make documentation the primary entry point for the platform. +- Preserve legacy Talos/PXE infrastructure as archive reference. +- Establish ADR and roadmap workflow for subsequent implementation. + +## Exit criteria + +- Core docs structure is in place and reviewable. +- Initial ADR set recorded. +- Starter backlog and milestone plan available. +- Priority TODOs identified without speculative assumptions. diff --git a/docs/roadmap/media-migration.md b/docs/roadmap/media-migration.md new file mode 100644 index 0000000..72872ca --- /dev/null +++ b/docs/roadmap/media-migration.md @@ -0,0 +1,28 @@ +# Media Migration Roadmap (Draft) + +## Current baseline + +- Media stack runs in Docker Compose on a Proxmox VM. +- Storage is NFS-backed by TrueNAS. +- Plex currently uses NVIDIA-backed transcoding. + +## Evaluation track + +1. Define success criteria (reliability, simplicity, performance, maintainability). +2. Compare platform options (Plex/Jellyfin/Emby). +3. Compare deployment options (TrueNAS-hosted apps vs dedicated VM). +4. Define migration sequencing and rollback boundaries. + +## Suggested phases + +- **Phase A:** Current-state validation and documentation hardening +- **Phase B:** Option analysis and proof-of-concept planning +- **Phase C:** Decision capture (ADR) +- **Phase D:** Controlled migration execution +- **Phase E:** Post-migration hardening and cleanup + +## TODOs + +- TODO: Define explicit non-functional requirements for media UX. +- TODO: Define cutover window constraints. +- TODO: Define backup/restore rehearsal expectations. diff --git a/docs/roadmap/milestones.md b/docs/roadmap/milestones.md new file mode 100644 index 0000000..bc5d773 --- /dev/null +++ b/docs/roadmap/milestones.md @@ -0,0 +1,46 @@ +# Milestones + +## M0 — Foundation / Repo Restructuring +- Documentation-first repository layout completed +- Legacy direction archived and labeled +- Issue/PR workflow templates added + +## M1 — Network Core +- Network inventory validated +- VLAN/IP strategy documented +- Security boundary baseline documented + +## M2 — Proxmox Platform +- Proxmox cluster planning complete +- Host baseline checklist finalized +- Initial implementation runbook drafted + +## M3 — Storage Integration +- TrueNAS role and access model documented +- NFS/other storage integration strategy documented + +## M4 — Virtualized Kubernetes +- Kubernetes VM architecture defined +- Bootstrap process documented +- Day-2 operations checklist drafted + +## M5 — Argo CD GitOps +- Argo CD bootstrap approach documented +- Initial GitOps application structure defined + +## M6 — Media Platform Migration Planning +- Current-state media documentation finalized +- Future media architecture options compared +- Migration recommendation captured in ADR/TODO set + +## M7 — Local CI/CD +- Repo checks and doc quality gates defined +- Local validation workflow documented + +## M8 — AI Platform Foundations +- AI platform requirements and guardrails documented +- Initial self-hosted AI workstream backlog defined + +## M9 — Agentic Development Workflows +- Agent-assisted workflow boundaries documented +- Automation/safety policy for agent tasks defined diff --git a/docs/runbooks/bootstrap-sequence.md b/docs/runbooks/bootstrap-sequence.md new file mode 100644 index 0000000..25410be --- /dev/null +++ b/docs/runbooks/bootstrap-sequence.md @@ -0,0 +1,32 @@ +# Bootstrap Sequence (Documentation-First) + +## Objective +Provide a conservative order of operations for establishing the new platform direction. + +## Sequence + +1. **Foundation docs alignment** + - Validate inventory, architecture drafts, and ADR baselines. +2. **Network core documentation and validation** + - Confirm switching/routing baseline and segmentation plan. +3. **Proxmox platform baseline** + - Establish cluster plan and host standardization checklist. +4. **Storage integration alignment** + - Confirm TrueNAS access model for platform workloads. +5. **Virtualized Kubernetes bootstrap** + - Define VM node model and cluster initialization approach. +6. **Argo CD bootstrap** + - Define Git repository and app-of-apps/bootstrapping pattern. +7. **Workload onboarding phases** + - Start with low-risk services before critical workloads. + +## Preconditions + +- No secrets committed to Git. +- TODO-marked unknowns tracked in backlog. +- Decisions requiring direction captured via ADRs. + +## TODOs + +- TODO: Add concrete command/runbook steps after implementation choices are finalized. +- TODO: Add rollback/checkpoint gates between phases. diff --git a/docs/vision/homelab-vision.md b/docs/vision/homelab-vision.md new file mode 100644 index 0000000..290169f --- /dev/null +++ b/docs/vision/homelab-vision.md @@ -0,0 +1,25 @@ +# Homelab Vision + +## Purpose +Build a resilient, maintainable homelab platform that prioritizes clarity, repeatability, and gradual evolution over premature complexity. + +## Direction + +- Proxmox-first infrastructure as the substrate +- Kubernetes initially as virtualized workloads on Proxmox +- Argo CD as the GitOps control plane +- TrueNAS retained as a separate storage/media anchor +- Future expansion for local AI and agentic development workflows + +## Non-goals (for now) + +- Immediate migration to bare-metal Kubernetes +- Full redesign of media architecture before documenting current state +- Premature optimization of every operational workflow + +## Guiding principles + +1. Documentation first, automation second, scale third. +2. Record decisions as ADRs before deep implementation. +3. Prefer explicit TODOs over guessed technical details. +4. Keep security posture and secret hygiene as baseline requirements. diff --git a/infra/live/prod/terraform.auto.tfvars b/infra/live/prod/terraform.auto.tfvars deleted file mode 100644 index 132a6b1..0000000 --- a/infra/live/prod/terraform.auto.tfvars +++ /dev/null @@ -1,41 +0,0 @@ -cluster_nodes = { - nx0 = { - hostname = "nx0.feenx.io" - ip = "10.10.97.10" - mac_address = "58:47:CA:7F:E2:16" - wake_on_lan_mac = "58:47:CA:7F:E2:14" - install_disk = "/dev/nvme0n1" - role = "controlplane" - bootstrap = true - }, - nx1 = { - hostname = "nx1.feenx.io" - ip = "10.10.97.11" - mac_address = "58:47:CA:7F:D3:B6" - wake_on_lan_mac = "58:47:CA:7F:D3:B4" - install_disk = "/dev/nvme0n1" - role = "controlplane" - depends_on = ["nx0"] - }, - nx2 = { - hostname = "nx2.feenx.io" - ip = "10.10.97.12" - mac_address = "58:47:CA:7F:D7:7E" - wake_on_lan_mac = "58:47:CA:7F:D7:7C" - install_disk = "/dev/nvme0n1" - role = "controlplane" - depends_on = ["nx1"] - } -} - -cluster_info = { - name = "fnx-platform-prod-k8s" - nameservers = ["10.10.97.254"] - virtual_ip = "10.10.97.20" - endpoint = "https://k8s.feenx.io:6443" -} - -k8s_version = "1.33.0" - -github_organization = "feenx-lab" -github_repository = "platform" \ No newline at end of file diff --git a/kubernetes/README.md b/kubernetes/README.md new file mode 100644 index 0000000..9b3aa0c --- /dev/null +++ b/kubernetes/README.md @@ -0,0 +1,5 @@ +# Kubernetes + +Design and operations docs for the virtualized Kubernetes cluster running on Proxmox. + +TODO: Add node VM patterns, bootstrap flow, and lifecycle practices. diff --git a/proxmox/README.md b/proxmox/README.md new file mode 100644 index 0000000..9e29adc --- /dev/null +++ b/proxmox/README.md @@ -0,0 +1,5 @@ +# Proxmox + +Planning and implementation artifacts for the Proxmox-first platform layer. + +TODO: Add cluster design notes, host baseline checklist, and bootstrap runbooks. diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..2fc2e3b --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,8 @@ +# Scripts + +Utility scripts for validation, bootstrap helpers, and operational tasks. + +Guidelines: +- No hard-coded secrets. +- Prefer idempotent behavior. +- Document usage at file header.