Improved documentation.

Improved validation.
trippsc2 · Jul 9, 2024 · 0ba55c1 · 0ba55c1
1 parent ac55688
commit 0ba55c1
Show file tree

Hide file tree

Showing 19 changed files with 203 additions and 143 deletions.
diff --git a/galaxy.yml b/galaxy.yml
@@ -1,7 +1,7 @@
 ---
 namespace: trippsc2
 name: ad
-version: 1.2.5
+version: 1.2.6
 readme: README.md
 authors:
   - Jim Tarpley

diff --git a/roles/authorize_dhcp_server/README.md b/roles/authorize_dhcp_server/README.md
@@ -1,7 +1,7 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 
 # Ansible Role: trippsc2.ad.authorize_dhcp_server
-Version: 1.2.5
+Version: 1.2.6
 
 This role authorizes a domain member as a DHCP Server in Active Directory.
 

diff --git a/roles/authorize_dhcp_server/tasks/validate.yml b/roles/authorize_dhcp_server/tasks/validate.yml
@@ -1,19 +1,22 @@
 ---
 - name: Gather OS facts
   when:
-    - ansible_distribution is not defined
+    - ansible_distribution is not defined or
+      ansible_os_family is not defined
   ansible.builtin.setup:
     gather_subset:
       - '!all'
       - '!min'
       - distribution
+      - os_family
 
 - name: Validate Windows Server
   ansible.builtin.assert:
     that:
-      - ansible_distribution | regex_search('(Microsoft Windows Server)')
-    fail_msg: This role only supports Windows Server.
-    success_msg: This role supports Windows Server.
+      - ansible_os_family == 'Windows'
+      - ("Windows Server" in ansible_distribution)
+    fail_msg: "This role can only be run on a Windows Server system.  {{ ansible_distribution }} is not supported."
+    success_msg: "This role is running on {{ ansible_distribution }}."
 
 - name: Validate DHCP DNS Name
   loop: "{{ dhcp_authorize_servers }}"

diff --git a/roles/domain_controller/README.md b/roles/domain_controller/README.md
@@ -1,10 +1,18 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 
 # Ansible Role: trippsc2.ad.domain_controller
-Version: 1.2.5
+Version: 1.2.6
 
 This role configures the Windows Server machine as an Active Directory Domain Controller.
 
+The following scenarios are supported:
+- The server is the first domain controller in a new forest.
+- The server is an additional domain controller in an existing domain.
+
+The following scenarios are not supported, but may be added in the future:
+- The server is the first domain controller in a child or tree domain in an existing forest.
+
+
 ## Requirements
 
 | Platform | Versions |
@@ -28,25 +36,27 @@ This role configures the Windows Server machine as an Active Directory Domain Co
 ## Role Arguments
 |Option|Description|Type|Required|Choices|Default|
 |---|---|---|---|---|---|
-| dc_vault_create_mount_point | <p>Whether to create the KV version 2 mount point in HashiCorp Vault for the safe mode password.</p> | bool | no |  | true |
+| vault_url | <p>The URL for accessing HashiCorp Vault.</p><p>Alternatively, this can be configured through ansible.cfg or environment variables.</p> | str | no |  |  |
+| vault_token | <p>The token for accessing HashiCorp Vault.</p><p>Alternatively, this (or any other authentication method) can be configured through ansible.cfg or environment variables.</p> | str | no |  |  |
+| dc_vault_create_mount_point | <p>Whether to create the KV version 2 mount point in HashiCorp Vault for the safe mode password, if it doesn't exist.</p> | bool | no |  | true |
 | dc_vault_managed_safe_mode_password | <p>Whether to manage the safe mode password in HashiCorp Vault.</p> | bool | no |  | true |
