mirrors/terraform-provider-proxmox
0
0
Fork 0
mirror of https://github.com/bpg/terraform-provider-proxmox.git synced 2025-08-22 19:38:35 +00:00
Code

chore(docs): reorganize API token auth section (#1761)

Browse Source 
* chore(docs): reorganize API token auth section

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

* docs: enhance authentication documentation

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>

---------

Signed-off-by: Pavel Boldyrev <627562+bpg@users.noreply.github.com>
This commit is contained in:
Pavel Boldyrev 2025-02-12 22:22:45 -05:00 committed by GitHub
parent a5251d119a
commit 4057d13715
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 134 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

205
docs/index.md
View File

@ -15,7 +15,11 @@ Use the navigation to the left to read about the available resources.
- [Environment Variables Summary](#environment-variables-summary) - [Environment Variables Summary](#environment-variables-summary)
- [Example Usage](#example-usage) - [Example Usage](#example-usage)
- [Authentication](#authentication) - [Authentication](#authentication)
- [Authentication Methods Comparison](#authentication-methods-comparison)
- [Static Credentials Examples](#static-credentials-examples)
- [Security Best Practices](#security-best-practices)
- [Environment variables](#environment-variables) - [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) - [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 Agent](#ssh-agent)
@ -23,7 +27,6 @@ Use the navigation to the left to read about the available resources.
- [SSH User](#ssh-user) - [SSH User](#ssh-user)
- [Node IP address used for SSH connection](#node-ip-address-used-for-ssh-connection) - [Node IP address used for SSH connection](#node-ip-address-used-for-ssh-connection)
- [SSH Connection via SOCKS5 Proxy](#ssh-connection-via-socks5-proxy) - [SSH Connection via SOCKS5 Proxy](#ssh-connection-via-socks5-proxy)
- [API Token Authentication](#api-token-authentication)
- [VM and Container ID Assignment](#vm-and-container-id-assignment) - [VM and Container ID Assignment](#vm-and-container-id-assignment)
- [Temporary Directory](#temporary-directory) - [Temporary Directory](#temporary-directory)
- [Argument Reference](#argument-reference) - [Argument Reference](#argument-reference)
@ -75,37 +78,98 @@ provider "proxmox" {
The Proxmox provider offers a flexible means of providing credentials for authentication. The Proxmox provider offers a flexible means of providing credentials for authentication.
Static credentials and pre-authenticated session-ticket can be provided to the `proxmox` block through one the choices of arguments below, ordered by precedence: Static credentials and pre-authenticated session-ticket can be provided to the `proxmox` block through one the choices of arguments below, ordered by precedence:
- `auth_ticket` and `csrf_prevention_token`
- `api_token` - `api_token`
- `auth_ticket` and `csrf_prevention_token`
- `username` and `password` - `username` and `password`
!> Hard-coding credentials into any Terraform configuration is not recommended, and risks secret leakage should this file ever be committed to a public version control system. !> Hard-coding credentials into any Terraform configuration is not recommended, and risks secret leakage should this file ever be committed to a public version control system.
Static credentials can be provided in-line in the Proxmox provider block, by adding one of the arguments above (example with username and password): ### Authentication Methods Comparison
| Method | Use Case | Pros | Cons | Security Level |
|------------------------------------------------------------------------------------------|----------------------|-------------------------------------------------------------------|-------------------------------------------------------------------|----------------|
| [API Token](#api-token-authentication) | Production, CI/CD | - No password needed<br>- Fine-grained permissions<br>- Revocable | - Some operations not supported<br>- Requires SSH username config | High |
| [Auth Ticket](#pre-authentication-or-passing-an-authentication-ticket-into-the-provider) | Automated scripts | - Short-lived<br>- No password storage<br>- TOTP support | - More complex setup<br>- Needs periodic renewal | High |
| Username/Password | Development, Testing | - Full API support<br>- Simple setup | - Password in config/env<br>- Not revocable individually | Medium |
### Static Credentials Examples
Credentials can be provided in-line in the Proxmox provider block. Here are examples for each authentication method:
**API Token (Recommended for Production):**
```hcl
provider "proxmox" {
endpoint = "https://10.0.0.2:8006/"
api_token = "terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```
**Username/Password (Development/Testing):**
```hcl ```hcl
provider "proxmox" { provider "proxmox" {
endpoint = "https://10.0.0.2:8006/" endpoint = "https://10.0.0.2:8006/"
insecure = true
username = "username@realm" username = "username@realm"
password = "a-strong-password" password = "a-strong-password"
} }
``` ```
**Auth Ticket (Automated Scripts):**
```hcl
provider "proxmox" {
endpoint = "https://10.0.0.2:8006/"
auth_ticket = "PVE:username@realm:12345678::some_base64_payload=="
csrf_prevention_token = "12345678:some_blob"
}
```
A better approach is to extract these values into Terraform variables, and reference the variables instead: A better approach is to extract these values into Terraform variables, and reference the variables instead:
```hcl ```hcl
provider "proxmox" { provider "proxmox" {
endpoint = var.virtual_environment_endpoint endpoint = var.virtual_environment_endpoint
username = var.virtual_environment_username # Choose one authentication method:
password = var.virtual_environment_password 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
} }
``` ```
The variable values can be provided via a separate `.tfvars` file that should be gitignored. The variable values can be provided via a separate `.tfvars` file that should be gitignored.
See the [Terraform documentation](https://www.terraform.io/docs/configuration/variables.html) for more information. See the [Terraform documentation](https://www.terraform.io/docs/configuration/variables.html) for more information.
### Security Best Practices
1. **API Token Usage:**
- Use API tokens in production environments
- Create tokens with minimal required permissions
- Rotate tokens periodically
2. **Password Authentication:**
- Limit to development/testing environments
- Never commit passwords to version control
- Use strong passwords
- Change passwords regularly
3. **Auth Ticket:**
- Implement proper token renewal mechanism
- Store tickets securely
- Use TOTP when available
4. **General:**
- Use HTTPS with valid certificates
- Only set `insecure = true` in development
- Use separate credentials for different environments
- Implement proper secret rotation
### Environment variables ### Environment variables
Instead of using static arguments, credentials can be handled through the use of environment variables. Instead of using static arguments, credentials can be handled through the use of environment variables.
@ -125,9 +189,70 @@ terraform plan
See the [Argument Reference](#argument-reference) section for the supported variable names and use cases. See the [Argument Reference](#argument-reference) section for the supported variable names and use cases.
### API Token Authentication
API Token authentication can be used to authenticate with the Proxmox API without the need to provide a password.
In combination with the `ssh` block and `ssh-agent` support, this allows for a fully password-less authentication.
You can create an API Token for a user via the Proxmox UI, or via the command line on the Proxmox host or cluster:
- Create a user:
```sh
sudo pveum user add terraform@pve
```
- 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 "Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Pool.Allocate Sys.Audit Sys.Console Sys.Modify SDN.Use VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.Cloudinit VM.Config.CPU VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Migrate VM.Monitor VM.PowerMgmt User.Modify"
```
~> The list of privileges above is only an example, 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:
```sh
sudo pveum aclmod / -user terraform@pve -role Terraform
```
- Create an API token for the user:
```sh
sudo pveum user token add terraform@pve provider --privsep=0
```
Refer to the upstream docs as needed for additional details concerning [PVE User Management](https://pve.proxmox.com/wiki/User_Management).
Generating the token will output a table containing the token's ID and secret which are meant to be concatenated into a single string for use with either the `api_token` field of the `provider` block (fine for testing but should be avoided) or sourced from the `PROXMOX_VE_API_TOKEN` environment variable.
```hcl
provider "proxmox" {
endpoint = var.virtual_environment_endpoint
api_token = "terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
insecure = true
ssh {
agent = true
username = "terraform"
}
}
```
-> The token authentication is taking precedence over the password authentication.
-> Not all Proxmox API operations are supported via API Token.
You may see errors like
`error creating container: received an HTTP 403 response - Reason: Permission check failed (changing feature flags for privileged container is only allowed for root@pam)` or
`error creating VM: received an HTTP 500 response - Reason: only root can set 'arch' config` or
`Permission check failed (user != root@pam)` when using API Token authentication, even when `Administrator` role or the `root@pam` user is used with the token.
The workaround is to use password authentication for those operations.
-> You can also configure additional Proxmox users and roles using [`virtual_environment_user`](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/data-sources/virtual_environment_user) and [`virtual_environment_role`](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/data-sources/virtual_environment_role) resources of the provider.
### Pre-Authentication, or Passing an Authentication Ticket into the provider ### Pre-Authentication, or Passing an Authentication Ticket into the provider
It is possible to generate a session ticket with the API, and to pass the ticket and csrf_prevention_token into the provider using environment variables `PROXMOX_VE_AUTH_TICKET` and `PROXMOX_VE_CSRF_PREVENTION_TOKEN` (or provider's arguments `auth_ticket` and `csrf_prevention_token`). It is possible to generate a session ticket with the API, and to pass the ticket and csrf_prevention_token into the provider using environment variables `PROXMOX_VE_AUTH_TICKET` and `PROXMOX_VE_CSRF_PREVENTION_TOKEN` (or provider's arguments `auth_ticket` and `csrf_prevention_token`). See more details in the [Proxmox Wiki](https://pve.proxmox.com/wiki/Proxmox_VE_API#Ticket_Cookie).
An example of using `curl` and `jq` to query the Proxmox API to get a Proxmox session ticket; it is also very easy to pass in a TOTP password this way: An example of using `curl` and `jq` to query the Proxmox API to get a Proxmox session ticket; it is also very easy to pass in a TOTP password this way:
@ -364,67 +489,6 @@ provider "proxmox" {
If enabled, this method will be used for all SSH connections to the target nodes in the cluster. If enabled, this method will be used for all SSH connections to the target nodes in the cluster.
## API Token Authentication
API Token authentication can be used to authenticate with the Proxmox API without the need to provide a password.
In combination with the `ssh` block and `ssh-agent` support, this allows for a fully password-less authentication.
You can create an API Token for a user via the Proxmox UI, or via the command line on the Proxmox host or cluster:
- Create a user:
```sh
sudo pveum user add terraform@pve
```
- 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 "Datastore.Allocate Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit Pool.Allocate Sys.Audit Sys.Console Sys.Modify SDN.Use VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.Cloudinit VM.Config.CPU VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Migrate VM.Monitor VM.PowerMgmt User.Modify"
```
~> The list of privileges above is only an example, 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:
```sh
sudo pveum aclmod / -user terraform@pve -role Terraform
```
- Create an API token for the user:
```sh
sudo pveum user token add terraform@pve provider --privsep=0
```
Refer to the upstream docs as needed for additional details concerning [PVE User Management](https://pve.proxmox.com/wiki/User_Management).
Generating the token will output a table containing the token's ID and secret which are meant to be concatenated into a single string for use with either the `api_token` field of the `provider` block (fine for testing but should be avoided) or sourced from the `PROXMOX_VE_API_TOKEN` environment variable.
```hcl
provider "proxmox" {
endpoint = var.virtual_environment_endpoint
api_token = "terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
insecure = true
ssh {
agent = true
username = "terraform"
}
}
```
-> The token authentication is taking precedence over the password authentication.
-> Not all Proxmox API operations are supported via API Token.
You may see errors like
`error creating container: received an HTTP 403 response - Reason: Permission check failed (changing feature flags for privileged container is only allowed for root@pam)` or
`error creating VM: received an HTTP 500 response - Reason: only root can set 'arch' config` or
`Permission check failed (user != root@pam)` when using API Token authentication, even when `Administrator` role or the `root@pam` user is used with the token.
The workaround is to use password authentication for those operations.
-> You can also configure additional Proxmox users and roles using [`virtual_environment_user`](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/data-sources/virtual_environment_user) and [`virtual_environment_role`](https://registry.terraform.io/providers/bpg/proxmox/latest/docs/data-sources/virtual_environment_role) resources of the provider.
## VM and Container ID Assignment ## VM and Container ID Assignment
When creating VMs and Containers, you can specify the optional `vm_id` attribute to set the ID of the VM or Container. However, the ID is a mandatory attribute in the Proxmox API and must be unique within the cluster. If the `vm_id` attribute is not specified, the provider will generate a unique ID and assign it to the resource. When creating VMs and Containers, you can specify the optional `vm_id` attribute to set the ID of the VM or Container. However, the ID is a mandatory attribute in the Proxmox API and must be unique within the cluster. If the `vm_id` attribute is not specified, the provider will generate a unique ID and assign it to the resource.
@ -439,8 +503,7 @@ Using `proxmox_virtual_environment_file` with `.iso` files or disk images can re
Consider pointing `tmp_dir` to a directory with enough space, especially if the default temporary directory is limited by the system memory (e.g. `tmpfs` mounted on `/tmp`). Consider pointing `tmp_dir` to a directory with enough space, especially if the default temporary directory is limited by the system memory (e.g. `tmpfs` mounted on `/tmp`).
A better approach is to use `proxmox_virtual_environment_download_file` resource to A better approach is to use `proxmox_virtual_environment_download_file` resource to download the file directly to the target node, without buffering to the local machine.
download the file directly to the target node, without buffering to the local machine.
## Argument Reference ## Argument Reference