add role to manage folders

changelogs/fragments/47__mm_feature__add_manage_folder.yml

@@ -0,0 +1,3 @@
+---
+minor_changes:
+  - manage_folder - Added new role, tests, and playbook to create or delete a folder in VCenter

playbooks/manage_folder.yml

@@ -0,0 +1,7 @@
+---
+- name: Manage Folder In VCenter
+  hosts: all
+  gather_facts: false
+
+  roles:
+    - role: cloud.vmware_ops.manage_folder

roles/manage_folder/README.md

@@ -0,0 +1,128 @@
+# Manage Folder Role
+
+A role to create, delete, or update a folder or folder tree in VCenter.
+
+## Requirements
+
+N/A
+
+## Role Variables
+### Auth
+- **manage_folder_username**:
+  - The vSphere vCenter username.
+
+- **manage_folder_password**:
+  - The vSphere vCenter password.
+
+- **manage_folder_hostname**:
+  - The hostname or IP address of the vSphere vCenter.
+
+- **manage_folder_validate_certs**
+  - Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
+
+- **manage_folder_datacenter_name**:
+  - The name of the datacenter in vSphere vCenter which contains the cluster to configure.
+
+- **manage_folder_port**:
+  - str or int, The port to use to authenticate to the vSphere vCenter which contains the cluster to configure.
+
+### Other
+- **manage_folder_folder_name**:
+  - str, required, The name of folder to manage. It can be a single name like `foo` or a path like `foo/bar/buzz`.
+
+- **manage_folder_parse_name_as_path**:
+  - bool, If true then `manage_folder_folder_name` is treated as a path. All folders along the path will be managed.
+    If false, the name is treated as a literal string. Default is true.
+
+- **manage_folder_folder_type**:
+  - str, The type of folder to manage. Can be `datastore`, `host`, `vm`, or `network`. The default is `vm`.
+
+- **manage_folder_parent_folder**:
+  - >-
+    str, Set the folder path where the new folder(s) should be managed. This path must already exist.
+    For example, for the folder `foo/bizz/buzz` the parent is `foo/bizz/buzz`
+
+- **manage_folder_state**:
+  - str, optional, Choose if the folder should be 'present' or 'absent'. Default value is 'present'
+
+### Other
+- **manage_folder_proxy_host**:
+  - str, The hostname of a proxy host that should be used for all HTTPs communication by the role. Optional
+
+- **manage_folder_proxy_port**:
+  - str, The port of a proxy host that should be used for all HTTPs communication by the role. Optional
+
+## Dependencies
+
+- community.vmware
+
+## Example Playbook
+```yaml
+---
+- name: Manage VMWare Folders
+  hosts: all
+  gather_facts: false
+  vars:
+    manage_folder_username: <>
+    manage_folder_password: <>
+    manage_folder_hostname: <>
+    manage_folder_datacenter: DC01
+    manage_folder_type: host
+
+  roles:
+    - role: cloud.vmware_ops.manage_folder
+      manage_folder_folder_name: my/folder
+      manage_folder_state: present
+
+    - role: cloud.vmware_ops.manage_folder
+      manage_folder_folder_name: my/folder
+      manage_folder_state: absent
+
+  tasks:
+    - name: Create Folder Trees
+      ansible.builtin.include_role:
+        name: manage_folder
+      vars:
+        manage_folder_state: present
+        manage_folder_folder_name: "{{ item }}"
+      loop:
+        - production/foo/web
+        - uat/foo/web
+        - development/foo/web
+
+    - name: Create Folders Without Managing Full Tree
+      ansible.builtin.include_role:
+        name: manage_folder
+      vars:
+        manage_folder_state: present
+        manage_folder_folder_name: "{{ item }}"
+        manage_folder_parent_folder: production/foo
+      loop:
+        - backend
+        - db
+
+    - name: Create A Folder With A Slash In It
+      ansible.builtin.include_role:
+        name: manage_folder
+      vars:
+        manage_folder_state: present
+        manage_folder_folder_name: security/syseng
+        manage_folder_parent_folder: production/foo
+        manage_folder_parse_name_as_path: false
+
+    - name: Delete The Whole Tree
+      ansible.builtin.include_role:
+        name: manage_folder
+      vars:
+        manage_folder_state: absent
+        manage_folder_folder_name: production
+```
+## License
+
+GNU General Public License v3.0 or later
+
+See [LICENCE](https://github.com/ansible-collections/cloud.aws_troubleshooting/blob/main/LICENSE) to see the full text.
+
+## Author Information
+
+- Ansible Cloud Content Team

roles/manage_folder/defaults/main.yml

@@ -0,0 +1,4 @@
+---
+manage_folder_state: present
+manage_folder_parent_folder: ""
+manage_folder_parse_name_as_path: true

roles/manage_folder/tasks/main.yml

@@ -0,0 +1,43 @@
+---
+- name: Check Mandatory Variables Are Defined
+  ansible.builtin.assert:
+    that:
+      - manage_folder_datacenter_name is defined
+      - manage_folder_folder_name is defined and ((manage_folder_folder_name | length) > 0)
+      - manage_folder_hostname is defined
+      - manage_folder_username is defined
+      - manage_folder_password is defined
+    quiet: true
+    fail_msg: Variable must be set when using this role.
+
+- name: Fail If Folder Path Is Absolute
+  ansible.builtin.fail:
+    msg: Folder name should not be absolute. It should be relative to /<datacenter>/<type>
+  when: manage_folder_folder_name[0] == '/'
+
+- name: Manage Full Folder Path
+  when: manage_folder_parse_name_as_path
+  block:
+    - name: Split Folder Into Parts
+      ansible.builtin.set_fact:
+        _folder_parts: "{{ manage_folder_folder_name | split('/') }}"
+        _folder_path_task_output: false
+    - name: Manage Folder Path Part
+      ansible.builtin.include_tasks: manage_path_part.yml
+      when: manage_folder_state == 'present' or not _folder_path_task_output
+      loop: "{{ _folder_parts }}"
+      loop_control:
+        loop_var: _folder_part
+        index_var: _part_index
+      vars:
+        _child: "{{ _folder_parts[_part_index : _part_index + 1] | first }}"
+        _parent: >-
+          {{ (manage_folder_parent_folder + '/' + (_folder_parts[:_part_index] | join('/'))) |
+          regex_replace('^\/?(.*)\/?$', '\1') }}
+
+- name: Manage Folder Endpoint Only
+  ansible.builtin.include_tasks: manage_path_part.yml
+  when: not manage_folder_parse_name_as_path
+  vars:
+    _child: "{{ manage_folder_folder_name }}"
+    _parent: "{{ manage_folder_parent_folder }}"

roles/manage_folder/tasks/manage_path_part.yml

@@ -0,0 +1,16 @@
+---
+- name: Manage VCenter Folder - {{ (_parent | ternary(_parent + '/', '')) + _child }}
+  community.vmware.vcenter_folder:
+    hostname: "{{ manage_folder_hostname }}"
+    username: "{{ manage_folder_username }}"
+    password: "{{ manage_folder_password }}"
+    validate_certs: "{{ manage_folder_validate_certs | default(omit) }}"
+    port: "{{ manage_folder_port | default(omit) }}"
+    proxy_host: "{{ manage_folder_proxy_host | default(omit) }}"
+    proxy_port: "{{ manage_folder_proxy_port | default(omit) }}"
+    datacenter_name: "{{ manage_folder_datacenter_name }}"
+    folder_type: "{{ manage_folder_folder_type | default(omit) }}"
+    folder_name: "{{ _child }}"
+    parent_folder: "{{ _parent or omit }}"
+    state: "{{ manage_folder_state }}"
+  register: _folder_path_task_output

tests/integration/targets/manage_folder_test/run.yml

@@ -0,0 +1,13 @@
+- hosts: localhost
+  gather_facts: no
+  collections:
+    - community.general
+
+  tasks:
+    - name: Vcsim
+      ansible.builtin.import_role:
+        name: prepare_soap
+
+    - name: Import manage folder test
+      ansible.builtin.import_role:
+        name: manage_folder_test

tests/integration/targets/manage_folder_test/runme.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+source ../init.sh
+exec ansible-playbook run.yml

tests/integration/targets/manage_folder_test/tasks/main.yml

@@ -0,0 +1,50 @@
+---
+- name: Create Folder Tree
+  ansible.builtin.include_role:
+    name: cloud.vmware_ops.manage_folder
+  vars:
+    manage_folder_state: present
+    manage_folder_folder_name: production/foo/web
+
+- name: Create Folder Without Managing Full Tree
+  ansible.builtin.include_role:
+    name: cloud.vmware_ops.manage_folder
+  vars:
+    manage_folder_state: present
+    manage_folder_folder_name: db
+    manage_folder_parent_folder: production/foo
+
+- name: Create A Folder With A Slash In It
+  ansible.builtin.include_role:
+    name: cloud.vmware_ops.manage_folder
+  vars:
+    manage_folder_state: present
+    manage_folder_folder_name: security/syseng
+    manage_folder_parent_folder: production/foo
+    manage_folder_parse_name_as_path: false
+
+- name: Get Folder Info
+  community.vmware.vmware_folder_info:
+    hostname: "{{ manage_folder_hostname }}"
+    username: "{{ manage_folder_username }}"
+    password: "{{ manage_folder_password }}"
+    datacenter: "{{ manage_folder_datacenter_name }}"
+    port: "{{ manage_folder_port }}"
+    validate_certs: false
+  delegate_to: localhost
+  register: _folder_info
+
+- name: Check Folders Were Created
+  ansible.builtin.assert:
+    that:
+      - _folder_info.folder_info.hostFolders.subfolders.production.subfolders.foo.subfolders['web'] is defined
+      - _folder_info.folder_info.hostFolders.subfolders.production.subfolders.foo.subfolders['db'] is defined
+      - _folder_info.folder_info.hostFolders.subfolders.production.subfolders.foo.subfolders['security%2fsyseng'] is defined
+    fail_msg: Folder structure does not match expected result.
+
+- name: Delete The Whole Tree
+  ansible.builtin.include_role:
+    name: cloud.vmware_ops.manage_folder
+  vars:
+    manage_folder_state: absent
+    manage_folder_folder_name: production

tests/integration/targets/manage_folder_test/vars/main.yml

@@ -0,0 +1,8 @@
+---
+manage_folder_hostname: "127.0.0.1"
+manage_folder_username: "test"
+manage_folder_password: "test"
+manage_folder_validate_certs: false
+manage_folder_port: "8989"
+manage_folder_datacenter_name: DC0
+manage_folder_folder_type: host