configuration.md

Configuration DSL

Builderator's configuration language is a Ruby DSL, composed of attributes, which are grouped into namespaces. A namespace may be singular, or it may be part of a collection, in which case more than one named entry may be defined with the same namespace.

Namespaces and collections can accessed with blocks, or with a fluent interface:

aws do |a|
  a.region = 'us-west-1'
end

## Is the same as
aws.region = 'us-west-1'

Collections are sets of named items. Like namespaces, they can be accessed with blocks, or a fluent interface:

profile :default do |default_profile|
  default_profile.chef.run_list 'apt:default', 'redis:server', 'app::server'
end

profile(:default).chef.environment 'development'
profile(:prod).chef.environment 'production'

In the example above, the same collection item is accessed twice. A second item is also defined in the same collection. The final result looks like:

{
  "profile": {
    "default": {
      "chef": {
        "run_list": ["apt:default", "redis:server", "app::server"],
        "environment": "development"
      }
    },
    "prod": {
      "chef": {
        "environment": "production"
      }
    }
  }
}

Collections and namespaces may be nested indefinitely.

Extending Collection Items

A collection item can extend another item using a hash-notation:

profile :prod => Config.profile(:default) do |prod|
  prod.chef.environment = 'production'
end

Following the example, above, the prod profile will now be pre-populated with all of the values in the default profile, which can be overridden:

{
  "profile": {
    "default": {
      "chef": {
        "run_list": ["apt:default", "redis:server", "app::server"],
        "environment": "development"
      }
    },
    "prod": {
      "chef": {
        "run_list": ["apt:default", "redis:server", "app::server"],
        "environment": "production"
      }
    }
  }
}

List-type Attributes

Some configuration attributes are actually ordered sets of values. These are referred to as list-type attributes, and have some additional options:

chef.run_list 'apt:default', :mode => :override

The :mode parameter tells the configuration manager how how to compile a list-type attribute that is defined in two or more layers, or is modified in an extended collection item. Currently, two modes are implemented:

• :override - Instructs the compiler to discard any elements that have been loaded from lower layers. This does not have any effect upon the behavior of the same attribute in higher layers, meaning that the current layer's override may be appended to or overridden by future layers, according to their mode parameter.
• :union - Default behavior. Instructs the compiler to perform a set-union between the current layer's elements and the current set of elements compiled from lower layers.

List-type attributes may also have an appender method, which allows elements to be appended to the current set in that layer. List-type attributes do not have an = setter.

Because chef.run_list is a list-type attribute, we can tell Builderator to override the default profile's run_list:

profile :prod => Config.profile(:default) do |prod|
  prod.chef.environment = 'production'
  prod.chef.run_list 'apt:default', 'redis:server', 'app::server', 'app::tls', :mode => :override
end

We could also append to default's run_list without modifying default:

profile :prod => Config.profile(:default) do |prod|
  prod.chef.environment = 'production'
  prod.chef.run_list_item 'app::tls'
end

Both of the above will result in the same compiled configuration:

{
  "profile": {
    "default": {
      "chef": {
        "run_list": ["apt:default", "redis:server", "app::server"],
        "environment": "development"
      }
    },
    "prod": {
      "chef": {
        "run_list": ["apt:default", "redis:server", "app::server", "app::tls"],
        "environment": "production"
      }
    }
  }
}

Helper Methods

• lookup(source, query) - Query an external data-source for a value inline.

• Source :image: Return an array of EC2 instances, sorted by creation_date (See http://docs.aws.amazon.com/sdkforruby/api/Aws/EC2/Client.html#describe_images-instance_method)

• vendored(name, path) - Return the absolute path to path in the named vendor resource. _ Hint: Use this helper to reference Builderator policy files and Chef data_bag and environment sources in an external repository._

• relative(path) - Return the absolute path to path relative to the calling Buildfile Hint: Use this helper to reference templates included with a vendored policy.

Configuration Parameters

• Namespace cookbook

• Collection profile

• build_name, required: true The name of the build

• build_number Optional reference to the CI build number for this release

• build_url Optional link the CI page for this release

• description A short human-readable description of the build

• version The version of this release of the build. Auto-populated by autoversion by default

• cleanup Enable post-build cleanup tasks. Default true

Namespace autoversion

• create_tags During a release, automatically create and push new SCM tags
• search_tags Use SCM tags to determine the current version of the build

Namespace chef

Global configurations for chef provisioners in Vagrant and Packer

• log_level Chef client/solo log level
• staging_directory the path in VMs and images that Chef artifacts should be mounted/copied to. Defaults to /var/chef
• version The version of chef to install with Omnibus

Namespace local

Local paths used for build tasks

• cookbook_path Path at which to vendor cookbooks. Default .builderator/cookbooks
• data_bag_path and environment_path Paths that Chef providers should load data-bag and environment documents from.

Collection policy

Load additional attributes into the parent file from a relative path

• path Load a DSL file, relative => true
• json Load a JSON file relative => true

Namespace aws

AWS API configurations. Hint: Configure these in $HOME/.builderator/Buildfile, or use a built-in credential source, e.g. ~/.aws/config!

• region The default AWS region to use
• access_key and secret_key A valid IAM key-pair

Collection vendor

Fetch remote artifacts for builds

• Sources:
  • path Link to a local file/directory
  • git Fetch a git repository
  • github Fetch a git repository from a GitHub URI (e.g. OWNER/REPO) using the SSH protocol. You must have a valid SSH key configuration for public GitHub.
• Git-specific parameters:
  • remote - The name of the remote repository at git or github. Defaults to origin
  • branch - The SCM branch to check out. Defaults to master
  • tag or ref - A SHA-ish or SCM tag to check out. Overrides branch.
  • rel Checkout a sub-directory of a git repository

Namespace cleaner

Configuration parameters for build-clean tasks

Namespace limits

Maximum number of resources to remove without manual override

• images
• launch_configs
• snapshots
• volumes

Namespace generator

Configurations for the generator task

Collection project

• builderator.version The version of Builderator to install with Bundler
• ruby.version The version of ruby to require for Bundler and rbenv/rvm

Namespace vagrant

• install Boolean, include the vagrant gem from GitHub mitchellh/vagrant
• version The version of Vagrant to use from GitHub, if install is true

Collection plugin

Vagrant plugins to install, either with the build vagrant plugin command, for a system-wide installation of Vagrant, or in the generated Gemfile if install is true

Collection resource

Add a managed file to the project definition

• action One of
  • :create Add a file from a template if it's missing
  • :sync Create or update a file from a template, stopping to ask for instructions if the file exists and the templated output does not match
  • :ignore Do nothing
  • :rm Delete a file if it exists
• path One or more path in the working directory the this resource manages. Action :rm will delete multiple files, while :create and :sync will only use the first element of the list as their destination.
• template The path to an ERB template. Must be an absolute path: use the helpers in the Buildfile namespace to extend paths inline.