beaker 2.27.0 → 2.28.0

data/docs/Beaker-with-Masterless-Puppet.md

@@ -0,0 +1,42 @@
+# Overview
+
+## What is masterless Puppet?
+
+Masterless Puppet is a common way of running Puppet where you might have a number of Puppet Agents, but no hosts running under any other roles (master, dashboard, database, default).
+
+## Why Would You Want to Do This?
+
+A few examples of common situations where running masterless Puppet would be useful are below:
+
+- Testing modules against Windows.  Traditionally, a non-Windows master would be required, but is really just needless overhead in this case.
+- running Puppet to provision hosts, only running it the once, using `puppet agent`, and then providing it to your users
+
+## How Do I Run Masterless?
+
+In order to have Beaker support a masterless Puppet setup, you have to do a few things:
+
+1. include the `masterless: true` flag in the `CONFIG` section of your hosts file
+2. Make sure the roles are correct for the hosts now. You'll want to make sure a host doesn't have a role that it won't be able to fulfill
+3. Run Beaker just like you normally would
+
+# Under the Hood
+
+## What is Beaker Doing by Default?
+
+Be default (without the masterless flag), when someone calls for a host of a particular role, using the `Beaker::DSL::Roles` module's methods (ie. `master`, `dashboard`, etc), Beaker checks to verify that a host was given with that role.
+
+If no host was given with this role, then Beaker throws a `DSL::Outcomes::FailTest` Error, which causes that test case to fail.
+
+## What Does This Flag Do?
+
+Inside Beaker, when you call `Beaker::DSL::Roles` module's methods with the masterless flag set, Beaker will allow there to be hosts which don't fit defined roles.  If a host can't be found for a particular role, that role method will now return `nil`.
+
+If you'd like to test both masterless and not, you'll have to deal with a role method potentially returning `nil`.
+
+## How Do I Avoid Issues With This?
+
+You can make it so that a test will only run if we're not running masterless with this line:
+
+    confine :to, :masterless => false
+
+and vice versa.

data/docs/Creating-A-Test-Environment.md

