Skip to content

Commit 61d7d1d

Browse files
bpg-devclaude
bpg-dev
and
claude
committed
feat(access): add short-name aliases for access resources
Add proxmox_acl, proxmox_realm_ldap, proxmox_realm_openid, proxmox_realm_sync, and proxmox_user_token as short-name aliases for the corresponding proxmox_virtual_environment_* resources. Old names emit a deprecation warning pointing to the new name. New names implement MoveState for Terraform moved block support. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Pavel Boldyrev <pavel@bpg.sh>
1 parent b2bb732 commit 61d7d1d

30 files changed

+1006
-57
lines changed

‎docs/resources/acl.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
---
2+
layout: page
3+
title: proxmox_acl
4+
parent: Resources
5+
subcategory: Virtual Environment
6+
description: |-
7+
Manages ACLs on the Proxmox cluster.
8+
ACLs are used to control access to resources in the Proxmox cluster.
9+
Each ACL consists of a path, a user, group or token, a role, and a flag to allow propagation of permissions.
10+
---
11+
12+
# Resource: proxmox_acl
13+
14+
Manages ACLs on the Proxmox cluster.
15+
16+
ACLs are used to control access to resources in the Proxmox cluster.
17+
Each ACL consists of a path, a user, group or token, a role, and a flag to allow propagation of permissions.
18+
19+
20+
21+
<!-- schema generated by tfplugindocs -->
22+
## Schema
23+
24+
### Required
25+
26+
- `path` (String) Access control path
27+
- `role_id` (String) The role to apply
28+
29+
### Optional
30+
31+
- `group_id` (String) The group the ACL should apply to (mutually exclusive with `token_id` and `user_id`)
32+
- `propagate` (Boolean) Allow to propagate (inherit) permissions.
33+
- `token_id` (String) The token the ACL should apply to (mutually exclusive with `group_id` and `user_id`)
34+
- `user_id` (String) The user the ACL should apply to (mutually exclusive with `group_id` and `token_id`)
35+
36+
### Read-Only
37+
38+
- `id` (String) The unique identifier of this resource.

