test-kitchen 1.23.2 → 1.23.3

data/docs/content/docs/getting-started/13-adding-feature.md

@@ -0,0 +1,30 @@
+---
+title: Adding a New Feature
+slug: adding-feature
+menu:
+  docs:
+    parent: getting_started
+    weight: 130
+---
+
+Now we're going to add limited support to our Git cookbook for a read-only Git daemon. This will walk us through adding a new suite, recipe, and corresponding set of tests.
+
+> **We're not looking to make the perfect Chef cookbook in this guide. There will be more than a couple style and code smells as we go but this is to keep us focused on driving our tool. Think of it as a dirty first-pass implementation. Plenty of room for refactoring!**
+
+It seems like the reasonable thing to do would be to create another recipe in our Chef cookbook to deal with the Git server. After all, not every server that requires the Git tool needs to be a server. We are adding net-new behavior that needs to operate independently of the default recipe. So it's natural that we want to test these two behaviors in isolation.
+
+> **Testing different behaviors of a codebase in isolation is the primary use case for Kitchen Suites.**
+
+Now that we have a feel for developing a Chef cookbook with Kitchen let's up the ante and add this feature test-first. That is, let's determine the acceptance criteria for a simple Git daemon and encode this as an executable test.
+
+After consulting the web and the man page for `git-daemon`, two simple acceptance criteria emerge:
+
+* A process is listening on port `9418` (the default Git daemon port).
+* A service is running called `git-daemon`. This name is arbitrary but shouldn't surprise anyone using this cookbook.
+
+Let's work through this step by step.
+
+<div class="sidebar--footer">
+<a class="button primary-cta" href="/docs/getting-started/adding-suite">Next - Adding a Suite</a>
+<a class="sidebar--footer--back" href="/docs/getting-started/adding-platform">Back to previous step</a>
+</div>

data/docs/content/docs/getting-started/14-adding-suite.md

@@ -0,0 +1,60 @@
+---
+title: Adding a Suite
+slug: adding-suite
+menu:
+  docs:
+    parent: getting_started
+    weight: 140
+---
+
+We're going to call our new suite `"server"` by editing `.kitchen.yml` in your editor of choice so that it looks similar to:
+
+~~~
+---
+driver:
+  name: vagrant
+
+provisioner:
+  name: chef_zero
+
+verifier:
+  name: inspec
+
+platforms:
+  - name: ubuntu-16.04
+  - name: centos-7
+
+suites:
+  - name: default
+    run_list:
+      - recipe[git_cookbook::default]
+    verifier:
+      inspec_tests:
+        - test/integration/default
+    attributes:
+  - name: server
+    run_list:
+      - recipe[git_cookbook::server]
+    verifier:
+      inspec_tests:
+        - test/integration/server
+    attributes:
+~~~
+
+Now run `kitchen list` to see our new suite in action:
+
+~~~
+$ kitchen list
+Instance             Driver   Provisioner  Verifier  Transport  Last Action    Last Error
+default-ubuntu-1604  Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+default-centos-7     Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+server-ubuntu-1604   Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+server-centos-7      Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+~~~
+
+Woah, we've doubled our number of instances! Yes, that is going to happen. This explosion of test cases is just one reason why testing is hard.
+
+<div class="sidebar--footer">
+<a class="button primary-cta" href="/docs/getting-started/adding-test">Next - Adding a Test</a>
+<a class="sidebar--footer--back" href="/docs/getting-started/adding-feature">Back to previous step</a>
+</div>

data/docs/content/docs/getting-started/15-adding-test.md

