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

docs/data-sources/backup_jobs.md

@@ -0,0 +1,47 @@
+---
+layout: page
+title: proxmox_backup_jobs
+parent: Data Sources
+subcategory: Virtual Environment
+description: |-
+  Retrieves the list of cluster-wide backup jobs.
+---
+
+# Data Source: proxmox_backup_jobs
+
+Retrieves the list of cluster-wide backup jobs.
+
+## Example Usage
+
+```terraform
+data "proxmox_backup_jobs" "all" {}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `id` (String) Unique identifier for this data source.
+- `jobs` (Attributes List) List of backup jobs. (see [below for nested schema](#nestedatt--jobs))
+
+<a id="nestedatt--jobs"></a>
+### Nested Schema for `jobs`
+
+Read-Only:
+
+- `all` (Boolean) Indicates whether all VMs and CTs are backed up.
+- `compress` (String) Compression algorithm used for the backup.
+- `enabled` (Boolean) Indicates whether the backup job is enabled.
+- `id` (String) Unique identifier of the backup job.
+- `mailnotification` (String) When to send email notifications (always or failure).
+- `mailto` (String) Comma-separated list of email addresses for notifications.
+- `mode` (String) Backup mode (e.g. snapshot, suspend, stop).
+- `node` (String) Node on which the backup job runs.
+- `notes_template` (String) Template for backup notes.
+- `pool` (String) Pool whose members are backed up.
+- `protected` (Boolean) Indicates whether backups created by this job are protected from pruning.
+- `prune_backups` (String) Prune options in the format `keep-last=N,...`.
+- `schedule` (String) Backup schedule in systemd calendar format.
+- `storage` (String) Target storage for the backup.
+- `vmid` (List of String) List of VM/CT IDs included in the backup job.

docs/resources/backup_job.md

@@ -0,0 +1,91 @@
+---
+layout: page
+title: proxmox_backup_job
+parent: Resources
+subcategory: Virtual Environment
+description: |-
+  Manages a Proxmox VE cluster backup job.
+---
+
+# Resource: proxmox_backup_job
+
+Manages a Proxmox VE cluster backup job.
+
+## Example Usage
+
+```terraform
+resource "proxmox_backup_job" "daily_backup" {
+  id       = "daily-backup"
+  schedule = "*-*-* 02:00"
+  storage  = "local"
+  all      = true
+  mode     = "snapshot"
+  compress = "zstd"
+}
+```
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Required
+
+- `id` (String) The identifier of the backup job.
+- `schedule` (String) Backup schedule in cron format or systemd calendar event.
+- `storage` (String) The storage identifier for the backup.
+
+### Optional
+
+- `all` (Boolean) Whether to back up all known guests on the node.
+- `bwlimit` (Number) I/O bandwidth limit in KiB/s.
+- `compress` (String) The compression algorithm (0, gzip, lzo, or zstd).
+- `enabled` (Boolean) Whether the backup job is enabled.
+- `exclude_path` (List of String) A list of paths to exclude from the backup.
+- `fleecing` (Attributes) Fleecing configuration for the backup job. (see [below for nested schema](#nestedatt--fleecing))
+- `ionice` (Number) I/O priority (0-8).
+- `lockwait` (Number) Maximum wait time in minutes for the global lock.
+- `mailnotification` (String) Email notification setting (always or failure).
+- `mailto` (String) A comma-separated list of email addresses to send notifications to.
+- `maxfiles` (Number) Deprecated: use prune_backups instead. Maximum number of backup files per guest.
+- `mode` (String) The backup mode (snapshot, suspend, or stop).
+- `node` (String) The cluster node name to limit the backup job to.
+- `notes_template` (String) Template for notes attached to the backup.
+- `pbs_change_detection_mode` (String) PBS change detection mode (legacy, data, or metadata).
+- `performance` (Attributes) Performance-related settings for the backup job. (see [below for nested schema](#nestedatt--performance))
+- `pigz` (Number) Number of pigz threads (0 disables, 1 uses single-threaded gzip).
+- `pool` (String) Limit backup to guests in the specified pool.
+- `protected` (Boolean) Whether the backup should be marked as protected.
+- `prune_backups` (String) Retention options as a comma-separated list of key=value pairs (e.g. keep-last=3,keep-weekly=2).
+- `remove` (Boolean) Whether to remove old backups if there are more than maxfiles.
+- `repeat_missed` (Boolean) Whether to repeat missed backup jobs as soon as possible.
+- `script` (String) Path to a script to execute before/after the backup job.
+- `starttime` (String) The scheduled start time (HH:MM).
+- `stdexcludes` (Boolean) Whether to exclude common temporary files from the backup.
+- `stopwait` (Number) Maximum wait time in minutes for a guest to stop.
+- `tmpdir` (String) Path to the temporary directory for the backup job.
+- `vmid` (List of String) A list of guest VM/CT IDs to include in the backup job.
+- `zstd` (Number) Number of zstd threads (0 uses half of available cores).
+
+<a id="nestedatt--fleecing"></a>
+### Nested Schema for `fleecing`
+
+Optional:
+
+- `enabled` (Boolean) Whether fleecing is enabled.
+- `storage` (String) The storage identifier for fleecing.
+
+
+<a id="nestedatt--performance"></a>
+### Nested Schema for `performance`
+
+Optional:
+
+- `max_workers` (Number) Maximum number of workers for parallel backup.
+- `pbs_entries_max` (Number) Maximum number of entries for PBS catalog.
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+terraform import proxmox_backup_job.daily_backup daily-backup
+```

