microsoft.ad.gpo module – Manage Group Policy Object links

Note

This module is part of the microsoft.ad collection (version 1.12.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 microsoft.ad.

To use it in a playbook, specify: microsoft.ad.gpo.

New in microsoft.ad 1.12.0

Synopsis

• Create, modify, or remove a Group Policy Object (GPO) link on a target container such as an OU, domain, or site.

• Uses the GroupPolicy PowerShell module cmdlets New-GPLink, Set-GPLink, Remove-GPLink, and Get-GPInheritance.

Parameters

Parameter	Comments
domain_server string	The FQDN of the domain controller to target for all operations. When not specified, the module uses the default domain controller discovery.
enabled boolean	Whether the GPO link is enabled. When not specified during creation, the link defaults to enabled. Choices: false true
enforced boolean	Whether the GPO link is enforced (No Override). When not specified during creation, the link defaults to not enforced. Choices: false true
guid string	The GUID of the GPO to link. Mutually exclusive with name. One of name or guid must be provided.
name string	The display name of the GPO to link. Mutually exclusive with guid. One of name or guid must be provided.
order integer	The link order (1-based) for the GPO on the target container. Lower numbers have higher precedence.
state string	Whether the GPO link should be present or absent on the target. Choices: "present" ← (default) "absent"
target string / required	The distinguished name of the container (OU, domain, or site) to which the GPO should be linked. Example: OU=Servers,DC=contoso,DC=com.

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: windows	Target OS/families that can be operated against

Notes

Note

• This module must be run on a Windows host with the GroupPolicy PowerShell module installed (available on domain controllers or via RSAT).

• The GPO identified by name or guid must already exist. This module does not create or delete GPOs, only their links.

See Also

See also

microsoft.ad.ou

Manage Active Directory organizational units.

microsoft.ad.object_info

Gather information an Active Directory object.

Examples

- name: Link a GPO to an OU
  microsoft.ad.gpo:
    name: Security_Hardening_Policy
    target: 'OU=Servers,DC=contoso,DC=com'
    state: present

- name: Link a GPO by GUID and enforce it
  microsoft.ad.gpo:
    guid: 5990264b-7000-482d-a2f0-c43eb26aa956
    target: 'OU=Workstations,DC=contoso,DC=com'
    enforced: true
    state: present

- name: Disable a GPO link without removing it
  microsoft.ad.gpo:
    name: Optional_Policy
    target: 'OU=Staging,DC=contoso,DC=com'
    enabled: false
    state: present

- name: Set link order for a GPO
  microsoft.ad.gpo:
    name: Security_Hardening_Policy
    target: 'OU=Servers,DC=contoso,DC=com'
    order: 1
    state: present

- name: Remove a GPO link from an OU
  microsoft.ad.gpo:
    name: Old_Policy
    target: 'OU=Servers,DC=contoso,DC=com'
    state: absent

- name: Link a GPO using a specific domain controller
  microsoft.ad.gpo:
    name: Security_Hardening_Policy
    target: 'OU=Servers,DC=contoso,DC=com'
    domain_server: dc01.contoso.com
    state: present

Authors

• Ron Gershburg (@rgershbu)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication