LoopAware-Infra/windows-iac-vm-tooling
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

feat: Add professional hierarchical documentation
Some checks are pending
Build and Release / build-sign-package (push) Waiting to run
Details

Browse source 
- Created comprehensive README.md with Mermaid diagrams, badges, and TOC
- Added docs/ directory with 7 sections and 14 markdown files
- Included architecture diagrams, flowcharts, and sequence diagrams
- All documentation is fully interlinked with cross-references
- Added ISO storage location on Proxmox development server
- Included troubleshooting guide and evaluation management docs
- All config files (Packer, Terraform, Ansible, Forgejo) documented
- Added icons and visual elements throughout documentation
This commit is contained in:
root 2026-02-06 14:47:15 +00:00
parent faf04d69f8
commit e4f03427b7
24 changed files with 3844 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

182
docs/02-prerequisites/isos.md Normal file
View file

@ -0,0 +1,182 @@
# 💿 ISO Requirements
[![ISO](https://img.shields.io/badge/ISO-Windows%2011%20LTSC-0078D6?style=flat&logo=windows)](https://www.microsoft.com/en-us/windows/windows-11-enterprise)
## Storage Location
All ISO files must be placed on the Proxmox development server at:
```bash
/mnt/pve-07-iso-nvme/template/iso/
```
### Verify Storage Path
```bash
# SSH to Proxmox host and verify
ssh root@la-vmh-07
ls -la /mnt/pve-07-iso-nvme/template/iso/
```
---
## Required Files
### ✅ Mandatory
| File | Description | Size | Notes |
|------|-------------|------|-------|
| `CLIENT_LTSC_EVAL_x64FRE_en-us.iso` | Windows 11 LTSC 2024 Evaluation | ~5.5 GB | Primary OS image |
| `virtio-win.iso` | VirtIO Drivers | ~500 MB | Required for I/O performance |
### 📁 Optional
| File | Description | Use Case |
|------|-------------|----------|
| `SERVER_EVAL_x64FRE_en-us.iso` | Windows Server 2022 Evaluation | Server deployments |
| `26100.1742.240906-0331.ge_release_svc_refresh_CLIENT_LTSC_EVAL_x64FRE_en-us.iso` | Windows 11 LTSC Update | Latest build |
---
## ISO Manifest
```bash
# Current directory contents
/mnt/pve-07-iso-nvme/template/iso/
├── CLIENT_LTSC_EVAL_x64FRE_en-us.iso ✅ Required
├── SERVER_EVAL_x64FRE_en-us.iso 📁 Optional
├── debian-live-13.2.0-amd64-gnome.iso 📁 Linux (not used)
├── virtio-win.iso ✅ Required
└── 26100.1742.240906-0331...iso 📁 Optional (alternate)
```
---
## Download Sources
### Windows 11 Enterprise
| Property | Value |
|----------|-------|
| **Product** | Windows 11 Enterprise LTSC 2024 |
| **Edition** | Enterprise (Evaluation) |
| **Architecture** | 64-bit (x64) |
| **Language** | English (US) |
| **Download URL** | [Microsoft Eval Center](https://info.microsoft.com/ww-landing-windows-11-enterprise.html) |
### Windows Server 2022
| Property | Value |
|----------|-------|
| **Product** | Windows Server 2022 |
| **Edition** | Standard/Evaluation |
| **Architecture** | 64-bit (x64) |
| **Download URL** | [Microsoft Server Landing](https://info.microsoft.com/ww-landing-windows-server-2022.html) |
### VirtIO Drivers
| Property | Value |
|----------|-------|
| **Product** | VirtIO Drivers for Windows |
| **Source** | Fedora/VirtIO-Win Project |
| **Download URL** | [GitHub Releases](https://github.com/virtio-win/virtio-win-pkg-scripts/releases) |
---
## Download Steps
### 1. Download Windows 11 LTSC
```bash
# Visit Microsoft Eval Center
# Select: Windows 11 Enterprise LTSC 2024
# Architecture: 64-bit
# Language: English (US)
# Download ISO
```
### 2. Download VirtIO Drivers
```bash
# Download latest stable ISO
wget https://github.com/virtio-win/virtio-win-pkg-scripts/releases/download/v1.1.5/virtio-win-0.1.240-1.iso
mv virtio-win-0.1.240-1.iso virtio-win.iso
```
### 3. Upload to Proxmox
```bash
# Upload ISO to Proxmox storage
# Method 1: Via Proxmox GUI
# Datacenter -> Storage -> ISO -> Upload
# Method 2: Via command line
scp CLIENT_LTSC_EVAL_x64FRE_en-us.iso root@la-vmh-07:/mnt/pve-07-iso-nvme/template/iso/
scp virtio-win.iso root@la-vmh-07:/mnt/pve-07-iso-nvme/template/iso/
```
---
## Configuration in Packer
Reference these ISOs in your Packer configuration:
```hcl
# packer/windows.pkr.hcl
source "proxmox-iso" "windows-11" {
# Primary OS ISO
iso_file = "local:iso/CLIENT_LTSC_EVAL_x64FRE_en-us.iso"
# VirtIO Drivers as secondary CD
additional_iso_files {
device = "sata1"
iso_file = "local:iso/virtio-win.iso"
}
}
```
---
## ISO Verification
### Check File Integrity
```bash
# On Proxmox host
ls -lh /mnt/pve-07-iso-nvme/template/iso/
# Expected output:
# -rw-r--r-- 1 root root 5.5G Feb 6 10:50 CLIENT_LTSC_EVAL_x64FRE_en-us.iso
# -rw-r--r-- 1 root root 500M Feb 6 10:50 virtio-win.iso
```
### Verify in Proxmox GUI
1. Navigate to **Datacenter** → **Storage** → **ISO**
2. Confirm files are listed and **Content** shows correct ISOs
3. Verify **Available** status is ✅
---
## Troubleshooting
| Issue | Cause | Solution |
|-------|-------|----------|
| ISO not found | Wrong storage path | Verify `/mnt/pve-07-iso-nvme/template/iso/` |
| Mount failed | ISO corrupted | Re-download and verify checksum |
| VirtIO not loading | Wrong driver location | Check `additional_iso_files` path |
---
## Next Steps
| Goal | Next Document |
|------|---------------|
| Configure secrets | [Secret Management](../02-prerequisites/secrets.md) |
| Build template | [Packer Configuration](../03-packer/configuration.md) |
| View architecture | [Architecture Overview](../01-overview/architecture.md) |
---
[← Documentation Index](../index.md) | [→ Secret Management](../02-prerequisites/secrets.md) | [← Architecture](../01-overview/architecture.md)

224
docs/02-prerequisites/secrets.md Normal file
View file

@ -0,0 +1,224 @@
# 🔐 Secret Management
[![Security](https://img.shields.io/badge/Security-Secrets%20Management-green)](https://forgejo.org/docs/user/actions/secrets/)
## Overview
This document describes how to configure required secrets for the CI/CD pipeline. All secrets should be stored securely in Forgejo and never committed to the repository.
---
## Required Secrets
| Secret Name | Description | Used By | Required |
|-------------|-------------|---------|----------|
| `PFX_PASS` | Code signing certificate password | osslsigncode | ✅ Yes |
| `PM_TOKEN_ID` | Proxmox API token ID | OpenTofu | ✅ Yes |
| `PM_TOKEN_SECRET` | Proxmox API token secret | OpenTofu | ✅ Yes |
| `WIN_ADMIN_PASS` | Windows Administrator password | Ansible | ✅ Yes |
---
## Forgejo Configuration
### Accessing Secrets
1. Navigate to your Forgejo repository
2. Go to **Settings** → **Secrets**
3. Add each secret with the exact names listed below
### Required Secrets List
```mermaid
graph TD
subgraph Forgejo["Forgejo Settings"]
Settings["Settings"] --> Secrets["Secrets"]
Secrets --> Add["Add Secret"]
Add --> |"Enter Name & Value"| Created[Secret Created]
end
subgraph CreatedSecrets["Configured Secrets"]
PFX["🔐 PFX_PASS"]
PM_ID["🔑 PM_TOKEN_ID"]
PM_SEC["🔑 PM_TOKEN_SECRET"]
WIN["🪟 WIN_ADMIN_PASS"]
end
Created --> PFX
Created --> PM_ID
Created --> PM_SEC
Created --> WIN
style Forgejo fill:#e1f5fe
style CreatedSecrets fill:#e8f5e9
```
---
## Proxmox API Token
### Create API Token
1. **SSH to Proxmox host:**
```bash
ssh root@la-vmh-07
```
2. **Navigate to API Tokens:**
- Go to **Datacenter** → **API Tokens**
- Click **Add**
3. **Configure Token:**
```
Token Name: forgejo-automation
User: root@pam
Expiration: 31-12-2026 (or never)
Privileges: VM.Admin (or Administrator)
```
4. **Save Credentials:**
```
Token ID: root@pam!forgejo-automation
Secret: <YOUR_SECRET_VALUE>
```
### Set Environment Variables
```bash
# In Forgejo workflow or local environment
export PM_API_TOKEN_ID="root@pam!forgejo-automation"
export PM_API_TOKEN_SECRET="<your-token-secret>"
```
---
## Code Signing Certificate
### Certificate Requirements
| Property | Value |
|----------|-------|
| **Format** | PKCS#12 (.pfx or .p12) |
| **Algorithm** | SHA-256 |
| **Timestamp Server** | http://timestamp.digicert.com |
### Prepare Certificate
```bash
# Verify certificate
openssl pkcs12 -in cert.pfx -info -noout
# Extract for use (if needed)
openssl pkcs12 -in cert.pfx -clcerts -nokeys -out cert.pem
openssl pkcs12 -in cert.pfx -nocerts -out key.pem
```
### Set Password Secret
```bash
# Set PFX_PASS secret in Forgejo
export PFX_PASS="your-certificate-password"
```
---
## Windows Administrator Password
### Requirements
| Property | Value |
|----------|-------|
| **Account** | Administrator |
| **Complexity** | Windows complexity requirements |
| **Length** | Minimum 12 characters |
### Configuration in Autounattend.xml
The password is configured in [`packer/Autounattend.xml`](../../packer/Autounattend.xml):
```xml
<UserAccounts>
<AdministratorPassword>
<Value>PackerPassword123!</Value>
<PlainText>true</PlainText>
</AdministratorPassword>
</UserAccounts>
```
### Ansible Integration
```yaml
# ansible/pipeline.yml
- name: Verify Installer
hosts: windows_vm
vars:
ansible_user: Administrator
ansible_password: "{{ lookup('env', 'WIN_ADMIN_PASS') }}"
```
---
## Security Best Practices
```mermaid
flowchart LR
subgraph BestPractices["Security Guidelines"]
direction TB
NeverCommit["❌ Never commit secrets to git"]
RotateKeys["🔄 Rotate keys regularly"]
UseVault["🔐 Use Forgejo Secrets"]
LimitScopes["📊 Limit token privileges"]
AuditLogs["📝 Audit access logs"]
end
NeverCommit --> RotateKeys
RotateKeys --> UseVault
UseVault --> LimitScopes
LimitScopes --> AuditLogs
style BestPractices fill:#ffebee
```
| Practice | Description |
|----------|-------------|
| **Never commit secrets** | Use .gitignore for .pfx, .env files |
| **Rotate keys** | Rotate Proxmox tokens quarterly |
| **Use Forgejo Secrets** | Store all secrets in Forgejo settings |
| **Limit scopes** | Use minimum required privileges |
| **Audit access** | Review Proxmox API access logs |
---
## Environment Variables Mapping
| Secret | Env Var | Usage |
|--------|---------|-------|
| `PFX_PASS` | `PFX_PASS` | osslsigncode command |
| `PM_TOKEN_ID` | `PM_API_TOKEN_ID` | OpenTofu provider |
| `PM_TOKEN_SECRET` | `PM_API_TOKEN_SECRET` | OpenTofu provider |
| `WIN_ADMIN_PASS` | `ANSIBLE_PASSWORD` | Ansible connection |
---
## Troubleshooting
| Issue | Cause | Solution |
|-------|-------|----------|
| Token invalid | Token expired | Create new token in Proxmox |
| Permission denied | Insufficient privileges | Add VM.Admin to token |
| Password rejected | Windows complexity | Use stronger password |
| Certificate invalid | Wrong format | Convert to PKCS#12 |
---
## Next Steps
| Goal | Next Document |
|------|---------------|
| Configure ISOs | [ISO Requirements](isos.md) |
| Build template | [Packer Configuration](../03-packer/configuration.md) |
| View architecture | [Architecture Overview](../01-overview/architecture.md) |
---
[← Documentation Index](../index.md) | [→ ISO Requirements](isos.md) | [← Architecture](../01-overview/architecture.md)