/website/website.html
HTML | 385 lines | 282 code | 101 blank | 2 comment | 0 complexity | 4c61604a0eecd02ad594ae3a4541e9d1 MD5 | raw file
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
- "http://www.w3.org/TR/html4/strict.dtd">
- <html lang="en">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>Cucumber-chef</title>
- <!-- Typekit service section -->
- <script type="text/javascript"
- src="http://use.typekit.com/jmb0kkz.js"></script>
- <script type="text/javascript">try{Typekit.load();}catch(e){}</script>
- <!-- End of typekit service section -->
- <!-- Framework CSS --> <link rel="stylesheet" href="style/style.css"
- type="text/css" media="screen, projection"> </head>
- <body> <div class="container">
-
-
- <div id="nav">
- <ul>
- <li class="selected">Main</li>
- <li>Docs</li>
- </ul>
- </div>
- <div id="header">
- <img src="images/cucumber-chef-logo.png" width="380" height="46"
- alt="Cucumber Chef Logo"/>
-
- <h3>A library of tools to enable test driven development</h3>
- </div>
- <div class="page">
-
- <div id="panel">
- <a href="https://github.com/Atalanta/cucumber-chef"><img
- src="images/large-button.png" width="252" height="52" class="imgpad"
- alt="Git Hub" /></a>
-
- <a href="http://oreilly.com/catalog/0636920020042"><img
- src="images/book-cover.png" width="252" height="330" alt="Book
- Cover"/></a>
-
- <p class="book-description">Test-Driven Infrastructure with
- Chef<br/>by Stephen Nelson-Smith<br/>Published by O’Reilly</p>
-
- <a href="http://oreilly.com/catalog/0636920020042"><img
- src="images/buy-button.png" width="62" height="27" alt="Buy
- Button"/></a>
-
- </div>
- <h2>Overview</h2>
- <p><strong>Cucumber-chef</strong>is a library of tools to enable the
- emerging discipline of infrastructure as code to practice test driven
- development. It provides a testing platform within which cucumber
- tests can be run which provision lightweight virtual machines,
- configure them by applying the appriporaite Chef roles to them, and
- then run acceptance and integration tests against the environment.</p>
- <p>It begins with a very simple premise. with a very simple
- premise. If we are framing our infratructure as code - if we're
- writing cookbooks, recipes and other pieces of automation in a high
- level programming language, such as Ruby, then it makes sense to
- follow the current wisdom across the software development world to
- maximise the quality, maintainability and reusability of our code,
- providing maximum chance that we'll deliver value with it. One
- area which has been shown to have a very positive effect is the
- practive of 'test-driven' development. In this paradigm, the
- developer begins by writing a test that captures the intended
- behaviour of the code they are going to write. This test will
- start out by failing. The developer then writes code to make the
- test pass, and iterates thereafter.</p>
- <strong>Cucumber-Chef</strong> provides a framework to make it easier
- to do test-driven development for infrastructure. It does this by
- providing a test infrastructure, in the cloud, which provides a very
- fast, lightweight and cheap way to fire up virtual machines for
- testing. We call this the "test lab".</p>
- <p>As you might have guessed from the name, we're going to write high
- level acceptance tests using Cucumber. Cucumber-Chef provides step
- definitions and helper methods to make it easy to provision and manage
- machines with Chef, and then build end-to-end tests.</p>
- <ul> <li><strong>Test Lab:</strong> An environment made up (at
- present) of an EC2 instance, configured to be an LXC host. This
- machine does nothing other than provide space in which Linux
- containers can be created and destroyed.</li>
-
- <li><strong>Controller:</strong> One special Linux container which
- acts as the central point from which tests are run. This machine is
- where the tests run, and has connectivity and credentials to connect
- to the machines that are created as part of a test run.</li>
-
- <li><strong>Container:</strong> A container is a lightweight virtual
- machine - it is entirely self-contained, with its own process tree,
- resource constraints, filesystem and network stack. It shares a
- kernel with the Test Lab host server.</li> </ul>
-
-
- <h3>Getting Started</h3>
- <p>Getting started with <strong>Cucumber-Chef</strong> is a simple,
- three step process:</p>
-
- <ul>
- <li>1) Install Cucumber-Chef</li>
- <li>2) Integrate with Hosted Chef and Amazon EC2</li>
- <li>3) Run cucumber-chef setup</li>
- </ul>
- <h3>Installing Cucumber-Chef</h3>
- <p>Installing Cucumber-Chef is simple. It's distributed as a
- RubyGem, so you can simply run:</p>
-
- <div class="inset-box">
- <pre><code>$ gem install cucumber-chef
- </code></pre>
- </div>
- <p>Once installed, you can run cucumber-chef on the command line to
- get an overview of the tasks it can carry out.</p>
- <div class="inset-box">
- <pre><code>$ cucumber-chef
- Tasks:
- cucumber-chef connect # Connect to a container in your test lab
- cucumber-chef destroy # Destroy running test labs
- cucumber-chef displayconfig # Display the current config from knife.rb
- cucumber-chef help [TASK] # Describe available tasks or one specific task
- cucumber-chef info # Display information about the current test lab
- cucumber-chef project <project name> # Create a project template for testing an infrastructure
- cucumber-chef setup # Set up a cucumber-chef test lab in Amazon EC2
- cucumber-chef test # Run a cucumber-chef test suite from a workstation.
- cucumber-chef upload <project name> # Upload a cucumber-chef test
- </code></pre>
- </div>
- <h3>Integrate with Hosted Chef and Amazon EC2</h3>
- <p>In it's current incarnation, Cucumber-Chef makes two important
- assumptions. Firstly, it assumes you're using Opscode Hosted Chef
- rather than your own Chef server. Secondly, it assume that you are
- comfortable with using Amazon's EC2 service for providing the 'bare
- metal' on which we set up the test lab. </p>
- <p><strong>Cucumber-chef</strong> is tightly integrated with Chef - it
- uses your knife.rb for credentials, and any cucumber-chef-specific
- configuration goes in knife.rb under the cucumber-chef namespace.</p>
- <p>On installation, the first thing you should do is run:</p>
- <div class="inset-box">
- <pre>
- $ cucumber-chef displayconfig
- </pre>
- </div>
- <p>This will look for your knife.rb, and extract the relevant
- sections, check them, and display them on the screen. If any entries
- are missing, it will alert you.</p>
- <p>The recommended best practice for Chef is to keep your knife.rb
- inside your organisation's Chef repository, inside the .chef
- directory, and use environment variables to specify username,
- organisation name and cloud provider credentials. Cucumber-chef
- supports and encourages this approach. It will search for a
- directory called .chef in your current directory, and then carry on
- going up the directory tree until it finds one. In practice this
- means that if you stay within the chef-repo directory for the
- organisation on which you're working, cucumber-chef will use the
- knife.rb; if your elsewhere in the filesystem rooted in your home
- directory, and have .chef in your home directory, cucumber-chef
- will use that. Otherwise you'll need to either change into a
- directory where a .chef can be found, or copy, creatre or link
- accordingly. In most cases we anticipate that you'll be inside the
- chef-repo of your organisation, and the documentation is written
- from this perspective.</p>
- <p>If you haven't already, refactor your knife.rb to look like this:</p>
- <div class="inset-box">
- <pre><code>current_dir = File.dirname(__FILE__)
- user = ENV['OPSCODE_USER'] || ENV['USER']
- log_level :info
- log_location STDOUT
- node_name user
- client_key "#{ENV['HOME']}/.chef/#{user}.pem"
- validation_client_name "#{ENV['ORGNAME']}-validator"
- validation_key "#{ENV['HOME']}/.chef/#{ENV['ORGNAME']}-validator.pem"
- chef_server_url "https://api.opscode.com/organizations/#{ENV['ORGNAME']}"
- cache_type 'BasicFile'
- cache_options( :path => "#{ENV['HOME']}/.chef/checksums" )
- cookbook_path ["#{current_dir}/../cookbooks"]
- </code></pre>
- </div>
- <p>Now set your Hosted Chef username and organization name using
- environment variables:</p>
- <div class="inset-box">
- <pre><code>$ export OPSCODE_USER=platform_user_name
- $ export ORGNAME=platform_organisation
- </code></pre>
- </div>
- <p>Now put your validator and client keys in $HOME/.chef. Verify that
- everything still works:</p>
- <div class="inset-box">
- <pre><code>$ knife client list
- </code></pre>
- </div>
- <p>If you get results back, we're in business.</p>
- <p>Now add the EC2 configuration:</p>
- <div class="inset-box">
- <pre><code>knife[:aws_access_key_id] = ENV['AWS_ACCESS_KEY_ID']
- knife[:aws_secret_access_key] = ENV['AWS_SECRET_ACCESS_KEY']
- knife[:aws_ssh_key_id] = ENV['AWS_SSH_KEY_ID']
- knife[:identity_file] = "/path/to/aws_ssh_key.pem"
- knife[:availability_zone] = "eu-west-1a"
- knife[:region] = "eu-west-1"
- knife[:aws_image_id] = "ami-339ca947"
- </code></pre>
- </div>
- <p>Note that right now Cucumber-Chef only supports Ubuntu-based test
- labs.</p>
- <p>And set your environment variables:</p>
- <div class="inset-box">
- <pre><code>$ export AWS_ACCESS_KEY_ID=SEKRITKEY
- $ export AWS_SECRET_ACCESS_KEY=REELYSEKRITKEY
- $ export AWS_SSH_KEY_ID
- </code></pre>
- </div>
- <p>And then ensure your AWS ssh key is in place.</p>
- <p>Now check your config again, with cucumber-chef display config. If
- you get no complaints, you're ready to set up a test lab.</p>
- <h3>Run cucumber-chef setup</h3>
- <div class="inset-box">
- <pre><code>$ cucumber-chef setup
- </code></pre>
- </div>
- <p>This command will set up a complete test lab environment, As long
- as you've provided valid AWS and Opscode credentials, it will do this
- automatically. The process takes about 15 minutes, after which you'll
- have a fully funtioning platform available for you to use. Let's just
- quickly review what that means. You will have an EC2 machine, fully
- managed by Chef, and providing the following:</p>
- <ul>
- <li>The ability to provision LXC containers</li>
- <li>The ability to run tests against LXC containers</li>
- <li>A dedicated container for certain kinds of testing scenarios</li>
- </ul>
- <p>The next stage is to set up a project. A project is simply a
- directory structure for containing your cucumber features and steps,
- already set up with an appropriate environment to make use of the
- step definitions provided with cucumber-chef. We think it makes
- most sense to have this in your organisation's chef repo.
- Cucumber-chef provides a task which will create a the directory for
- you, and populate it with a README and an example feature and
- step.</p>
- <div class="inset-box">
- <pre><code>$ cd /path/to/chef-repo
- $ cucumber-chef project example
- </code></pre>
- </div>
- <p>This will create a directory, cucumber-chef, and a subdirectory, example.</p>
- <div class="inset-box">
- <pre><code>└── example
- ├── README
- └── features
- ├── example.feature
- ├── step_definitions
- │ └── example_step.rb
- └── support
- └── env.rb
- </code></pre>
- </div>
- <h2>Writing tests</h2>
- <p>Once you've got your test lab set up, and you've generated a
- project, it's time to crack on with writing a test. The basic idea is
- this:</p>
- <p>
- <ul>
- <li>1) An infrastructure requirement is established</li>
- <li>2) Write a cucumber feature that expresses the required
- behaviour of the infrastructure requirement</li>
-
- <li>3) Write steps that will build this infrastructure environment
- on the test lab, using the step definitions provided - these include
- the ability to create a container, apply roles to it, and destroy it
- again.</li>
-
- <li>4) Write cookbooks and recipes and supporting code to make
- the test pass</li>
- </ul></p>
- <h2>Running tests</h2>
- <p>You can write the tests and Chef code wherever you like. We're
- assuming you prefer working on your local machine, and checking into
- version control. But we don't really care. When it's time to run
- tests, cucumber-chef provides a task which handles this:</p>
- <div class="inset-box">
- <pre><code>$ cucumber-chef test myproject
- </code></pre>
- </div>
- <p>At the moment cucumber-chef doesn't pass though clever filtering
- and tagging options that cucumber supports - you run all the tests.
- We're going to improve that soon, again, patches and pull requests
- very welcome.</p>
- <p>Running the test task will upload your current project to the test
- lab, and run the tests, reporting the results back to the screen.
- Cucumber-chef also provides an upload task, so you can push the
- current project to the test lab, and then connect to test lab yourself
- to run tests in a more granular way. To do this, you need to know the
- IP of the test lab. You can find this out by running:</p>
- <div class="inset-box">
- <pre><code>$ cucumber-chef info
- </code></pre>
- </div>
- <p>At present, Cucumber-Chef only allows one test lab per AWS account
- and Opscode Hosted Chef account.</p>
- </div>
- </div>
- </body>
- </html>