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
This commit is contained in:
Jordan Borean
GitHub
parent
a52fb20b54
commit
07e9df11b3
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue