serverspec_launcher 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 76cfad81b886a35a1ac5a27b3e6d2e756d7c46b8d3e32e4d6c8eb661220414bf
-  data.tar.gz: fb6bd787d1246aad83ac4e89a504be1c9a0d47c6f1369c038a59760dede06718
+  metadata.gz: 217a10415a16256a4478b48180e91464a29a4f209e404eb61242b199468838dc
+  data.tar.gz: 55ecc7919b6656d639dc7394e325ccfbc4926055b54d7ee9ec18cd3bbae3f200
 SHA512:
-  metadata.gz: 9a719d32252a27fdf36853e46730f823d136b4432aea72a028643395b2de1cd99ea9ab41e3a5fe34d74ea25f9f21a521119dabd4ad442f1d5120448473e759bd
-  data.tar.gz: 5657731b4a4fd10086d0f4aed6e89c7d4348b6ddd361cde408477dd60524e8f42500e4fad7f8d8f8e57b8666a43dd78e9eba0c6fcd3515c9e5ce202bc5f3f14a
+  metadata.gz: 4a9e79d1fccd7615c1152ffaaab40ed94ae5e2a9cc2c018f8f46475bb7e942314e2357ad217118b7d304ea46e4eba429a7998a113083b02d512013bf734c8dbc
+  data.tar.gz: b2ac6435e1e44084e60b94f4809db2ab6e0f97a476122d6166ea7af308d5650c4e7473a36af6b724df459d919786f3d6fbe237b478cb9d4a43b7487de0a2485a

data/README.md

