Running the Puppet Debugging Kit on Windows

Up and running with Vagrant, VirtualBox and the Puppet Debugging Kit on Windows.

Why?

Running the Puppet Debugging Kit on Windows is fairly straightforward, in that the setup process is nearly identical to setup on OSX and Linux.

However, the typical "Vagrant on Windows" caveats apply.

I've attempted to cover the entire setup process here, going from a system with no virtualization tools installed, to a working Vagrant + Oscar + Puppet Debugging Kit environment

How?

Prerequisites

Tools

Install the following software, accepting all default options. In other words, just click next 😎

We'll also need Cygwin. See below.

Cygwin

Cygwin gets its own section because setup is slightly more complex.

Installers: https://cygwin.com/install.html NB: Either the 64 or 32-bit version is fine. I used the 64-bit version but it shouldn't matter.

Run the cygwin installer (setup-x86_64.exe in my case), and accept all defaults until you get to Select Local Package Directory.
Enter C:\cygwinpackages, or any other directory you like, for cygwin to download packages to prior to installing them. DO NOT accept the defaults, or you'll end up with all your packages downloaded to C:\Users\$yourname\Downloads.
Click Next, and if you are prompted to create the directory, click Yes.
You'll be prompted to configure a proxy on the next page. Choose the appropriate option and click next.

If your company does require a proxy and Internet Explorer is not configured to use it, and it requires credentials: Unfortunately the Cygwin installer does not support this scenario. We're only installing Cygwin to grab a command-line SSH binary. If you wish, you may try using the ones provided here — http://www.mls-software.com/opensshd.html

On the Choose a Download Site step, pick a mirror close to your location and click next. It can be hard to tell which mirror is the best or the closest just by looking. I tend to use:

http://cygwin.osuosl.org when I'm in Oregon.
http://mirrors.xmission.com when I'm anywhere else.

I also prefer HTTP mirrors over FTP, as outbound FTP tends to be blocked by corporate firewalls.

On the Select Packages screen, in the search box, type ssh, and after a few seconds, expand the Net list with the + icon. Then, next to the openssh package, click the word Skip once. All packages are "skipped" by default. Clicking on Skip toggles openssh into install mode. Once that's done, click next.
Once you're at the Resolving Dependencies page, click next.
The installation begins! Hurry up and wait! Once it completes...
Add Cygwin binaries to your path via your PowerShell profile:

Create or edit C:\Users\<YOUR USER NAME HERE>\Documents\WindowsPowerShell\profile.ps1
Append this line to it: $env:Path += ";C:\cygwin64\bin"
- Note that this may be different if you are using 32-bit cygwin.

Open a new PowerShell Prompt and ensure that the SSH client is accessible:

If you don't get that output, and get something like this instead, then you have not successfully added Cygwin binaries to your path:

Make sure you open a completely new PowerShell window after updating profile.ps1.

Sanity Checking

Before we move on, let's make sure our Vagrant + VirtualBox environment is generally functional.

VirtualBox

Open up VirtualBox, and click the New button to create a new VM. Choose any name at all for the VM, and then click next until it is created. No need to change any of the options.
Click on the test VM and then click Start
- If prompted to Select start-up disk just click Cancel.
- If a banner is displayed in the VM console window that says You have the auto capture keyboard option turned on, click the X symbol on the right hand side of the banner.
If you see a message in the VM's display similar to FATAL: No bootable medium found! System halted. then you're good to go! That's exactly what we'd expect a "new" computer with no OS installed to say.

If the VM won't boot at all, it's likely that your system's BIOS is configured to disable virtualization extensions built into the CPU (VT-d, VT-x, etc). You'll need to ensure these are not disabled in your BIOS settings. They're labeled differently on every type of computer, so you'll have to do some exploration here.

At this point you can shut down the test VM and then delete it completely.

Vagrant

We're going to create a test Vagrant environment that will:

Download a CentOS 6.6 x64 image
Import it into VirtualBox
Boot it up
Give us SSH Access

This process will require about 3 GB of free disk space to complete.

Open up a PowerShell prompt and run the following commands:

mkdir C:\Working\Vagrant\testenv
cd C:\Working\Vagrant\testenv
vagrant init puppetlabs/centos-6.6-64-nocm
vagrant up

This may take some time to complete, as the CentOS 6.6 x64 image is downloaded from the internet.

If vagrant up fails at the step where it downloads the box, and you are behind a corporate proxy, you may need to configure vagrant to use the proxy for internet access. Justin James has a decent write-up on the configuration involved: http://digitaldrummerj.me/vagrant-behind-proxy-server/

Still inside C:\Working\Vagrant\testenv, run vagrant ssh. If you get a BASH prompt inside PowerShell, then everything is working!
At this point you can vagrant destroy --force to destroy the test environment.

Overall, the process should look like this:

Puppet Debugging Kit Setup

This section assumes that all steps in previous sections have been completed.

Install Oscar, Grab a copy of the puppet-debugging-kit and create a basic configuration:

vagrant plugin install oscar
cd C:\Working\Vagrant
git clone https://github.com/Sharpie/puppet-debugging-kit.git
cd puppet-debugging-kit\config
cp vms.yaml.example vms.yaml

Optionally Set up PE installers:

Note: If many people at your organization may end up using the PDK, you might wish to skip this step and follow the next one instead, to save on bandwidth. Either this step OR the next one must be completed.

Copy the installer tarball for the version of PE you wish to use to C:\Users\<your-user-name>\.vagrant.d\pe_builds.

You could probably map the above directory to a shared drive, although this has not been tested.

Optionally configure pe_build:

