Getting Started

For a video introduction to charmhelpers, check out this Charm School session. To start using charmhelpers, proceed with the instructions on the remainder of this page.

Installing Charm Tools

First, follow these instructions to install the charm-tools package for your platform.

Creating a New Charm

$ cd ~
$ mkdirs -p charms/precise
$ cd charms/precise
$ charm create -t python mycharm
INFO: Generating template for mycharm in ./mycharm
INFO: No mycharm in apt cache; creating an empty charm instead.
Symlink all hooks to one python source file? [yN] y
INFO:root:Loading charm helper config from charm-helpers.yaml.
INFO:root:Checking out lp:charm-helpers to /tmp/tmpPAqUyN/charm-helpers.
Branched 160 revisions.
INFO:root:Syncing directory: /tmp/tmpPAqUyN/charm-helpers/charmhelpers/core -> lib/charmhelpers/core.
INFO:root:Adding missing __init__.py: lib/charmhelpers/__init__.py

Let’s see what our new charm looks like:

$ tree mycharm/
mycharm/
├── charm-helpers.yaml
├── config.yaml
├── hooks
│   ├── config-changed -> hooks.py
│   ├── hooks.py
│   ├── install -> hooks.py
│   ├── start -> hooks.py
│   ├── stop -> hooks.py
│   └── upgrade-charm -> hooks.py
├── icon.svg
├── lib
│   └── charmhelpers
│       ├── core
│       │   ├── fstab.py
│       │   ├── hookenv.py
│       │   ├── host.py
│       │   └── __init__.py
│       └── __init__.py
├── metadata.yaml
├── README.ex
├── revision
├── scripts
│   └── charm_helpers_sync.py
└── tests
    ├── 00-setup
    └── 10-deploy

6 directories, 20 files

The charmhelpers code is bundled in our charm in the lib/ directory. All of our python code will go in hooks/hook.py. A look at that file reveals that charmhelpers has been added to the python path and imported for us:

$ head mycharm/hooks/hooks.py -n11
#!/usr/bin/python

import os
import sys

sys.path.insert(0, os.path.join(os.environ['CHARM_DIR'], 'lib'))

from charmhelpers.core import (
    hookenv,
    host,
)

Updating Charmhelpers Packages

By default, a new charm installs only the charmhelpers.core package, but other packages are available (for a complete list, see the API Documentation). The installed packages are controlled by the charm-helpers.yaml file in our charm:

$ cd mycharm
$ cat charm-helpers.yaml
destination: lib/charmhelpers
branch: lp:charm-helpers
include:
  - core

Let’s update this file to include some more packages:

$ vim charm-helpers.yaml
$ cat charm-helpers.yaml
destination: lib/charmhelpers
branch: lp:charm-helpers
include:
  - core
  - contrib.storage
  - fetch

Now we need to download the new packages into our charm:

$ ./scripts/charm_helpers_sync.py -c charm-helpers.yaml
INFO:root:Loading charm helper config from charm-helpers.yaml.
INFO:root:Checking out lp:charm-helpers to /tmp/tmpT38Y87/charm-helpers.
Branched 160 revisions.
INFO:root:Syncing directory: /tmp/tmpT38Y87/charm-helpers/charmhelpers/core -> lib/charmhelpers/core.
INFO:root:Syncing directory: /tmp/tmpT38Y87/charm-helpers/charmhelpers/contrib/storage -> lib/charmhelpers/contrib/storage.
INFO:root:Adding missing __init__.py: lib/charmhelpers/contrib/__init__.py
INFO:root:Syncing directory: /tmp/tmpT38Y87/charm-helpers/charmhelpers/fetch -> lib/charmhelpers/fetch.

A look at our charmhelpers directory reveals that the new packages have indeed been added. We are now free to import and use them in our charm:

$ tree lib/charmhelpers/
lib/charmhelpers/
├── contrib
│   ├── __init__.py
│   └── storage
│       ├── __init__.py
│       └── linux
│           ├── ceph.py
│           ├── __init__.py
│           ├── loopback.py
│           ├── lvm.py
│           └── utils.py
├── core
│   ├── fstab.py
│   ├── hookenv.py
│   ├── host.py
│   └── __init__.py
├── fetch
│   ├── archiveurl.py
│   ├── bzrurl.py
│   └── __init__.py
└── __init__.py

5 directories, 15 files

Next Steps

Now that you have access to charmhelpers in your charm, check out the Examples or API Documentation to learn about all the great functionality that charmhelpers provides.