ironfan 5.0.11 → 6.0.0

data/notes/Upgrading-to-v4.md

@@ -1,66 +0,0 @@
-While the refactoring that lead to version 4 was intended to be as backwards compatible as possible, there have been some small but important changes to the way homebases and the DSL work.
-
-## Bundler
-Ironfan v4 uses bundler to manage its dependencies. In order to take advantage of it, the homebase's Gemfile should be updated to use ```gem 'ironfan', "~> 4.0"``` 
-
-We highly recommend that you run all your knife commands via bundle exec. This can be accomplished with an alias:
-```
-knife() {
-  bundle exec knife "$@"
-}
-```
-
-If you are comfortable with having bundle run every knife command (e.g. - you only have one homebase, or are using a Ironfan > 3.1.6 for all homebases you do use), you can add the above snippet to your .bashrc.
-
-## Vagrant
-Vagrant support has been discontinued for the time being. One of the first targets for the multicloud capabilities of Ironfan v4 will be a Virtualbox or Vagrant extension.
-
-## DSL Changes
-### Role implications removed
-In v3, certain roles could trigger further steps via role_implications.rb, which was used to add servers to corresponding EC2 Security Groups. This was deemed to be too risky and indirect, and has been removed for now. (A better mechanism for binding roles and provider-specific resources into repeatable components is being worked on.)
-
-If you used any of the roles below, you will probably want to add the following stanzas next to them in the clusters file, to replace the removed implications. **Be aware that EC2 instances can only be added to a security group at startup; if you fail to add the security groups before launch, you will have to kill and relaunch the machines to change them.**
-
-* `role :systemwide`
-```
-cloud(:ec2).security_group :systemwide
-```
-* `role :nfs_server`
-```
-cloud(:ec2).security_group(:nfs_server).authorize_group :nfs_client
-```
-* `role :nfs_client`
-```
-cloud(:ec2).security_group :nfs_client
-```
-* `role :ssh`
-```
-cloud(:ec2).security_group(:ssh).authorize_port_range 22..22
-```
-* `role :chef_server`
-```
-cloud(:ec2).security_group :chef_server do
-  authorize_port_range 4000..4000  # chef-server-api
-  authorize_port_range 4040..4040  # chef-server-webui
-end
-```
-* `role :web_server`
-```
-cloud(:ec2).security_group("#{self.cluster_name}-web_server") do
-  authorize_port_range  80..80
-  authorize_port_range 443..443
-end
-```
-* `role :redis_server`
-```
-cloud(:ec2).security_group("#{self.cluster_name}-redis_server") do
-  authorize_group("#{self.cluster_name}-redis_client")
-end
-```
-* `role :redis_client`
-```
-cloud(:ec2).security_group("#{self.cluster_name}-redis_client")
-```
-
-### Default statements removed
-Defaults should not need to be selected, and have been removed as a statement from the cluster DSL (in both cluster and volume). Although this is a non-breaking change, it has been flagged to raise a halting error, to alert people to the role_implications change above (which lacks well-defined indicators of its usage).

data/notes/advanced-superpowers.md

