Skip to content

Commit ad7ce07

Browse files
Danilop95Danilop95
committed
feat: Add CI workflow for template validation and rendering
- Introduced a GitHub Actions workflow to lint, validate, and render templates on pull requests and pushes to the main branch. - Added steps for installing necessary tools, running Yamllint, validating JSON schemas, and performing dry-run renders of templates. chore: Configure pre-commit hooks for YAML and JSON validation - Set up pre-commit hooks for yamllint, shellcheck, and JSON schema validation to ensure code quality and adherence to standards. style: Add yamllint configuration - Created a .yamllint.yaml file to customize yamllint rules, disabling line length checks and configuring truthy checks. feat: Implement template rendering script (qm.sh) - Developed a bash script (qm.sh) to translate YAML templates into Proxmox `qm` commands, supporting various VM configurations and storage options. feat: Create template control script (templatectl.sh) - Added a CLI script (templatectl.sh) for managing VM templates, including commands for listing, validating, rendering, and applying templates. docs: Add README for templates directory - Created a README.md file in the templates directory to provide an overview of the structure, requirements, and usage examples for VM templates. feat: Add VM templates for Linux and Windows - Introduced YAML templates for Linux Workstation and Media Server, as well as a Windows Gaming template, each with specific configurations and metadata. feat: Define JSON schema for VM templates - Created a JSON schema (template.schema.json) to validate the structure and required fields of VM templates, ensuring compliance with the defined specifications.
1 parent b418db5 commit ad7ce07

File tree

14 files changed

+2928
-638
lines changed

14 files changed

+2928
-638
lines changed

‎.github/workflows/templates.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Templates CI
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'templates/**'
7+
- 'src/tools/templatectl.sh'
8+
- 'src/tools/renderers/**'
9+
push:
10+
branches: [ main ]
11+
paths:
12+
- 'templates/**'
13+
- 'src/tools/templatectl.sh'
14+
- 'src/tools/renderers/**'
15+
16+
jobs:
17+
lint-validate:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
22+
- name: Install tools
23+
run: |
24+
sudo apt-get update
25+
sudo apt-get install -y jq curl python3 python3-pip shellcheck
26+
pip3 install jsonschema pyyaml
27+
# yq v4 está en GitHub releases; para CI usamos binario estático
28+
YQ_VERSION="v4.44.3"
29+
wget -q https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64 -O yq
30+
chmod +x yq
31+
sudo mv yq /usr/local/bin/yq
32+
yq --version
33+
34+
- name: Yamllint
35+
uses: ibiqlik/action-yamllint@v3
36+
with:
37+
strict: true
38+
file_or_dir: templates/
39+
40+
- name: JSON Schema validate
41+
run: |
42+
python3 - <<'PY'
43+
import sys, json, yaml, glob
44+
from jsonschema import Draft202012Validator as V
45+
schema = json.load(open('templates/schemas/template.schema.json'))
46+
validator = V(schema)
47+
ok = True
48+
for f in glob.glob('templates/**/*.yaml', recursive=True):
49+
try:
50+
data = yaml.safe_load(open(f))
51+
validator.validate(data)
52+
print('OK', f)
53+
except Exception as e:
54+
ok = False
55+
print('FAIL', f, '->', e, file=sys.stderr)
56+
sys.exit(0 if ok else 1)
57+
PY
58+
59+
- name: Shellcheck
60+
run: |
61+
shellcheck -x src/tools/templatectl.sh src/tools/renderers/qm.sh
62+
63+
- name: Dry-run render all templates
64+
run: |
65+
chmod +x src/tools/templatectl.sh src/tools/renderers/qm.sh
66+
find templates -name '*.yaml' -print0 | while IFS= read -r -d '' f; do
67+
./src/tools/templatectl.sh render "$f" --vmid 999 --storage-pool local-lvm --dry-run >/dev/null
68+
done

