DOCSEARCHbyAlgolia
Submit Docs

Telmate Terraform Provider for Proxmox

repository·master·Indexed 25 days ago

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

A Terraform provider for the Proxmox virtualization platform that enables the management of QEMU virtual machines and LXC containers. It supports Cloud-Init configuration via automatic settings or custom snippets (cicustom), fine-grained control over VM CPU, boot, and hotplug options, and provides guides for installation and developer debugging.

Tokens
23.6K
Snippets
40
Records
79
Agent score
81%

What's inside terraform-provider-proxmox

  1. Get started with the Proxmox Terraform provider

    master
    The Proxmox Terraform provider allows you to provision QEMU VMs and LXC Containers on the Proxmox virtualization platform. To begin using the provider, refer to the comprehensive documentation located in the docs/ directory of this repository, which includes a full list of provider options and guides for configuring specific VM types.

  2. Enable advanced features in LXC

    master

    You can enable advanced container features using the features block within the proxmox_lxc resource. Supported features include:

    • fuse: Boolean to enable FUSE.
    • nesting: Boolean to enable nesting.
    • mount: A string containing semicolon-separated mount types (e.g., nfs;cifs).
    resource "proxmox_lxc" "advanced_features" {
  target_node  = "pve"
  hostname     = "lxc-advanced-features"
  ostemplate   = "local:vztmpl/ubuntu-20.04-standard_20.04-1_amd64.tar.gz"
  unprivileged = true

  ssh_public_keys = <<-EOT
    ssh-rsa <public_key_1> user@example.com
    ssh-ed25519 <public_key_2> user@example.com
  EOT

  features {
    fuse    = true
    nesting = true
    mount   = "nfs;cifs"
  }

  rootfs {
    storage = "local-zfs"
    size    = "8G"
  }

  mountpoint {
    slot    = "0"
    storage = "/mnt/host/nfs"
    mp      = "/mnt/container/nfs"
    size    = "250G"
  }

  network {
    name   = "eth0"
    bridge = "vmbr0"
    ip     = "10.0.0.2/24"
    ip6    = "auto"
  }
}

  4. Provision a VM through PXE Network Boot

    master

    To enable Network Boot (PXE), set pxe = true. For a successful PXE boot, ensure the following requirements are met:

    • Boot Order: The boot parameter must include a network type in its order (e.g., order=scsi0;net0).
    • Network Interface: A valid NIC must be attached to a network that has access to a PXE boot server.
    • Agent Configuration: Generally, you should disable the agent by setting agent = 0 unless the OS installation specifically includes the agent.

    Note: PXE boot mode requires external infrastructure to support the Network PXE boot request by the VM.

    resource "proxmox_vm_qemu" "pxe-minimal-example" {
    name                      = "pxe-minimal-example"
    agent                     = 0
    boot                      = "order=scsi0;net0"
    pxe                       = true
    target_node               = "test"
    network {
        id = 0
        bridge    = "vmbr0"
        firewall  = false
        link_down = false
        model     = "e1000"
    }
}

  5. Report an issue with the Proxmox provider

    master

    When reporting issues on the issue tracker, follow these steps to ensure your problem can be reproduced quickly:

    1. Provide a minimal reproduction: Create the smallest possible issue.tf file that recreates your problem. You can do this by taking a minimal working example and adding elements from your original Terraform file until the issue reappears.
    2. Include configuration: Attach your provider.tf file. You do not need to include vars.tf files.
    3. Describe the behavior: Clearly state what you are trying to accomplish, your expected outcome, and the actual outcome.
    4. Include errors: Copy and paste any error messages you received.

  6. Import an existing Qemu VM into Terraform

    master

    You can import an existing Proxmox VM into your Terraform state using its node, type, and VM ID. The <type> must always be qemu for VM resources.

    Command Syntax:

    terraform import [options] <RESOURCE_ADDRESS> <node>/qemu/<vmId>

    Example Workflow: To understand how Proxmox GUI settings map to Terraform configuration:

    1. Create a file (e.g., test.tf) with a dummy resource block:
      resource "proxmox_vm_qemu" "import_test" { }
    2. Run the import command (assuming node name is mynode and VM ID is 106):
      terraform import proxmox_vm_qemu.import_test mynode/qemu/106
    3. Inspect the terraform.tfstate file to see the imported configuration attributes.
    terraform import proxmox_vm_qemu.import_test mynode/qemu/106

  8. Manually install the Proxmox provider for Terraform >=0.13

    master

    For Terraform versions 0.13 and later, third-party providers must follow a specific filesystem layout using a virtual source registry (e.g., registry.example.com).

    1. Determine your architecture: Use linux_amd64 for Linux or darwin_amd64 for macOS.
    2. Create the plugin directory: Use the format ~/.terraform.d/plugins/[host.domain]/telmate/proxmox/[version]/[arch].
    3. Copy the executable: Move the built binary from ./bin to the newly created directory.
    4. Configure Terraform: Update your main.tf to use the virtual source address.

    Example using registry.example.com and version 1.0.0 on Linux:

    PLUGIN_ARCH=linux_amd64
mkdir -p ~/.terraform.d/plugins/registry.example.com/telmate/proxmox/1.0.0/${PLUGIN_ARCH}
cp bin/terraform-provider-proxmox ~/.terraform.d/plugins/registry.example.com/telmate/proxmox/1.0.0/${PLUGIN_ARCH}/

    In your main.tf:

    terraform {
  required_providers {
    proxmox = {
      source  = "registry.example.com/telmate/proxmox"
      version = ">=1.0.0"
    }
  }
  required_version = ">= 0.14"
}
    # Example for Linux
PLUGIN_ARCH=linux_amd64
mkdir -p ~/.terraform.d/plugins/registry.example.com/telmate/proxmox/1.0.0/${PLUGIN_ARCH}
cp bin/terraform-provider-proxmox ~/.terraform.d/plugins/registry.example.com/telmate/proxmox/1.0.0/${PLUGIN_ARCH}/

  10. Build the Proxmox provider from source

    master

    To compile the provider executables manually, you must have Go installed.

    1. Clone the repository:
    git clone https://github.com/Telmate/terraform-provider-proxmox
cd terraform-provider-proxmox
    1. Compile the provider using make:
    make

    The resulting executable will be located in the ./bin directory.

    git clone https://github.com/Telmate/terraform-provider-proxmox
cd terraform-provider-proxmox
make

  11. Authenticate with Username and API Token

    master

    To use an API token, set the PM_API_TOKEN_ID and PM_API_TOKEN_SECRET environment variables.

    Note: When setting PM_API_TOKEN_ID in a shell, use single quotes because the token ID contains an exclamation mark (!).

    # use single quotes for the API token ID because of the exclamation mark
export PM_API_TOKEN_ID='terraform-prov@pve!mytoken'
export PM_API_TOKEN_SECRET="afcd8f45-acc1-4d0f-bb12-a70b0777ec11"
    provider "proxmox" {
  pm_api_url = "https://proxmox-server01.example.com:8006/api2/json"
}