101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
kpr-genesis — Git‑Driven KPR Proxmox Automation
|
||
===================================================
|
||
|
||
**kpr-genesis** is both the runner and the repository that keep your Arch‑based Proxmox homelab declarative. A push to the `main` branch triggers:
|
||
|
||
1. **Terraform** – provisions / reconciles LXCs on Proxmox.
|
||
2. **Ansible** – installs Docker, then deploys services in those LXCs.
|
||
|
||
The first wired‑in service is the Rust paste‑bin [w4/bin](https://github.com/w4/bin).
|
||
|
||
Repository Layout
|
||
-----------------
|
||
|
||
```
|
||
kpr-genesis/
|
||
├─ scripts/
|
||
│ └─ run\_pipeline.sh # git‑pull → terraform apply → ansible
|
||
├─ terraform/ # infra layer (Proxmox provider)
|
||
│ ├─ main.tf
|
||
│ ├─ variables.tf
|
||
│ ├─ versions.tf
|
||
│ └─ (no outputs – DHCP IP comes from Ansible)
|
||
└─ ansible/
|
||
├─ inventory.proxmox.yml # dynamic inventory (Proxmox API)
|
||
├─ ansible.cfg # points to the inventory above
|
||
├─ requirements.yml # galaxy roles / collections
|
||
├─ site.yml # top‑level playbook
|
||
├─ group\_vars/
|
||
│ └─ all.yml
|
||
└─ roles/
|
||
├─ docker/
|
||
│ └─ tasks/main.yml
|
||
└─ bin/
|
||
├─ tasks/main.yml
|
||
└─ templates/docker-compose.yml.j2
|
||
```
|
||
|
||
Prerequisites
|
||
-------------
|
||
|
||
* Proxmox VE 8.x with an API token that has at least **PVEAdmin** on `/` (`root@pam!kpr-genesis` in the samples).
|
||
* Arch Linux LXC named `kpr-genesis` with `terraform`, `ansible-core`, `python-proxmoxer`, and `python-requests` installed.
|
||
* Public SSH key committed as `id_ed25519.pub` (Terraform injects it into each new container).
|
||
* Webhook from your Gitea server hitting `http://kpr-genesis.<lan>:9000/hook`.
|
||
|
||
First‑Time Setup
|
||
----------------
|
||
|
||
\# clone the repo as the 'infra' user
|
||
```
|
||
git clone https://tetera.kernelpanic.lol/ozymandias/kpr-genesis
|
||
cd kpr-genesis
|
||
```
|
||
|
||
# install Ansible roles / collections
|
||
`ansible-galaxy install -r ansible/requirements.yml`
|
||
|
||
# export the Proxmox token
|
||
`export PROXMOX\_TOKEN=<PROXMOX TOKEN HERE>``
|
||
|
||
# run the pipeline once
|
||
```
|
||
export TF_VAR_pm_api_url=https://<PROXMOX IP HERE>:8006/api2/json
|
||
export TF_VAR_pm_user=root@pam
|
||
export TF_VAR_pm_token=<PROXMOX TOKEN HERE>
|
||
export TF_VAR_node=pacifica
|
||
export TF_VAR_bin_lxc_password='<PASSWORD HERE>'
|
||
export PROXMOX_TOKEN=<PROXMOX TOKEN HERE>
|
||
|
||
./scripts/run_pipeline.sh
|
||
```
|
||
|
||
|
||
Terraform creates a DHCP LXC named **bin**; Ansible installs Docker inside it and starts the `w4/bin` container on port 8000.
|
||
|
||
Workflow
|
||
--------
|
||
|
||
1. Edit Terraform or Ansible files.
|
||
2. Commit and push to `main`.
|
||
3. Webhook triggers pipeline; infrastructure converges.
|
||
|
||
Adding a Service
|
||
----------------
|
||
|
||
1. Add a `proxmox_lxc` block in `terraform/main.tf`.
|
||
2. Create a role under `ansible/roles/` and reference it in `site.yml`.
|
||
3. Commit & push — pipeline handles the rest.
|
||
|
||
Secrets
|
||
-------
|
||
|
||
Only public keys live in Git. The Proxmox token is supplied via the `PROXMOX_TOKEN` environment variable (or through Ansible Vault if preferred).
|
||
|
||
Troubleshooting
|
||
---------------
|
||
|
||
* `ansible-inventory -i ansible/inventory.proxmox.yml --graph`
|
||
* `journalctl -u infra-hook` for pipeline logs
|
||
* `terraform state list` to inspect tracked resources
|