Note: If you are copying PE installers to the pe_builds directory as described in the previous step, you do NOT need to complete this one. Either this step OR the previous one must be completed.

If you wish to automatically download installers ad-hoc from a central source, you can configure pe_build.yaml. In the same config directory, create a pe_build.yaml file, if you wish to automatically download PE installers ad-hoc:

pe_build.yaml expects to be supplied with URL (or local path) to PE Installer tarballs, to use for installation.

Here's an example:

---
pe_build:
  download_root: 'http://zee.space/puppet-enterprise/:version'

:version corresponds to a directory full of installers for the version of PE we're looking for.

For example, if I wanted the PDK to install PE 2016.2.0 on RHEL 6 x64, this would translate to a download target of: http://zee.space/puppet-enterprise/2016.2.0/puppet-enterprise-2016.2.0-el-6-x86_64.tar.gz

If I wanted it to install PE 3.8.5 on RHEL 7 x64, this would translate to a download URL of: http://zee.space/puppet-enterprise/3.8.5/puppet-enterprise-3.8.5-el-6-x86_64.tar.gz

Note: Technically, pe_build can take a local path instead of a URL, but I've been unable to make that work on Windows.

At this point I should be good to go. Let's give it a spin!

I'll be installing PE 2016.2.0 to a CentOS 6 x64 vm, so I've placed puppet-enterprise-2016.2.0-el-6-x86_64.tar.gz in C:\Users\<your-user-name>\.vagrant.d\pe_builds

PS C:\Working\Vagrant\puppet-debugging-kit> vagrant status
Current machine states:

pe-201620-master          not created (virtualbox)
pe-201620-agent           not created (virtualbox)
pe-385-master             not created (virtualbox)
pe-385-agent              not created (virtualbox)

PS C:\Working\Vagrant\puppet-debugging-kit> vagrant up pe-201620-master
Bringing machine 'pe-201620-master' up with 'virtualbox' provider...
==> pe-201620-master: Preparing master VM for linked clones...
    pe-201620-master: This is a one time operation. Once the master VM is prepared,
    pe-201620-master: it will be used as a base for linked clones, making the creation
    pe-201620-master: of new VMs take milliseconds on a modern system.
==> pe-201620-master: Importing base box 'puppetlabs/centos-6.6-64-nocm'...
==> pe-201620-master: Cloning VM...
==> pe-201620-master: Matching MAC address for NAT networking...
==> pe-201620-master: Checking if box 'puppetlabs/centos-6.6-64-nocm' is up to date...
==> pe-201620-master: Setting the name of the VM: puppet-debugging-kit_pe-201620-master_1467767909252_25633
==> pe-201620-master: Clearing any previously set network interfaces...
==> pe-201620-master: Preparing network interfaces based on configuration...
    pe-201620-master: Adapter 1: nat
    pe-201620-master: Adapter 2: hostonly
==> pe-201620-master: Forwarding ports...
    pe-201620-master: 443 (guest) => 4443 (host) (adapter 1)
    pe-201620-master: 22 (guest) => 2222 (host) (adapter 1)
==> pe-201620-master: Running 'pre-boot' VM customizations...
==> pe-201620-master: Booting VM...
==> pe-201620-master: Waiting for machine to boot. This may take a few minutes...
  pe-201620-master: SSH address: 127.0.0.1:2222
  pe-201620-master: SSH username: vagrant
  pe-201620-master: SSH auth method: private key
  pe-201620-master: Warning: Remote connection disconnect. Retrying...
  pe-201620-master: Warning: Remote connection disconnect. Retrying...
  pe-201620-master: Warning: Remote connection disconnect. Retrying...
==> pe-201620-master: Machine booted and ready!
==> pe-201620-master: Checking for guest additions in VM...
==> pe-201620-master: Setting hostname...
==> pe-201620-master: Configuring and enabling network interfaces...
==> pe-201620-master: Mounting shared folders...
  pe-201620-master: /vagrant => C:/Working/Vagrant/puppet-debugging-kit
==> pe-201620-master: Running provisioner: base networking (hosts)...
==> pe-201620-master: Running provisioner: shell...
  pe-201620-master: Running: inline script
==> pe-201620-master: Running provisioner: shell...
  pe-201620-master: Running: inline script
==> pe-201620-master: iptables: Setting chains to policy ACCEPT: filter
==> pe-201620-master: [  OK  ]
==> pe-201620-master: iptables: Flushing firewall rules:
==> pe-201620-master: [  OK  ]
==> pe-201620-master: iptables: Unloading modules:
==> pe-201620-master: [  OK  ]
==> pe-201620-master: Running provisioner: file...
==> pe-201620-master: Running provisioner: shell...
  pe-201620-master: Running: inline script
==> pe-201620-master: Running provisioner: pe_bootstrap...

And awaaaaayyyyy we go!

Installation

Completion

** PE Console**

When the installation is complete, you will be able to access the console via https://localhost:4443, username admin, password puppetlabs. You can also bring up agents and they will automatically be configured to talk to the right master, based on node-name. E.g. pe-201620-agent will automatically be connected to pe-201620-master.

For general configuration of the stack, check out the Oscar documentation. Oscar provides most of the base functionality: https://github.com/oscar-stack/oscar

The rest (for example, automatically assigning the right Oscar roles based on nodename) comes from the Puppet Debugging Kit. For Puppet Debugging Kit-specific features and docs, see: https://github.com/Sharpie/puppet-debugging-kit

For general Vagrant configuration and use, including a tutorial, see: https://www.vagrantup.com/docs/

Thanks

There's basically no original work in this document, just a collection of information I've gathered from others. h/t to @Sharpie and @adrienthebo.

big-samantha/Puppet Debugging Kit on Windows.md