@@ -0,0 +1,66 @@
+---
+title: Adding a Test
+slug: adding-test
+menu:
+  docs:
+    parent: getting_started
+    weight: 150
+---
+
+Our first test was created for us automatically for us by our cookbook generator so here we will create the folders and files manually.
+
+First we're going to create a directory for our test file:
+
+~~~
+mkdir -p test/integration/server
+~~~
+
+Next, create a file called `test/integration/server/git_daemon_test.rb` with the following:
+
+~~~
+# # encoding: utf-8
+
+# Inspec test for recipe git_cookbook::server
+
+describe port(9418) do
+  it { should be_listening }
+end
+
+describe service('git-daemon') do
+  it { should be_enabled }
+  it { should be_running }
+end
+~~~
+
+This test checks that a process is listening on port 9418 and a service called "git-daemon" is installed, enabled, and running.
+
+As our primary target platform was Ubuntu 16.04, we'll target this one first for development. Now, in Test-Driven style we'll run `kitchen verify` to watch our tests fail spectacularly:
+
+~~~
+...
+================================================================================
+Recipe Compile Error
+================================================================================
+
+Chef::Exceptions::RecipeNotFound
+--------------------------------
+could not find recipe server for cookbook git_cookbook
+...
+~~~
+
+One quick check of `kitchen list` tells us that our instance was created but not successfully converged:
+
+~~~
+$ kitchen list server-ubuntu-1604
+Instance            Driver   Provisioner  Verifier  Transport  Last Action  Last Error
+server-ubuntu-1604  Vagrant  ChefZero     Inspec    Ssh        Created      Kitchen::ActionFailed
+~~~
+
+Yes, you can specify one or more instances with the same Ruby regular expression globbing as any other `kitchen` sub-commands.
+
+Okay, no recipe called `server` in our Git cookbook. Let's go create one.
+
+<div class="sidebar--footer">
+<a class="button primary-cta" href="/docs/getting-started/adding-recipe">Next - Adding a Recipe</a>
+<a class="sidebar--footer--back" href="/docs/getting-started/adding-suite">Back to previous step</a>
+</div>

data/docs/content/docs/getting-started/16-adding-recipe.md

@@ -0,0 +1,53 @@
+---
+title: Adding a Recipe
+slug: adding-recipe
+menu:
+  docs:
+    parent: getting_started
+    weight: 160
+---
+
+As we've already added our tests, we have a pretty good idea of what needs to happen.
+
+With this solution in mind we'll create a file called `recipes/server.rb` with the following:
+
+~~~
+# the default recipe is implied if only the cookbook name is provided
+# effectively `include_recipe "git_cookbook::default"`
+include_recipe "git_cookbook"
+
+# install the above `daemon_pkg`
+package 'git-daemon-run'
+
+# create our data directory
+directory '/opt/git'
+
+# setup the systemd unit (service) with the above `daemon_bin`, enable, and
+# start it
+systemd_unit 'git-daemon.service' do
+  content <<-EOU.gsub(/^\s+/, '')
+    [Unit]
+    Description=Git Repositories Server Daemon
+    Documentation=man:git-daemon(1)
+
+    [Service]
+    ExecStart=/usr/bin/git daemon \
+    --reuseaddr \
+    --base-path=/opt/git/ \
+    /opt/git/
+
+    [Install]
+    WantedBy=getty.target
+    DefaultInstance=tty1
+    EOU
+
+  action [ :create, :enable, :start ]
+end
+~~~
+
+Before we give our new recipe a go, a quick detour to cover how we might exclude a particular platform from a suite's tests.
+
+<div class="sidebar--footer">
+<a class="button primary-cta" href="/docs/getting-started/excluding-platforms">Next - Excluding Platforms</a>
+<a class="sidebar--footer--back" href="/docs/getting-started/adding-test">Back to previous step</a>
+</div>

data/docs/content/docs/getting-started/17-excluding-platforms.md

