Proxmox Provider

https://registry.terraform.io/providers/bpg/proxmox/latest/docs
Admin
This provider for Terraform / OpenTofu is used for interacting with resources supported by Proxmox...
Tokens:5,218
Snippets:68
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Configure Proxmox Provider with SSH Private Key (Heredoc)

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Alternatively, provide the private key directly as a string using heredoc syntax. This method is not recommended due to security risks.

```terraform
provider "proxmox" {
  // ...

  ssh {
    agent       = false
    private_key = <<-EOF
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtzc2gtZW
    <SKIPPED>
    DMUWUEaH7yMCKl7uCZ9xAAAAAAECAwQF
    -----END OPENSSH PRIVATE KEY-----
    EOF
  }
}
```

--------------------------------

### Test SSH Connection and Sudo

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Verify SSH connectivity and password-less sudo access to a Proxmox node. Ensure the user can execute necessary commands.

```bash
ssh terraform@<target-node> sudo pvesm apiinfo 
```

--------------------------------

### Create API Token for User in Proxmox

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This command generates an API token for a specified user. The '--privsep=0' flag is used here. Remember to copy the token secret as it won't be shown again.

```bash
pveum user token add terraform@pve provider --privsep=0
```

--------------------------------

### Create New System User

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Command to create a new system user on a Proxmox host. This user will be used for SSH connections.

```bash
useradd -m terraform
```

--------------------------------

### Configure Sudo Privileges for User

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Configure sudo privileges for a user, allowing specific commands without a password. Essential for provider operations.

```bash
visudo -f /etc/sudoers.d/terraform
```

```bash
terraform ALL=(root) NOPASSWD: /usr/sbin/pvesm
terraform ALL=(root) NOPASSWD: /usr/sbin/qm
terraform ALL=(root) NOPASSWD: /usr/bin/tee /var/lib/vz/snippets/[a-zA-Z0-9_][a-zA-Z0-9_.-]*
```

```bash
terraform ALL=(root) NOPASSWD: /usr/bin/sed -i * /etc/pve/lxc/*.conf
terraform ALL=(root) NOPASSWD: /usr/bin/tee -a /etc/pve/lxc/*.conf
```

```bash
terraform ALL=(root) NOPASSWD: /usr/bin/tee /mnt/pve/cephfs/snippets/[a-zA-Z0-9_][a-zA-Z0-9_.-]*
```

--------------------------------

### Create a User on Proxmox Server

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This command creates a new user for Proxmox VE. Replace 'terraform' with your desired username.

```bash
pveum user add terraform@pve
```

--------------------------------

### Create a Custom Role on Proxmox Server

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This command creates a custom role with specified privileges. Adjust the privileges list according to your security needs. Note that privileges may differ in PVE 9.0 and later.

```bash
pveum role add Terraform -privs "Realm.AllocateUser, VM.PowerMgmt, VM.GuestAgent.Unrestricted, Sys.Console, Sys.Audit, Sys.AccessNetwork, VM.Config.Cloudinit, VM.Replicate, Pool.Allocate, SDN.Audit, Realm.Allocate, SDN.Use, Mapping.Modify, VM.Config.Memory, VM.GuestAgent.FileSystemMgmt, VM.Allocate, SDN.Allocate, VM.Console, VM.Clone, VM.Backup, Datastore.AllocateTemplate, VM.Snapshot, VM.Config.Network, Sys.Incoming, Sys.Modify, VM.Snapshot.Rollback, VM.Config.Disk, Datastore.Allocate, VM.Config.CPU, VM.Config.CDROM, Group.Allocate, Datastore.Audit, VM.Migrate, VM.GuestAgent.FileWrite, Mapping.Use, Datastore.AllocateSpace, Sys.Syslog, VM.Config.Options, Pool.Audit, User.Modify, VM.Config.HWType, VM.Audit, Sys.PowerMgmt, VM.GuestAgent.Audit, Mapping.Audit, VM.GuestAgent.FileRead, Permissions.Modify"
```

--------------------------------

### Configure Proxmox Provider (Minimal)

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This is a minimal configuration for the Proxmox provider, suitable for use cases that do not require SSH access. Ensure your Proxmox VE endpoint, username, and password (or token) are correctly set. It's recommended to use environment variables or Terraform variables for sensitive information like passwords.

