Proposal: Add proxmox_domain_realm module

[PendaGTP]

SUMMARY

Add a new module to manage PVE authentication realms.

I'm currently implementing this module and would like to get feedback before opening a PR. I also have several design questions (see below).

Current implementation proposal

A generic module named proxmox_domain_realm to manage all realm types (ad, ldap, openid, ...).

Module documentation:

module: proxmox_domain_realm
short_description: Management of authentication realms for Proxmox VE cluster
description:
  - Create, update or delete Proxmox VE authentication realms.
author:
  - Clément Cruau (@PendaGTP)
version_added: "1.6.0"
attributes:
  check_mode:
    support: full
  diff_mode:
    support: none
options:
  realm:
    description:
      - The realm name.
    type: str
    aliases: ["name"]
    required: true
  state:
    description:
      - Desired state of the realm.
    choices: ["present", "absent"]
    default: present
    type: str
  type:
    description:
      - The realm type.
      - Only required when O(state=present).
    type: str
    choices: ["ad", "ldap", "openid", "pam", "pve"]
  options:
    description:
      - Realm configuration options.
      - See U(https://pve.proxmox.com/wiki/Manual:_datacenter.cfg) and L(Authentication Realms,https://pve.proxmox.com/pve-docs/chapter-pveum.html).
      - The entire value is masked in logs.
    type: dict

seealso:
  - module: community.proxmox.proxmox_domain_info
    description: Retrieve information about Proxmox VE authentication realms.

extends_documentation_fragment:
  - community.proxmox.proxmox.actiongroup_proxmox
  - community.proxmox.proxmox.documentation
  - community.proxmox.attributes

Examples:

- name: Update the comment on the pam realm
  community.proxmox.proxmox_domain_realm:
    api_host: node1
    api_user: root@pam
    api_password: password
    realm: pam
    type: pam
    options:
      comment: Updated PAM authentication comment

- name: Create a new Proxmox VE openid realm
  community.proxmox.proxmox_domain_realm:
    api_host: node1
    api_user: root@pam
    api_password: password
    realm: openid
    type: openid
    options:
      comment: OpenID authentication
      client-id: 1234567890
      client-key: 1234567890
      issuer-url: https://example.com/issuer

- name: Delete a Proxmox VE openid realm
  community.proxmox.proxmox_domain_realm:
    api_host: node1
    api_user: root@pam
    api_password: password
    realm: openid
    state: absent

Full implementation draft

Design Questions

Handling realm options, with options param:

Currently:

• options is a simple dict
• No pre-validation is performed
• The entire options dict is marked with no_log=True

Questions:

• Is masking the entire options dict acceptable?
• Should all possible realm parameters be explicitly defined as module options instead of using a generic dict?

What are your thoughts? Any feedback or suggestions are welcome. If preferred, I can open a draft PR with the current implementation.

ISSUE TYPE

• Feature Idea

[teslamania31]

Hello @PendaGTP ,

I think it's a great idea to add a module for managing realms! However, I’m a little bit confused because I was also working on something similar. Here’s a link to my progress: https://github.com/teslamania31/community.proxmox/blob/8fab6c1400f247c508a3010086c08c7d94b51566/plugins/modules/proxmox_domain.py I haven’t created a PR yet, as it’s not finished. And I still need to write the unit tests (which are quite time-consuming 😅).

I took a different approach than the options dict, where I added several parameters (not all, some are deprecated or not visible in the UI). I used the required_if logic to link the required parameters to their respective types.

I’ve tested the module with a real LDAP server (I have a FreeIPA setup), but I haven’t tested it on AD or OpenID yet.

I didn’t implement PVE or PAM because there’s limited functionality with those at the moment. Additionally, I added a state sync feature so that we can run a sync with LDAP or AD. This way, we could create a playbook that adds the realm, syncs it to create users/groups, and then uses the proxmox_access_acl module to assign roles to groups.

I’m not sure how to proceed from here. Should we try to merge our work, or would it be better for one of us to continue? Feel free to use any of the work I’ve done so far if that helps. What are your thoughts on the next steps?

[PendaGTP]

Hi @teslamania,

Thanks you for your message and for sharing your work, that’s actually great timing and that's the goal of my issue -> discuss implementation, etc with the community.

To be honest, I’m not entirely sure what the best way forward is either as I mentioned on the issue. We took two quite different approaches and at this stage, I’m not sure which implementation is objectively “better”.

At this time, personally, I tend to prefer keeping options as a free dict where the user can pass whatever parameters they need. My reasoning is:

• It keeps the module flexible as new realm parameters are added/updates/removed in PVE.
• The code remains smaller and (in my opinion) easier to maintain long-term.
• We avoid duplicating validation logic that is already handled by the Proxmox API.

Regarding the sync feature: I’m not fully convinced that state=sync belongs in the same module as realm management. Conceptually, creating/updating a realm and triggering a sync feel like two different responsibilities.

I would lean toward creating a dedicated module just for LDAP/AD sync, for example:

- name: Sync LDAP
  community.proxmox.proxmox_domain_ldap_sync:
    api_host: node1
    api_user: root@pam
    api_password: password
    realm: ldap
    sync: true            # optional, default true
    enable_new: true      # optional
    remove_vanished:      # optional
    scope: users          # optional

This way:

• proxmox_domain_realm is responsible only for managing the realm definition.
• A dedicated module handles synchronization logic.
• It could also be used cleanly as a handler (e.g. triggered when proxmox_domain_realm changes).
• Responsibilities stay clearly separated.

That said, I don’t think one of us should “continue alone”. It would be much better to merge ideas with other Contributors and Maintainers. I’m open to merging efforts.

Maybe a good next step would be:

• Agree on the overall design philosophy (generic options vs explicit parameters).
• Decide whether sync should be integrated or split into a dedicated module.
• Then consolidate both implementations into one PR

What do you think? Be free to ping other maintainers/owners/... to get more throughts, idk exactly which ones ping.

@IamLunchbox
@Thulium-Drake

[teslamania31]

Hi @PendaGTP,
Thank you for your reply.

The more I think about the generic dict approach, the more I tend to prefer explicit parameters instead. While I understand and agree that a generic dictionary would offer greater flexibility, I still believe the module should expose a clearly defined list of supported parameters, along with proper documentation.

This is especially important for LDAP or AD configurations. These setups are not always straightforward; they can be time-consuming and sometimes frustrating to get right. In that context, having well-documented parameters, detailed descriptions, and complete usage examples would provide significant value. Simply linking to the Proxmox documentation, while helpful, is not sufficient in my opinion. It does not necessarily clarify the exact parameter names, accepted values, or valid combinations from an Ansible perspective.

Another benefit of explicit parameters is that it helps prevent the use of deprecated options. It also aligns, in my view, with the overall philosophy of the collection. If you look at modules like proxmox_node_network or proxmox_node_disk, they expose many explicit parameters rather than relying on a generic options dictionary.

Regarding the no_log option applied to the entire dictionary, I am not convinced this is ideal either.

Concerning the sync feature: I see proxmox_domain as a module designed to manage realms. Managing a realm typically involves four actions: create, delete, update, and sync. I do not quite understand why the sync operation should live in a separate module. We do not separate creation and deletion into different modules, so it seems reasonable to me that sync could be handled within the same one. It can also be used from a handler — I have tested this and it works as expected :

tasks:
  - name: Add ldap domain
  community.proxmox.proxmox_domain:
    api_host: 192.168.1.21
    api_user: "root@pam"
    api_password: secret
    base_dn: "cn=accounts,dc=example,dc=test"
    bind_dn: "uid=sa-proxmox,cn=users,cn=accounts,dc=example,dc=test"
    default: True
    filter: "memberof=cn=admins-proxmox,cn=groups,cn=accounts,dc=example,dc=test"
    group_filter: "cn=admins-proxmox"
    group_name_attr: "cn"
    mode: "ldaps"
    password: XXXXX
    realm: "ipa.example.test"
    server1: "ipa.example.test"
    state: present
    type: "ldap"
    user_attr: "uid"
    verify: False
    sync_defaults_options:
      scope: "both"
      enable_new: True
      remove_vanished: "acl;properties;entry"
    notify:
      - Sync ldap domain

  handlers:
    - name: Sync ldap domain
      community.proxmox.proxmox_domain:
        api_host: 192.168.1.21
        api_user: "root@pam"
        api_password: secret
        realm: "ipa.example.test"
        state: sync

That said, these are just my thoughts. I would also be very interested in hearing the opinion of others on this topic. I do not who else to ping. @Thulium-Drake, @IamLunchbox

[Thulium-Drake]

Hi all,

Nice work on both ends, it's a tough semantic discussion and sometimes it's mostly style instead of functionally better. I'm on the fence a bit. Both options have merit, on the one hand I agree with having explicit options defined, as it makes it easier for users to input the (complex) configurations needed.

On the other hand, I don't think it would help us to have all of the API validation logic duplicated in the modules, especially because there can be some time between it changing and us having time to adapt to those changes. Which would favor generic dictionaries.

With regards to sync built-in or in a separate module, I'm favoring separate modules, as sync actions don't have a state, whereas the other CRUD actions do. They also do this in the awx.awx collection for projects (read Git repos that are configured in AWX). Yes the way you have it configured works, but the interface for stateful and stateless actions is now the same.

It's loosely related to the custom in the broader Ansible community to have modules that make changes community.example.stuff and those that read it into a variable community.example.stuff_info.

Finally, the no_log, the only information processed by this module that should be a secret is either the password or other authentication keys. So I think those values should be marked as secrets (I don't know how on top of my head), and the rest of the info should be fine to be reported in logs. This should also make diff mode simpler to use (we'll need to document that we cannot diff passwords)

[IamLunchbox]

Strict vs loose options

While many options may seem daunting, I think this could be a good way to go. Maybe this could be handled by splitting up the possible realms (ldap, openid,ad or openid|ldap/ad) into different modules and sharing the overlapping code through module_utils.

But I don't strictly oppose the loose dictionary.

Stateful vs stateless actions

I think I'd prefer a separate module. Otherwise, if users want to configure and sync it either breaks idempotence, because syncing is (probably?) always setting the state to changed, or they would need to run the same plugin twice, once for config and once for syncing.

And triggering a sync is probably way faster than the comparision and required api calls to ensure idempotence.

No log

Generally no_log is a flag for the module argument spec secret=dict(type="string",no_log=True), for example. When using a loose dict we would keep all entered options hidden, if we strictly define the possible options we can narrow it down - which IMHO would lead to a better user experience.

[PendaGTP]

Thanks for sharing yours throughts.

To summarize our discussion, I think we have a path that is beginning to take shape:

• Create a new modules e.g. proxmox_realm and proxmox_realm_ldap_sync
• Use explicit options with "basic" validation and let the API to do specific validation logic
• Set on_log on the field password (nb: currently secret-key used by openid is returned by the API and I think it's ok to follow same behavior)

Note : Perhaps we can still discuss the names of the modules, proxmox_realm and proxmox_realm_ldap_sync lgtm, any throughts?

@Thulium-Drake @IamLunchbox @teslamania31 Is this summarize looks ok to you?

@teslamania31 If you would like to work on it, that's perfectly fine, it's up to you, I'm happy either way :-)

[teslamania31]

Thanks everyone for your comments, I really appreciate the feedback!

I agree with your summary. If that’s okay with you, I’d be happy to continue working on this — I’m already quite advanced on the module.

Regarding the naming: there is already a module called proxmox_domain_info that retrieves information about realms. For consistency, it might make sense to name these proxmox_domain and proxmox_domain_sync (the sync one being for Active Directory and LDAP).

That said, I personally find proxmox_realm and proxmox_realm_sync clearer.

Is that possible to change the proxmox_domain_info in proxmox_realm_info ?

Happy to align with whatever naming convention you prefer 🙂

[Thulium-Drake]

Those names do match the module we already have in the collection, so that sounds fine to me! And to top it off, it's also called Realms in the Proxmox UI, so it also maps perfectly to the name of the functionality ;-)

[PendaGTP]

Thanks @teslamania31 🚀