-| dc_vault_safe_mode_mount_point | <p>The KV version 2 mount point in HashiCorp Vault for the safe mode password.</p> | str | no |  | os |
-| dc_vault_safe_mode_path | <p>The path within the mount point in HashiCorp Vault for the safe mode password.</p> | str | no |  | {{ inventory_hostname }}/safe_mode |
-| dc_safe_mode_password | <p>The safe mode password for the domain controller.</p><p>If `dc_vault_managed_safe_mode_password` is `true`, this value is ignored.</p> | str | no |  |  |
+| dc_vault_safe_mode_mount_point | <p>The KV version 2 mount point in HashiCorp Vault for storing the safe mode password.</p> | str | no |  | os |
+| dc_vault_safe_mode_path | <p>The path within the KV version 2 mount point in HashiCorp Vault for storing the safe mode password.</p> | str | no |  | {{ inventory_hostname }}/safe_mode |
+| dc_safe_mode_password | <p>The safe mode password for the domain controller.</p><p>If *dc_vault_managed_safe_mode_password* is `true`, this is required.</p><p>If *dc_vault_managed_safe_mode_password* is `false` and the secret is already stored in HashiCorp Vault, this is ignored.</p><p>If *dc_vault_managed_safe_mode_password* is `false` and the secret is not stored in HashiCorp Vault, this password used and stored in HashiCorp Vault.</p> | str | no |  |  |
 | dc_first_domain_controller | <p>Whether the server is the first domain controller in the domain.</p> | bool | no |  | false |
-| dc_domain_name | <p>The name of the domain to which the domain controller will belong.</p> | str | yes |  |  |
-| dc_domain_admin_user | <p>The user account to use for configuring the domain controller.</p> | str | yes |  |  |
-| dc_domain_admin_password | <p>The password for the user account to use for configuring the domain controller.</p> | str | yes |  |  |
+| dc_domain_name | <p>The name of the domain for which the server will serve as domain controller.</p> | str | yes |  |  |
+| dc_domain_admin_user | <p>The user account to use for configuring the domain controller.</p><p>If *dc_first_domain_controller* is `true`, this is ignored.</p><p>Otherwise, this is required and the user account must have the necessary permissions to promote the server to a domain controller.</p> | str | no |  |  |
+| dc_domain_admin_password | <p>The password for the *dc_domain_admin_user* user account.</p> | str | no |  |  |
 | dc_database_path | <p>The path to the database files for the domain controller.</p> | path | no |  | C:\Windows\NTDS |
 | dc_domain_log_path | <p>The path to the log files for the domain controller.</p> | path | no |  | C:\Windows\Logs |
 | dc_sysvol_path | <p>The path to the SYSVOL files for the domain controller.</p> | path | no |  | C:\Windows\SYSVOL |
-| dc_dns_forwarders | <p>A list of DNS forwarders for the domain controller.</p> | list of 'str' | no |  | ["8.8.8.8", "4.2.2.2"] |
-| dc_dns_servers | <p>A list of DNS servers for the domain controller.</p> | list of 'str' | yes |  |  |
-| dc_is_domain_naming_master | <p>Whether the domain controller is the domain naming master.</p> | bool | no |  | false |
-| dc_is_schema_master | <p>Whether the domain controller is the schema master.</p> | bool | no |  | false |
-| dc_is_infrastructure_master | <p>Whether the domain controller is the infrastructure master.</p> | bool | no |  | false |
-| dc_is_pdc_emulator | <p>Whether the domain controller is the PDC emulator.</p> | bool | no |  | false |
-| dc_is_rid_master | <p>Whether the domain controller is the RID master.</p> | bool | no |  | false |
+| dc_dns_forwarders | <p>A list of DNS forwarder IP addresses for the domain controller.</p> | list of 'str' | no |  | ["8.8.8.8", "4.2.2.2"] |
+| dc_dns_servers | <p>A list of DNS server IP addresses for the domain controller.</p> | list of 'str' | yes |  |  |
+| dc_is_domain_naming_master | <p>Whether the domain controller should hold the Domain Naming Master FSMO role.</p> | bool | no |  | false |
+| dc_is_schema_master | <p>Whether the domain controller should hold the Schema Master FSMO role.</p> | bool | no |  | false |
+| dc_is_infrastructure_master | <p>Whether the domain controller should hold the Infrastructure Master FSMO role.</p> | bool | no |  | false |
+| dc_is_pdc_emulator | <p>Whether the domain controller should hold the PDC Emulator FSMO role.</p> | bool | no |  | false |
+| dc_is_rid_master | <p>Whether the domain controller should hold the RID Master FSMO role.</p> | bool | no |  | false |
 
 
 ## License

diff --git a/roles/domain_controller/meta/argument_specs.yml b/roles/domain_controller/meta/argument_specs.yml
@@ -6,12 +6,24 @@ argument_specs:
       - This role configures the Windows Server machine as an Active Directory Domain Controller.
     author: Jim Tarpley
     options:
