Restucture the gateway_organizations role so that only one role needs to be called to create and configure the organization (#1054)

Co-authored-by: David Danielsson <djdanielsson@users.noreply.github.com>

Author: Tompage1994

.markdownlint.yml

@@ -18,4 +18,6 @@ MD0046:
 MD033:
   allowed_elements:
     - br
+    - a
+    - img
 ...

changelogs/fragments/organizations.yml

@@ -0,0 +1,5 @@
+---
+major_changes:
+  - Restucture the gateway_organizations role so that only one role needs to be called to create and configure the organization. Adds the logic which existed from the controller_organizations role previously.
+  - Dispatch no longer calls the controller_organizations role by default, as the gateway_organizations role should be sufficient.
+...

roles/controller_organizations/README.md

@@ -2,7 +2,7 @@
 
 ## Description
 
-An Ansible Role to create/update/remove Organizations on Ansible Controller.
+An Ansible Role to create/update/remove Organizations on Ansible Controller. Note that this role will not create organizations in AAP 2.5 and beyond. Instead, make use of the `gateway_organizations` role from this collection.
 
 ## Requirements
 

roles/dispatch/README.md

@@ -41,6 +41,9 @@ gateway_configuration_dispatcher_roles:
   - role: gateway_organizations
     var: aap_organizations
     tags: organizations
+    assign_galaxy_credentials_to_org: false
+    assign_default_ee_to_org: false
+    assign_notification_templates_to_org: false
   - role: gateway_service_clusters
     var: gateway_service_clusters
     tags: service_clusters
@@ -116,12 +119,6 @@ controller_configuration_dispatcher_roles:
   - role: controller_settings
     var: controller_settings
     tags: settings
-  - role: controller_organizations
-    var: aap_organizations
-    tags: organizations
-    assign_galaxy_credentials_to_org: false
-    assign_default_ee_to_org: false
-    assign_notification_templates_to_org: false
   - role: controller_instances
     var: controller_instances
     tags: instances
@@ -149,7 +146,7 @@ controller_configuration_dispatcher_roles:
   - role: controller_notification_templates
     var: controller_notifications
     tags: notification_templates
-  - role: controller_organizations
+  - role: gateway_organizations
     var: aap_organizations
     tags: organizations
     assign_galaxy_credentials_to_org: true

roles/dispatch/defaults/main.yml

@@ -12,6 +12,9 @@ gateway_configuration_dispatcher_roles:
   - role: gateway_organizations
     var: aap_organizations
     tags: organizations
+    assign_galaxy_credentials_to_org: false
+    assign_default_ee_to_org: false
+    assign_notification_templates_to_org: false
   - role: gateway_applications
     var: aap_applications
     tags: applications
@@ -85,12 +88,6 @@ controller_configuration_dispatcher_roles:
   - role: controller_settings
     var: controller_settings
     tags: settings
-  - role: controller_organizations
-    var: aap_organizations
-    tags: organizations
-    assign_galaxy_credentials_to_org: false
-    assign_default_ee_to_org: false
-    assign_notification_templates_to_org: false
   - role: controller_instances
     var: controller_instances
     tags: instances
@@ -118,7 +115,7 @@ controller_configuration_dispatcher_roles:
   - role: controller_notification_templates
     var: controller_notifications
     tags: notification_templates
-  - role: controller_organizations
+  - role: gateway_organizations
     var: aap_organizations
     tags: organizations
     assign_galaxy_credentials_to_org: true

roles/gateway_organizations/README.md

@@ -4,6 +4,10 @@
 
 An Ansible Role to add Organizations on Ansible Automation gateway.
 
+## Requirements
+
+This role requires both `ansible.platform` and `ansible.controller` collections. Note that the `awx.awx` collection will not work with this role. See the `controller_organizations` role for the AWX/Controller only implementation.
+
 ## Variables
 
 |Variable Name|Default Value|Required|Description|Example|
@@ -16,6 +20,26 @@ An Ansible Role to add Organizations on Ansible Automation gateway.
 |`aap_token`|""|no|Controller Admin User's token on the Ansible Automation Platform Server. This should be stored in an Ansible Vault at or elsewhere and called from a parent playbook. Either username / password or oauthtoken need to be specified.||
 |`aap_request_timeout`|`10`|no|Specify the timeout in seconds Ansible should use in requests to the Ansible Automation Platform host.||
 |`aap_organizations`|`see below`|yes|Data structure describing your organizations Described below.||
+|`assign_galaxy_credentials_to_org`|`true`|no|Boolean to indicate whether credentials should be assigned or not. It should be noted that credentials must exist before adding it. The dispatch role will set this to `false`, before re-running the role with it set to `true`. ||
+|`assign_default_ee_to_org`|`true`|no|Boolean to indicate whether default execution environment should be assigned or not. It should be noted that execution environment must exist before adding it. The dispatch role will set this to `false`, before re-running the role with it set to `true`. ||
+|`assign_notification_templates_to_org`|`true`|no|Boolean to indicate whether notification templates should be assigned or not. It should be noted that the templates must exist before adding them. The dispatch role will set this to `false`, before re-running the role with it set to `true`. ||
+|`assign_instance_groups_to_org`|`true`|no|Boolean to indicate whether an instance group should be assigned or not. It should be noted that the instance group must exist before adding it. ||
+
+### Enforcing defaults
+
+The following Variables compliment each other.
+If Both variables are not set, enforcing default values is not done.
+Enabling these variables enforce default values on options that are optional in the controller API.
+This should be enabled to enforce configuration and prevent configuration drift. It is recommended to be enabled, however it is not enforced by default.
+
+Enabling this will enforce configuration without specifying every option in the configuration files.
+
+'gateway_organizations_enforce_defaults' defaults to the value of 'aap_configuration_enforce_defaults' if it is not explicitly called. This allows for enforced defaults to be toggled for the entire suite of controller configuration roles with a single variable, or for the user to selectively use it.
+
+|Variable Name|Default Value|Required|Description|
+|:---:|:---:|:---:|:---:|
+|`gateway_organizations_enforce_defaults`|`false`|no|Whether or not to enforce default option values on only the applications role|
+|`aap_configuration_enforce_defaults`|`false`|no|This variable enables enforced default values as well, but is shared across multiple roles, see above.|
 
 ### Secure Logging Variables
 
@@ -52,12 +76,21 @@ This also speeds up the overall role.
 
 Options for the `aap_organizations` variable:
 
-| Variable Name | Default Value | Required | Type | Description                                                                      |
-|:--------------|:-------------:|:--------:|:----:|:---------------------------------------------------------------------------------|
-| `name`        |      N/A      |   yes    | str  | The name of the resource                                                         |
-| `new_name`    |      N/A      |    no    | str  | Setting this option will change the existing name (looked up via the name field) |
-| `description` |      N/A      |    no    | str  | Description of the organization                                                  |
-| `state`       |   `present`   |    no    | str  | Desired state of the resource.                                                   |
+| Variable Name                      | Default Value | Required | Type | Description                                                                      |
+|:-----------------------------------|:-------------:|:--------:|:----:|:---------------------------------------------------------------------------------|
+| `name`                             |      N/A      |   yes    | str  | The name of the resource                                                         |
+| `new_name`                         |      N/A      |    no    | str  | Setting this option will change the existing name (looked up via the name field) |
+| `description`                      |      N/A      |    no    | str  | Description of the organization                                                  |
+| `custom_virtualenv`                |      N/A      |    no    | str  | Local absolute file path containing a custom Python virtualenv to use.           |
+| `max_hosts`                        |      N/A      |    no    | int  | The max hosts allowed in this organization.                                      |
+| `instance_groups`                  |      N/A      |    no    | list | list of Instance Groups for this Organization to run on.                         |
+| `galaxy_credentials`               |      N/A      |    no    | list | The credentials to use with private automation hub.                              |
+| `default_environment`              |      N/A      |    no    | str  | Default Execution Environment to use for jobs owned by the Organization.         |
+| `notification_templates_started`   |      N/A      |    no    | list | The notifications on started to use for this organization in a list.             |
+| `notification_templates_success`   |      N/A      |    no    | list | The notifications on success to use for this organization in a list.             |
+| `notification_templates_error`     |      N/A      |    no    | list | The notifications on error to use for this organization in a list.               |
+| `notification_templates_approvals` |      N/A      |    no    | list | The notifications for approval to use for this organization in a list.           |
+| `state`                            |   `present`   |    no    | str  | Desired state of the resource.                                                   |
 
 ### Unique value
 
@@ -71,15 +104,22 @@ Options for the `aap_organizations` variable:
 
 ```json
 {
-  "aap_organizations": [
-    {
-      "name": "Org 1",
-      "description": "First Organization"
-    },
-    {
-      "name": "Org 2"
-    }
-  ]
+    "aap_organizations": [
+      {
+        "name": "Default",
+        "description": "This is the Default Group"
+      },
+      {
+        "name": "Automation Group",
+        "description": "This is the Automation Group",
+        "custom_virtualenv": "/opt/cust/environment/",
+        "max_hosts": 10,
+        "galaxy_credentials": "Automation Hub",
+        "notification_templates_error": [
+          "Slack_for_testing"
+        ]
+      }
+    ]
 }
 ```
 
@@ -95,13 +135,12 @@ File name: `data/aap_organizations.yml`
 ```yaml
 ---
 aap_organizations:
-- name: "Deprecated Org"
-  state: absent
-- name: Org 1
-  state: exists
-- name: Org 2
-- name: Org 3
-  new_name: Organization 3
+- name: Default
+  description: This is the Default Group
+- name: Automation Group
+  description: This is the Automation Group
+  custom_virtualenv: "/opt/cust/environment/"
+  max_hosts: 10
 ```
 
 ### Run Playbook

roles/gateway_organizations/defaults/main.yml

@@ -14,5 +14,11 @@ gateway_organizations_secure_logging: "{{ aap_configuration_secure_logging | def
 gateway_organizations_async_retries: "{{ aap_configuration_async_retries | default(30) }}"
 gateway_organizations_async_delay: "{{ aap_configuration_async_delay | default(1) }}"
 gateway_organizations_loop_delay: "{{ aap_configuration_loop_delay | default(0) }}"
+gateway_organizations_enforce_defaults: "{{ aap_configuration_enforce_defaults | default(false) }}"
 aap_configuration_async_dir:
+
+assign_galaxy_credentials_to_org: true
+assign_default_ee_to_org: true
+assign_notification_templates_to_org: true
+assign_instance_groups_to_org: true
 ...

roles/gateway_organizations/tasks/main.yml

@@ -43,4 +43,64 @@
   vars:
     __operation: "{{ operation_translate[__gateway_organizations_job_async_results_item.state | default(platform_state) | default('present')] }}"
     ansible_async_dir: "{{ aap_configuration_async_dir }}"
+
+- name: Organizations | Controller Configuration
+  ansible.controller.organization:
+    name: "{{ __controller_organizations_item.name | mandatory }}"
+    new_name: "{{ __controller_organizations_item.new_name | default(omit) }}"
+    description: "{{ __controller_organizations_item.description | default(('' if gateway_organizations_enforce_defaults else omit), true) }}"
+    custom_virtualenv: "{{ __controller_organizations_item.custom_virtualenv | default(omit, true) }}"
+    max_hosts: "{{ __controller_organizations_item.max_hosts | default((0 if gateway_organizations_enforce_defaults else omit), true) }}"
+    instance_groups: "{{ (__controller_organizations_item.instance_groups | default(([] if gateway_organizations_enforce_defaults else omit), true))if (assign_instance_groups_to_org is defined and assign_instance_groups_to_org) else omit }}"
+    default_environment: "{{ (__controller_organizations_item.default_environment.name | default(__controller_organizations_item.default_environment | default(__controller_organizations_item.execution_environment | default(omit)))) if (assign_default_ee_to_org is defined and assign_default_ee_to_org) else omit }}"
+    galaxy_credentials: "{{ (__controller_organizations_item.galaxy_credentials | default(([] if gateway_organizations_enforce_defaults else omit), true)) if (assign_galaxy_credentials_to_org is defined and assign_galaxy_credentials_to_org) else omit }}"
+    notification_templates_approvals: "{{ (__controller_organizations_item.related.notification_templates_approvals | map(attribute='name') | list if __controller_organizations_item.related.notification_templates_approvals is defined) | default(__controller_organizations_item.notification_templates_approvals) | default(([] if gateway_organizations_enforce_defaults else omit), true) if (assign_notification_templates_to_org is defined and assign_notification_templates_to_org) else omit }}"
+    notification_templates_started: "{{ (__controller_organizations_item.related.notification_templates_started | map(attribute='name') | list if __controller_organizations_item.related.notification_templates_started is defined) | default(__controller_organizations_item.notification_templates_started) | default(([] if gateway_organizations_enforce_defaults else omit), true) if (assign_notification_templates_to_org is defined and assign_notification_templates_to_org) else omit }}"
+    notification_templates_success: "{{ (__controller_organizations_item.related.notification_templates_success | map(attribute='name') | list if __controller_organizations_item.related.notification_templates_success is defined) | default(__controller_organizations_item.notification_templates_success) | default(([] if gateway_organizations_enforce_defaults else omit), true) if (assign_notification_templates_to_org is defined and assign_notification_templates_to_org) else omit }}"
+    notification_templates_error: "{{ (__controller_organizations_item.related.notification_templates_error | map(attribute='name') | list if __controller_organizations_item.related.notification_templates_error is defined) | default(__controller_organizations_item.notification_templates_error) | default(([] if gateway_organizations_enforce_defaults else omit), true) if (assign_notification_templates_to_org is defined and assign_notification_templates_to_org) else omit }}"
+    state: "{{ __controller_organizations_item.state | default(platform_state | default('present')) }}"
+
+    # Role Standard Options
+    controller_username: "{{ aap_username | default(omit, true) }}"
+    controller_password: "{{ aap_password | default(omit, true) }}"
+    controller_oauthtoken: "{{ aap_token | default(omit, true) }}"
+    request_timeout: "{{ aap_request_timeout | default(omit, true) }}"
+    controller_host: "{{ aap_hostname | default(omit, true) }}"
+    validate_certs: "{{ aap_validate_certs | default(omit) }}"
+  loop: "{{ aap_organizations }}"
+  loop_control:
+    loop_var: __controller_organizations_item
+    label: "{{ __operation.verb }} organization {{ __controller_organizations_item.name }}"
+    pause: "{{ gateway_organizations_loop_delay }}"
+  no_log: "{{ gateway_organizations_secure_logging }}"
+  async: "{{ ansible_check_mode | ternary(0, 1000) }}"
+  poll: 0
+  register: __organizations_job_async
+  changed_when: (__organizations_job_async.changed if ansible_check_mode else false)
+  vars:
+    __operation: "{{ operation_translate[__controller_organizations_item.state | default(platform_state) | default('present')] }}"
+    ansible_async_dir: "{{ aap_configuration_async_dir }}"
+
+- name: Flag for errors (check mode only)
+  ansible.builtin.set_fact:
+    error_flag: true
+  when: ansible_check_mode and __organizations_job_async.failed is defined and __organizations_job_async.failed
+
+- name: Managing Controller Organizations | Wait for finish the Organizations management
+  ansible.builtin.async_status:
+    jid: "{{ __organizations_job_async_results_item.ansible_job_id }}"
+  register: __organizations_job_async_result
+  until: __organizations_job_async_result.finished
+  retries: "{{ gateway_organizations_async_retries }}"
+  delay: "{{ gateway_organizations_async_delay }}"
+  loop: "{{ __organizations_job_async.results }}"
+  loop_control:
+    loop_var: __organizations_job_async_results_item
+    label: "{{ __operation.verb }} Controller Organization {{ __organizations_job_async_results_item.__controller_organizations_item.name }} | Wait for finish the
+      organization {{ __operation.action }}"
+  when: not ansible_check_mode and __organizations_job_async_results_item.ansible_job_id is defined
+  no_log: "{{ gateway_organizations_secure_logging }}"
+  vars:
+    __operation: "{{ operation_translate[__organizations_job_async_results_item.__controller_organizations_item.state | default(platform_state) | default('present')] }}"
+    ansible_async_dir: "{{ aap_configuration_async_dir }}"
 ...