This directory contains Architecture Decision Records (ADRs) for terraform-provider-proxmox. ADRs document the key architectural patterns contributors must follow.
| ADR | Title | Summary |
|---|---|---|
| 001 | Use Plugin Framework | All new resources use Terraform Plugin Framework, not SDKv2 |
| 002 | API Client Structure | Layered domain clients in proxmox/ with ExpandPath() pattern |
| 003 | Resource File Organization | Domain hierarchy, 3-file pattern, naming conventions |
| 004 | Schema Design Conventions | Attribute types, validators, model-API conversion, CheckDelete, PVE-defaults rule |
| 005 | Error Handling | "Unable to [Action] [Resource]" format, 3-layer error architecture, retry policies |
| 006 | Testing Requirements | Acceptance tests required, table-driven structure, test helpers |
| 007 | Resource Type Name Migration | Migrate from proxmox_virtual_environment_ to proxmox_ prefix in 3 phases |
| 008 | Sub-block Contract | Value-centric NewValue / FillCreateBody / FillUpdateBody shape for sub-packages of VM-style composite resources |
When implementing a new resource, read the ADRs in this order:
- ADR-001 — Confirms you're using the right framework
- ADR-003 — Where to put files and what to name them
- ADR-002 — How to access the Proxmox API
- ADR-004 — Schema attributes, model conversion, field deletion, PVE-defaults rule
- ADR-005 — Error message format and sentinel error handling
- ADR-006 — Acceptance test structure and helpers
- ADR-008 — Only if the resource composes sub-packages (VM-style). Skip otherwise.
- reference-examples.md — Copy-from code walkthroughs and checklist
The reference-examples.md document provides annotated walkthroughs of three real resources at increasing complexity:
- SDN VNet — start here for any new resource (simplest clean 3-file pattern)
- Replication — many optional fields, split create/update methods, perfect audit score
- Backup Job — ConfigValidators, comma-separated-to-list, nested objects
It also includes a checklist for new resource implementation.