+      vault_url:
+        type: str
+        required: false
+        description:
+          - The URL for accessing HashiCorp Vault.
+          - Alternatively, this can be configured through ansible.cfg or environment variables.
+      vault_token:
+        type: str
+        required: false
+        description:
+          - The token for accessing HashiCorp Vault.
+          - Alternatively, this (or any other authentication method) can be configured through ansible.cfg or environment variables.
       dc_vault_create_mount_point:
         type: bool
         required: false
         default: true
         description:
-          - Whether to create the KV version 2 mount point in HashiCorp Vault for the safe mode password.
+          - Whether to create the KV version 2 mount point in HashiCorp Vault for the safe mode password, if it doesn't exist.
       dc_vault_managed_safe_mode_password:
         type: bool
         required: false
@@ -23,19 +35,21 @@ argument_specs:
         required: false
         default: os
         description:
-          - The KV version 2 mount point in HashiCorp Vault for the safe mode password.
+          - The KV version 2 mount point in HashiCorp Vault for storing the safe mode password.
       dc_vault_safe_mode_path:
         type: str
         required: false
         default: "{{ inventory_hostname }}/safe_mode"
         description:
-          - The path within the mount point in HashiCorp Vault for the safe mode password.
+          - The path within the KV version 2 mount point in HashiCorp Vault for storing the safe mode password.
       dc_safe_mode_password:
         type: str
         required: false
         description:
           - The safe mode password for the domain controller.
-          - If `dc_vault_managed_safe_mode_password` is `true`, this value is ignored.
+          - If *dc_vault_managed_safe_mode_password* is `true`, this is required.
+          - If *dc_vault_managed_safe_mode_password* is `false` and the secret is already stored in HashiCorp Vault, this is ignored.
+          - If *dc_vault_managed_safe_mode_password* is `false` and the secret is not stored in HashiCorp Vault, this password used and stored in HashiCorp Vault.
       dc_first_domain_controller:
         type: bool
         required: false
@@ -46,17 +60,19 @@ argument_specs:
         type: str
         required: true
         description:
-          - The name of the domain to which the domain controller will belong.
+          - The name of the domain for which the server will serve as domain controller.
       dc_domain_admin_user:
         type: str
-        required: true
+        required: false
         description:
           - The user account to use for configuring the domain controller.
+          - If *dc_first_domain_controller* is `true`, this is ignored.
+          - Otherwise, this is required and the user account must have the necessary permissions to promote the server to a domain controller.
       dc_domain_admin_password:
         type: str
-        required: true
+        required: false
         description:
-          - The password for the user account to use for configuring the domain controller.
+          - The password for the *dc_domain_admin_user* user account.
       dc_database_path:
         type: path
         required: false
@@ -83,40 +99,40 @@ argument_specs:
           - '4.2.2.2'
         elements: str
         description:
-          - A list of DNS forwarders for the domain controller.
+          - A list of DNS forwarder IP addresses for the domain controller.
       dc_dns_servers:
         type: list
         required: true
         elements: str
         description:
-          - A list of DNS servers for the domain controller.
+          - A list of DNS server IP addresses for the domain controller.
       dc_is_domain_naming_master:
         type: bool
         required: false
         default: false
         description:
-          - Whether the domain controller is the domain naming master.
+          - Whether the domain controller should hold the Domain Naming Master FSMO role.
       dc_is_schema_master:
         type: bool
         required: false
         default: false
         description:
-          - Whether the domain controller is the schema master.
+          - Whether the domain controller should hold the Schema Master FSMO role.
       dc_is_infrastructure_master:
         type: bool
         required: false
         default: false
         description:
-          - Whether the domain controller is the infrastructure master.
+          - Whether the domain controller should hold the Infrastructure Master FSMO role.
       dc_is_pdc_emulator:
         type: bool
         required: false
         default: false
         description:
-          - Whether the domain controller is the PDC emulator.
+          - Whether the domain controller should hold the PDC Emulator FSMO role.
       dc_is_rid_master:
         type: bool
         required: false
         default: false
         description:
-          - Whether the domain controller is the RID master.
+          - Whether the domain controller should hold the RID Master FSMO role.
diff --git a/roles/domain_controller/meta/main.yml b/roles/domain_controller/meta/main.yml
@@ -3,7 +3,15 @@ galaxy_info:
   author: Jim Tarpley
   namespace: trippsc2
   role_name: domain_controller
