community.windows.win_domain_ou – Manage Active Directory Organizational Units
Note
This plugin is part of the community.windows collection (version 1.8.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 |
Comments |
---|---|
The password for the domain you are accessing |
|
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. |
|
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 for lookup of ou. Default: “*” |
|
The name of the Organizational Unit |
|
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. |
|
Free form dict of properties for the organizational unit. Follows LDAP property names, like |
|
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. Choices:
|
|
Removes the OU and any child items it contains. You must specify this parameter to remove an OU that is not empty. Choices:
|
|
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. Choices:
|
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 |
Description |
---|---|
New/Updated organizational unit parameters Returned: When state=present Sample: {“AddedProperties”: [], “City”: “Sandy Springs”, “Country”: null, “DistinguishedName”: “OU=VMW Atlanta,DC=ansible,DC=test”, “LinkedGroupPolicyObjects”: [], “ManagedBy”: null, “ModifiedProperties”: [], “Name”: “VMW Atlanta”, “ObjectClass”: “organizationalUnit”, “ObjectGUID”: “3e987e30-93ad-4229-8cd0-cff6a91275e4”, “PostalCode”: null, “PropertyCount”: 11, “PropertyNames”: “City Country DistinguishedName LinkedGroupPolicyObjects ManagedBy Name ObjectClass ObjectGUID PostalCode State StreetAddress”, “RemovedProperties”: [], “State”: “Georgia”, “StreetAddress”: “1155 Perimeter Center West”} |
|
Base ou path used by module either when provided path=DC=Ansible,DC=Test or derived by module. Returned: always Sample: {“path”: “DC=ansible,DC=test”} |
Authors
Joe Zollo (@joezollo)
Larry Lane (@gamethis)