Barclamp: create & install steps

Adam Spiers edited this page Aug 26, 2016 · 10 revisions

FIXME: this page is way out of date!

Version 1.x

15 minute how to video:

A barclamp is a deployment module that is imported from its own code repository into the Crowbar framework. A barclamp cannot operate without Crowbar, but you do not have to create a unique build of Crowbar in order to create a barclamp.

The first thing to know about barclamps is that most of the work (80%!) is building your Chef cookbooks. If you don’t have a cookbook that deploys your application then stop here and work on that first.

The second thing to know about barclamps is that there are a lot of them that you can study for examples. Check out the Glance barclamp if you have a single server deployment, Nagios if you have a service that needs to be integrated into every node, Nova if you have a complex multi-component system and Provisioner if you want to impact core Crowbar functionality.

We’ve done a lot of work to make it easy to create and install a stub barclamp. Our experience is that building a barclamp is a highly iterative exercise with a lot of testing. Luckily, Crowbar’s primary mission is to help you brush, rinse and repeat. From there, you can customize and extend your barclamp to deploy your application’s full untamed glory.

Before you try to create a new barclamp, you must install Crowbar.

Creating a barclamp

The following steps use the barclamp_model that included under /dell/opt and is described below.

  1. Figure out the name of your barclamp. I’m naming our example “foo barclamp”
    1.     Barclamps must have unique names.
    2.     Do not use spaces or hyphens.
  2. From the Crowbar server, become the super admin: sudo -i
  3. Create a directory for your barclamp: mkdir /barclamps
  4. Run the barclamp create script: /opt/dell/bin/barclamp_create.rb foo “Zehicle” /barclamps
    1.     “foo” is our barclamp name [required]
    2.     “Zehicle” is my company name for the copyright information [default is Dell]
    3.     “/barclamps” is the path where we are putting the barclamp [default is /opt/dell/barclamps]
  5.     Result will be a populated barclamp. In this example: /barclamps/foo

That’s it! If you want to plan ahead then you could use an initialized git repo as the target.

Reminder: In building your barclamp, you’ll need to learn about Chef, how Crowbar extends cookbooks and how barclamps interact. That’s beyond the scope of this post.

Importing a barclamp

Once you created a barclamp, you can import the barclamp into Crowbar & Chef.

Assuming that you already created the foo barclamp in /barclamps, here are the steps:

  1. From the Crowbar server, become the super admin: sudo –i
  2. Run the barclamp install script: /opt/dell/bin/barclamp_install /barclamps/foo
    1.     “/barclamps/foo” is the path to your barclamp. It could be anything!
    2.     The core barclamps are in /opt/dell/barclamps.
    3.     In a vm, you could mount a shared folder to access the barclamp (e.g.: /mnt/hgfs/barclamps)

Your barclamp should now show up in the Crowbar UI! You can also see it in Chef under the Crowbar databag.

While barclamps are generally safe to install multiple times, you can uninstall a barclamp using “barclamp_uninstall.rb /path/to/barclamp”

Barclamp layout

A barclamp has the following core components:

crowbar.yml configuration file (documented below)
README.txt file (optional, recommended)
chef directory containing
    Cookbooks directory with Chef cookbooks
    Data_bags directory with Crowbar configuration files
    Roles directory with Chef roles used by the cookbooks and data_bags
crowbar_framework directory
    app directory with Crowbar model, controller, and view code
    other optional directories to add components needed by the UI such as images

The barclamp_model has a functional layout that covers most configuration requirements. The string ==BC-MODEL== indicates places where the name of the barclamp must be substituted. It is critical to understand that the name of the barclamp is embedded into the barclamp path and file names! This is needed to avoid file collisions when the barclamp is imported. Crowbar.yml

The crowbar.yml file is a required configuration file that gives direction to the installer. The file has many components and documented on the Barclamp crowbar.yml page.

The minimum components are:

barclamp: name: name of your barclamp (required, do not use space or hyphens)


layout: 1 (use the # one. This is required because it tells the installer what to expect inside your barclamp)

Barclamp Proposal

To provide configuration information for your barclamp when handling node transitions or cookbook attributes, a proposal and its validation schema needs to be defined. The crowbar framework defines a basic schema for all proposals. This is required to meet basic crowbar functions. This is versioned and controlled by the installation process to make sure the schema is up to date or updated to the latest. The base crowbar sections are controlled by the crowbar/proposal_schema_version in the crowbar.yml file. Barclamp Proposal Schema description and versions.

The attributes section of the proposal defines the barclamp's unique configuration space. This is versioned and controlled by the barclamp/proposal_schema_version. The installer doesn't do anything with this currently.