```terraform
provider "proxmox" {
  endpoint = "https://10.0.0.2:8006/"

  # TODO: use terraform variable or remove the line, and use PROXMOX_VE_USERNAME environment variable
  username = "root@pam"
  # TODO: use terraform variable or remove the line, and use PROXMOX_VE_PASSWORD environment variable
  password = "the-password-set-during-installation-of-proxmox-ve"
}
```

--------------------------------

### Configure Proxmox Provider with SSH Private Key

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Use this configuration when an SSH agent is not available. Provide the path to the unencrypted PEM-formatted private key file.

```terraform
provider "proxmox" {
  // ...
  ssh {
    agent       = false
    private_key = file("~/.ssh/id_rsa")
  }
}
```

--------------------------------

### Configure Provider SSH SOCKS5 Proxy

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Enable SSH connections through a SOCKS5 proxy. Requires the proxy server's address and optional credentials.

```hcl
provider "proxmox" {
  // ...
  ssh {
    // ...
    socks5_server     = "ip-or-fqdn-of-socks5-server:port"
    socks5_username   = "username"  # optional  
    socks5_password   = "password"  # optional
  }
}
```

--------------------------------

### Configure Proxmox Provider with API Token

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Use this configuration to authenticate with the Proxmox API using an existing API token. Ensure the endpoint and api_token are correctly set.

```terraform
provider "proxmox" {
  endpoint  = "https://10.0.0.2:8006/"
  api_token = "user@realm!tokenid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

--------------------------------

### Configure Proxmox Provider with SSH Agent and API Token

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This configuration uses an API token for authentication and enables SSH agent forwarding. The 'insecure = true' option disables SSL certificate verification, use with caution.

```terraform
provider "proxmox" {
  endpoint  = var.virtual_environment_endpoint
  api_token = "terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  insecure  = true
  ssh {
    agent    = true
    username = "terraform"
  }
}
```

--------------------------------

### Proxmox Provider with Environment Variables

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Configure the Proxmox provider endpoint and authenticate using environment variables for username and password. This avoids hard-coding sensitive information.

```terraform
provider "proxmox" {
  endpoint = "https://10.0.0.2:8006/"
}
```

```shell
export PROXMOX_VE_USERNAME="username@realm"
export PROXMOX_VE_PASSWORD='a-strong-password'
terraform plan
```

--------------------------------

### Generate Proxmox Auth Ticket and CSRF Token with Bash

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This script uses curl and jq to query the Proxmox API for an authentication ticket and CSRF prevention token. It handles cases requiring Two-Factor Authentication (TFA) by making a second API call with the TOTP password. The obtained tokens are then exported as environment variables for Terraform.

```bash
#!/usr/bin/bash

## assume vars are set: PROXMOX_VE_ENDPOINT, PROXMOX_VE_USERNAME, PROXMOX_VE_PASSWORD
## end-goal: automatically set PROXMOX_VE_AUTH_TICKET and PROXMOX_VE_CSRF_PREVENTION_TOKEN

_user_totp_password='123456' ## optional TOTP password


proxmox_api_ticket_path='api2/json/access/ticket' ## cannot have double "//" - ensure endpoint ends with a "/" and this string does not begin with a "/", or vice-versa

## call the auth api endpoint
resp=$( curl -q -s -k --data-urlencode "username=${PROXMOX_VE_USERNAME}"  --data-urlencode "password=${PROXMOX_VE_PASSWORD}"  "${PROXMOX_VE_ENDPOINT}${proxmox_api_ticket_path}" )
auth_ticket=$( jq -r '.data.ticket' <<<"${resp}" )
resp_csrf=$( jq -r '.data.CSRFPreventionToken' <<<"${resp}" )

## check if the response payload needs a TFA (totp) passed, call the auth-api endpoint again
if [[ $(jq -r '.data.NeedTFA' <<<"${resp}") == 1 ]]; then
  resp=$( curl -q -s -k  -H "CSRFPreventionToken: ${resp_csrf}" --data-urlencode  "username=${PROXMOX_VE_USERNAME}" --data-urlencode "tfa-challenge=${auth_ticket}" --data-urlencode "password=totp:${_user_totp_password}"  "${PROXMOX_VE_ENDPOINT}${proxmox_api_ticket_path}" )
  auth_ticket=$( jq -r '.data.ticket' <<<"${resp}" )
  resp_csrf=$( jq -r '.data.CSRFPreventionToken' <<<"${resp}" )
