Skip to content

kanare-dev/homelab

BranchesTags

Repository files navigation

homelab

Proxmox 上に複数 VM を構築し、Terraform + Ansible + Docker Compose で再現可能に運用する homelab リポジトリ。

現在は 24GB RAM の ThinkCentre Tiny を前提に、無理なく常時運用できる構成を維持している。vm-infra・vm-monitoring・vm-apps が常時稼働し、vm-dev は必要なときに自由に壊して試せる検証用 VM とする。

現在の運用方針

  • 常時起動は vm-infra・vm-monitoring・vm-apps
  • vm-dev は Ansible や Docker の検証用に必要時だけ起動
  • まずは DNS、reverse proxy、monitoring、ダッシュボードの再現性を固める

思想

  • 再現可能性: すべての構成をコードで管理し、いつでも同じ環境を再構築できる
  • 最小構成から育てる: まずは軽量な構成で動かし、必要に応じて段階的に拡張する
  • ドキュメント駆動: このリポジトリを読めば全体像、命名規約、セットアップ手順が分かる
  • 観測可能性: Prometheus と Grafana で VM やサービスの状態を継続的に可視化する

構成図

構成図

現行アーキテクチャ

┌──────────────────────────────────────────────────────────────────┐
│  LAN: 192.168.11.0/24                  GW: 192.168.11.1          │
│                                                                  │
│  ┌──────────────┐  ┌───────────────┐  ┌──────────────┐           │
│  │  vm-infra    │  │ vm-monitoring │  │ vm-apps      │           │
│  │  .11  1.5GB  │  │  .13  2GB     │  │  .20  1GB    │           │
│  │  AdGuard Home│  │  Prometheus   │  │  Homepage    │           │
│  │  Caddy       │  │  Grafana      │  │              │           │
│  │  Tailscale   │  │  node_exporter│  │              │           │
│  └──────┬───────┘  └──────┬────────┘  └──────┬───────┘           │
│         │                 │                  │                   │
│  ┌──────┴─────────────────┴──────────────────┴─────────────────┐ │
│  │                      Proxmox VE (.10)                       │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐                              │
│  │  IoT devices │  │  vm-dev      │                              │
│  │  .100~       │  │  .21 任意起動 │                              │
│  │  ESP32 etc.  │  │  playground  │                              │
│  └──────────────┘  └──────────────┘                              │
└──────────────────────────────────────────────────────────────────┘

なぜこの構成から始めるか

観点 判断
メモリ余裕 24GB に増設済み。重めのワークロードや追加 VM を検討できる
優先順位 まずは DNS、reverse proxy、monitoring をコード化して再現性を固めたい
学習効率 vm-dev があると、設定や playbook を安全に壊して試せる
拡張性 将来 vm-apps や Home Assistant を追加しやすい

ハードウェア

機器 モデル スペック IP 備考
ルーター Buffalo WSR-1800AX4P — 192.168.11.1 現在利用中
サーバー Lenovo ThinkCentre M70q Tiny i5-10400T / 24GB RAM (8GB+16GB) / 256GB NVMe 192.168.11.10 Proxmox VE ホスト
IoT ESP32 — 192.168.11.100 Prometheus metrics を公開予定

メモリ配分（24GB）

対象 用途 割当メモリ 備考
Proxmox host ハイパーバイザ本体 ~2GB ホスト側の余裕を削りすぎない
vm-infra CoreDNS / Caddy / Tailscale 1.5GB 実使用 ~500MB
vm-monitoring Prometheus / Grafana 2GB 実使用 ~660MB
vm-apps Homepage 等 1GB 実使用 ~256MB
vm-dev 検証用 Ubuntu 1GB 常時起動しない前提
余白 キャッシュ / 追加 VM 用 ~16GB k3s 等の重めの構成を検討可能

技術スタック

レイヤ 採用技術 用途
ハイパーバイザ Proxmox VE VM の作成・実行・管理
IaC Terraform Proxmox 上の VM プロビジョニング
構成管理 Ansible OS 初期設定、Docker、node_exporter、監視基盤のデプロイ
コンテナ実行 Docker Compose Prometheus、Grafana、reverse proxy、Homepage の起動
監視 Prometheus, Grafana, node_exporter VM / ホスト / IoT のメトリクス収集と可視化
ネットワーク AdGuard Home, Unbound, CoreDNS, Caddy, Tailscale DNS フィルタリング・フル再帰解決・内部権威 DNS、reverse proxy、VPN（サブネットルーター）
TLS 証明書 Let's Encrypt + Cloudflare DNS-01 LAN 内サービスへの正規証明書発行
秘密情報管理 SOPS + age, Ansible Vault 機密情報の暗号化と運用