-  description: This role configures the Windows Server machine as an Active Directory Domain Controller.
+  description: |
+    This role configures the Windows Server machine as an Active Directory Domain Controller.
+    
+    The following scenarios are supported:
+    - The server is the first domain controller in a new forest.
+    - The server is an additional domain controller in an existing domain.
+    
+    The following scenarios are not supported, but may be added in the future:
+    - The server is the first domain controller in a child or tree domain in an existing forest.
 
   license: MIT
 

diff --git a/roles/domain_controller/molecule/default/prepare.yml b/roles/domain_controller/molecule/default/prepare.yml
@@ -17,27 +17,5 @@
 - name: Prepare Vault server
   hosts:
     - vault
-  pre_tasks:
-    - name: Bootstrap python for Ansible
-      become: true
-      ansible.builtin.raw: |
-        command -v python3 python || (
-        command -v apk >/dev/null && sudo apk add --no-progress --update python3 ||
-        (test -e /usr/bin/dnf && sudo dnf install -y python3) ||
-        (test -e /usr/bin/apt && (apt -y update && apt install -y python-minimal)) ||
-        (test -e /usr/bin/yum && sudo yum -y -qq install python3) ||
-        (test -e /usr/sbin/pkg && sudo env ASSUME_ALWAYS_YES=yes pkg update && sudo env ASSUME_ALWAYS_YES=yes pkg install python3) ||
-        (test -e /usr/sbin/pkg_add && sudo /usr/sbin/pkg_add -U -I -x python%3.7) ||
-        echo "Warning: Python not bootstrapped due to unknown platform."
-        )
-      changed_when: false
   roles:
     - role: trippsc2.hashi_vault.testing
-  tasks:
-    - name: Create secret engine
-      delegate_to: localhost
-      trippsc2.hashi_vault.vault_kv2_secret_engine:
-        token: "{{ vault_token }}"
-        url: "{{ vault_url }}"
-        engine_mount_point: os
-        state: present
diff --git a/roles/domain_controller/molecule/default/verify.yml b/roles/domain_controller/molecule/default/verify.yml
@@ -22,7 +22,7 @@
     - name: Verify that the domain controller is promoted
       ansible.builtin.assert:
         that:
-          - ansible_windows_domain_role | regex_search('(domain controller)')
+          - ("domain controller" in ansible_windows_domain_role)
           - ansible_windows_domain == 'test.loc'
         fail_msg: The domain controller is not promoted.
         success_msg: The domain controller is promoted.

diff --git a/roles/domain_controller/molecule/new/prepare.yml b/roles/domain_controller/molecule/new/prepare.yml
@@ -2,28 +2,5 @@
 - name: Prepare Vault server
   hosts:
     - vault
-  gather_facts: false
-  pre_tasks:
-    - name: Bootstrap python for Ansible
-      become: true
-      ansible.builtin.raw: |
-        command -v python3 python || (
-        command -v apk >/dev/null && sudo apk add --no-progress --update python3 ||
-        (test -e /usr/bin/dnf && sudo dnf install -y python3) ||
-        (test -e /usr/bin/apt && (apt -y update && apt install -y python-minimal)) ||
-        (test -e /usr/bin/yum && sudo yum -y -qq install python3) ||
-        (test -e /usr/sbin/pkg && sudo env ASSUME_ALWAYS_YES=yes pkg update && sudo env ASSUME_ALWAYS_YES=yes pkg install python3) ||
-        (test -e /usr/sbin/pkg_add && sudo /usr/sbin/pkg_add -U -I -x python%3.7) ||
-        echo "Warning: Python not bootstrapped due to unknown platform."
-        )
-      changed_when: false
   roles:
     - role: trippsc2.hashi_vault.testing
-  tasks:
-    - name: Create secret engine
-      delegate_to: localhost
-      trippsc2.hashi_vault.vault_kv2_secret_engine:
-        token: "{{ vault_token }}"
-        url: "{{ vault_url }}"
-        engine_mount_point: os
-        state: present
diff --git a/roles/domain_controller/molecule/new/verify.yml b/roles/domain_controller/molecule/new/verify.yml
@@ -22,7 +22,7 @@
     - name: Verify that the domain controller is promoted
       ansible.builtin.assert:
         that:
-          - ansible_windows_domain_role | regex_search('(domain controller)')
+          - ("domain controller" in ansible_windows_domain_role)
           - ansible_windows_domain == 'test.loc'
         fail_msg: The domain controller is not promoted.
         success_msg: The domain controller is promoted.