@@ -0,0 +1,91 @@
+Hosts/Nodes/SUTs are defined in the --hosts (--config) file in Yaml format.  This file defines each node in the test configuration. The file can be saved anywhere and used with `beaker --hosts yourhost.cfg` see [The Command Line](The-Command-Line.md) for more info.
+
+Example hosts file:
+
+    HOSTS:
+      ubuntu-1404-x64-master:
+        roles:
+          - master
+          - agent
+          - dashboard
+          - database
+        platform: ubuntu-1404-x86_64
+        hypervisor: vagrant
+        box: puppetlabs/ubuntu-14.04-64-nocm
+        box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
+        ip: 192.168.20.20
+      ubuntu-1404-x64-agent:
+        roles:
+          - agent
+        platform: ubuntu-1404-x86_64
+        hypervisor: vagrant
+        box: puppetlabs/ubuntu-14.04-64-nocm
+        box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
+        ip: 192.168.21.21
+    CONFIG:
+      nfs_server: none
+      consoleport: 443
+
+## Host Requirements ##
+Hosts, or SUTs (Systems Under Test), must meet the following requirements:
+* The SUT will need a properly configured network, hosts will need to be able to reach each other by hostname.
+* On the SUT, you must configure passwordless SSH authentication for the root user.
+* The SUT must have the `ntpdate` binary installed.
+* The SUT must have the `curl` binary installed.
+* On Windows, `Cygwin` must be installed (with `curl`, `sshd`, `bash`) and the necessary windows gems (`sys-admin`, `win32-dir`, etc).
+* FOSS install: you must have `git`, `ruby`, and `rdoc` installed on your SUT.
+
+## Required Host Settings ##
+To properly define a host you must provide:
+
+* name
+  * The string identifying this host.
+* platform
+  * One of the Beaker supported platforms.
+
+## Optional Host Settings ##
+Additionally, Beaker supports the following host options:
+
+* ip
+  * The IP address of the SUT.
+* hypervisor
+  * One of `docker`, `solaris`, `ec2`, `vsphere`, `fusion`, `aix`, `vcloud` or `vagrant`.
+  * Additional settings may be required depending on the selected hypervisor (ie, template, box, box_url, etc).  Check the documentation below for your hypervisor for details.
+* snapshot
+  * The name of the snapshot to revert to before testing.
+* roles
+  * The 'job' of this host, an array of `master`, `agent`, `frictionless`, `dashboard`, `database`, `default` or any user-defined string.
+* pe_dir
+  * The directory where PE builds are located, may be local directory or a URL.
+* pe_ver
+  * The version number of PE to install.
+* vagrant_memsize
+  * The memory size (in MB) for this host
+
+## Supported Platforms ##
+Beaker depends upon each host in the configuration file having a platform type that is correctly formatted and supported.  The platform is used to determine how various operations are carried out internally (such as installing packages using the correct package manager for the given operating system).
+
+The platform's format is `/^OSFAMILY-VERSION-ARCH.*$/` where `OSFAMILY` is one of:
+
+* fedora
+* debian
+* oracle
+* scientific
+* sles
+* ubuntu
+* windows
+* solaris
+* aix
+* el (covers centos, redhat and enterprise linux)
+
+`VERSION`'s format is not enforced, but should reflect the `OSFAMILY` selected (ie, ubuntu-1204-i386-master, scientific-6-i386-agent, etc).  `ARCH`'s format is also not enforced, but should be appropriate to the `OSFAMILY` selected (ie, ubuntu-1204-i386-master, sles-11-x86_64-master, debian-7-amd64-master, etc).
+
+## Supported Virtualization Providers ##
+* [VMWare Fusion](VMWare-Fusion-Support.md)
+* [EC2](EC2-Support.md)
+* [vSphere](vSphere-Support.md)
+* [Vagrant](Vagrant-Support.md)
+* [Google Compute Engine](Google-Compute-Engine-Support.md)
+* [Docker Support](Docker-Support.md)
+* [Openstack](Openstack-Support.md)
+* [Solaris](Solaris-Support.md)

data/docs/Docker-Support.md