fi


export PROXMOX_VE_AUTH_TICKET="${auth_ticket}"
export PROXMOX_VE_CSRF_PREVENTION_TOKEN="${resp_csrf}"

terraform plan

```

--------------------------------

### Proxmox Provider with API Token Authentication

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Use API token authentication for the Proxmox provider, recommended for production and CI/CD environments. Ensure the token is correctly formatted.

```terraform
provider "proxmox" {
  endpoint  = "https://10.0.0.2:8006/"
  api_token = "terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

--------------------------------

### Configure Provider SSH Node Override

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Specify custom IP addresses or FQDNs for SSH connections to specific Proxmox nodes. Overrides automatic IP resolution.

```hcl
provider "proxmox" {
  // ...
  ssh {
    // ...
    node {
      name    = "pve1"
      address = "192.168.10.1"
    }
    node {
      name    = "pve2"
      address = "192.168.10.2"
    }
  }
}
```

--------------------------------

### Proxmox Provider with Username/Password Authentication

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Configure the Proxmox provider using username and password, suitable for development and testing. Avoid hard-coding credentials in production.

```terraform
provider "proxmox" {
  endpoint = "https://10.0.0.2:8006/"
  insecure = true
  username = "username@realm"
  password = "a-strong-password"
}
```

--------------------------------

### Configure Proxmox Provider with SSH Agent

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Use this configuration when SSH agent forwarding is available. The provider will attempt to use the SSH agent for authentication.

```terraform
provider "proxmox" {
  endpoint = "https://10.0.0.2:8006/"
  username = "username@realm"
  password = "a-strong-password"
  insecure = true

  ssh {
    agent = true
  }
}
```

--------------------------------

### Configure Proxmox Provider Endpoint

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Specifies the Proxmox VE endpoint for the provider. Ensure the endpoint URL is correctly formatted.

```hcl
provider "proxmox" {
  endpoint = "https://10.0.0.2:8006/"
}
```

--------------------------------

### Proxmox Provider with Terraform Variables

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Configure the Proxmox provider referencing endpoint and authentication details via Terraform variables. This promotes better security and flexibility.

```terraform
provider "proxmox" {
  endpoint = var.virtual_environment_endpoint

  # Choose one authentication method:
  api_token = var.virtual_environment_api_token
  # OR
  username  = var.virtual_environment_username
  password  = var.virtual_environment_password
  # OR
  auth_ticket           = var.virtual_environment_auth_ticket
  csrf_prevention_token = var.virtual_environment_csrf_prevention_token
}
```

--------------------------------

### Assign Role to User in Proxmox

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

This command assigns a previously created role to a user for a specific path. Here, it grants the 'Terraform' role to 'terraform@pve' for the root path '/'.

```bash
pveum aclmod / -user terraform@pve -role Terraform
```

--------------------------------

### Proxmox Provider with SSH Access

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Configure the Proxmox provider with SSH access enabled. This is useful for snippets or certain file uploads that require SSH connectivity.

```terraform
provider "proxmox" {
  endpoint = "https://10.0.0.2:8006/"
  username = "root@pam"
  password = "the-password-set-during-installation-of-proxmox-ve"
  insecure = true

  ssh {
    agent = true
    # username = "root"  # required when using api_token
  }
}
```

--------------------------------

### Proxmox Provider with Auth Ticket Authentication

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Utilize auth ticket authentication for the Proxmox provider, useful for automated scripts with TOTP support. Ensure both auth_ticket and csrf_prevention_token are provided.

```terraform
provider "proxmox" {
  endpoint              = "https://10.0.0.2:8006/"
  auth_ticket          = "PVE:username@realm:12345678::some_base64_payload=="
  csrf_prevention_token = "12345678:some_blob"
}
```

--------------------------------

### Configure Proxmox Provider with SSH User Override

Source: https://registry.terraform.io/providers/bpg/proxmox/latest/docs

Override the default SSH username for the connection. This is useful when the SSH username differs from the Proxmox API username.

```terraform
provider "proxmox" {
  // ...

  ssh {
    agent    = true
    username = "terraform"
  }
}
```
Tokens:
Raw