* 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
@ -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