@@ -0,0 +1,129 @@
+This option allows for testing against Docker containers.
+
+
+### Why?
+
+Using docker as a hypervisor significantly speeds up the provisioning process, as you don't have to spin up an entire VM to run the tests, which has significant overhead.
+
+### How?
+
+So first of all, install Docker using the instructions [here](https://docs.docker.com/installation/#installation).
+
+In the real world, it's generally seen as [bad practice to have sshd running in a Docker container](http://blog.docker.com/2014/06/why-you-dont-need-to-run-sshd-in-docker/). However, for the purpose of a disposable test instance, we're not going to worry about that!
+
+### Basic docker hosts file ###
+The base image to use for the container is named by the image key.
+
+    HOSTS:
+      ubuntu-12-10:
+        platform: ubuntu-12.10-x64
+        image: ubuntu:12.10
+        hypervisor: docker
+    CONFIG:
+      type: foss
+
+### Docker hosts file, with image modification ###
+You can specify extra commands to be executed in order to modify the image with the `docker_image_commands` key.
+
+    HOSTS:
+      ubuntu-12-10:
+        platform: ubuntu-12.10-x64
+        image: ubuntu:12.10
+        hypervisor: docker
+        docker_image_commands:
+          - 'apt-get install -y myapp'
+          - 'myapp --setup'
+    CONFIG:
+      type: foss
+
+### Docker hosts files, with modified start commands ###
+By default the docker container just runs an sshd which is adequate for 'puppet apply' style testing. You can specify a different command to start with the `docker_cmd` key. This gives you scope to run something with more service supervision baked into it, but it is is important that this command starts an sshd listening on port 22 so that beaker can drive the container.
+
+    HOSTS:
+      ubuntu-12-10:
+      platform: ubuntu-12.10-x64
+      image: ubuntu:12.10
+      hypervisor: docker
+      docker_cmd: '["/sbin/init"]'
+    CONFIG:
+      type: foss
+
+### Preserve Docker Image ###
+Unless the image configuration changes you might want to keep the Docker image for multiple spec runs. Use `docker_preserve_image` option for a host.
+
+    HOSTS:
+      ubuntu-12-10:
+      platform: ubuntu-12.10-x64
+      image: ubuntu:12.10
+      hypervisor: docker
+      docker_preserve_image: true
+    CONFIG:
+      type: foss
+
+### Reuse Docker Image ###
+In case you want to rerun the puppet again on the docker container, you can pass BEAKER_provision=no on the command line to set the env. Add this line in you default.ml file
+
+```
+HOSTS:
+  centos6-64:
+    roles:
+     - agent
+    platform: el-6-x86_64
+    image: centos:6.6
+    hypervisor: docker
+CONFIG:
+  type: foss
+  log_level: verbose
+ssh:
+  password: root
+  auth_methods: ["password"]
+```
+
+### Example Output
+
+For this example made a new docker nodeset file in the [puppetlabs-inifile](https://github.com/puppetlabs/puppetlabs-inifile) repo and ran the ini_setting_spec.rb spec:
+
+```bash
+$ bundle exec rspec spec/acceptance/ini_setting_spec.rb
+Hypervisor for debian-7 is docker
+Beaker::Hypervisor, found some docker boxes to create
+Provisioning docker
+provisioning debian-7
+Creating image
+Dockerfile is         FROM debian:7.4
+          RUN apt-get update
+          RUN apt-get install -y openssh-server openssh-client curl ntpdate lsb-release
+        RUN mkdir -p /var/run/sshd
+        RUN echo root:root | chpasswd
+RUN apt-get install -yq lsb-release wget net-tools ruby rubygems ruby1.8-dev libaugeas-dev libaugeas-ruby ntpdate locales-all
+RUN REALLY_GEM_UPDATE_SYSTEM=1 gem update --system --no-ri --no-rdoc
+        EXPOSE 22
+        CMD ["/sbin/init"]
+```
+
+This step may take a while, as Docker will have to download the image. The subsequent runs will be a lot faster (as long as `docker_preserve_image: true` has been enabled).
+
+For example, running this took 5 minutes to download and setup the `debian:7.4` image, but runs instantly the second time.
+
+You should then see something like:
+
+```
+Creating container from image 3a86e5aba94d
+post
+/v1.15/containers/create
+{}
+{"Image":"3a86e5aba94d","Hostname":"debian-7"}
+Starting container b8b31702b34b4aedd137c8a6a72fe730560bb00533e68764ba6263405f9244e4
+post
+/v1.15/containers/b8b31702b34b4aedd137c8a6a72fe730560bb00533e68764ba6263405f9244e4/start
+{}
+{"PublishAllPorts":true,"Privileged":true}
+Using docker server at 192.168.59.103
+get
+/v1.15/containers/b8b31702b34b4aedd137c8a6a72fe730560bb00533e68764ba6263405f9244e4/json
+{}
+
+node available as  ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@192.168.59.103 -p 49155
+```
+
+The tests should then run as normal from there.

data/docs/EC2-Support.md

@@ -0,0 +1,77 @@
+Pre-requisite: .fog file correctly configured with your credentials.
+
+hypervisor: ec2
+
+### example .fog file ###
+    :default:
+      :aws_access_key_id: IMTHEKEYID
+      :aws_secret_access_key: IMALONGACCESSKYE
+
+### Basic ec2 hosts file ###
+    HOSTS:
+      centos-5-64-1:
+        roles:
+          - master
+          - dashboard
+          - database
+          - agent
+        vmname: centos-5-x86-64-west
+        platform: el-5-x86_64
+        hypervisor: ec2
+        amisize: c1.medium
+        snapshot: pe
+      centos-5-64-1:
+        roles:
+          - agent
+        vmname: centos-5-x86-64-west
+        platform: el-5-x86_64
+        hypervisor: ec2
+        amisize: c1.medium
+        snapshot: pe
+    CONFIG:
+      nfs_server: none
+      consoleport: 443
+
+Currently, there is limited support EC2 nodes; we are adding support for new platforms shortly.
+
+AMIs are built for PE based installs on:
+  - Enterprise Linux 6, 64 and 32 bit
+  - Enterprise Linux 5, 32 bit
+  - Ubuntu 10.04, 32 bit
+
+Beaker will automagically provision EC2 nodes, provided the 'platform:' section of your config file lists a supported platform type: ubuntu-10.04-i386, el-6-x86_64, el-6-i386, el-5-i386.
+
+### Supported EC2 Variables ###
+These variables can either be set per-host or globally.
+####`additional_ports`####
+Ports to be opened on the instance, in addition to those opened by Beaker to support Puppet functionality.  Can be a single value or an array.  Example valid values: 1001, [1001], [1001, 1002].
+
+Ports opened by default:
+* all hosts have [22, 61613, 8139] opened
+* `master` will also have 8140 opened
+* `dashboard` will also have [443, 4433, 4435] opened
+* `database` will also have [5432, 8080, 8081] opened
+
+####`amisize` ####
+The [instance type](https://aws.amazon.com/ec2/instance-types/) - defaults to `m1.small`.  
+####`snapshot`####
+The snapshot to use for ec2 instance creation.
+####`subnet_id`####
+If defined the instance will be created in this EC2 subnet.  `vpc_id` must be defined.  Cannot be defined at the same time as `subnet_ids`.
+####`subnet_ids`####
+If defined the instace will be crated in one of the provided array of EC2 subnets.  `vpc_id` must be defined.  Cannot be defined at the same time as `subnet_id`.
+####`vmname`####
+Used to look up the pre-defined AMI information in `config/image_templates/ec2.yaml`.  Will default to `platform` if not defined.
+#####Example ec2.yaml#####
+In this example the `vmname` would be `puppetlabs-centos-5-x86-64-west`.  Looking up the `vmname` in the `ec2.yaml` file provides an AMI ID by type (`pe` or `foss`) and the region.
+```
+AMI:
+  puppetlabs-centos-5-x86-64-west:
+    :image:
+      :pe: ami-pl-12345
+    :region: us-west-2
+```
+####`volume_size`####
+Size of the [EBS Volume](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EBSVolumes.html) that will be attached to the EC2 instance.
+####`vpc_id`####
+ID of the [VPC](https://aws.amazon.com/vpc/) to create the instances in.  If not provided will either use the default VPC for the provided region (marked as `isDefault`), otherwise falls back to `nil`.  If subnet information is provided (`subnet_id`/`subnet_ids`) this must be defined.

data/docs/Example-Vagrant-Hosts-Files.md

@@ -0,0 +1,66 @@
+#centos-511-x64.yml
+```
+HOSTS:
+  centos-511-x64:
+    roles:
+      - master
+    platform: el-5-x86_64
+    box: puppetlabs/centos-5.11-64-nocm
+    box_url: https://vagrantcloud.com/puppetlabs/boxes/centos-5.11-64-nocm
+    hypervisor: vagrant
+```
+#centos-65-x64.yml
+```
+HOSTS:
+  centos-65-x64:
+    roles:
+      - master
+    platform: el-6-x86_64
+    box: puppetlabs/centos-6.5-64-nocm
+    box_url: https://vagrantcloud.com/puppetlabs/boxes/centos-6.5-64-nocm
+    hypervisor: vagrant
+```
+#debian-609-x64.yml
+```
+HOSTS:
+  debian-609-x64:
+    roles:
+      - master
+    platform: debian-6-amd64
+    box: puppetlabs/debian-6.0.9-64-nocm
+    box_url: https://vagrantcloud.com/puppetlabs/boxes/debian-6.0.9-64-nocm
+    hypervisor: vagrant
+```
+#debian-78-x64.yml
+```
+HOSTS:
+  debian-78-x64:
+    roles:
+      - master
+    platform: debian-7-amd64
+    box: puppetlabs/debian-7.8-64-nocm
+    box_url: https://vagrantcloud.com/puppetlabs/boxes/debian-7.8-64-nocm
+    hypervisor: vagrant
+```
+#ubuntu-server-1204-x64.yml
+```
+HOSTS:
+  ubuntu-server-1204-x64:
+    roles:
+      - master
+    platform: ubuntu-1204-amd64
+    box: puppetlabs/ubuntu-12.04-64-nocm
+    box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-12.04-64-nocm
+    hypervisor: vagrant
+```
+#ubuntu-server-1404-x64.yml
+```
+HOSTS:
+  ubuntu-server-1404-x64:
+    roles:
+      - master
+    platform: ubuntu-14.04-amd64
+    box: puppetlabs/ubuntu-14.04-64-nocm
+    box_url: https://vagrantcloud.com/puppetlabs/boxes/ubuntu-14.04-64-nocm
+    hypervisor: vagrant
+```

data/docs/File-a-Beaker-Bug.md

@@ -0,0 +1,3 @@
+Something wrong?  Need a new feature?  File Beaker bugs here:
+
+[beaker jira ticket tracker](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR).

data/docs/Google-Compute-Engine-Support.md

@@ -0,0 +1,41 @@
+This option provisions instances from pre-existing Google Compute Engine images.  Currently only supports debian-7 and centos-6 platforms (<a href = "https://developers.google.com/compute/docs/images#availableimages">Google Compute Engine available images</a>)
+
+Pre-requisites:
+
+  * A Google Compute Engine project.
+  * An active service account to your Google Compute Engine project (<a href = "https://developers.google.com/drive/service-accounts">Service Accounts Documentation</a>), along with the following information:
+    * The service account private key file (named xxx-privatekey.p12).
+    * The service account email address (named xxx@developer.gserviceaccount.com).
+    * The service account password.
+  * A passwordless ssh keypair (<a href = "http://www.linuxproblem.org/art_9.html">SSH login without password</a>, <a href = "https://developers.google.com/compute/docs/console#sshkeys">Setting up Google Compute sshKeys metadata</a>).
+    * Name the pair `google-compute`
+    * Place the public key in your Google Compute Engine project metadata
+      * `key`: `sshKeys`
+      * `value` is the contents of your google_compute.pub with "google_compute:" prepended, eg:
+<pre>
+google_compute:ssh-rsaAAAABCCCCCCCCCCDDDDDeeeeeeeeFFFFFFFGGGGGGGGGGGGGGGGHHHHHHHHiiiiiiiiiiiJJJJJJJJKKKKKKKKKlllllllllllllllllllMNOppppppppppppppppppQRSTUV123456789101010101101010101011010101010110/ABCDEFGHIJKLMNOP+AB user@machine.local </pre>
+
+### example GCE hosts file###
+
+    HOSTS:
+      debian-7-master:
+        roles:
+          - master
+          - agent
+          - database
+        platform: debian-7-wheezy-xxx
+        hypervisor: google
+      centos-6-agent:
+        roles:
+          - agent
+        platform: centos-6-xxx
+        hypervisor: google
+    CONFIG:
+      nfs_server: none
+      consoleport: 443
+      gce_project: google-compute-project-name
+      gce_keyfile: /path/to/*****-privatekey.p12
+      gce_password: notasecret
+      gce_email: *********@developer.gserviceaccount.com
+
+Google Compute cloud instances and disks are deleted after test runs, but it is up to the owner of the Google Compute Engine project to ensure that any zombie instances/disks are properly removed should Beaker fail during cleanup.