‎.gitignore‎

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,32 @@
1+
# Ignore everything by default
12
*
2-
!scripts/
3-
!release-notes/
4-
!src/
3+
4+
# Include important project files
55
!LICENSE
66
!README.md
7-
!release-notes/release-notes.md
7+
!SECURITY.md
8+
!.gitignore
9+
10+
# Include configuration files
11+
!.pre-commit-config.yaml
12+
!.yamllint.yaml
13+
14+
# Include GitHub configuration
15+
!.github/
16+
!.github/**
17+
18+
# Include documentation
819
!doc/
920
!doc/**
10-
!scripts/pecu_release_selector.sh
11-
!scripts/pecu_release_selector_old.sh
12-
!scripts/versions.conf
13-
!src/proxmox-configurator.sh
14-
!.gitignore
21+
22+
# Include scripts
23+
!scripts/
24+
!scripts/**
25+
26+
# Include source code
27+
!src/
28+
!src/**
29+
30+
# Include templates
31+
!templates/
32+
!templates/**

‎.pre-commit-config.yaml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
repos:
2+
- repo: https://github.com/adrienverge/yamllint
3+
rev: v1.35.1
4+
hooks:
5+
- id: yamllint
6+
files: ^templates/
7+
- repo: https://github.com/jumanjihouse/pre-commit-hooks
8+
rev: 3.0.0
9+
hooks:
10+
- id: shellcheck
11+
files: ^src/tools/
12+
- repo: https://github.com/sirosen/check-jsonschema
13+
rev: 0.28.6
14+
hooks:
15+
- id: check-jsonschema
16+
files: ^templates/.*\.yaml$
17+
args: ["--schemafile", "templates/schemas/template.schema.json"]

‎.yamllint.yaml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
extends: default
2+
rules:
3+
line-length: disable
4+
truthy:
5+
allowed-values: ['true', 'false']
6+
check-keys: false

‎README.md‎

Lines changed: 61 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,19 @@
33
<br>
44
Proxmox-Enhanced-Configuration-Utility<br><sub>( PECU )</sub>
55
</h1>
6+
## Features
67

7-
8-
<p align="center">
8+
| Category | Highlights |
9+
| --------------------- | ---------------------------------------------------------------------------------------- |
10+
| **Repositories** | Backup / restore `sources.list`, add "non-subscription" repo, edit with Nano. |
11+
| **GPU Passthrough** | Wizard-style setup for NVIDIA, AMD, Intel; supports driverctl override; rollback option. |
12+
| **Kernel Tweaks** | Add `pcie_acs_override`, `video=efifb:off`, or custom flags with risk prompts. |
13+
| **Multi-GPU** | Detects multiple GPUs and lets you choose the one to passthrough. |
14+
| **Intel iGPU (test)** | Experimental automatic isolation of iGPU functions. |
15+
| **VM Templates** | Declarative YAML templates with CLI tools for common VM configurations. |
16+
| **Template Validation** | JSON Schema validation and CI/CD integration for template quality assurance. |
17+
| **Proxmox 9.0** | Full support for the latest Proxmox VE 9.0 with Debian Trixie compatibility. |
18+
| **Logging** | Detailed `/var/log/pecu.log` with timestamps and automatic log rotation. |="center">
919
<a href="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/actions">
1020
<img src="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/actions/workflows/release.yml/badge.svg" alt="CI Status"></a>
1121
<a href="https://github.com/Danilop95/Proxmox-Enhanced-Configuration-Utility/wiki">
@@ -25,6 +35,7 @@
2535
- [Direct execution (recommended)](#direct-execution-recommended)
2636
- [Offline / local install](#offline--local-install)
2737
- [What Is the Release Selector?](#what-is-the-release-selector)
38+
- [VM Templates System](#vm-templates-system)
2839
- [Features](#features)
2940
- [Community & Contribution](#community--contribution)
3041
- [Support the Project](#support-the-project)
@@ -40,6 +51,8 @@ as painless as possible:
4051
* interactive menus for repositories, kernel flags, GPU passthrough, etc.
4152
* reversible operations (backup / rollback built-in)
4253
* auto-detects NVIDIA, AMD **and** Intel iGPUs out of the box
54+
* **NEW**: declarative VM template system with CLI management tools
55+
* **NEW**: full Proxmox VE 9.0 support with enhanced compatibility
4356

4457
---
4558

@@ -48,11 +61,11 @@ as painless as possible:
4861
> The selector and the underlying scripts are designed for a **typical, up-to-date Proxmox host**.
4962
> If your stack falls outside the matrix below, use at your own risk.
5063
51-
|   |   |
64+
| | |
5265
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53-
| **Platform** | <img src="https://img.shields.io/badge/Proxmox VE-7.x %2F 8.x-000000?style=for-the-badge&logo=proxmox&logoColor=white" alt="Proxmox 7 / 8 badge"> *(tested weekly on the latest ISO)* |
66+
| **Platform** | <img src="https://img.shields.io/badge/Proxmox VE-7.x %2F 8.x %2F 9.x-000000?style=for-the-badge&logo=proxmox&logoColor=white" alt="Proxmox 7 / 8 / 9 badge"> *(tested weekly on the latest ISO)* |
5467
| **CPU arch** | <img src="https://img.shields.io/badge/x86--64-required-6A737D?style=for-the-badge"> |
55-
| **Privileges** | <img src="https://img.shields.io/badge/root_or_sudo-required-E74C3C?style=for-the-badge" alt="root badge">
68+
| **Privileges** | <img src="https://img.shields.io/badge/root_or_sudo-required-E74C3C?style=for-the-badge" alt="root badge">
5669

5770
> **Heads-up** PECU does **not** support ARM / Raspberry Pi builds of Proxmox at this time.
5871
> Community ports are welcome, but official testing is x86-64 only.
@@ -116,6 +129,49 @@ lector.
116129

117130
---
118131

132+
## VM Templates System
133+
134+
**New in 2025.08** – PECU now includes a declarative VM template system with CLI management tools.
135+
136+
### Template Features
137+
138+
* **Declarative YAML templates** for common VM configurations (Windows Gaming, Linux Workstation, Media Server)
139+
* **JSON Schema validation** ensuring template consistency and correctness
140+
* **CLI management** with `templatectl.sh` for listing, validating, rendering, and applying templates
141+
* **Safe rendering** – view `qm` commands before execution with `--dry-run`
142+
* **Storage flexibility** – supports `local-lvm`, `local`, and auto-detection
143+
* **CI/CD ready** – GitHub Actions workflow for automatic validation
144+
145+
### Quick Template Usage
146+
147+
```bash
148+
# List available templates
149+
src/tools/templatectl.sh list --channel Stable
150+
151+
# Validate all templates
152+
src/tools/templatectl.sh validate templates/
153+
154+
# Preview commands (safe, no execution)
155+
src/tools/templatectl.sh render templates/windows/windows-gaming.yaml \
156+
--vmid 200 --storage-pool local-lvm --dry-run
157+
158+
# Apply template (creates VM)
159+
sudo src/tools/templatectl.sh apply templates/windows/windows-gaming.yaml \
160+
--vmid 200 --storage-pool local-lvm
161+
```
162+
163+
### Available Templates
164+
165+
| Template | Channel | OS Type | Description |
166+
|----------|---------|---------|-------------|
167+
| `windows-gaming` | Stable | win11 | Windows 11 VM optimized for gaming with GPU passthrough support |
168+
| `linux-workstation` | Stable | l26 | Linux workstation for development and productivity |
169+
| `media-server` | Stable | l26 | Lightweight Linux VM for media services (Plex, Jellyfin, etc.) |
170+
171+
See [templates/README.md](templates/README.md) for detailed documentation.
172+
173+
---
174+
119175
## Features
120176

121177
| Category | Highlights |

0 commit comments

Comments
 (0)