‎docs/resources/realm_ldap.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
---
2+
layout: page
3+
title: proxmox_realm_ldap
4+
parent: Resources
5+
subcategory: Virtual Environment
6+
description: |-
7+
Manages an LDAP authentication realm in Proxmox VE.
8+
LDAP realms allow Proxmox to authenticate users against an LDAP directory service.
9+
---
10+
11+
# Resource: proxmox_realm_ldap
12+
13+
Manages an LDAP authentication realm in Proxmox VE.
14+
15+
LDAP realms allow Proxmox to authenticate users against an LDAP directory service.
16+
17+
## Privileges Required
18+
19+
| Path | Attribute |
20+
|-----------------|----------------|
21+
| /access/domains | Realm.Allocate |
22+
23+
24+
25+
<!-- schema generated by tfplugindocs -->
26+
## Schema
27+
28+
### Required
29+
30+
- `base_dn` (String) LDAP base DN for user searches (e.g., 'ou=users,dc=example,dc=com').
31+
- `realm` (String) Realm identifier (e.g., 'example.com').
32+
- `server1` (String) Primary LDAP server hostname or IP address.
33+
34+
### Optional
35+
36+
- `bind_dn` (String) LDAP bind DN for authentication (e.g., 'cn=admin,dc=example,dc=com').
37+
- `bind_password` (String, Sensitive) Password for the bind DN. Note: stored in Proxmox but not returned by API.
38+
- `ca_path` (String) Path to CA certificate file for SSL verification.
39+
- `case_sensitive` (Boolean) Enable case-sensitive username matching.
40+
- `cert_key_path` (String) Path to client certificate key.
41+
- `cert_path` (String) Path to client certificate for SSL authentication.
42+
- `comment` (String) Description of the realm.
43+
- `default` (Boolean) Use this realm as the default for login.
44+
- `filter` (String) LDAP filter for user searches.
45+
- `group_classes` (String) LDAP objectClasses for groups (comma-separated).
46+
- `group_dn` (String) LDAP base DN for group searches.
47+
- `group_filter` (String) LDAP filter for group searches.
48+
- `group_name_attr` (String) LDAP attribute representing the group name.
49+
- `mode` (String) LDAP connection mode (ldap, ldaps, ldap+starttls).
50+
- `port` (Number) LDAP server port. Default: 389 (LDAP) or 636 (LDAPS).
51+
- `secure` (Boolean, Deprecated) Use LDAPS (LDAP over SSL/TLS) instead of plain LDAP.
52+
- `server2` (String) Fallback LDAP server hostname or IP address.
53+
- `ssl_version` (String) SSL/TLS version (tlsv1, tlsv1_1, tlsv1_2, tlsv1_3).
54+
- `sync_attributes` (String) Comma-separated list of attributes to sync (e.g., 'email=mail,firstname=givenName').
55+
- `sync_defaults_options` (String) Default synchronization options. Format: comma-separated 'key=value' pairs. Valid keys: 'scope' (users/groups/both), 'enable-new' (1/0), 'remove-vanished' (semicolon-separated: entry/acl/properties), 'full' (deprecated), 'purge' (deprecated). Example: 'scope=users,enable-new=1,remove-vanished=entry;acl'.
56+
- `user_attr` (String) LDAP attribute representing the username.
57+
- `user_classes` (String) LDAP objectClasses for users (comma-separated).
58+
- `verify` (Boolean) Verify LDAP server SSL certificate.
59+
60+
### Read-Only
61+
62+
- `id` (String) Realm identifier (same as realm)
63+
64+
## Notes
65+
66+
### Password Security
67+
68+
The `bind_password` is sent to Proxmox and stored securely, but it's never returned by the API. This means:
69+
- Terraform cannot detect if the password was changed outside of Terraform
70+
- You must maintain the password in your Terraform configuration or use a variable
71+
- The password will be marked as sensitive in Terraform state
72+
73+
### LDAP vs LDAPS
74+
75+
- **LDAP (port 389)**: Unencrypted connection. Not recommended for production.
76+
- **LDAPS (port 636)**: Encrypted connection using SSL/TLS. Recommended for production.
77+
- **LDAP+StartTLS**: Upgrades plain LDAP connection to TLS. Alternative to LDAPS.
78+
79+
### User Synchronization
80+
81+
To trigger synchronization, use the `proxmox_realm_sync` resource.
82+
83+
### Common Configuration Scenarios
84+
85+
#### Anonymous Binding
86+
For testing or public LDAP servers, omit `bind_dn` and `bind_password` to use anonymous binding:
87+
```hcl
88+
resource "proxmox_realm_ldap" "anonymous" {
89+
realm = "public-ldap"
90+
server1 = "ldap.example.com"
91+
base_dn = "ou=users,dc=example,dc=com"
92+
user_attr = "uid"
93+
}
94+
```
95+
96+
#### Secure LDAPS with Failover
97+
```hcl
98+
resource "proxmox_realm_ldap" "secure" {
99+
realm = "secure-ldap"
100+
server1 = "ldap1.example.com"
101+
server2 = "ldap2.example.com" # Failover server
102+
port = 636
103+
base_dn = "ou=users,dc=example,dc=com"
104+
bind_dn = "cn=readonly,dc=example,dc=com"
105+
bind_password = var.ldap_password
106+
mode = "ldaps"
107+
verify = true
108+
ca_path = "/etc/pve/priv/ca.crt"
109+
}
110+
```
111+
112+
#### With Group Synchronization
113+
```hcl
114+
resource "proxmox_realm_ldap" "with_groups" {
115+
realm = "corporate-ldap"
116+
server1 = "ldap.corp.example.com"
117+
base_dn = "ou=users,dc=corp,dc=example,dc=com"
118+
bind_dn = "cn=svc_ldap,ou=services,dc=corp,dc=example,dc=com"
119+
bind_password = var.ldap_password
120+
mode = "ldap+starttls"
121+
122+
# Group settings
123+
group_dn = "ou=groups,dc=corp,dc=example,dc=com"
124+
group_filter = "(objectClass=groupOfNames)"
125+
group_name_attr = "cn"
126+
127+
# Sync configuration
128+
sync_attributes = "email=mail,firstname=givenName,lastname=sn"
129+
sync_defaults_options = "scope=both,enable-new=1"
130+
}
131+
```
132+
133+
## See Also
134+
135+
- [Proxmox VE User Management](https://pve.proxmox.com/wiki/User_Management)
136+
- [Proxmox VE LDAP Authentication](https://pve.proxmox.com/wiki/User_Management#pveum_ldap)
137+
- [Proxmox API: /access/domains](https://pve.proxmox.com/pve-docs/api-viewer/index.html#/access/domains)
138+

‎docs/resources/realm_openid.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
layout: page
3+
title: proxmox_realm_openid
4+
parent: Resources
5+
subcategory: Virtual Environment
6+
description: |-
7+
Manages an OpenID Connect authentication realm in Proxmox VE.
8+
OpenID Connect realms allow Proxmox to authenticate users against an external OpenID Connect provider.
9+
---
10+
11+
# Resource: proxmox_realm_openid
12+
13+
Manages an OpenID Connect authentication realm in Proxmox VE.
14+
15+
OpenID Connect realms allow Proxmox to authenticate users against an external OpenID Connect provider.
16+
17+
## Privileges Required
18+
19+
| Path | Attribute |
20+
|-----------------|----------------|
21+
| /access/domains | Realm.Allocate |
22+
23+
24+
25+
<!-- schema generated by tfplugindocs -->
26+
## Schema
27+
28+
### Required
29+
30+
- `client_id` (String) OpenID Connect Client ID.
31+
- `issuer_url` (String) OpenID Connect issuer URL. Proxmox uses OpenID Connect Discovery to configure the provider.
32+
- `realm` (String) Realm identifier (e.g., 'my-oidc').
33+
34+
### Optional
35+
36+
- `acr_values` (String) Authentication Context Class Reference values for the OpenID provider.
37+
- `autocreate` (Boolean) Automatically create users on the Proxmox cluster if they do not exist.
38+
- `client_key` (String, Sensitive) OpenID Connect Client Key (secret). Note: stored in Proxmox but not returned by API.
39+
- `comment` (String) Description of the realm.
40+
- `default` (Boolean) Use this realm as the default for login.
41+
- `groups_autocreate` (Boolean) Automatically create groups from claims rather than using existing Proxmox VE groups.
42+
- `groups_claim` (String) OpenID claim used to retrieve user group memberships.
43+
- `groups_overwrite` (Boolean) Replace assigned groups on login instead of appending to existing ones.
44+
- `prompt` (String) Specifies whether the authorization server prompts for reauthentication and/or consent (e.g., 'none', 'login', 'consent', 'select_account').
45+
- `query_userinfo` (Boolean) Query the OpenID userinfo endpoint for claims. Required when the identity provider does not include claims in the ID token.
46+
- `scopes` (String) Space-separated list of OpenID scopes to request.
47+
- `username_claim` (String) OpenID claim used to generate the unique username. Common values are `subject`, `username`, `email`, and `upn`.
48+
49+
### Read-Only
50+
51+
- `id` (String) Realm identifier (same as realm)
52+
53+
## Notes
54+
55+
### Client Key Security
56+
57+
The `client_key` is sent to Proxmox and stored securely, but it's never returned by the API. This means:
58+
59+
- Terraform cannot detect if the client key was changed outside of Terraform
60+
- You must maintain the client key in your Terraform configuration or use a variable
61+
- The client key will be marked as sensitive in Terraform state
62+
63+
### Username Claim
64+
65+
The `username_claim` attribute is **fixed after creation** — it cannot be changed once the realm is created. Changing it requires destroying and recreating the realm. Common values:
66+
67+
- `subject` (default) — Uses the OpenID `sub` claim
68+
- `username` — Uses the `preferred_username` claim
69+
- `email` — Uses the `email` claim
70+
- `upn` — Uses the User Principal Name claim (common with ADFS/Azure AD)
71+
72+
Any valid OpenID claim name can be used. Ensure the chosen claim provides unique, stable identifiers for your users.
73+
74+
### Common Configuration Scenarios
75+
76+
#### Minimal Configuration
77+
78+
```hcl
79+
resource "proxmox_realm_openid" "minimal" {
80+
realm = "my-oidc"
81+
issuer_url = "https://auth.example.com"
82+
client_id = var.oidc_client_id
83+
client_key = var.oidc_client_secret
84+
}
85+
```
86+
87+
#### With User and Group Provisioning
88+
89+
```hcl
90+
resource "proxmox_realm_openid" "full" {
91+
realm = "corporate-oidc"
92+
issuer_url = "https://auth.example.com/realms/my-realm"
93+
client_id = var.oidc_client_id
94+
client_key = var.oidc_client_secret
95+
username_claim = "email"
96+
autocreate = true
97+
98+
# Group synchronization
99+
groups_claim = "groups"
100+
groups_autocreate = true
101+
102+
scopes = "openid email profile"
103+
query_userinfo = true
104+
}
105+
```
106+
107+
## See Also
108+
109+
- [Proxmox VE User Management](https://pve.proxmox.com/wiki/User_Management)
110+
- [Proxmox VE OpenID Connect Authentication](https://pve.proxmox.com/wiki/User_Management#pveum_openid)
111+
- [Proxmox API: /access/domains](https://pve.proxmox.com/pve-docs/api-viewer/index.html#/access/domains)

‎docs/resources/realm_sync.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
layout: page
3+
title: proxmox_realm_sync
4+
parent: Resources
5+
subcategory: Virtual Environment
6+
description: |-
7+
Triggers synchronization of an existing authentication realm using /access/domains/{realm}/sync. This resource represents the last requested sync configuration; deleting it does not undo the sync.
8+
---
9+
10+
# Resource: proxmox_realm_sync
11+
12+
Triggers synchronization of an existing authentication realm using `/access/domains/{realm}/sync`. This resource represents the last requested sync configuration; deleting it does not undo the sync.
13+
14+
This resource wraps the `/access/domains/{realm}/sync` API and is intended to be
15+
used alongside realm configuration resources such as
16+
`proxmox_realm_ldap`.
17+
18+
19+
20+
<!-- schema generated by tfplugindocs -->
21+
## Schema
22+
23+
### Required
24+
25+
- `realm` (String) Name of the realm to synchronize.
26+
27+
### Optional
28+
29+
- `dry_run` (Boolean) Only simulate the sync without applying changes.
30+
- `enable_new` (Boolean) Enable newly synced users.
31+
- `full` (Boolean, Deprecated) Perform a full sync.
32+
- `purge` (Boolean, Deprecated) Purge removed entries.
33+
- `remove_vanished` (String) How to handle vanished entries (e.g. `acl;properties;entry` or `none`).
34+
- `scope` (String) Sync scope: users, groups, or both.
35+
36+
### Read-Only
37+
38+
- `id` (String) Unique sync identifier (same as realm).
39+
40+
## Behavior Notes
41+
42+
- The sync operation is **one-shot**: applying the resource runs the sync
43+
with the specified options. Proxmox does not expose a persistent sync
44+
object, so this resource only records the last requested sync
45+
configuration in Terraform state.
46+
- Destroying the resource does **not** undo any previously performed sync;
47+
it simply removes the resource from Terraform state.
48+

‎docs/resources/user_token.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
layout: page
3+
title: proxmox_user_token
4+
parent: Resources
5+
subcategory: Virtual Environment
6+
description: |-
7+
User API tokens.
8+
---
9+
10+
# Resource: proxmox_user_token
11+
12+
User API tokens.
13+
14+
15+
16+
<!-- schema generated by tfplugindocs -->
17+
## Schema
18+
19+
### Required
20+
21+
- `token_name` (String) User-specific token identifier.
22+
- `user_id` (String) User identifier.
23+
24+
### Optional
25+
26+
- `comment` (String) Comment for the token.
27+
- `expiration_date` (String) Expiration date for the token.
28+
- `privileges_separation` (Boolean) Restrict API token privileges with separate ACLs (default), or give full privileges of corresponding user.
29+
30+
### Read-Only
31+
32+
- `id` (String) Unique token identifier with format `<user_id>!<token_name>`.
33+
- `value` (String, Sensitive) API token value used for authentication. It is populated only when creating a new token, and can't be retrieved at import.

‎docs/resources/virtual_environment_acl.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ description: |-
1111

1212
# Resource: proxmox_virtual_environment_acl
1313

14+
~> **Deprecated:** Use [`proxmox_acl`](acl.md) instead. This resource will be removed in v1.0.
15+
1416
Manages ACLs on the Proxmox cluster.
1517

1618
ACLs are used to control access to resources in the Proxmox cluster.

‎docs/resources/virtual_environment_realm_ldap.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
# Resource: proxmox_virtual_environment_realm_ldap
1212

13+
~> **Deprecated:** Use [`proxmox_realm_ldap`](realm_ldap.md) instead. This resource will be removed in v1.0.
14+
1315
Manages an LDAP authentication realm in Proxmox VE.
1416

1517
LDAP realms allow Proxmox to authenticate users against an LDAP directory service.

‎docs/resources/virtual_environment_realm_openid.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ description: |-
1010

1111
# Resource: proxmox_virtual_environment_realm_openid
1212

13+
~> **Deprecated:** Use [`proxmox_realm_openid`](realm_openid.md) instead. This resource will be removed in v1.0.
14+
1315
Manages an OpenID Connect authentication realm in Proxmox VE.
1416

1517
OpenID Connect realms allow Proxmox to authenticate users against an external OpenID Connect provider.

0 commit comments

Comments
 (0)