Add win_format (#53925)

* Add win_format

* Some doc changes were missed

* Fixes for ansible-test, additional assertion for check mode

* Fix -WhatIf issues

* Support for idempotency and changes to integration tests

* Fix trailing whitespace

* Fixes from review, and added check for non-empty volumes

* Remove an extra line

* Structural changes

* Minor fixes for CI

test/integration/targets/win_format/aliases

@@ -0,0 +1,3 @@
+shippable/windows/group4
+skip/windows/2008
+skip/windows/2008-R2

test/integration/targets/win_format/meta/main.yml

@@ -0,0 +1,2 @@
+dependencies:
+- setup_remote_tmp_dir

test/integration/targets/win_format/tasks/main.yml

@@ -0,0 +1,7 @@
+---
+- name: Check if Format-Volume is supported
+  win_shell: if (Get-Command -Name Format-Volume -ErrorAction SilentlyContinue) { $true } else { $false }
+  register: module_present
+
+- include: pre_test.yml
+  when: module_present.stdout | trim | bool

test/integration/targets/win_format/tasks/pre_test.yml

@@ -0,0 +1,21 @@
+---
+- set_fact:
+    AnsibleVhdx: '{{ remote_tmp_dir }}\AnsiblePart.vhdx'
+
+- name: Copy VHDX scripts
+  win_template:
+    src: "{{ item.src }}"
+    dest: '{{ remote_tmp_dir }}\{{ item.dest }}'
+  loop:
+    - { src: partition_creation_script.j2, dest: partition_creation_script.txt }
+    - { src: partition_deletion_script.j2, dest: partition_deletion_script.txt }
+
+- name: Create partition
+  win_command: diskpart.exe /s {{ remote_tmp_dir }}\partition_creation_script.txt
+
+- name: Run tests
+  block:
+    - include: tests.yml
+  always:
+    - name: Detach disk
+      win_command: diskpart.exe /s {{ remote_tmp_dir }}\partition_deletion_script.txt

test/integration/targets/win_format/tasks/tests.yml

@@ -0,0 +1,138 @@
+---
+- win_shell: $AnsiPart = Get-Partition -DriveLetter T; $AnsiVol = Get-Volume -DriveLetter T; "$($AnsiPart.Size),$($AnsiVol.Size)"
+  register: shell_result
+
+- name: Assert volume size is 0 for pristine volume
+  assert:
+    that:
+      - shell_result.stdout | trim == "2096037888,0"
+
+- name: Get partition access path
+  win_shell: (Get-Partition -DriveLetter T).AccessPaths[1]
+  register: shell_partition_result
+
+- name: Try to format using mutually exclusive parameters
+  win_format:
+    drive_letter: T
+    path: "{{ shell_partition_result.stdout | trim }}"
+  register: format_mutex_result
+  ignore_errors: True
+
+- assert:
+    that:
+      - format_mutex_result is failed
+      - 'format_mutex_result.msg == "parameters are mutually exclusive: drive_letter, path, label"'
+
+- name: Fully format volume and assign label (check)
+  win_format:
+    drive_letter: T
+    new_label: Formatted
+    full: True
+  register: format_result_check
+  check_mode: True
+
+- win_shell: $AnsiPart = Get-Partition -DriveLetter T; $AnsiVol = Get-Volume -DriveLetter T; "$($AnsiPart.Size),$($AnsiVol.Size),$($AnsiVol.FileSystemLabel)"
+  register: formatted_value_result_check
+
+- name: Fully format volume and assign label
+  win_format:
+    drive_letter: T
+    new_label: Formatted
+    full: True
+  register: format_result
+
+- win_shell: $AnsiPart = Get-Partition -DriveLetter T; $AnsiVol = Get-Volume -DriveLetter T; "$($AnsiPart.Size),$($AnsiVol.Size),$($AnsiVol.FileSystemLabel)"
+  register: formatted_value_result
+
+- assert:
+    that:
+      - format_result_check is changed
+      - format_result is changed
+      - formatted_value_result_check.stdout | trim == "2096037888,0,"
+      - formatted_value_result.stdout | trim == "2096037888,2096033792,Formatted"
+
+- name: Format NTFS volume with integrity streams enabled
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    file_system: ntfs
+    integrity_streams: True
+  ignore_errors: True
+  register: ntfs_integrity_streams
+
+- assert:
+    that:
+      - ntfs_integrity_streams is failed
+      - 'ntfs_integrity_streams.msg == "Integrity streams can be enabled only on ReFS volumes. You specified: ntfs"'
+
+- name: Format volume (require force_format for specifying different file system)
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    file_system: fat32
+  ignore_errors: True
+  register: require_force_format
+
+- assert:
+    that:
+      - require_force_format is failed
+      - 'require_force_format.msg == "Force format must be specified since target file system: fat32 is different from the current file system of the volume: ntfs"'
+
+- name: Format volume (forced) (check)
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    file_system: refs
+    force: True
+  check_mode: True
+  ignore_errors: True
+  register: not_pristine_forced_check
+
+- name: Format volume (forced)
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    file_system: refs
+    force: True
+  register: not_pristine_forced
+
+- name: Format volume (forced) (idempotence will not work)
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    file_system: refs
+    force: True
+  register: not_pristine_forced_idem_fails
+
+- name: Format volume (idempotence)
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    file_system: refs
+  register: not_pristine_forced_idem
+
+- assert:
+    that:
+      - not_pristine_forced_check is changed
+      - not_pristine_forced is changed
+      - not_pristine_forced_idem_fails is changed
+      - not_pristine_forced_idem is not changed
+
+- name: Add a file
+  win_file:
+    path: T:\path\to\directory
+    state: directory
+  register: add_file_to_volume
+
+- name: Format volume with file inside without force
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+  register: format_volume_without_force
+  ignore_errors: True
+
+- name: Format volume with file inside with force
+  win_format:
+    path: "{{ shell_partition_result.stdout | trim }}"
+    force: True
+  register: format_volume_with_force
+
+- assert:
+    that:
+      - add_file_to_volume is changed
+      - format_volume_without_force is failed
+      - 'format_volume_without_force.msg == "Force format must be specified to format non-pristine volumes"'
+      - format_volume_with_force is changed

test/integration/targets/win_format/templates/partition_creation_script.j2

@@ -0,0 +1,11 @@
+create vdisk file="{{ AnsibleVhdx }}" maximum=2000 type=fixed
+
+select vdisk file="{{ AnsibleVhdx }}"
+
+attach vdisk
+
+convert mbr
+
+create partition primary
+
+assign letter="T"

test/integration/targets/win_format/templates/partition_deletion_script.j2

@@ -0,0 +1,3 @@
+select vdisk file="{{ AnsibleVhdx }}"
+
+detach vdisk