New module: Add module to add/remove a network static route on windows (windows/win_route) (#23405)

* adds win_route windows module

* fix documentation indent

* fix documentation pep8 issues

* fix documentation issues

* genaral code review

* changed 'supported_by' in doc, supports_check_mode removed

* use of powershell cmdlet instead of route command, destnation in CIDR format, adds check mode support

* adds win_psmodule module

* documentation review

* documentation review

* removed files accidentatlly pushed

* add integration tests, add return in documentation

* add conditional statement in test, add os requirementes in documentation

* fix documentation

* fix os check in tests

5 files changed, 120 insertions, 0 deletions

diff --git a/test/integration/targets/win_route/aliases b/test/integration/targets/win_route/aliases
new file mode 100644
index 0000000000..90d83328b3
--- /dev/null
+++ b/test/integration/targets/win_route/aliases
@@ -0,0 +1 @@
+windows/ci/group1
\ No newline at end of file
diff --git a/test/integration/targets/win_route/defaults/main.yml b/test/integration/targets/win_route/defaults/main.yml
new file mode 100644
index 0000000000..a77ebc16cb
--- /dev/null
+++ b/test/integration/targets/win_route/defaults/main.yml
@@ -0,0 +1,3 @@
+---
+default_gateway: 192.168.1.1
+destination_ip_address: 192.168.2.10
diff --git a/test/integration/targets/win_route/files/Test-Os.ps1 b/test/integration/targets/win_route/files/Test-Os.ps1
new file mode 100644
index 0000000000..f91aa91c40
--- /dev/null
+++ b/test/integration/targets/win_route/files/Test-Os.ps1
@@ -0,0 +1,13 @@
+$os = [Environment]::OSVersion
+$major = $os.Version.Major
+$minor = $os.Version.Minor
+$ok = $false
+
+if(($major -gt 6)){
+    $ok = $true
+}
+elseif (($major -eq 6) -and ($minor -ge 3)){
+    $ok = $true
+}
+
+$ok
\ No newline at end of file
diff --git a/test/integration/targets/win_route/tasks/main.yml b/test/integration/targets/win_route/tasks/main.yml
new file mode 100644
index 0000000000..79e1838b9a
--- /dev/null
+++ b/test/integration/targets/win_route/tasks/main.yml
@@ -0,0 +1,29 @@
+---
+# test code for the win_psmodule module when using winrm connection
+# (c) 2017, Daniele Lazzari <lazzari@mailup.com>
+
+# This file is part of Ansible
+#
+# Ansible is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Ansible is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+
+
+- name: get os info
+  script: ../files/Test-Os.ps1
+  register: os
+
+- name: Perform with os Windows 2012R2 or newer
+  when: os.stdout_lines[0] == "True"
+  block:
+    - name: run all tasks
+      include: tests.yml
diff --git a/test/integration/targets/win_route/tasks/tests.yml b/test/integration/targets/win_route/tasks/tests.yml
new file mode 100644
index 0000000000..61513aff22
--- /dev/null
+++ b/test/integration/targets/win_route/tasks/tests.yml
@@ -0,0 +1,74 @@
+---
+- name: add a static route
+  win_route:
+    destination: "{{ destination_ip_address }}/32"
+    gateway: "{{ default_gateway }}"
+    metric: 1
+    state: present
+  register: route
+
+- name: check if route successfully addedd
+  win_shell: (Get-CimInstance win32_ip4PersistedrouteTable -Filter "Destination = '{{ destination_ip_address }}'").Caption
+  register: route_added
+
+- name: test if route successfully addedd
+  assert:
+    that:
+      - route|changed
+      - route_added.stdout_lines[0] == "{{ destination_ip_address }}"
+
+- name: add a static route to test idempotency
+  win_route:
+    destination: "{{ destination_ip_address }}/32"
+    gateway: "{{ default_gateway }}"
+    metric: 1
+    state: present
+  register: idempotent_route
+
+- name: test idempotency
+  assert:
+    that:
+      - not idempotent_route|changed
+      - idempotent_route.output == "Static route already exists"
+
+- name: remove route
+  win_route:
+    destination: "{{ destination_ip_address }}/32"
+    state: absent
+  register: route_removed
+
+- name: check route is removed
+  win_shell: Get-CimInstance win32_ip4PersistedrouteTable -Filter "Destination = '{{ destination_ip_address }}'"
+  register: check_route_removed
+
+- name: test route is removed
+  assert:
+    that:
+      - route_removed|changed
+      - check_route_removed.stdout == ''
+
+- name: remove static route to test idempotency
+  win_route:
+    destination: "{{ destination_ip_address }}/32"
+    state: absent
+  register: idempotent_route_removed
+
+- name: test idempotency
+  assert:
+    that:
+      - not idempotent_route_removed|changed
+      - idempotent_route_removed.output == "No route to remove"
+
+- name: add route to wrong ip address
+  win_route:
+    destination: "715.18.0.0/32"
+    gateway: "{{ default_gateway }}"
+    metric: 1
+    state: present
+  ignore_errors: yes
+  register: wrong_ip
+
+- name: test route to wrong ip address
+  assert:
+    that:
+      - wrong_ip|failed