@@ -1,16 +0,0 @@
-### Set up Knife on your local machine, and a Chef Server in the cloud
-
-If you already have a working chef installation you can skip this section.
-
-To get started with knife and chef, follow the "Chef Quickstart,":http://wiki.opscode.com/display/chef/Quick+Start We use the hosted chef service and are very happy, but there are instructions on the wiki to set up a chef server too. Stop when you get to "Bootstrap the Ubuntu system" -- cluster chef is going to make that much easier.
-
-* [Launch Cloud Instances with Knife](http://wiki.opscode.com/display/chef/Launch+Cloud+Instances+with+Knife)
-* [EC2 Bootstrap Fast Start Guide](http://wiki.opscode.com/display/chef/EC2+Bootstrap+Fast+Start+Guide)
-
-### Auto-vivifying machines (no bootstrap required!)
-
-On EC2, you can make a machine that auto-vivifies -- no bootstrap necessary. Burn an AMI that has the `config/client.rb` file in /etc/chef/client.rb. It will use the ec2 userdata (passed in by knife) to realize its purpose in life, its identity, and the chef server to connect to; everything happens automagically from there. No parallel ssh required!
-
-### EBS Volumes
-
-Define a `snapshot_id` for your volumes, and set `create_at_launch` true.

data/notes/cookbook-versioning.md

@@ -1,11 +0,0 @@
-Cookbook Versioning and Tracking
-================================
-
-@temujin9 please complete and correct
-
-* git tag labels the *release* of a cookbook version: tag 'cookbooks-elasticsearch-3.1.7' denotes the *last* commit to that tag.
-* The next commit will be the one that bumps the version number: the `metadata.rb` will then read '3.1.8'.
-
-Periodically, we will release a 'gold' version set and push those to the opscode cookbook community site.
-
-* 

data/notes/core_concepts.md

@@ -1,200 +0,0 @@
-# Ironfan Core Concepts
-
-<a name="TOC"></a>
-
-* [Build your architecture from clusters of cooperating machines](#clusters)
-
-* [Decoupled *Components* connect](#components)
-
-* [Components *Announce* their capabilities](#announcements)
-
-* [Announcements enable *Service Discovery*](#discovery)
-
-* [Components announce cross-cutting *Aspects*](#aspects)
-
-* [Aspects enable zero-conf *Amenities*](#amenities) - 
-
-* [Announcements effectively define a component's *Contract*](#contract)
-
-* [Contracts enable zero-conf *specification testing*](#specs)
-
-* [Specs + monitoring enable zero-conf *integration testing*](#ci)
-
-* [Systems *Bind* to provisioned resources](#binding)
-
-* [Binding declarations enable *Resource Sharing*](#resource-sharing)
-
-<a name="overview"></a>
-### Overview
-
-Ironfan is your system diagram come to life. In ironfan, you use Chef to assemble and configure components on each machine. Ironfan assembles those machines into clusters -- a group of machines united to provide an important service. For example, at Infochimps one cluster of machines serves the webpages for infochimps.com; another consists only of elasticsearch machines to power our API; and another runs the lightweight goliath proxies that implement our API. Our data scientists are able to spin up and shut down terabyte-scale hadoop clusters in minutes. All this is supported by an Ops team of one -- who spends most of his time hacking on Ironfan. 
-
-The powerful abstractions provided by Chef and Ironfan enables an autowiring system diagram, inevitable best practices in the form of "amenities", and a readable, testable contract for each component in the stack.
-
-<a name="clusters"></a><a name="facets"></a>
-### Clusters and Facets
-
-A `cluster`, as mentioned, groups a set of machines around a common purpose. Within that cluster, you define `facet`s: a set of servers with identical components (and nearly identical configuration). 
-
-For example, a typical web stack cluster might have these facets:
-
-* `webnode`s: nginx reverse-proxies requests to a pool of unicorns running Rails
-* `mysql`: one or many MySQL servers, with attached persistent storage
-* `qmaster`s: a redis DB and resque front end to distribute batch-processing tasks
-* `qworkers`s: resque worker processes
-
-<a name="components"></a>
-### Components
-
-As you can see, the details of a machine largely follow from the list its `component`s: `mysql_server`, `resque_dashboard`, and so forth. What's a component? If you would draw it in a box on your system diagram, want to discover it from elsewhere, or it it forms part of the contract for your machine, it's a component. 
-
-Some systems have more than one component: the `ganglia` monitoring system has a component named `agent` to gather operating metrics, and a component named `master` to aggregate those metrics. 
-
-Those examples all describe daemon processes that listen on ports, but component is more general that that -- it's any isolatable piece of functionality that is interesting to an outside consumer. Here is a set of example systems we'll refer to repeatedly:
-
-* *Ganglia*, a distributed system monitoring tool. The `agent` components gather and exchange system metrics, and the `master` component aggregates them. A basic setup would run the `master` component on a single machine, and the `agent` component on many machines (including the master). In order to work, the master must discover all agents, and each agent must discover the master.
-
-* *Elasticsearch* is a powerful distributed document database. A basic setup runs a single `server` component on each machine. Elasticsearch handles discovery, but needs a stable subset of them to declare as discovery `seed`s.
-
-* *Nginx* is a fast, lightweight webserver (similar to apache). Its `server` component can proxy web requests for one or many web apps. Those apps register a `site` component, which defines the receiving address (public/private/local), how the app connects to nginx (socket, port, files).
-
-* *Pig* is a Big Data analysis tool that works with Hadoop, Elasticsearch and more. It provides an executable, and imports jars from hadoop, elasticsearch and others.
-
-<a name="announcements"></a>
-### Components *Announce* their capabilities
-
-Notice the recurring patterns: *capabilities* (serve webpages, execute script, send metrics, answer queries), *handles* (ip+port, jars, swarm), *aspects* (ports, daemons, logs, files, dashboards).
-
-The Silverware cookbook lets your services `announce` their capabilities and `discover` other resources.
-
-Chef cookbooks describe the related components that form a system. You should always have a recipe, separate from the `default` recipe, that clearly corresponds to the component: the `ganglia` cookbook has `master` and `agent` recipes; the `pig` cookbook has `install_from_package` and `install_from_release` recipes. Those recipes are grouped together into Chef roles that encapsulate the component: the `elasticsearch_server` role calls the recipes to install the software, start the daemon process, and write the config files, each in the correct order.
-
-Cookbooks do *not* bake in assumptions about their scale or about the machine they're on. The same Elasticsearch cookbook can deploy a tiny little search box to sit next to a web app, or one server in a distributed terabyte scale database.
-
-<a name="discovery"></a>
-### Announcements enable *Service Discovery*
-
-The `discover` and `discover_all` connect decoupled components. Your systems
-
-* Don't care whether the discovered components are on the same machine, different machines, or a remote data center.
-* Don't care about the number of underlying machines -- the whole thing might run on your laptop while developing, across a handful of nodes in staging, and on dozens of nodes in production.
-* Don't necessarily care about the actual system -- your load balancer doesn't care whether it's nginx or apache or anything else, it just wants to discover the correct set of `webnode`s.
-
-<a name="aspects"></a>
-### Components announce cross-cutting *Aspects*
-
-Besides the component's capabilities, the announcement also describes its aspects: cross-cutting attributes common to many components.
-
-* **log**:         write data to a log file.
-* **daemon**:      long-running process. Can specify run state, resource bounds,  etc.
-* **port**:        serves data over a port. Can specify the protocol, performance expectations, etc.
-* **dashboard**:   HTML, JMX, etc -- internal component metrics and control
-* **executable**:  executes scripts
-* **export**:      libraries, `jar`s, `conf` files, etc 
-* **consumes**:    registered whenever you `discover` another component
-
-<a name="amenities"></a>
-### Aspects enable zero-conf *Amenities* 
-
-Typically, consumers discover their provider, and the provider is unconcerned with which consumers it attends to. Ironfan lets you invert this pattern: decoupled `amenities` find components they can cater to.
-
-* A log aspect would enable the following amenities
-  - `logrotated` to intelligently manage its logs
-  - `flume` to archive logs to a predictable location
-  - If the log is known to be an apache web log, a flume decorator can track rate and duration of requests and errors.
-* A port aspect would enable
-  - zeroconf configuration of firewall and security groups
-  - remote monitors to regularly pinging the port for uptime and latency 
-  - and pings the interfaces that it should *not* appear on to ensure the firewall is in place?
-
-<a name="contracts"></a>
-### Announcements effectively define a component's *Contract*
-
-The announcements that components make don’t just facilitate discovery. In a larger sense, they describe the external contract for the component.
-
-When `nginx` announces that it listens on `node[:nginx][:http_port] = 80`, it is promising a capability (namely, that http requests to that port return certain results). When elasticsearch announces that it runs the `elasticsearch` daemon, it promised that the daemon will be running, with the right privileges, and not consuming more than its fair share of resources.
-
-<a name="specs"></a>
-### Contracts enable zero-conf *Specification Testing*
-
-
-
-* A daemon aspect
-  - implies a process should be running
-  - owned by the right user
-  - with a stable PID
-  - and live within defined memory bounds
-* A log aspect
-  - should be open and receiving content from the process
-  - should contain lines showing successful startup (and not contain lines matching an error).
-* A dashboard/JMX/metrics aspect:
-  - actual configuration settings as read out of the running app should match those drawn from the node attributes. No more finding out a setting was overridden by some hidden config file.
-  - should have a healthy heartbeat and status
-
-[Ironfan-CI](http://github.com/infochimps-labs/ironfan-ci) uses the announcement  to create a suite of detailed [Cucumber](http://cukes.info) (via [Cuken](https://github.com/hedgehog/cuken)) feature tests that document and enforce the machine's contract. You're not limited to just the zeroconf tests: it's easy to drop in additional cucumber specs.
-
-Ironfan-CI is young -- it's for the tenacious zealot only -- but is the subject of current work and developing fast.
-
-<a name="ci"></a>
-### Specs + Monitoring enable zero-conf *Full-stack Testing*
-
-You can now look at monitoring as the equivalent of a full-stack continuous integration test suite. The same announcement that Ironfan-CI maps into cucumber statements can as well drive your favorite monitoring suite (or more likely, the monitoring suite you hate the least).
-
-The Ironfan Enterprise product ships with Zabbix, which is actually pretty loveable -- even moreso when you don't have to perform fiddly repeated template definitions.
-
-<a name="binding"></a>
-### Systems *Bind* to provisioned resources 
-
-Components should adapt to their machine, but be largely unaware of its defaul arrangement. One common anti-pattern we see in many cookbooks is to place data at some application-specific absolute path, to assume a certain layout of volumes.
-
-When my grandmother comes to visit, she quite reasonably asks for a room with a comfortable bed and a short climb. This means that at my apartment, she stays in the main bedroom and I use the couch. At my brother's house, she stays in the downstairs guest room, while my brother and sister-in-law stay in their bedroom.
-
-Suppose Grandmom instead always chose 'the master bedroom on the first floor' no matter how the house was set up. At my apartment, she'd find herself in the parking garage. At my brother's house, she'd find herself in a crowded bed and uninvited from returning to visit.
-
-Similarly, the well-mannered cookbook does not hard-code a large data directory onto the root partition. The root drive is the private domain of the operating system; typically, there's a large and comfortably-appointed volume just for it to use. On the other hand, hard-coding a location of `/mnt/external2` will end in tears if I'm testing the cookbook on my laptop, where no such drive exists.
-
-The solution is to request for volumes by their characteristics, and defer to the machine's best effort in meeting that request.
-
-        # Data striped across all persistent dirs
-        volume_dirs('foo.datanode.data') do
-          type          :persistent, :bulk, :fallback
-          selects       :all
-          mode          "0700"
-        end
-
-        # Scratch space for indexing, striped across all scratch dirs
-        volume_dirs('foo.indexer.journal') do
-          type          :fast, local, :bulk, :fallback
-          selects       :first
-          mode          "0755"
-        end
-
-Another example of this is binding to a network interface. Unfortunately most cookbooks choose the primary address; most of ours choose the 'private' interface if any and fall back to the primary.
-
-The right pattern here is 
-* provisioners tag resources
-* cookbooks to request the best match to their purpose
-* at the cookbook's option, if no good match is found use a fallback or raise an exception
-
-<a name="resource-sharing"></a>
-### Binding declarations enable *Resource Sharing*
-
-Resource sharing is yet another place where an assertive announcement can enable best practices.
-
-Right now, most java-based components hard-code a default JVM heap size. This can lead to a situation where a component shows up on a 16GB machine with 1GB heap allocated, or where five components show up on a 0.7GB machine each with 1GB allocated. 
-
-We instead deserve a deft but highly predictable way to apportion resources (disks, ram, etc). Nothing that gets in the way of explicit tuning, but one which gives a reasonable result in the default case.
-
-The Hadoop cookbook has an initial stab at this, but for the most part Resource Sharing is on the roadmap but not yet in place.
-
-
-__________________________________________________________________________
-
-### Learn More
-
-[Aspect-Oriented Programming](http://en.wikipedia.org/wiki/Aspect-oriented_programming): The Ironfan concept of `aspects` as cross-cutting concerns is taken from AOP. Amenities don't correspond precisely to join cuts etc., so don't take the analogy too far. (Or perhaps instead help us understand how to take the analogy the rest of the way.)
-
-
-Ironfan's primary models form a component-based approach to building a  [Service-Oriented Architecture](http://msdn.microsoft.com/en-us/library/aa480021.aspx). Model examples of a modern SOA include the [Netflix API](http://www.slideshare.net/danieljacobson/the-futureofnetflixapi) (see [also](http://techblog.netflix.com/2011/12/making-netflix-api-more-resilient.html)) and [Postrank](http://www.igvita.com/2011/03/08/goliath-non-blocking-ruby-19-web-server/) (see [also](http://www.igvita.com/2010/01/28/cluster-monitoring-with-ganglia-ruby/)).
-
-

data/notes/declaring_volumes.md

@@ -1,3 +0,0 @@
-
-Please see the [README from the volumes cookbook](https://github.com/infochimps-labs/ironfan-pantry/blob/master/cookbooks/volumes/README.md) for more information.
-

data/notes/design_notes-aspect_oriented_devops.md

@@ -1,36 +0,0 @@
-
-Examples of concerns that tend to be crosscutting include:
-
-Synchronization -- (declare an action dependency, trigger, event)
-Real-time constraints
-Feature interaction
-Memory management
-  - data checks
-  - feature checks
-* security
-  - firewall rules
-  - access control
-Logging
-Monitoring
-Business rules
-Tuning 
-Refactor pivot
-
-
-AOP:
-
-- Scattered (1:n) / Tangled (n:1) 
-- join point: hook
-- point cut: matches join points
-- advice: behavior evoked at point cut
-
-* Interception
-  - Interjection of advice, at least around methods.
-* Introduction
-  - Enhancing with new (orthogonal!) state and behavior .
-* Inspection
-  - Access to meta-information that may be exploited by pointcuts or
-advice.
-* Modularization
-  - Encapsulate as aspects.
-

data/notes/design_notes-ci_testing.md

@@ -1,169 +0,0 @@
-
-  
-https://github.com/acrmp/chefspec
-
-
-pre-testing -- converge machine 
-  https://github.com/acrmp/chefspec
-
-  http://wiki.opscode.com/display/chef/Knife#Knife-test
-
-benchmarks
-
-  bonnie++ 
-  hdparm -t
-  iozone
-
-
-in-machine
-
-* x ports on x interfaces open
-* daemon is running
-* file exists and has string
-
-* log file is accumulating lines at rate X
-* script x runs successfully
-
-in-chef
-
-* runlist is X
-* chef attribute X should be Y
-
-meta
-
-* chef run was idempotent
-
-
-
-
-
-__________________________________________________________________________
-
-## Notes from around the web
-
-
-* ...
-
-  > I'm thinking that the useful thing to test is NOT did chef install
-  > some package or setup a user, but rather after chef has run can I
-  > interact with the system as I would expect from an external
-  > perspective. For example:
-  > 
-  > * Is the website accessible?
-  > * Are unused ports blocked?
-  > * When I send an email thorough the website does it end up in my inbox?
-  > 
-  > Capybara (http://github.com/jnicklas/capybara) enforces this external
-  > perspective for webapp testing:
-  > 
-  > "Access to session, request and response from the test is not
-  > possible. Maybe we’ll do response headers at some point in the future,
-  > but the others really shouldn’t be touched in an integration test
-  > anyway. "
-  > 
-  > They only let you interact with screen elements that a user could
-  > interact with. It makes sense because the things that users interact
-  > with are what provides the business value
-
-* Andrew Shafer < andrew@cloudscaling.com>
-
-  > Here's my thinking at this point... which could be wrong on every level.
-  > There is really no good way to TDD/BDD configuration management for several
-  > reasons:
-  > The recipes are already relatively declarative
-  > Mocking is useless because it may not reflect 'ground truth'
-  > The cycle times to really test convergence are relatively long
-  > Trying to test if a package is installed or not is testing the framework,
-  > not the recipe IMHO.
-  > I agree with the general sentiment that the functional service is the true
-  > test.
-  > I'm leaning towards 'testing' at that level, ideally with (a superset of?)
-  > what should be used for the production monitoring system.
-  > So the CI builds services, runs all the checks in test, green can go live
-  > and that's that.
-  
-
-* Jeremy Deininger < jeremy@rightscale.com>
-
-  > Thought I'd chime in with my experience testing system configuration code @ RightScale so far.  What we've been building are integration style cucumber tests to run a cookbook through it's paces on all platforms and OSs that we support.  
-  > First we use our API to spin up 'fresh' server clusters in EC2, one for every platform/OS (variation) that the cookbook will be supporting.  The same could be done using other cloud APIs (anyone else doing this with VMware or etc?)  Starting from scratch is important because of chef's idempotent nature.
-  > Then a cucumber test is run against every variation in parallel.  The cucumber test runs a series of recipes on the cluster then uses what we call 'spot checks' to ensure the cluster is configured and functional.  The spot checks are updated when we find a bug, to cover the bug.  An example spot check would be, sshing to every server and checking the mysql.err file for bad strings.
-  > These high level integration tests are long running but have been very useful flushing out bugs.
-  > ...
-  > If you stop by the #rightscale channel on Freenode I'd be happy to embarrass myself by giving you a sneak peak at the features etc..  Would love to bounce ideas around and collaborate if you're interested. jeremydei on Freenode IRC
-
-Ranjib Dey < ranjibd@th...s.com>
-
-  > So far, what we've done for testing is to use rspec for implementing tests.  Here's an example:
-  > 
-  >    it "should respond on port 80" do
-  >      lambda {
-  >        TCPSocket.open(@server, 'http')
-  >      }.should_not raise_error
-  >    end
-  > 
-  > Before running the tests, I have to manually bootstrap a node using knife. If my instance is the only one in its environment, the spec can find it using knife's search feature.  The bootstrap takes a few minutes, and the 20 or so tests take about half a minute to run.
-  > 
-  > While I'm iteratively developing a recipe, my work cycle is to edit source, upload a cookbook, and rerun chef-client (usually by rerunning knife boostrap, because the execution environment is different from invoking chef-client directly).  This feels a bit slower than the cycle I'm used to when coding in Ruby because of the upload and bootstrap steps.
-  > 
-  > I like rspec over other testing tools because of how it generates handy reports, such as this one, which displays an English list of covered test cases:
-  > 
-  >    $ rspec spec/ -f doc
-  > 
-  >    Foo role
-  >      should respond on port 80
-  >      should run memcached
-  >      should accept memcached connections
-  >      should have mysql account
-  >      should allow passwordless sudo to user foo as user bar
-  >      should allow passwordless sudo to root as a member of sysadmin
-  >      should allow key login as user bar
-  >      should mount homedirs on ext4, not NFS
-  >      should rotate production.log
-  >      should have baz as default vhost
-  >      ...
-  > 
-  > That sample report also gives a feel for sort of things we check.  So far, nearly all of our checks are non-intrusive enough to run on a production system.  (The exception is testing of local email delivery configurations.)
-  > 
-  > Areas I'd love to see improvement:
-  > 
-  >    * Shortening the edit-upload-bootstrap-test cycle
-  >    * Automating the bootstrap in the context of testing
-  >    * Adding rspec primitives for Chef-related testing, which might
-  >      include support for multiple platforms
-  > 
-  > As an example of rspec primitives, instead of:
-  > 
-  >    it "should respond on port 80" do
-  >      lambda {
-  >        TCPSocket.open(@server, 'http')
-  >      }.should_not raise_error
-  >    end
-  > 
-  > I'd like to write:
-  > 
-  >    it { should respond_on_port(80) }
-  > 
-  > Rspec supports the the syntactic sugar; it's just a matter of adding some "matcher" plugins.
-  > 
-  > How do other chef users verify that recipes work as expected?
-  > 
-  > I'm not sure how applicable my approach is to opscode/cookbooks because it relies on having a specific server configuration and can only test a cookbook in the context of that single server.  If we automated the boostrap step so it could be embedded into the rspec setup blocks, it would be possible to test a cookbook in several sample contexts, but the time required to setup each server instance might be prohibitive.
-  > 
-
-
-Andrew Crump < acrump@gmail.com>
-
-  > Integration tests that exercise the service you are building definitely give you the most bang for buck.
-  > 
-  > We found the feedback cycle slow as well so I wrote chefspec which builds on RSpec to support unit testing cookbooks:
-  > 
-  > https://github.com/acrmp/chefspec
-  > 
-  > This basically fakes a convergence and allows you to make assertions about the created resources. At first glance Chef's declarative nature makes this less useful, but once you start introducing conditional execution I've found this to be a time saver.
-  > 
-  > If you're looking to do CI (which you should be) converging twice goes some way to verifying that your recipes are idempotent.
-  > 
-  > knife cookbook test is a useful first gate for CI:
-  > 
-  > http://wiki.opscode.com/display/chef/Knife#Knife-test