@@ -0,0 +1,101 @@
+---
+title: Excluding Platforms
+slug: excluding-platforms
+menu:
+  docs:
+    parent: getting_started
+    weight: 170
+---
+
+Perhaps our enterprise has standardized on Ubuntu 16.04 for server tasks so we really only care about testing that our `server` recipe works on that platform. That said we still want to be able to test our default recipe against CentOS.
+
+Let's give `kitchen list` a look:
+
+~~~
+$ kitchen list
+Instance             Driver   Provisioner  Verifier  Transport  Last Action    Last Error
+default-ubuntu-1604  Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+default-centos-7     Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+server-ubuntu-1604   Vagrant  ChefZero     Inspec    Ssh        Verified       <None>
+server-centos-7      Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+~~~
+
+> **Add a platform name to an `excludes` array in a suite to remove the platform/suite combination from testing.**
+
+Let's exclude the `centos-7` platform from the `server` suite so that it
+doesn't accidentally get run. Update `.kitchen.yml` to look like the following:
+
+~~~
+---
+driver:
+  name: vagrant
+
+provisioner:
+  name: chef_zero
+
+verifier:
+  name: inspec
+
+platforms:
+  - name: ubuntu-16.04
+  - name: centos-7
+
+suites:
+  - name: default
+    run_list:
+      - recipe[git_cookbook::default]
+    verifier:
+      inspec_tests:
+        - test/integration/default
+    attributes:
+  - name: server
+    run_list:
+      - recipe[git_cookbook::server]
+    verifier:
+      inspec_tests:
+        - test/integration/server
+    attributes:
+    excludes:
+      - centos-7
+~~~
+
+Now let's run `kitchen list` to ensure the instance is gone:
+
+~~~
+$ kitchen list
+Instance             Driver   Provisioner  Verifier  Transport  Last Action    Last Error
+default-ubuntu-1604  Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+default-centos-7     Vagrant  ChefZero     Inspec    Ssh        <Not Created>  <None>
+server-ubuntu-1604   Vagrant  ChefZero     Inspec    Ssh        Verified       <None>
+~~~
+
+Finally let's destroy our running instances:
+
+~~~
+$ kitchen destroy
+-----> Starting Kitchen (v1.23.2)
+-----> Destroying <default-ubuntu-1604>...
+       Finished destroying <default-ubuntu-1604> (0m0.00s).
+-----> Destroying <default-centos-7>...
+       Finished destroying <default-centos-7> (0m0.00s).
+-----> Destroying <server-ubuntu-1604>...
+       ==> default: Forcing shutdown of VM...
+       ==> default: Destroying VM and associated drives...
+       Vagrant instance <server-ubuntu-1604> destroyed.
+       Finished destroying <server-ubuntu-1604> (0m12.55s).
+-----> Kitchen is finished. (0m17.39s)
+~~~
+
+Now that we've completed our git daemon feature and made sure we're testing it on only the
+platform we care about we've come to the end of our guide!
+
+#### Congratulations!
+
+You've just written a valid Chef cookbook, complete with tests, that is ready to
+be improved upon further. Before you leave, check out some further resources to
+help you along your testing journey.
+
+<div class="sidebar--footer">
+<a class="button primary-cta" href="/docs/getting-started/next-steps">Next Steps</a>
+<a class="sidebar--footer--back" href="/docs/getting-started/adding-recipe">Back to previous step</a>
+</div>

data/docs/content/docs/getting-started/18-next-steps.md

