windows dev docs - vagrant info (#33515)

* windows dev docs - vagrant info

* added info about FileUtil and LinkUtil

* Initial edit pass - WIP

* updated some wording

* fix some more general sayings to be more professional

docs/docsite/rst/dev_guide/developing_modules_general_windows.rst

@@ -15,8 +15,146 @@ What's covered in this section:
 Windows environment setup
 =========================
 
-TODO: Add in more information on how to use Vagrant to setup a Windows host.
+Unlike Python module development which can be run on the host that runs
+Ansible, Windows modules need to be written and tested for Windows hosts.
+While evaluation editions of Windows can be downloaded from
+Microsoft, these images are usually not ready to be used by Ansible without
+further modification. The easiest way to set up a Windows host so that it is
+ready to by used by Ansible is to set up a virtual machine using Vagrant.
+Vagrant can be used to download existing OS images called *boxes* that are then
+deployed to a hypervisor like VirtualBox. These boxes can either be created and
+stored offline or they can be downloaded from a central repository called
+Vagrant Cloud.
 
+This guide will use the Vagrant boxes created by the `packer-windoze <https://github.com/jborean93/packer-windoze>`_
+repository which have also been uploaded to `Vagrant Cloud <https://app.vagrantup.com/boxes/search?utf8=%E2%9C%93&sort=downloads&provider=&q=jborean93>`_.
+To find out more info on how these images are created, please go to the Github
+repo and look at the ``README`` file.
+
+Before you can get started, the following programs must be installed (please consult the Vagrant and
+VirtualBox documentation for installation instructions):
+
+- Vagrant
+- VirtualBox
+
+Create a Windows Server in a VM
+===============================
+
+To create a single Windows Server 2016 instance, run the following:
+
+.. code-block:: shell
+
+    vagrant init jborean93/WindowsServer2016
+    vagrant up
+
+This will download the Vagrant box from Vagrant Cloud and add it to the local
+boxes on your host and then start up that instance in VirtualBox. When starting
+for the first time, the Windows VM will run through the sysprep process and
+then create a HTTP and HTTPS WinRM listener automatically. Vagrant will finish
+its process once the listeners are onlinem, after which the VM can be used by Ansible.
+
+Create an Ansible Inventory
+===========================
+
+The following Ansible inventory file can be used to connect to the newly
+created Windows VM:
+
+.. code-block:: ini
+
+    [windows]
+    WindowsServer  ansible_host=127.0.0.1
+
+    [windows:vars]
+    ansible_user=vagrant
+    ansible_password=vagrant
+    ansible_port=55986
+    ansible_connection=winrm
+    ansible_winrm_transport=ntlm
+    ansible_winrm_server_cert_validation=ignore
+
+.. note:: The port ``55986`` is automatically forwarded by Vagrant to the
+    Windows host that was created, if this conflicts with an existing local
+    port then Vagrant will automatically use another one at random and display
+    show that in the output.
+
+The OS that is created is based on the image set. The following
+images can be used:
+
+- `jborean93/WindowsServer2008-x86 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2008-x86>`_
+- `jborean93/WindowsServer2008-x64 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2008-x64>`_
+- `jborean93/WindowsServer2008R2 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2008R2>`_
+- `jborean93/WindowsServer2012 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2012>`_
+- `jborean93/WindowsServer2012R2 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2012R2>`_
+- `jborean93/WindowsServer2016 <https://app.vagrantup.com/jborean93/boxes/WindowsServer2016>`_
+
+When the host is online, it can accessible by RDP on ``127.0.0.1:3389`` but the
+port may differ depending if there was a conflict. To get rid of the host, run
+``vagrant destroy --force`` and Vagrant will automatically remove the VM and
+any other files associated with that VM.
+
+While this is useful when testing modules on a single Windows instance, these
+host won't work without modification with domain based modules. The Vagrantfile
+at `ansible-windows <https://github.com/jborean93/ansible-windows/tree/master/vagrant>`_
+can be used to create a test domain environment to be used in Ansible. This
+repo contains three files which are used by both Ansible and Vagrant to create
+multiple Windows hosts in a domain environment. These files are:
+
+- ``Vagrantfile``: The Vagrant file that reads the inventory setup of ``inventory.yml`` and provisions the hosts that are required
+- ``inventory.yml``: Contains the hosts that are required and other connection information such as IP addresses and forwarded ports
+- ``main.yml``: Ansible playbook called by Vagrant to provision the domain controller and join the child hosts to the domain
+
+By default, these files will create the following environment:
+
+- A single domain controller running on Windows Server 2016
+- Five child hosts for each major Windows Server version joined to that domain
+- A domain with the DNS name ``domain.local``
+- A local administrator account on each host with the username ``vagrant`` and password ``vagrant``
+- A domain admin account ``vagrant-domain@domain.local`` with the password ``VagrantPass1``
+
+The domain name and accounts can be modified by changing the variables
+``domain_*`` in the ``inventory.yml`` file if it is required. The inventory
+file can also be modified to provision more or less servers by changing the
+hosts that are defined under the ``domain_children`` key. The host variable
+``ansible_host`` is the private IP that will be assigned to the VirtualBox host
+only network adapter while ``vagrant_box`` is the box that will be used to
+create the VM.
+
+Provisioning the Environment
+============================
+
+To provision the environment as is, run the following:
+
+.. code-block:: shell
+
+    git clone https://github.com/jborean93/ansible-windows.git
+    cd vagrant
+    vagrant up
+
+.. note:: Vagrant provisions each host sequentially so this can take some time
+    to complete. If any errors occur during the Ansible phase of setting up the
+    domain, run ``vagrant provision`` to rerun just that step.
+
+Unlike setting up a single Windows instance with Vagrant, these hosts can also
+be accessed using the IP address directly as well as through the forwarded
+ports. It is easier to access it over the host only network adapter as the
+normal protocol ports are used, e.g. RDP is still over ``3389``. In cases where
+the host cannot be resolved using the host only network IP, the following
+protocols can be access over ``127.0.0.1`` using these forwarded ports:
+
+- ``RDP``: 295xx
+- ``SSH``: 296xx
+- ``WinRM HTTP``: 297xx
+- ``WinRM HTTPS``: 298xx
+- ``SMB``: 299xx
+
+Replace ``xx`` with the entry number in the inventory file where the domain
+controller started with ``00`` and is incremented from there. For example, in
+the default ``inventory.yml`` file, WinRM over HTTPS for ``SERVER2012R2`` is
+forwarded over port ``29804`` as it's the fourth entry in ``domain_children``.
+
+.. note:: While an SSH server is available on all Windows hosts but Server
+    2008 (non R2), it is not a support connection for Ansible managing Windows
+    hosts and should not be used with Ansible.
 
 Windows new module development
 ==============================
@@ -96,7 +234,9 @@ they do:
 - ArgvParser: Utiliy used to convert a list of arguments to an escaped string compliant with the Windows argument parsing rules.
 - CamelConversion: Utility used to convert camelCase strings/lists/dicts to snake_case.
 - CommandUtil: Utility used to execute a Windows process and return the stdout/stderr and rc as separate objects.
+- FileUtil: Utility that expands on the ``Get-ChildItem`` and ``Test-Path`` to work with special files like ``C:\pagefile.sys``.
 - Legacy: General definitions and helper utilities for Ansible module.
+- LinkUtil: Utility to create, remove, and get information about symbolic links, junction points and hard inks.
 - SID: Utilities used to convert a user or group to a Windows SID and vice versa.
 
 For more details on any specific module utility and their requirements, please see the `Ansible