feat(backup): add proxmox_backup_job resource and proxmox_backup_jobs data source

[bpg-dev]

What does this PR do?

Adds a new proxmox_backup_job resource and proxmox_backup_jobs data source for managing Proxmox VE cluster backup jobs via the /cluster/backup API. This implements the backup job management requested in #1815 by porting and rewriting the abandoned PR #2540 to comply with all current project ADRs.

The resource supports full CRUD lifecycle including VM targeting (by ID list, pool, or all), scheduling, storage, compression, retention policies (prune_backups), fleecing, performance tuning, and field deletion via the Proxmox delete parameter. Uses the proxmox_ prefix per ADR-007.

Also adds shared attribute.StringPtrFromValue / CustomBoolPtrFromValue / Int64PtrFromValue helpers for safely converting Optional+Computed fields (where ValueStringPointer() returns &"" for Unknown values).

Contributor's Note

• I have run make lint and fixed any issues.
• I have updated documentation (FWK: schema descriptions + make docs; SDK: manual /docs/ edits).
• I have added / updated acceptance tests (required for new resources and bug fixes — see ADR-006).
• I have considered backward compatibility (no breaking schema changes without ! in PR title).
• For new resources: I followed the reference examples.
• I have run make example to verify the change works (mainly for SDK / provider config changes).

Proof of Work

Acceptance Tests (6/6 pass)

$ ./testacc "TestAccResourceBackupJob|TestAccDataSourceBackupJobs" -- -v

=== RUN   TestAccResourceBackupJob
=== RUN   TestAccResourceBackupJob/create_and_update_backup_job
=== RUN   TestAccResourceBackupJob/create_with_minimal_attributes
=== RUN   TestAccResourceBackupJob/field_deletion
=== RUN   TestAccResourceBackupJob/backup_specific_VMs_by_ID
=== RUN   TestAccResourceBackupJob/backup_with_retention_policy
=== RUN   TestAccDataSourceBackupJobs
--- PASS: TestAccDataSourceBackupJobs (2.12s)
--- PASS: TestAccResourceBackupJob (0.00s)
    --- PASS: TestAccResourceBackupJob/backup_with_retention_policy (1.02s)
    --- PASS: TestAccResourceBackupJob/create_and_update_backup_job (1.84s)
    --- PASS: TestAccResourceBackupJob/backup_specific_VMs_by_ID (1.84s)
    --- PASS: TestAccResourceBackupJob/create_with_minimal_attributes (2.04s)
    --- PASS: TestAccResourceBackupJob/field_deletion (2.56s)
PASS
ok  github.com/bpg/terraform-provider-proxmox/fwprovider/cluster/backup 4.216s

Test scenarios:

• create and update — creates with optional fields, updates them, verifies import round-trip
• minimal attributes — creates with only required fields, verifies server defaults populated
• field deletion — sets mailto, then removes it, verifies delete parameter sent to API
• specific VMs by ID — creates with vmid = ["100", "101", "102"], updates to ["100", "200"], verifies import round-trip with list
• retention policy — creates with prune_backups, verifies key sorting round-trip
• data source — creates a job, reads via data source, verifies listing

API Verification (mitmproxy)

Verified all API calls with mitmdump --flow-detail 4. 29 calls, zero errors.

Create (POST /cluster/backup/) — sends only set fields, no empty strings for omitted Optional+Computed fields:

all: '1'
compress: zstd
id: acc-test-bj
mode: snapshot
schedule: '*-*-* 02:00'
storage: local

Update with field deletion (PUT /cluster/backup/{id}) — delete parameter correctly sent:

all: '1'
delete: mailto
schedule: '*-*-* 04:00'
storage: local

Minimal Create — only required + explicitly set fields, no leaking empty strings:

all: '1'
id: acc-test-min
schedule: sun 01:00
storage: local

Community Note

• Please vote on this pull request by adding a 👍 reaction to the original pull request comment to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for pull request followers and do not help prioritize the request

Closes #1815 | Relates #2540

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the Proxmox Terraform provider's capabilities by introducing a new resource and data source for managing cluster-wide backup jobs. It enables users to define and control their Proxmox backup strategies directly through Terraform, covering a wide array of configuration options from basic scheduling to advanced performance and retention settings. The changes also include internal improvements for more robust attribute handling and adherence to project architectural decision records.

Highlights

• New Resource: proxmox_backup_job: Introduced a new Terraform resource for managing Proxmox VE cluster backup jobs, supporting full CRUD operations.
• New Data Source: proxmox_backup_jobs: Added a new data source to retrieve a list of all cluster-wide backup jobs.
• Comprehensive Backup Configuration: The new resource allows detailed configuration of backup jobs, including VM targeting (by ID, pool, or all), scheduling, storage, compression, retention policies (prune_backups), fleecing, and performance tuning.
• Enhanced Attribute Handling: Implemented shared helper functions (StringPtrFromValue, CustomBoolPtrFromValue, Int64PtrFromValue) to safely convert optional and computed fields, preventing empty strings from being sent to the API for unknown values.
• ADR Updates: Updated ADR-004 with a new convention for handling comma-separated API values as Terraform lists and ADR-006 to include functional test coverage requirements.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces the proxmox_backup_job resource and proxmox_backup_jobs data source, providing comprehensive management for Proxmox VE cluster backup jobs. The implementation is robust, effectively handling complex API interactions such as the delete parameter for updates, conversion of list attributes to/from comma-separated strings, and the inconsistent data types for prune-backups through a custom PruneBackupsString type. The new helper functions in fwprovider/attribute/attribute.go correctly manage nil values for optional and computed fields, preventing unwanted API calls and perpetual diffs. Documentation and acceptance tests are well-integrated, ensuring the new features are clear and functional. Overall, this is a high-quality addition that significantly enhances the provider's capabilities.

[bpg-dev]

/gemini review again

[gemini-code-assist]

Code Review

This pull request introduces a well-implemented proxmox_backup_job resource and proxmox_backup_jobs data source. The code is robust, handling API inconsistencies gracefully, and is accompanied by thorough acceptance tests. I've only found a few minor opportunities to improve the documentation for clarity and consistency.