examples/data-sources/proxmox_backup_jobs/data-source.tf

@@ -0,0 +1 @@
+data "proxmox_backup_jobs" "all" {}

examples/resources/proxmox_backup_job/import.sh

@@ -0,0 +1 @@
+terraform import proxmox_backup_job.daily_backup daily-backup

examples/resources/proxmox_backup_job/resource.tf

@@ -0,0 +1,8 @@
+resource "proxmox_backup_job" "daily_backup" {
+  id       = "daily-backup"
+  schedule = "*-*-* 02:00"
+  storage  = "local"
+  all      = true
+  mode     = "snapshot"
+  compress = "zstd"
+}

fwprovider/attribute/attribute.go

@@ -11,8 +11,10 @@ import (
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/planmodifier"
 	"github.com/hashicorp/terraform-plugin-framework/resource/schema/stringplanmodifier"
+	"github.com/hashicorp/terraform-plugin-framework/types"
 
 	"github.com/bpg/terraform-provider-proxmox/fwprovider/types/stringset"
+	proxmoxtypes "github.com/bpg/terraform-provider-proxmox/proxmox/types"
 )
 
 // ResourceID generates an attribute definition suitable for the always-present resource `id` attribute.
@@ -42,6 +44,35 @@ func IsDefined(v attr.Value) bool {
 	return !v.IsNull() && !v.IsUnknown()
 }
 
+// StringPtrFromValue returns a *string from a types.String, returning nil for null or unknown values.
+// Use this instead of ValueStringPointer() when the field is Optional+Computed without a Default,
+// because ValueStringPointer() returns &"" for unknown values which sends empty strings to the API.
+func StringPtrFromValue(v types.String) *string {
+	if v.IsNull() || v.IsUnknown() {
+		return nil
+	}
+
+	return v.ValueStringPointer()
+}
+
+// CustomBoolPtrFromValue returns a *CustomBool from a types.Bool, returning nil for null or unknown values.
+func CustomBoolPtrFromValue(v types.Bool) *proxmoxtypes.CustomBool {
+	if v.IsNull() || v.IsUnknown() {
+		return nil
+	}
+
+	return proxmoxtypes.CustomBoolPtr(v.ValueBoolPointer())
+}
+
+// Int64PtrFromValue returns a *int64 from a types.Int64, returning nil for null or unknown values.
+func Int64PtrFromValue(v types.Int64) *int64 {
+	if v.IsNull() || v.IsUnknown() {
+		return nil
+	}
+
+	return v.ValueInt64Pointer()
+}
+
 // CheckDelete adds an API field name to the delete list if the plan field is null but the state field is not null.
 // This is used to handle attribute deletion in API calls.
 func CheckDelete(planField, stateField attr.Value, toDelete *[]string, apiName string) {

fwprovider/cluster/backup/datasource.go

@@ -0,0 +1,178 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+package backup
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/hashicorp/terraform-plugin-framework/datasource"
+	"github.com/hashicorp/terraform-plugin-framework/datasource/schema"
+	"github.com/hashicorp/terraform-plugin-framework/types"
+
+	"github.com/bpg/terraform-provider-proxmox/fwprovider/config"
+	"github.com/bpg/terraform-provider-proxmox/proxmox/cluster/backup"
+)
+
+// Ensure the implementation satisfies the expected interfaces.
+var (
+	_ datasource.DataSource              = &backupJobsDataSource{}
+	_ datasource.DataSourceWithConfigure = &backupJobsDataSource{}
+)
+
+type backupJobsDataSource struct {
+	client *backup.Client
+}
+
+// backupJobsDataSourceModel is the top-level model for the backup jobs data source.
+type backupJobsDataSourceModel struct {
+	ID   types.String               `tfsdk:"id"`
+	Jobs []backupJobDatasourceModel `tfsdk:"jobs"`
+}
+
+// NewDataSource creates a new backup jobs data source.
+func NewDataSource() datasource.DataSource {
+	return &backupJobsDataSource{}
+}
+
+func (d *backupJobsDataSource) Metadata(
+	_ context.Context,
+	_ datasource.MetadataRequest,
+	resp *datasource.MetadataResponse,
+) {
+	resp.TypeName = "proxmox_backup_jobs"
+}
+
+func (d *backupJobsDataSource) Configure(
+	_ context.Context,
+	req datasource.ConfigureRequest,
+	resp *datasource.ConfigureResponse,
+) {
+	if req.ProviderData == nil {
+		return
+	}
+
+	cfg, ok := req.ProviderData.(config.DataSource)
+	if !ok {
+		resp.Diagnostics.AddError(
+			"Unexpected DataSource Configure Type",
+			fmt.Sprintf("Expected config.DataSource, got: %T", req.ProviderData),
+		)
+
+		return
+	}
+
+	d.client = cfg.Client.Cluster().Backup()
+}
+
+func (d *backupJobsDataSource) Schema(
+	_ context.Context,
+	_ datasource.SchemaRequest,
+	resp *datasource.SchemaResponse,
+) {
+	resp.Schema = schema.Schema{
+		Description: "Retrieves the list of cluster-wide backup jobs.",
+		Attributes: map[string]schema.Attribute{
+			"id": schema.StringAttribute{
+				Description: "Unique identifier for this data source.",
+				Computed:    true,
+			},
+			"jobs": schema.ListNestedAttribute{
+				Description: "List of backup jobs.",
+				Computed:    true,
+				NestedObject: schema.NestedAttributeObject{
+					Attributes: map[string]schema.Attribute{
+						"id": schema.StringAttribute{
+							Description: "Unique identifier of the backup job.",
+							Computed:    true,
+						},
+						"schedule": schema.StringAttribute{
+							Description: "Backup schedule in systemd calendar format.",
+							Computed:    true,
+						},
+						"storage": schema.StringAttribute{
+							Description: "Target storage for the backup.",
+							Computed:    true,
+						},
+						"enabled": schema.BoolAttribute{
+							Description: "Indicates whether the backup job is enabled.",
+							Computed:    true,
+						},
+						"node": schema.StringAttribute{
+							Description: "Node on which the backup job runs.",
+							Computed:    true,
+						},
+						"vmid": schema.ListAttribute{
+							Description: "List of VM/CT IDs included in the backup job.",
+							Computed:    true,
+							ElementType: types.StringType,
+						},
+						"all": schema.BoolAttribute{
+							Description: "Indicates whether all VMs and CTs are backed up.",
+							Computed:    true,
+						},
+						"mode": schema.StringAttribute{
+							Description: "Backup mode (e.g. snapshot, suspend, stop).",
+							Computed:    true,
+						},
+						"compress": schema.StringAttribute{
+							Description: "Compression algorithm used for the backup.",
+							Computed:    true,
+						},
+						"mailto": schema.StringAttribute{
+							Description: "Comma-separated list of email addresses for notifications.",
+							Computed:    true,
+						},
+						"mailnotification": schema.StringAttribute{
+							Description: "When to send email notifications (always or failure).",
+							Computed:    true,
+						},
+						"notes_template": schema.StringAttribute{
+							Description: "Template for backup notes.",
+							Computed:    true,
+						},
+						"pool": schema.StringAttribute{
+							Description: "Pool whose members are backed up.",
+							Computed:    true,
+						},
+						"prune_backups": schema.StringAttribute{
+							Description: "Prune options in the format `keep-last=N,...`.",
+							Computed:    true,
+						},
+						"protected": schema.BoolAttribute{
+							Description: "Indicates whether backups created by this job are protected from pruning.",
+							Computed:    true,
+						},
+					},
+				},
+			},
+		},
+	}
+}
+
+func (d *backupJobsDataSource) Read(
+	ctx context.Context,
+	_ datasource.ReadRequest,
+	resp *datasource.ReadResponse,
+) {
+	jobs, err := d.client.List(ctx)
+	if err != nil {
+		resp.Diagnostics.AddError("Unable to Read Backup Jobs", err.Error())
+		return
+	}
+
+	var state backupJobsDataSourceModel
+
+	state.ID = types.StringValue("backup_jobs")
+	state.Jobs = make([]backupJobDatasourceModel, len(jobs))
+
+	for i, job := range jobs {
+		state.Jobs[i].fromAPI(job)
+	}
+
+	resp.Diagnostics.Append(resp.State.Set(ctx, &state)...)
+}