yet.org

Anatomy of a Barclamp

As detailled in the official Crowbar glossary, a barclamp is a set of data, templates and other necessary logic for applying a particular role to a node, or to some set of nodes. Interesting description isn’t it. Let’s dig in the anatomy of a barclamp.

For the non anglophone around, here is a real barclamp.

As you’ve noticed, Crowbar terminology uses the toolbox vocabulary, you’ll find Jig and other tools around, but that’s for another day. Let’s talk about the Barclamp today.

If you look at an example barclamp, here is what you’ve got in stock.

As you can see, it’s a bunch of Ruby, ERB, JSON, HAML, YAML, MARKDOWN, it’s like a family reunion isn’t it.

./chef

The most significant component of a barclamp lies under the Chef directory. A barclamp is usefull to automate deployment of a role to a node, a role consist of a run-list and some attributes. A run-list is an ordered list of roles or recipes. And a recipe is stored in a Cookbook.

Seems complicated ? on the contrary when you’ll get familiar with this terminology having such standard ways to name all the component helps a lot.

So in this directory you’ll find all thoses required components: Cookbooks, Recipes, Roles, Attributes plus templates and data_bags. Before going any further you need to familiarize yourself with them by reading the corresponding Chef documentation.

Here is a brief summary

glossary
cookbook defines a scenario, contain all the required components to support it: attributs, recipes, templates, …
recipe a collection of resources in a Ruby syntax
role zero (or more) attributes and a run list
run-list ordered list of roles and/or recipes
template used to manage file contents with an ERB template
attribute can be defined in a cookbook (or a recipe) and then used to override the default settings on a node
data_bag global variable, stored as JSON data and is accessible from a Chef Server

Let’s take the git barclamp which is usefull to install and configure git on a node as an example. You’ll find inside the Chef directory:

It’s about:

  • 2 recipes (config and install)
  • 2 templates (authorized keys and upstart.conf)
  • 1 git role to install and configure git on a node.
  • 3 definitions (declares new resources)

All this is pretty standard Chef stuff, but there is one more thing here, data_bags/crowbar/bc-template-git.json contains a new data bag which is used to tie-in Chef and Crowbar Framework together.

crowbar.yml

Barclamp metadata. This file directs the installation of the barclamp by the Crowbar Framework. The major stanzas are:

  • barclamps - details about the barclamp itself
    • name
    • display
    • description
    • proposal_schema_version
    • user_managed - controls if barclamp is shown in UI list (true=yes)
    • version
    • requires - could use a another-barclamp or a @barclamp-group as dependency
    • member - allows you to declare that this barclamp is a member of a group of related barclamp.
    • os_support - declare that this barclamp only supports specific operating systems (support all by default)
  • crowbar - installation instructions
    • layout
    • order
    • run_order
    • chef_order
    • proposal_schema_version
  • nav - inject items in the Crowbar UI menu (if present)
  • debs - to add an apt repository that the build system should pull packages from.
    • repos - add an apt repository that the build system should pull packages from (std sources.list format)
    • ppas - declare Ubuntu personal package archives that the build should try to pull from.
    • pkg - a list of extra packages that the build system will try to pull and cache on the crowbar iso image within /tftpboot/ubuntu–12.04/crowbar-extra/
    • raw_pkgs - a list of URLs to .deb packages that the build system will try to download and add to the iso (no dep checking, curl used to download .deb)
    • os-token - you can have multiple OS specific sections as well.
      • repos
      • ppas
      • pkg
      • raw_pkgs
  • rpms - does the same thing that debs does for RPM-based systems.
    • repos
      • rpm - to use a repo that is set up using an RPM. (like EPEL).
      • bare - to use a repository that does not allow easy installation via rpm.
    • pkgs - put your rpms in this section
    • raw_pkgs
    • pkg_sources - pull a .src.rpm for use by the rest of the build system.
    • os-token
      • build_cmd: your_shell_script.sh - bash file called after the rest of the packages and files have been staged in the build cache. It should should have two functions declared
        • bc_needs_build - return 0 if the external pkg needs building, 1 otherwise
        • bc_build See (README.build) - responsible for using the provided chroot enviromnent to build the external package.
  • gems - declare the gems you need, including version, will resolve dependencies.
    • pkgs - put your gems in this section.
  • extra_files - downloads and saves a file to be slipstreamed on to the crowbar .iso in the extra/files directory
  • locale_additions - localization stuff

For more details consult /opt/dell/crowbar_framework/barclamp_model on an admin node.

crowbar_framework/app

Crowbar leverage the Rails Framework, in this directory you’ll find the corresponding components to be able to consume your barclamp through the Crowbar Rails application.

  • controllers/git_controller - Overrides BarclampController
  • models
  • views - defines UI stuffs

But this is now reworked as a crowbar_engine instead.

crowbar_engine

I don’t have much information regarding this new configuration architecture. I hope to update this section when more docs will come up from the dev team.

./bin

Contain binaries for /opt/dell/bin, which will be installed by barclamp_install.rb.

Conclusion

Just keep in mind that a barclamp does not standalone but require the Crowbar Framework.