現在の VM 一覧

名前 VMID IP RAM 状態 役割 主なサービス
Proxmox — 192.168.11.10 — 常時起動 ハイパーバイザ Proxmox VE
vm-infra 111 192.168.11.11 1.5GB 常時起動 インフラ基盤 AdGuard Home, Unbound, CoreDNS, Caddy, Tailscale
vm-monitoring 113 192.168.11.13 2GB 常時起動 監視 Prometheus, Grafana, node_exporter
vm-apps 120 192.168.11.20 1GB 常時起動 アプリ Homepage
vm-dev 121 192.168.11.21 1GB 任意起動 開発・実験 playground

管理画面リンク

サービス IP ドメイン 備考
ルーター http://192.168.11.1 — ルーター設定画面
Proxmox https://192.168.11.10:8006 https://pve.lab.kanare.dev Proxmox VE 管理画面
Homepage http://192.168.11.20:3001 https://home.lab.kanare.dev ランディングダッシュボード
Grafana http://192.168.11.13:3000 https://grafana.lab.kanare.dev 監視ダッシュボード
Prometheus http://192.168.11.13:9090 https://prometheus.lab.kanare.dev メトリクス確認
AdGuard Home http://192.168.11.11:3000 https://adguard.lab.kanare.dev DNS フィルタリング・クエリログ
ESP32 http://192.168.11.100 - ESP32簡易表示

IP アドレス規約

範囲 用途 例
192.168.11.1 ルーター / ゲートウェイ —
192.168.11.10–19 インフラ（Proxmox, VM） .10 Proxmox, .11 vm-infra, .13 vm-monitoring
192.168.11.20–59 サーバー / 検証用 VM .20 vm-apps 予約, .21 vm-dev
192.168.11.60–99 DHCP プール 動的割当
192.168.11.100–149 IoT デバイス .100 ESP32
192.168.11.150–254 予約 / 実験用 —

ドメイン命名規約

内部 DNS では lab.kanare.dev ゾーンを使い、サービスや VM を名前で引けるようにする。

FQDN DNS 解決先 実際の宛先 用途 状態
pve.lab.kanare.dev 192.168.11.11 (Caddy) 192.168.11.10:8006 Proxmox Web UI 利用中
home.lab.kanare.dev 192.168.11.11 (Caddy) 192.168.11.20:3001 Homepage ダッシュボード 利用中
infra.lab.kanare.dev 192.168.11.11 192.168.11.11 vm-infra 管理用 利用中
grafana.lab.kanare.dev 192.168.11.11 (Caddy) 192.168.11.13:3000 Grafana 利用中
prometheus.lab.kanare.dev 192.168.11.11 (Caddy) 192.168.11.13:9090 Prometheus 利用中
vm-apps.lab.kanare.dev 192.168.11.20 192.168.11.20 vm-apps 直接 利用中
dev.lab.kanare.dev 192.168.11.21 192.168.11.21 vm-dev 任意起動
adguard.lab.kanare.dev 192.168.11.11 (Caddy) 192.168.11.11:3000 AdGuard Home Web UI 利用中

DNS / Reverse Proxy / Monitoring

DNS

3層構成で内部 DNS とフルリゾルバを分離する:

client
  └─► AdGuard Home  port 53  (0.0.0.0)        ← フィルタリング・クエリログ・WebUI
         ├─► CoreDNS         port 5353 (127.0.0.1)  ← lab.kanare.dev 権威
         └─► Unbound         port 5335 (127.0.0.1)  ← 外部フル再帰解決
  • AdGuard Home: port 53 でリッスン。広告ブロック・クエリログ・Web UI (:3000)
  • CoreDNS: 127.0.0.1:5353 で lab.kanare.dev の権威 DNS として動作
  • Unbound: 127.0.0.1:5335 でルートから再帰解決（1.1.1.1 等への依存なし）
  • grafana.lab.kanare.dev と prometheus.lab.kanare.dev を reverse proxy の入口にする

詳細は docs/dns.md を参照。

Reverse Proxy

  • vm-infra 上で Caddy を Docker Compose で動かす
  • Cloudflare DNS-01 チャレンジで Let's Encrypt 証明書を自動取得（LAN 内サービスでも有効）
  • CLOUDFLARE_API_TOKEN は Ansible Vault で管理し、デプロイ時に .env として配置
  • 将来アプリを追加しても同じ入口に集約できる

