(BKR-1485) Update documentation (#6)

* (BKR-1485) Update documentation Thoroughly document acceptance testing environment configuration. [skip ci] * (BKR-1485) Autolinks don't work on local URIs :( * (BKR-1485) Minor formatting cleanup * (BKR-1485) Fix path reference * (BKR-1485) Take 2 * (BKR-1485) More Paths
voxpupuli · Jul 16, 2018 · 761d963 · 761d963
1 parent 5b31600
commit 761d963
Show file tree

Hide file tree

Showing 6 changed files with 303 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ Beaker library to use vmware fusion hypervisor
 
 # How to use this wizardry
 
-This gem that allows you to use hosts with [vmware_fusion](vmware_fusion.md) and [vsphere](vsphere.md) hypervisor with [beaker](https://github.com/puppetlabs/beaker). 
+This gem allows you to use hosts with [vmware_fusion](vmware_fusion.md) and [vsphere](vsphere.md) hypervisor with [beaker](https://github.com/puppetlabs/beaker).
 
 ### Right Now? (beaker 3.x)
 
@@ -20,15 +20,17 @@ next to beaker itself.
 # Spec tests
 
 Spec test live under the `spec` folder. There are the default rake task and therefore can run with a simple command:
-```bash
-bundle exec rake test:spec
+
+```console
+$ bundle exec rake test:spec
 ```
 
 # Acceptance tests
 
-We run beaker's base acceptance tests with this library to see if the hypervisor is working with beaker. Please refer to the setting up [vmware fusion](vmware_fusion.md) docs to setup your hosts for testing and modify the [test-nodes hosts](acceptance/config/nodes/test-nodes.yml) file. Once that's setup, there is a simple rake task to invoke acceptance test for the library:
-```bash
-bundle exec rake test:acceptance
+We run beaker's base acceptance tests with this library to see if the hypervisor is working with beaker. You can run the acceptance tests locally; see [Acceptance Setup](/docs/acceptance_setup.md). Once that's setup, there is a simple rake task to invoke acceptance test for the library:
+
+```console
+$ bundle exec rake test:acceptance
 ```
 
 # Contributing

diff --git a/acceptance/config/nodes/test-nodes.yml b/acceptance/config/nodes/test-nodes.yml
@@ -1,5 +1,5 @@
 HOSTS:
-  ubuntu.local:
+  beaker-ubuntu.local:
     roles:
       - master
       - agent
@@ -10,7 +10,7 @@ HOSTS:
     vmname: ubuntu-1604-64
     hypervisor: fusion
     snapshot: clear-keys
-  ubuntu2.local:
+  beaker-ubuntu2.local:
     roles:
       - agent
     platform: ubuntu-1604-amd64

diff --git a/beaker-vmware.gemspec b/beaker-vmware.gemspec
@@ -28,6 +28,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'rake', '~> 10.1'
   s.add_development_dependency 'simplecov'
   s.add_development_dependency 'pry', '~> 0.10'
+  s.add_development_dependency 'beaker', '~> 3.0'
 
   # Documentation dependencies
   s.add_development_dependency 'yard'

diff --git a/docs/acceptance_setup.md b/docs/acceptance_setup.md
@@ -0,0 +1,104 @@
+Setting up a local environment for running beaker-vmware's acceptance tests is as follows. This is just Beaker's core acceptance tests run against local VMWare Fusion VMs.
+
+# Configure Acceptance Testing VMs
+
+First, provision a base VM to clone for testing. Currently, tests are confirmed to pass on a vanilla Ubuntu 16.04 installation. However, any host supported by Beaker should be suitable. There are no prerequisite libraries and the only special configuration is to enable passwordless SSH access for root.
+
+## Provision a Base VM
+
+These instructions cover provisioning a Ubuntu 16.04 VM:
+
+1. Download [a Ubuntu 16.04 64-bit ISO](http://releases.ubuntu.com/16.04/).
+2. Create a new VMWare Virtual Machine for it, named `beaker-ubuntu-1604-64`.
+3. Run the OS installation. Default settings should be adequate. Name the main user whatever you want; testing relies on passwordless root login so this is unimportant.
+4. Install and configure OpenSSH on the VM:
+    ~~~console
+    $ sudo su -
+    root@host $ apt-get install openssh-server
+    root@host $ nano /etc/ssh/sshd_config
+    # Add/uncomment/modify the following lines:
+    PasswordAuthentication yes
+    PermitRootLogin without-password
+    RSAAuthentication yes
+    PubkeyAuthentication yes
+    root@host $ service ssh restart
+    ~~~
+5. Disable automatic package updates so they don't block test running. This can be accomplished easily from the UI: System Settings > Software & Updates > Updates > Automatically check for updates: "Never".
+
+## Configure Testing VMs
+
+These instructions cover provisioning the two testing VMs with a new public key for SSH access. We need two instances of the base VM, `beaker-ubuntu-1604-64` and `beaker-ubuntu-1604-64-2`:
+
+1. You can use the base VM configuration as the first SUT to save space.
+2. Configure a static IP for the VM. See [fusion_static_ip.md](fusion_static_ip.md).
+3. Add an entry in /etc/hosts: `<static ip> beaker-ubuntu.local`.
+4. Set Up password-less SSH access:
+    - Generate a new SSH key *without a passphrase*:
+        ~~~console
+        $ ssh-keygen -t rsa -b 4096 -C "you@example.com"
+        # Give this a descriptive name, e.g. "id_rsa-beaker-ubuntu"
+        # Make sure to leave passphrase blank (just hit return at prompt)
+        ~~~
+    - Add it to your local keychain:
+        ~~~console
+        $ ssh-add -i ~/.ssh/id_rsa-beaker-ubuntu
+        ~~~
+    - Add your SSH key to the VM's authorized keys:
+        ~~~console
+        $ ssh-copy-id puppetlabs@beaker-ubuntu.local
+        $ ssh puppetlabs@beaker-ubuntu.local
+        ~~~
+    - And then copy to root's `authorized_keys`:
+        ~~~console
+        $ ssh puppetlabs@beaker-ubuntu.local
+        puppetlabs@beaker-ubuntu.local $ sudo cp ~/.ssh/authorized_keys /root/.ssh/authorized_keys
+        ~~~
+    - Ensure that you can SSH in without password, e.g.:
+        ~~~console
+        $ ssh root@beaker-ubuntu.local
+        ~~~
+5. Create a new snapshot (of the running VM) in VMWare Fusion: with the VM selected, Virtual Machine > Snapshots... > Take Snapshot (Cmd-Shift-S). Name this new snapshot `clear-keys`. This snapshot name is used in [acceptance/config/nodes/test-nodes.yml](/acceptance/config/nodes/test-nodes.yml); when beaker provisions a VMWare host it restores it to a specified snapshot.
+6. Clone the second testing VM from this snapshot.
+    1. Right Click > "Create Full Clone" named `beaker-ubuntu-1604-64-2`.
+    2. Resume the clone and note the MAC address: VM > Settings > Network > Advanced. Make sure it's different from the original.
+    3. Configure a new static IP for this VM. See [fusion_static_ip.md](fusion_static_ip.md) again.
+    4. Add another entry in `/etc/hosts`: `<static ip> beaker-ubuntu2.local`.
+    5. Create a new snapshot named `clear-keys`.
+
+# Configure Fission
+
+Although originally written for VMWare Fusion 3.x, the Ruby Gem Fission which we use to configure VMWare Fusion VMs appears to work just fine with 10.x. All that is required is changing the local configuration to point to the CLI tools and VM datastore. Create `~/.fissionrc`:
+
+~~~yaml
+vm_dir: "/Users/<your user name>/Documents/Virtual Machines.localized/" # or whereved you've decided to store your `.vmwarevm` files
+vmrun_bin: "/Applications/VMware Fusion.app/Contents/Library/vmrun"
+~~~
+
+# DHCP/VMnet Issues
+
+If you have problems with DHCP leases not being issued automatically when a VM is booted or resumed, and manually restarting vmnet makes it work, follow debugging directions in [Debugging](fusion_static_ip.md#debugging).
+
+# Test Failures
+
+If you get test failures related to package installation, e.g.:
+
+~~~
+E: Could not get lock /var/lib/dpkg/lock - open (11: Resource temporarily unavailable)
+E: Unable to lock the administration directory (/var/lib/dpkg/), is another process using it?>
+~~~
+
+It's probably the VM's automatic upgrades running. Log in and check:
+
+~~~console
+$ sudo lsof /var/lib/dpkg/lock
+COMMAND    PID USER   FD   TYPE DEVICE SIZE/OFF   NODE NAME
+unattende 2441 root    4uW  REG    8,1        0 671664 /var/lib/dpkg/lock
+$ ps -p 2441 -o command=
+/usr/bin/python3 /usr/bin/unattended-upgrade # yep, autoupdate
+~~~
+
+Turn those off if you haven't already; they'll get run on the first resume during every update period (default: daily) and cause your tests to fail. Don't forget to update the `clear-keys` snapshot after you make configuration changes in the testing VMs.
+
+# Helpful References
+
+- Passwordless root ssh on Ubuntu: https://askubuntu.com/a/115323
diff --git a/docs/fusion_static_ip.md b/docs/fusion_static_ip.md
@@ -0,0 +1,187 @@
+# Setting Static IP on VMWare Fusion 10
+
+> Note: this guide last updated 20 June 2018, VMWare Fusion Professional Version 10.1.2 (8502123) on macOS High Sierra 10.13.5 (17F77)
+
+> Based on: http://henokmikre.com/blog/2015/09/vmware-static-ip
+
+Beaker expects hosts to be accessible by hostname with passwordless root access via SSH. This guide covers setting a static IP and local hostname on a VMWare Fusion guest.
+
+## Basics
+
+VMWare Fusion network configuration files are stored in:
+
+~~~
+/Library/Preferences/VMware Fusion/
+~~~
+
+These configurations are divided into folders by virtual networking device. In the base configuration, without any custom networking devices defined, the directory structure looks like this:
+
+~~~
+VMware Fusion/
+    thnuclnt/                       # virtual print server configuration
+        .thnumod
+        manifest
+        thnuclnt
+        thnuclnt.conf
+        thnuclnt.convs
+        thnuclnt.types
+        thnucups
+        thnusetup.sh
+    vmnet1/
+        dhcpd.conf                  # dhcp daemon configuration
+    vmnet8/
+        dhcpd.conf                  # dhcp daemon configuration
+        nat.conf                    # nat configuration
+        nat.mac                     # list of used VM mac addresses
+    lastLocationUsed                # path to "VMWare Fusion.app" last run
+    license-fusion-100-e4-201704    # license file
+    networking                      # network configuration check file
+~~~
+
+Virtual networks are called `vmnet<num>`:
+
+`vmnet1`:
+- is the default private (host-only) network
+- called "Private to my Mac" in VM > Network configuration
+- DHCP range 172.16.233.128 to 172.16.233.254
+
+`vmnet8`:
+- is the default public (NAT-enabled) network
+- called "Share with my Mac"
+- DHCP range 192.168.176.128 192.168.176.254
+
+Every VMWare-generated `dhcpd.conf` file is auto-generated and contains a clearly labeled section for private use, with instructions for custom configuration. Here's an example:
+
+~~~
+# Configuration file for ISC 2.0 vmnet-dhcpd operating on vmnet8.
+#
+# This file was automatically generated by the VMware configuration program.
+# See Instructions below if you want to modify it.
+#
+# We set domain-name-servers to make some DHCP clients happy
+# (dhclient as configured in SuSE, TurboLinux, etc.).
+# We also supply a domain name to make pump (Red Hat 6.x) happy.
+#
+
+
+###### VMNET DHCP Configuration. Start of "DO NOT MODIFY SECTION" #####
+# Modification Instructions: This section of the configuration file contains
+# information generated by the configuration program. Do not modify this
+# section.
+# You are free to modify everything else. Also, this section must start 
+# on a new line 
+# This file will get backed up with a different name in the same directory 
+# if this section is edited and you try to configure DHCP again.
+
+# Written at: 06/20/2018 14:34:59
+allow unknown-clients;
+default-lease-time 1800;                # default is 30 minutes
+max-lease-time 7200;                    # default is 2 hours
+
+subnet 192.168.176.0 netmask 255.255.255.0 {
+    range 192.168.176.128 192.168.176.254;
+    option broadcast-address 192.168.176.255;
+    option domain-name-servers 192.168.176.2;
+    option domain-name localdomain;
+    default-lease-time 1800;                # default is 30 minutes
+    max-lease-time 7200;                    # default is 2 hours
+    option netbios-name-servers 192.168.176.2;
+    option routers 192.168.176.2;
+}
+host vmnet8 {
+    hardware ethernet 00:50:56:C0:00:08;
+    fixed-address 192.168.176.1;
+    option domain-name-servers 0.0.0.0;
+    option domain-name "";
+    option routers 0.0.0.0;
+}
+####### VMNET DHCP Configuration. End of "DO NOT MODIFY SECTION" #######
+~~~
+
+## Modifying `dhcpd.conf`
+
+These configuration files can contain customizations. All custom configuration lines should be written *outside* of the clearly labeled private section. It's not clear if they can safely be placed above this section, so I recommend only placing them below it.
+
+You shouldn't try to override the `subnet` configuration directive. See [Modifying the DHCP settings of vmnet1 and vmnet8 in Fusion (1026510)
+](https://kb.vmware.com/s/article/1026510). Tl;DR: change settings in the private area (e.g. netmask and subnet) by modifying `networking`.
+
+You can, however, provide new `host` directives. This is what we want to do. As far as I can tell, the syntax is like such:
+
+~~~
+host <host id> {
+    <command with args>;
+}
+~~~
+
+Known configuration directives:
+
+~~~
+hardware ethernet <mac address>;
+fixed-address <ipv4 address>;
+option domain-name-servers <ipv4 address>;
+option domain-name "string";
+option routers <ipv4 address>;
+~~~
+
+## Setting a Static IP for a VM
+
+1. Gather VM configuration information
+    1. Hostname: VM > Settings > General > name. I don't know what restrictions there are on VM names, so recommend the safe approach of ensuring that you set the VM name only once, upon creation, and only use safe characters like `[a-z0-9\-]`. If you have special characters or spaces, it may be possible to quote the hostname but I haven't tested that. According to [this VMWare forum post](https://communities.vmware.com/message/2730360#2730360), spaces should be stripped. E.g. "Windows 8" becomes "Windows8".
+    2. Virtual network name: VM > Settings > Network. "Share with my Mac" is `vmnet8`, "Private to my Mac" is `vmnet1`.
+    3. MAC address: VM > Settings > Network > Advanced
+3. Edit the appropriate `dhcpd.conf` in `/Library/Preferences/VMware Fusion/<virtual network name>/dhcpd.conf`. Take note of the line that looks like (last checked: line 27):
+    ~~~
+    range 192.168.176.128 192.168.176.254;
+    ~~~
+    As this specifies the DHCP reservation range. We must select an IP **outside** of this range. Add the following:
+    ~~~
+    host <hostname> {
+        hardware ethernet <host mac>;
+        fixed-address <static ip>;
+    }
+    ~~~
+4. Regenerate the configuration files and restart the virtual networking stack:
+    ~~~console
+    $ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --configure
+    $ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --stop
+    $ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --start
+    ~~~
+    Note: pretty sure VMWare and even the target VM can be running while you do this.
+
+Complete example, to set fixed IP address of `192.168.176.127` on host `ubuntu-1604-64` with MAC `192.168.176.127`:
+
+~~~console
+$ sudo tee -a "/Library/Preferences/VMware Fusion/vmnet8/dhcpd.conf" <<EOF
+host ubuntu-1604-64 {
+    hardware ethernet 00:0C:29:C5:28:82;
+    fixed-address 192.168.176.127;
+}
+EOF
+$ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --configure
+$ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --stop
+$ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --start
+~~~
+
+### Debugging
+
+If your VMs don't get DHCP leases and VMWare Fusion > Preferences > Network settings is greyed out (and you don't want to restart your machine).
+- Quit Fusion
+- Stop networking from the CLI
+- Look for any leftover processes to kill
+
+~~~console
+# Quit VMWare Fusion from the GUI first, then:
+$ sudo /Applications/VMware\ Fusion.app/Contents/Library/vmnet-cli --stop
+$ ps aux | grep vm
+root             90722   0.0  0.0  4377632   3096   ??  Ss    2:15PM   0:00.44 /Library/PrivilegedHelperTools/com.vmware.KextControlHelper
+root             90721   0.0  0.0  4377632   3140   ??  Ss    2:15PM   0:00.22 /Library/PrivilegedHelperTools/com.vmware.VMMonHelper
+root             90589   0.0  0.0  4387172    840   ??  S     2:15PM   0:00.06 /Applications/VMware Fusion.app/Contents/Library/vmnet-bridge
+dakota.schneider 11615   0.0  0.0  4267768   1024 s011  S+   10:30AM   0:00.00 grep --color=auto --exclude-dir=.bzr --exclude-dir=CVS --exclude-dir=.git --exclude-dir=.hg --exclude-dir=.svn vm
+$ sudo kill -9 90589
+~~~
+
+Now restart Fusion. If you can access VMWare Fusion > Preferences > Network list (it's not greyed out), then your VMs should get DHCP without having to manually restart vmnet after boot or resume.
+
+## Edit `/etc/hosts`
+
+The acceptance tests rely on using hostnames. We need one machine `beaker-ubuntu.local` and one `beaker-ubuntu2.local`, or whatever matches the hostnames in `acceptance/config/nodes/test-nodes.yml`.
diff --git a/vmware_fusion.md b/vmware_fusion.md
@@ -9,7 +9,7 @@ You can then use the following arguments in the node configuration:
 - `hypervisor: fusion` tells us to enable this feature for this host. This is required.
 - `snapshot: <name>`, where <name> is the snapshot name to revert to.  This is required.
 
-We'll try and match up the hostname with a VM of the same name. Note that the VM is expected to be pre-configured for running acceptance tests; it should have all the right prerequisite libraries, password-less SSH access for root, etc.
+We'll try and match up the hostname with a VM of the same name. Note that the VM is expected to be pre-configured for running acceptance tests: a vanilla OS install with internet access and password-less SSH access for root is all that is required.
 
 There are a few additional options available in your configuration file. Each host
 section can now use: