community.windows.win_domain_ou – Manage Active Directory Organizational Units

Note

This plugin is part of the community.windows collection (version 1.9.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.windows.

To use it in a playbook, specify: community.windows.win_domain_ou.

New in version 1.8.0: of community.windows

Synopsis

  • Manage Active Directory Organizational Units

  • Adds, Removes and Modifies Active Directory Organizational Units

  • Task should be delegated to a Windows Active Directory Domain Controller

Requirements

The below requirements are needed on the host that executes this module.

  • This module requires Windows Server 2012 or Newer

  • Powershell ActiveDirectory Module

Parameters

Parameter Choices/Defaults Comments
domain_password
string
The password for the domain you are accessing
domain_server
string
Specifies the Active Directory Domain Services instance to connect to.
Can be in the form of an FQDN or NetBIOS name.
If not specified then the value is based on the domain of the computer running PowerShell.
domain_username
string
The username to use when interacting with AD.
If this is not set then the user Ansible used to log in with will be used instead when using CredSSP or Kerberos with credential delegation.
filter
string
Default:
"*"
filter for lookup of ou.
name
string / required
The name of the Organizational Unit
path
string
Specifies the X.500 path of the OU or container where the new object is created.
defaults to adding ou at base of domain connected to.
properties
dictionary
Free form dict of properties for the organizational unit. Follows LDAP property names, like StreetAddress or PostalCode.
protected
boolean
    Choices:
  • no ←
  • yes
Indicates whether to prevent the object from being deleted. When this protected=true, you cannot delete the corresponding object without changing the value of the property.
recursive
boolean
    Choices:
  • no ←
  • yes
Removes the OU and any child items it contains.
You must specify this parameter to remove an OU that is not empty.
state
string
    Choices:
  • present ←
  • absent
Specifies the desired state of the OU.
When state=present the module will attempt to create the specified OU if it does not already exist.
When state=absent, the module will remove the specified OU.
When state=absent and recursive=true, the module will remove all the OU and all child OU's.

Examples

---
- name: Ensure OU is present & protected
  community.windows.win_domain_ou:
    name: AnsibleFest
    state: present

- name: Ensure OU is present & protected
  community.windows.win_domain_ou:
    name: EUC Users
    path: "DC=euc,DC=vmware,DC=lan"
    state: present
    protected: true
  delegate_to: win-ad1.euc.vmware.lab

- name: Ensure OU is absent
  community.windows.win_domain_ou:
    name: EUC Users
    path: "DC=euc,DC=vmware,DC=lan"
    state: absent
  delegate_to: win-ad1.euc.vmware.lab

- name: Ensure OU is present with specific properties
  community.windows.win_domain_ou:
    name: WS1Users
    path: "CN=EUC Users,DC=euc,DC=vmware,DC=lan"
    protected: true
    properties:
      city: Sandy Springs
      state: Georgia
      StreetAddress: 1155 Perimeter Center West
      country: US
      description: EUC Business Unit
      PostalCode: 30189
  delegate_to: win-ad1.euc.vmware.lab

- name: Ensure OU updated with new properties
  community.windows.win_domain_ou:
    name: WS1Users
    path: DC=euc,DC=vmware,DC=lan
    protected: false
    properties:
      city: Atlanta
      state: Georgia
      managedBy: [email protected]
  delegate_to: win-ad1.euc.vmware.lab

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
ou
dictionary
When state=present
New/Updated organizational unit parameters

Sample:
{'AddedProperties': [], 'City': 'Sandy Springs', 'Country': None, 'DistinguishedName': 'OU=VMW Atlanta,DC=ansible,DC=test', 'LinkedGroupPolicyObjects': [], 'ManagedBy': None, 'ModifiedProperties': [], 'Name': 'VMW Atlanta', 'ObjectClass': 'organizationalUnit', 'ObjectGUID': '3e987e30-93ad-4229-8cd0-cff6a91275e4', 'PostalCode': None, 'PropertyCount': 11, 'PropertyNames': 'City Country DistinguishedName LinkedGroupPolicyObjects ManagedBy Name ObjectClass ObjectGUID PostalCode State StreetAddress', 'RemovedProperties': [], 'State': 'Georgia', 'StreetAddress': '1155 Perimeter Center West'}
path
string
always
Base ou path used by module either when provided path=DC=Ansible,DC=Test or derived by module.

Sample:
{'path': 'DC=ansible,DC=test'}


Authors

  • Joe Zollo (@joezollo)

  • Larry Lane (@gamethis)