@@ -1,8 +1,9 @@
 # serverspec_launcher
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/serverspec_launcher`. To experiment with that code, run `bin/console` for an interactive prompt.
+Serverspec launcher is utility for managing serverspec tests across servers, virtual machines, 
+and containers using a YAML based configuration files.
 
-TODO: Delete this and the text above, and describe your gem
+It allows for spec files (or lists of shared behaviours) to be ran across groups of servers. 
 
 ## Installation
 
@@ -22,7 +23,291 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Setup
+
+Run ```serverspec_launcher init``` from your applications root directory then add:
+
+to spec/spec_helper.rb
+```ruby
+require 'serverspec_launcher/spec_helper'
+```
+to Rakefile
+```ruby
+require 'serverspec_launcher/rake_tasks'
+```
+
+### properties.yml
+The properties.yml file contains the configuration for your test setup, it consists of a number of sections.
+
+##### targets
+The target section defines the targets (server, container), under test and consists of one or more hashes 
+defining the tests. Serverspec launcher will generate a rake task for each target it finds within 
+the target section, and a task for any hosts specifed within the targets config.  
+
+Each target consists of:
+
+targetname (hash key): (required) The name of the target
+* backend: (optional) Which backend to run against, supported backend are ssh, exec, docker, and vagrant. Windows based backend will be availible in future versions
+* user: (optional) what user to run the tests as, Defaults to current user
+* hosts: (optional) list or single value specifying the hostname(s) to run this against. defaults to target name 
+* spec_type: (optional) which spec file from the spec directory to execute against the target (do not include the _spec.rb). Defaults to role
+* roles: (optional/mandatory if using role spec_type) list of shared behaviors (see below), to run against the target
+* variables: (optional) hash of variables available to the the tests. Each variable specified here will be availible as property[:variables][:name_of_variable]. 
+Any values specified here will overwrite environment level(not to be confused with environment variables), and global level variables
+* environment: (optional) hash of environment variables which will be set on the target, environment level(not to be confused with environment variables), and global level environment varaibles(see below) that have previously defined values will be overwritten
+* fail_on_err: Stop running the tests if the target fails its checks
+
+Example :
+
+This would create the rake tasks serverspec:webservers, serverspec:webservers:webserver1 and serverspec:webservers:webserver2
+```yaml
+targets: 
+  webservers: # the name of the target
+    backend: ssh # use the 'ssh' backend.
+    user: ec2-user
+    hosts:
+      - webserver1
+      - webserver2
+    spec_type: webserver  
+```
+
+##### environments
+serverspec_launcher supports the concept of environments. Environments are groups of targets organised as a named entity, i.e. test or qa.
+
+An environment consists of the following:
+
+environment name (hash key): (required) the name of the environment
+* targets: a hash of targets (see above for target definition)
+* variables: (optional) hash of variables available to the the tests. Each variable specified here will be availible as property[:variables][:name_of_variable]. 
+Any values specified here will override global level variables previously defined.
+* environment: (optional) hash of environment variables which will be set on the target, global level environment varaibles(see below) that have previously defined values will be overwritten
+
+Example:
+```yaml
+environments:
+  qa:
+    targets:
+      webservers: &webservers
+        hosts:
+          - web1.qa.domain
+          - web2.qa.domain
+        variables:
+          some_thing: new value # Override variable
+    variables:
+        my_var: enviroment value  # Override global variable
+        some_thing: a value
+          
+  performance:
+    targets:
+      webservers:
+        # Yaml anchors are supported
+        <<: *webservers
+        hosts:
+        - web1.perf.domain
+        - web2.perf.domain
+        - web3.perf.domain
+        - web4.perf.domain
+```
+##### options
+A hash of options to pass to serverspec_launcher
+
+* fail_on_err: (optional) stop testing after the first target failure, defaults to true
+* color: (optional) colorize the output, defaults to true
+* formatters: (optional) list of RSpec formatter to process the results with. Supported formatters are:
+
+    - docs  RSpec Documentation Formatter writing to file reports/<target>.docs
+    - docs_screen - RSpec Documentation Formatter writing to screen
+    - tick -  Tick/Cross output to screen
+    - tick_file - Tick/Cross output to file reports/<target>.tick
+    - html - HTML Reports
+    - junit - Unit Reports (useful for jenkins jobs)
+    - html_pretty - Pretty HTML Reports
+    - json - JSON Output
+    - progress -  RSpec .F* progress output
+
+Example:
+```yaml
+options:
+  fail_on_err: false
+  colorize: true
+  formatters:
+    - tick
+    - docs
+
+```
+##### variables
+A hash containing key value pairs. Each entry will be available as property[:variables][:<key>]
+
+Example:
+```yaml
+variables:
+  my_var: some value
+```
+##### environment
+A hash containing key value pairs. Each entry will be available as an envirment variable on the target
+Example:
+```yaml
+environment:
+  JAVA_HOME: /usr/lib/java-1.7
+```
+##### Complete Example
+```yaml
+options:
+  # Stop the test on the first failure (default: true)
+  fail_on_err: true
+  # Specify output format defaults is docs_screen multiple formatters can be specified
+  formaters:
+    # RSpec Documentation Formatter writing to file reports/<target>.docs
+    - docs
+    # RSpec Documentation Formatter writing to screen
+    - docs_screen
+    # Tick/Cross output to screen
+    - tick
+    # Tick/Cross output to file reports/<target>.tick
+    - tick_file
+    # JUnit Reports
+    - junit
+    # HTML Reports
+    - html
+    # Pretty HTML Reports
+    - html_pretty
+    # JSON Output
+    - json
+    # RSpec .F* progress bar
+    - progress
+  # Use colorized output (default: true)
+  color: false
+
+# Load shared examples from third party gems, useful for sharing infrastucture tests 
+# across projects
+shared_example_gems:
+  - my_shared_examples
+
+# Specify environment variables used on the hosts when testing
+# these are available as ENV['<var name>'] from the tests
+environment:
+  SOMEVAR: some value
+
+# Specify variable to be used in the tests
+# these are available from the tests as property[:variables][:<variable name>]
+variables:
+  my_var: some value
+
+
+# Target Based Testing
+# For each target specified here there will be a rake task defined which can be invoked via 'serverspec:<target name>'.
+# Targets with multiple hosts will also have 'serverspec:<target name>:<hostname>' defined for each host.
+# Running 'serverspec:<target name>' will execute against all hosts in the target
+# Running the 'serverspec' rake task will invoke all targets and environments
+
+targets:
+  # Running against a host via ssh
+  ssh-example:
+    backend: ssh
+    # specify host if left blank will use target name as hostname
+    hosts: raspberrypi
+    # uses specific user
+    user: pi
+    # run spec file spec/pi_spec.rb
+    spec_type: pi
+  
+  # Running against multiple hosts via ssh
+  ssh-multi-host-example:
+    # Dont really need to specify ssh backend as it is the default but including for completeness
+    hosts:
+      - raspberrypi
+      - blueberrypi
+    # uses specific user
+    user: pi
+    # run spec file spec/pi_spec.rb
+    spec_type: pi
+    # Don't fail the run if the target fails (if blank uses the global value which defaults to true)
+    fail_on_err: true
+
+  # Run against local host  
+  exec-example:
+    backend: exec
+    # Run spec file spec/localhost_spec.rb
+    spec_type: localhost
+    # Specify variable to be used in tests as property[:variables][:<variable name>]
+    variables:
+      # Specify a new variable
+      some_var: some value
+      # Override an existing vale
+      my_var: new value
+
+  # Run tests against a docker images
+  docker-image-example:
+    backend: docker
+    # Run against the mongo docker image from docker hub
+    docker_image: mongo
+    # Use shared behaviors loaded from spec/shared/.rb
+    roles:
+      - database::mongo
+
+  # Run tests against a running docker container
+  docker-container-examples:
+    backend: docker
+    # Run against container named jenkins
+    docker_container: jenkins
+    # Explicitly specify the role spec file spec/role_spec.rb which should be generated by 'serverspec_launcher init'
+    # This isn't really needed as role is the default spec_type
+    spec_type: role
+    roles:
+      # Run role with in context
+      - name: build_tools::jenkins
+        description: Jenkins Container
+
+  # Run tests against a docker build file
+  dockerfile-examples:
+    backend: docker
+    # Build image from Dockerfile in current directory
+    docker_build_dir: .
+    # Run spec file spec/docker_spec.rb
+    spec_type: docker
+
+
+  # Run tests against a vagrant file
+  vagrant-example:
+    backend: vagrant
+    roles:
+    - debug::environment_vars
+    environment:
+      # This environment var will only be availble to this target
+      MY_VAR: my value
+      # Override a globally set environment var
+      SOMEVAR: some other value
+
+environments:
+  qa:
+    variables:
+      # Override global variable
+      my_var: enviroment value
+      some_thing: a value
+
+    targets:
+      webservers: &webservers
+        hosts:
+          - web1.qa.domain
+          - web2.qa.domain
+        variables:
+          # Override variable
+          some_thing: new value
+
+  performance:
+    targets:
+      webservers:
+        # Yaml anchors are supported
+        <<: *webservers
+        hosts:
+        - web1.perf.domain
+        - web2.perf.domain
+        - web3.perf.domain
+        - web4.perf.domain
+        variables:
+          # Override variable
+          some_thing: new value
+```
 
 ## Development
 

data/Rakefile

@@ -1,7 +1,13 @@
 # frozen_string_literal: true
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'conventional_changelog'
 
 RSpec::Core::RakeTask.new(:spec)
 
 task default: :spec
+
+
+task :changelog do
+  ConventionalChangelog::Generator.new.generate!
+end

data/lib/serverspec_launcher/rake_tasks.rb

@@ -25,8 +25,6 @@ class ServerspecLauncherRakeTasks
   def load_tasks
     task serverspec: 'serverspec:all'
 
-    debug_tasks
-
     namespace :serverspec do
       targets = @properties[:targets] || {}
       task all: targets.keys.map { |key| 'serverspec:' + key.to_s.split('.')[0] }
@@ -37,9 +35,13 @@ class ServerspecLauncherRakeTasks
 
       environments = @properties[:environments] || {}
       environments.keys.each do |key|
-        environment = environments[key]
-        environment[:targets].each do |target, hash|
-          process_target("#{key}:#{target}", hash, 'environment')
+        task key.to_sym => "serverspec:#{key}:all"
+        namespace key.to_sym do
+          environment = environments[key]
+          task all: environment[:targets].map { |target, _hash| "serverspec:#{key}:#{target.to_s.split(':')[0].to_sym}" }
+          environment[:targets].each do |target, hash|
+            process_target("#{target}", hash, 'environment', key.to_s)
+          end
         end
       end
 
@@ -49,22 +51,23 @@ class ServerspecLauncherRakeTasks
   def task_array(key, spec_type, target, options)
     desc "Run serverspec to #{key}"
     task key.to_sym => "serverspec:#{key}:all"
-    namespace key.to_sym do
-      task all: target[:hosts].map { |host| "serverspec:#{key}:#{host.split('.')[0].to_sym}" }
-      target[:hosts].each do |host|
-        task_name = "#{key}:#{host || target[:name]}"
-        rake_task(host, key, task_name, spec_type, options)
+      namespace key.to_sym do
+        task all: target[:hosts].map { |host| "serverspec:#{key}:#{host.split(':')[0].to_sym}" }
+        target[:hosts].each do |host|
+          task_name = "#{host || target[:name]}"
+          rake_task(host, key, task_name, spec_type, options)
+        end
       end
-    end
   end
 
   def rake_task(host, key, task_name, spec_type, options = {})
     desc "Run serverspec to #{key}"
-    RSpec::Core::RakeTask.new(host.to_s.split('.')[0].to_sym) do |t|
+    RSpec::Core::RakeTask.new(task_name.to_s.to_sym) do |t|
       ENV['TARGET_HOST'] = host.to_s
       ENV['TARGET'] = key.to_s
       ENV['TASK_NAME'] = task_name.to_s
       ENV['TASK_SOURCE'] = options[:source]
+      ENV['TASK_ENV'] = options[:environment]
       t.pattern = "spec/#{spec_type}_spec.rb"
       t.fail_on_error = options[:fail_on_err]
       set_formatters(task_name, options, t)
@@ -129,16 +132,16 @@ class ServerspecLauncherRakeTasks
 
   private
 
-  def process_target(key, target, task_source = 'target')
+  def process_target(key, target, task_source = 'target', environment = nil)
     options = {
         fail_on_err: target[:fail_on_err] || @fail_on_err,
         formatters: target[:formatters] || @formatters,
         color: target[:color].nil? ? @colorize : target[:color],
-        source: task_source
+        source: task_source,
+        environment: environment
     }
     spec_type = target[:spec_type] || 'role'
     if target[:hosts].is_a?(Array)
-
       task_array(key, spec_type, target, options)
     elsif target[:hosts]
       host = target[:hosts]

data/lib/serverspec_launcher/spec_helper.rb

@@ -22,22 +22,23 @@ class SpecHelper
 
   attr_reader :properties, :target_properties, :target_variables
 
-  def initialize(host = ENV['TARGET_HOST'], target = ENV['TARGET'], properties = nil, task_source = ENV['TASK_SOURCE'])
+  def initialize(host = ENV['TARGET_HOST'], target = ENV['TARGET'], properties = nil, task_source = ENV['TASK_SOURCE'], environment = ENV['TASK_ENV'])
     @host = host
     @target = target
     @source = task_source
+    @environment = ENV['TASK_ENV']
     load_properties properties
   end
 
   def load_properties(properties = nil)
     @properties = properties ? properties.deep_symbolize_keys : YAML.load_file('properties.yml').deep_symbolize_keys
-    if @target.include? ':'
-      @target_properties = @properties[:environments][@target.split(':')[0].to_sym][:targets][@target.split(':')[1].to_sym]
+    if @source == 'environment'
+      @target_properties = @properties[:environments][@environment.to_sym][:targets][@target.to_sym]
     else
       @target_properties = @properties[:targets][@target.to_sym]
     end
     if @source == 'environment'
-      vars = @properties[:environments][@target.split(':')[0].to_sym][:variables] ? @properties[:environments][@target.split(':')[0].to_sym][:variables] : {}
+      vars = @properties[:environments][@environment.to_sym][:variables] ? @properties[:environments][@environment.to_sym][:variables] : {}
       @target_variables =  @properties[:variables] ? @properties[:variables].deep_merge(vars) : {}.deep_merge(vars)
     else
       @target_variables = @properties[:variables] ? @properties[:variables] : {}
@@ -76,6 +77,7 @@ class SpecHelper
               end
 
     options[:user] ||= ssh_user
+    options[:keys] = [@target_properties[:identity_file]] if @target_properties[:identity_file]
 
     set :host, options[:host_name] || @host
     set :ssh_options, options
@@ -149,8 +151,8 @@ class SpecHelper
     end
   end
 
-  def self.load(host = ENV['TARGET_HOST'], target = ENV['TARGET'], properties = nil, task_source = ENV['TASK_SOURCE'])
-    helper = SpecHelper.new host, target, properties, task_source
+  def self.load(host = ENV['TARGET_HOST'], target = ENV['TARGET'], properties = nil, task_source = ENV['TASK_SOURCE'], environment = '')
+    helper = SpecHelper.new host, target, properties, task_source, environment
     props = helper.properties[:shared_example_gems] || []
     helper.load_shared_examples props
     helper.setup_backend

data/lib/serverspec_launcher/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module ServerspecLauncher
-  VERSION = '0.2.1'
+  VERSION = '0.2.3'
 end

data/serverspec_launcher.gemspec

@@ -30,6 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'simplecov'
   spec.add_development_dependency 'debase'
   spec.add_development_dependency 'ruby-debug-ide', '0.7.0.beta6'
+  spec.add_development_dependency 'conventional-changelog'
   spec.add_runtime_dependency 'serverspec'
   spec.add_runtime_dependency 'rspec_junit_formatter'
   spec.add_runtime_dependency 'rspec-tick-formatter', '0.1.3'

data/templates/properties.yaml.erb

@@ -1,5 +1,4 @@
 ---
-
 options:
   # Stop the test on the first failure (default: true)
   fail_on_err: true

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: serverspec_launcher
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - Andrew Wardrobe
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-09-22 00:00:00.000000000 Z
+date: 2018-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -108,6 +108,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.7.0.beta6
+- !ruby/object:Gem::Dependency
+  name: conventional-changelog
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: serverspec
   requirement: !ruby/object:Gem::Requirement