VPN（Tailscale）

  • vm-infra 上で Tailscale をサブネットルーターとして動かす（二重 NAT 環境のため WireGuard の代替）
  • --advertise-routes=192.168.11.0/24 で LAN 全体を外出先から透過的にアクセス可能にする
  • Split DNS: Tailscale Admin Console → DNS → Add nameserver で lab.kanare.dev のクエリを CoreDNS（vm-infra の Tailscale IP）に向けることで、VPN 接続中も内部ドメイン名が使える

Monitoring

  • vm-monitoring 上で Prometheus と Grafana を動かす
  • まずは各 VM の node_exporter を監視する
  • 将来的に ESP32 や Alertmanager を追加する

将来拡張

以下は現在の最小構成とは分けて扱う。

  • Cloudflare Tunnel + Split-Horizon DNS で grafana.lab.kanare.dev 等を外部公開する
  • vm-apps に Home Assistant などの追加アプリを載せる
  • VLAN を導入して Management / Servers / Clients / IoT / Guests を分離する
  • Alertmanager を追加して Slack / Discord 通知を行う
  • Loki + Promtail でログ収集を追加する
  • k3s などの重めの構成を検討する（メモリ増設済み）

リポジトリ構成

homelab/
├── README.md
├── tools/
│   └── lab/                # 監視 CLI (Go)
│       ├── lab.yaml        # VM・サービス定義
│       └── README.md
├── terraform/
│   └── proxmox/
├── ansible/
│   ├── inventory/
│   ├── roles/
│   └── playbooks/
├── docker/
│   └── compose/
│       ├── homepage/
│       ├── monitoring/
│       └── reverse-proxy/
├── diagrams/
└── docs/

Quick Start

前提条件

  • Terraform >= 1.5
  • Ansible >= 2.15
  • Proxmox VE 8.x が 192.168.11.10 で稼働済み
  • 対象 VM に SSH 鍵認証でログインできること

Important

Terraform の Proxmox provider には API トークンが必要。terraform/proxmox/README.md の手順に従い、事前に Proxmox 側でトークンを発行する。

1. リポジトリをクローン

git clone https://github.com/kanare-dev/homelab.git
cd homelab

2. Core VM をプロビジョニング

cd terraform/proxmox
cp terraform.tfvars.example terraform.tfvars
# terraform.tfvars を編集
terraform init
terraform plan
terraform apply

まずは vm-infra と vm-monitoring を優先し、vm-dev は必要になってから追加する。

3. VM を構成

cd ansible
# inventory/hosts.yml を環境に合わせて編集
ansible-playbook playbooks/site.yml

4. 動作確認

# DNS
dig @192.168.11.11 grafana.lab.kanare.dev

# Grafana
open http://192.168.11.13:3000

# Prometheus
open http://192.168.11.13:9090

# lab CLI で一括確認
cd tools/lab && go mod tidy && go build -o lab . && ./lab status

詳細な手順は docs/next.md を参照。

Screenshots

Proxmox VE — VM 稼働状況

Terraform でプロビジョニングした vm-infra (111) と vm-monitoring (113) が running 状態。

Proxmox VMs Running

Grafana — Node Exporter ダッシュボード

https://grafana.lab.kanare.dev（AdGuard Home + CoreDNS + Caddy 経由）で Grafana にアクセスし、 node_exporter で収集した VM のメトリクスを可視化している。

Grafana Node Exporter Dashboard

Terraform — 構成の冪等性

terraform apply を実行すると No changes. となり、実インフラがコードと完全に一致していることを確認。

Terraform Apply Output

Ansible — Playbook 実行結果

ansible-playbook で vm-infra・vm-monitoring の両 VM に設定を適用。failed=0 で正常完了。

Ansible Playbook Recap

セキュリティ

  • 秘密情報は Git に入れない: .env, terraform.tfvars, Ansible Vault ファイルは除外する
  • SOPS + age を推奨: 暗号化した状態で Git 管理可能
  • Ansible Vault: ansible-vault encrypt で変数ファイルを暗号化
  • LAN 内 TLS: Caddy + Cloudflare DNS-01 チャレンジで Let's Encrypt 証明書を自動取得・更新
  • SSH 鍵認証のみ: パスワード認証は無効化する
  • ファイアウォール: ufw で必要なポートのみ開放する

About

Proxmox-based homelab managed with Terraform, Ansible, and Docker Compose

Topics

linux docker ansible ubuntu terraform esp32 grafana prometheus self-hosted iac caddy proxmox homelab coredns tailscale tinyminimicro

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages