DOCSEARCHbyAlgolia
Submit Docs

bpg Proxmox Terraform Provider

repository·main·Indexed 24 days ago

https://github.com/bpg/terraform-provider-proxmox

A Terraform and OpenTofu provider for managing Proxmox Virtual Environment resources, including VMs, containers, and files. It supports Proxmox VE 9.x (recommended) and 8.x, requiring Terraform 1.5+ or OpenTofu 1.6+. Key features include an opt-in management model for cloned VMs via the proxmox_virtual_environment_cloned_vm resource, allowing selective control over network interfaces and disks.

Tokens
195.8K
Snippets
475
Records
884
Agent score
80%

What's inside terraform-provider-proxmox

  1. Manage file uploads with proxmox_download_file

    main

    The proxmox_download_file resource manages file uploads using the Proxmox VE download-url API. It is a faster and fully compatible replacement for proxmox_virtual_environment_file for managing VM images (ISO and disk images) and LXC templates (CT Templates).

    Permissions Required

    In addition to the Datastore.AllocateTemplate privilege, this resource requires:

    • Sys.Audit
    • Sys.Modify

    Enabling 'import' content type

    The import content type is not enabled by default on Proxmox VE storages. To use content_type = "import", you must manually add Import to the allowed content types for the target storage via the Proxmox web interface under Datacenter > Storage.

    resource "proxmox_download_file" "example" {
  content_type       = "iso"
  datastore_id       = "local"
  file_name          = "debian-12-generic-amd64-20231228-1609.img"
  node_name          = "pve"
  url                = "https://cloud.debian.org/images/cloud/bookworm/20231228-1609/debian-12-generic-amd64-20231228-1609.qcow2"
  checksum           = "d2fbcf11fb28795842e91364d8c7b69f1870db09ff299eb94e4fbbfa510eb78d141e74c1f4bf6dfa0b7e33d0c3b66e6751886feadb4e9916f778bab1776bdf1b"
  checksum_algorithm = "sha512"
}

  2. Use proxmox_virtual_environment_storage_directory (Deprecated)

    main

    Manages directory-based storage in Proxmox VE.

    Warning: This resource is deprecated. You should use proxmox_storage_directory instead. This resource is scheduled for removal in v1.0.

    resource "proxmox_virtual_environment_storage_directory" "example" {
  id    = "example-dir"
  path  = "/var/lib/vz"
  nodes = ["pve"]

  content = ["images"]
  shared  = true
  disable = false

  backups {
    max_protected_backups = 5
    keep_daily            = 7
  }
}

  3. Manage ZFS-based storage with proxmox_virtual_environment_storage_zfspool

    main

    The proxmox_virtual_environment_storage_zfspool resource manages ZFS-based storage in Proxmox VE.

    Warning: This resource is deprecated. You should use proxmox_storage_zfspool instead. This resource is scheduled for removal in v1.0.

    resource "proxmox_virtual_environment_storage_zfspool" "example" {
  id    = "example-zfs"
  nodes = ["pve"]

  zfs_pool       = "rpool/data"
  content        = ["images"]
  thin_provision = true
  blocksize      = "64k"
}

  5. Manage High Availability rules with proxmox_harule

    main

    The proxmox_harule resource manages High Availability (HA) rules in a Proxmox VE cluster. This resource is intended for Proxmox VE 9.0 or later, where HA rules have replaced the legacy HA groups. For PVE 8 and earlier, you must use proxmox_hagroup instead.

    HA rules provide two primary capabilities:

    1. Node Affinity: Assigning specific VMs or containers to preferred nodes with defined priorities.
    2. Resource Affinity: Controlling whether specific resources should be kept together on the same node or spread across different nodes for high availability.

  7. Use proxmox_virtual_environment_harule for HA rules (Deprecated)

    main

    The proxmox_virtual_environment_harule resource manages High Availability (HA) rules in Proxmox VE 9.0 or later. These rules replace legacy HA groups and provide node affinity and resource affinity capabilities.

    Warning: This resource is deprecated and will be removed in v1.0. You should migrate to proxmox_harule instead.

    Compatibility Note:

  8. Use proxmox_virtual_environment_storage_lvm for LVM storage

    main

    Manages LVM-based storage in Proxmox VE.

    Note: This resource is deprecated. You should use proxmox_storage_lvm instead. This resource is scheduled for removal in v1.0.

    resource "proxmox_virtual_environment_storage_lvm" "example" {
  id    = "example-lvm"
  nodes = ["pve"]

  volume_group = "vg0"
  content      = ["images"]

  wipe_removed_volumes = false
}

  9. Manage VM and Container ID assignment

    main

    When creating VMs or Containers, you can manually set the vm_id attribute. If omitted, the provider generates a unique ID automatically.

    To minimize ID conflicts in environments where multiple provider instances are running simultaneously, set random_vm_ids = true in the provider "proxmox" block. This causes the provider to generate random IDs and verify their uniqueness via the Proxmox API instead of using sequential IDs.

  10. Manage ACME accounts with proxmox_virtual_environment_acme_account

    main

    The proxmox_virtual_environment_acme_account resource manages an ACME account within a Proxmox VE cluster.

    Warning: This resource is deprecated. You should use proxmox_acme_account instead. This resource is scheduled for removal in v1.0.

    Authentication Requirement: This resource requires root@pam authentication to function correctly.

  11. LDAP Connection Modes and Security

    main

    When configuring LDAP in Proxmox, choose the appropriate connection mode based on your security requirements:

    • LDAP (port 389): Unencrypted connection. Not recommended for production.
    • LDAPS (port 636): Encrypted connection using SSL/TLS. Recommended for production. Set mode = "ldaps".
    • LDAP+StartTLS: Upgrades a plain LDAP connection to TLS. Set mode = "ldap+starttls".

    Password Security Note

    The bind_password is sent to Proxmox and stored securely, but it is never returned by the API. Consequently:

    • Terraform cannot detect if the password was changed outside of Terraform.
    • You must maintain the password in your Terraform configuration or via a variable.
    • The password will be marked as sensitive in your Terraform state.