@@ -0,0 +1,23 @@
+---
+title: Next Steps
+slug: next-steps
+menu:
+  docs:
+    parent: getting_started
+    weight: 180
+---
+
+This concludes the getting started guide for kitchen. Hopefully you are now more comfortable with Kitchen's basic usage, fundamental concepts, and a feel for a testing workflow.
+
+From here, there are a few resources that can help you along your infrastructure testing journey:
+
+* Jump in the `#test-kitchen` channel on [Chef Community Slack](http://community-slack.chef.io/)
+* Check out the [test-kitchen repo](https://github.com/test-kitchen/test-kitchen) on GitHub
+* Submit an [issue](https://github.com/test-kitchen/test-kitchen/issues)
+* Write a blog post describing getting started with kitchen, or an interesting problem kitchen has allowed you to solve
+
+Everyone can contribute to making kitchen better, including the documentation. If you've learned something and want to contribute, please [fork the docs](https://github.com/test-kitchen/kitchen-docs) and open a [pull request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)!
+
+<div class="sidebar--footer">
+<a class="sidebar--footer--back" href="/docs/getting-started/excluding-platforms">Back to previous step</a>
+</div>

data/docs/content/docs/getting-started/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Getting Started"
+layout: redirect
+redirect_url: /docs/getting-started/introduction
+---

data/docs/content/docs/provisioners/_index.md

@@ -0,0 +1,36 @@
+---
+title: Provisioners
+menu:
+  docs:
+    parent: provisioners
+    weight: 1
+---
+
+A Test-Kitchen *provisioner* takes care of configuring the compute instance provided by the *driver*. This is most commonly a configuration management framework like Chef or the Shell provisioner, both of which are included in test-kitchen by default.
+
+There are common settings that all provisioners inherit and can override. These are typically set in the context of a specific provisioner but are provided here for reference.
+
+```
+provisioner:
+  root_path: '/tmp/kitchen' # when platform is Windows '$env:TEMP\\kitchen'
+  sudo: true # when platform is Windows, nil
+  sudo_command: 'sudo -E' # when platform is Windows, nil
+  command_prefix: nil # prefix the provisioner exec with a command
+  http_proxy: nil
+  https_proxy: nil
+  ftp_proxy: nil
+  retry_on_exit_code: []
+  max_retries: 1
+  wait_for_retry: 30
+  downloads: # a Hash of remote => local file mappings to download post-converge
+  # if the local value is an existing dir, the file will be copied into it
+  # if the local value does not exist, a file with that value as name will be created
+    "/tmp/kitchen/client.rb": "./downloads"
+    "/tmp/kitchen/validation.pem": "./downloads/validation.pem"
+```
+
+Community provisioners:
+
+* [kitchen-ansible](https://github.com/neillturner/kitchen-ansible)
+* [kitchen-puppet](https://github.com/neillturner/kitchen-puppet)
+* [kitchen-dsc](https://github.com/test-kitchen/kitchen-dsc)

data/docs/content/docs/provisioners/chef.md

@@ -0,0 +1,69 @@
+---
+title: Chef
+slug: chef
+menu:
+  docs:
+    parent: provisioners
+    weight: 5
+---
+
+Test-kitchen includes two provisioners for Chef, `chef_solo` and `chef_zero`, which support nearly identical options.
+
+```
+---
+provisioner:
+  name: chef_zero # chef_solo or chef_zero
+  data_path: test/data # Path to directory of files to copy to instance
+  data_bags_path: test/data_bags # Path to directory containing data_bags
+  environments_path: test/envs # Path to directory containing environments
+  encrypted_data_bag_secret_key_path: test/secret_key # Path to secret file
+  nodes_path: test/nodes # Path to directory containing nodes
+  roles_path: test/roles # Path to directory containing roles
+  profile_ruby: false # true enables chef's Ruby profiling
+  deprecations_as_errors: false # true configures chef to exception on deprecation warnings
+  client_rb: # use solo_rb when chef_solo is used
+    environment: kitchen # requires a corresponding file in environments_path
+    silence_deprecation_warnings: # true for all or an array of deprecations to silence
+    - deploy_resource # deprecation key name
+    - chef-23 # deprecation numeric ID
+    - recipes/install.rb:22 # specific line in a file
+  product_name: chef # which package to install chef || chefdk
+  product_version: latest # 'latest', partial, or full version number
+  channel: stable # stable, current or unstable
+  install_strategy: once # once (install only if needed), always, skip (don't install)
+  download_url: https://url.to/specific-package.ext
+  checksum: <SHA256> # used in conjunction with download_url to validate
+
+platforms:
+  - name: ubuntu-16.04
+    attributes:
+      cookbook_a:
+        attr_b: "value"
+
+suites:
+  - name: default
+    attributes:
+      cookbook_b:
+        attr_c: "value"
+    run_list:
+      - role[role_a] # requires a corresponding file in roles_path
+      - recipe[cookbook_a]
+      - recipe[cookbook_b::recipe_c]
+```
+
+If not explicitly set, the following keys:
+
+- data_path
+- data_bags_path
+- encrypted_data_bag_secret_key_path
+- environments_path
+- nodes_path
+- roles_path
+
+Will be set to the first match, in the following order:
+
+1. test/integration/$SUITE/$KEY
+2. test/integration/$KEY
+3. $KEY
+
+Where `$KEY` corresponds to a folder named `data, data_bags, environments, nodes, roles` - the exception being `encrypted_data_bag_secret_key_path` which looks for a file named `encrypted_data_bag_secret_key`.