From 08ea66a4e0e1c92851c5811bacde075d169fb1cc Mon Sep 17 00:00:00 2001 From: Pavel Boldyrev <627562+bpg@users.noreply.github.com> Date: Sun, 17 Aug 2025 21:15:47 -0400 Subject: [PATCH] feat(docs): update compatibility notes for PVE 9.x (#2116) - Update primary support from Proxmox VE 8.x to 9.x - Change privilege examples from VM.Monitor to VM.GuestAgent.Audit (VM.Monitor removed in PVE 9.x) - Add backward compatibility notes for 8.x users - Update production requirements and examples Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com> --- README.md | 15 ++++++++++---- docs/index.md | 20 ++++++++++--------- docs/resources/virtual_environment_acl.md | 2 +- docs/resources/virtual_environment_role.md | 2 +- docs/resources/virtual_environment_user.md | 2 +- example/resource_virtual_environment_role.tf | 2 +- .../resource.tf | 2 +- 7 files changed, 27 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 5366ecdd..f7e84cc1 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,10 @@ The project is not affiliated with [Proxmox Server Solutions GmbH](https://www.p ## Compatibility Promise -This provider is compatible with Proxmox VE 8.x (currently **8.4**). +This provider is compatible with Proxmox VE 9.x (currently **9.0**). See [Known Issues](#known-issues) below for compatibility details. > [!IMPORTANT] +> Proxmox VE 8.x is supported, but some functionality might be limited or not work as expected. Testing against 8.x is not a priority, and issues specific to 8.x will not be addressed. > Proxmox VE 7.x is NOT supported. While some features might work with 7.x, we do not test against it, and issues specific to 7.x will not be addressed. While the provider is on version 0.x, it is not guaranteed to be backward compatible with all previous minor versions. @@ -31,7 +32,7 @@ However, we will try to maintain backward compatibility between provider version ### Production Requirements -- [Proxmox Virtual Environment](https://www.proxmox.com/en/proxmox-virtual-environment/) 8.x +- [Proxmox Virtual Environment](https://www.proxmox.com/en/proxmox-virtual-environment/) 9.x - TLS 1.3 for the Proxmox API endpoint (legacy TLS 1.2 is optionally supported) - [Terraform](https://www.terraform.io/downloads.html) 1.5+ or [OpenTofu](https://opentofu.org) 1.6+ @@ -77,7 +78,7 @@ The following assumptions are made about the test environment: Create `example/terraform.tfvars` with the following variables: ```sh -virtual_environment_endpoint = "https://pve.example.doc:8006/" +virtual_environment_endpoint = "https://pve.example.com:8006/" virtual_environment_ssh_username = "terraform" virtual_environment_api_token = "root@pam!terraform=00000000-0000-0000-0000-000000000000" ``` @@ -93,6 +94,12 @@ Work has started to migrate the provider to the new [Terraform Plugin Framework] ## Known Issues +### Proxmox VE 9.0 + +Proxmox VE 9.0 has a new API for managing HA resources, which is not yet supported by the provider, see [#2097](https://github.com/bpg/terraform-provider-proxmox/issues/2097) for more details. + +`apt_*` resources / datasources do not support the new deb822 style format. + ### HA VMs / containers If a VM or container resource is created with the provider but managed by an HA cluster, it might be migrated to a different node without the provider being aware of the change. @@ -110,7 +117,7 @@ Add the following block to your VM config: } ``` -For more context, see #1639 and #1770. +For more context, see issues #1639 and #1770. ### Disk Images from VMware Cannot Be Uploaded or Imported diff --git a/docs/index.md b/docs/index.md index 0694cacd..a9482315 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,24 +12,26 @@ Use the navigation to the left to read about the available resources. ## Table of Contents -- [Environment Variables Summary](#environment-variables-summary) -- [Example Usage](#example-usage) -- [Authentication](#authentication) +- [Proxmox Provider](#proxmox-provider) + - [Table of Contents](#table-of-contents) + - [Environment Variables Summary](#environment-variables-summary) + - [Example Usage](#example-usage) + - [Authentication](#authentication) - [Authentication Methods Comparison](#authentication-methods-comparison) - [Static Credentials Examples](#static-credentials-examples) - [Security Best Practices](#security-best-practices) - [Environment variables](#environment-variables) - [API Token Authentication](#api-token-authentication) - [Pre-Authentication, or Passing an Authentication Ticket into the provider](#pre-authentication-or-passing-an-authentication-ticket-into-the-provider) -- [SSH Connection](#ssh-connection) + - [SSH Connection](#ssh-connection) - [SSH Agent](#ssh-agent) - [SSH Private Key](#ssh-private-key) - [SSH User](#ssh-user) - [Node IP address used for SSH connection](#node-ip-address-used-for-ssh-connection) - [SSH Connection via SOCKS5 Proxy](#ssh-connection-via-socks5-proxy) -- [VM and Container ID Assignment](#vm-and-container-id-assignment) -- [Temporary Directory](#temporary-directory) -- [Argument Reference](#argument-reference) + - [VM and Container ID Assignment](#vm-and-container-id-assignment) + - [Temporary Directory](#temporary-directory) + - [Argument Reference](#argument-reference) ## Environment Variables Summary @@ -205,10 +207,10 @@ You can create an API Token for a user via the Proxmox UI, or via the command li - Create a role for the user (you can skip this step if you want to use any of the existing roles): ```sh - sudo pveum role add Terraform -privs "Mapping.Audit Mapping.Modify Mapping.Use Permissions.Modify Pool.Allocate Pool.Audit Realm.AllocateUser Realm.Allocate SDN.Allocate SDN.Audit Sys.Audit Sys.Console Sys.Incoming Sys.Modify Sys.AccessNetwork Sys.PowerMgmt Sys.Syslog User.Modify Group.Allocate SDN.Use VM.Allocate VM.Audit VM.Backup VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Console VM.Migrate VM.Monitor VM.PowerMgmt VM.Snapshot.Rollback VM.Snapshot Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit" + sudo 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" ``` - ~> The list of privileges above is only an example, please review it and adjust to your needs. + ~> The list of available privileges has been changed in PVE 9.0, and the above list is only an example (and most likely too excessive for most use cases), please review it and adjust to your needs. Refer to the [privileges documentation](https://pve.proxmox.com/pve-docs/pveum.1.html#_privileges) for more details. - Assign the role to the previously created user: diff --git a/docs/resources/virtual_environment_acl.md b/docs/resources/virtual_environment_acl.md index 48893272..d12236c3 100644 --- a/docs/resources/virtual_environment_acl.md +++ b/docs/resources/virtual_environment_acl.md @@ -29,7 +29,7 @@ resource "proxmox_virtual_environment_role" "operations_monitoring" { role_id = "operations-monitoring" privileges = [ - "VM.Monitor", + "VM.GuestAgent.Audit", ] } diff --git a/docs/resources/virtual_environment_role.md b/docs/resources/virtual_environment_role.md index fed2dcb2..88452912 100644 --- a/docs/resources/virtual_environment_role.md +++ b/docs/resources/virtual_environment_role.md @@ -16,7 +16,7 @@ resource "proxmox_virtual_environment_role" "operations_monitoring" { role_id = "operations-monitoring" privileges = [ - "VM.Monitor", + "VM.GuestAgent.Audit", ] } ``` diff --git a/docs/resources/virtual_environment_user.md b/docs/resources/virtual_environment_user.md index ac3885b9..5c9f9503 100644 --- a/docs/resources/virtual_environment_user.md +++ b/docs/resources/virtual_environment_user.md @@ -28,7 +28,7 @@ resource "proxmox_virtual_environment_role" "operations_monitoring" { role_id = "operations-monitoring" privileges = [ - "VM.Monitor", + "VM.GuestAgent.Audit", ] } ``` diff --git a/example/resource_virtual_environment_role.tf b/example/resource_virtual_environment_role.tf index 01a2cb3f..abfb6432 100644 --- a/example/resource_virtual_environment_role.tf +++ b/example/resource_virtual_environment_role.tf @@ -1,6 +1,6 @@ resource "proxmox_virtual_environment_role" "example" { privileges = [ - "VM.Monitor", + "VM.GuestAgent.Audit", ] role_id = "terraform-provider-proxmox-example" } diff --git a/examples/resources/proxmox_virtual_environment_acl/resource.tf b/examples/resources/proxmox_virtual_environment_acl/resource.tf index 5e87049e..66c0b041 100644 --- a/examples/resources/proxmox_virtual_environment_acl/resource.tf +++ b/examples/resources/proxmox_virtual_environment_acl/resource.tf @@ -8,7 +8,7 @@ resource "proxmox_virtual_environment_role" "operations_monitoring" { role_id = "operations-monitoring" privileges = [ - "VM.Monitor", + "VM.GuestAgent.Audit", ] }