Skip to content

Home

Jump to bottom
Erik Lönroth edited this page May 6, 2017 · 9 revisions

The hello world charm tutorial

This tutorial should get you started with the basics of developing a juju charm.

There are some official documentation on Canonical homepage that takes you through a similar process, but personally I found it too heavy, this tutorial hopefully constitutes the really minimal to get started.

The hello-world juju performs the following:

  • Installs a package
  • Implements the hooks "install", "start", "stop", "config-changed".
  • Shows how to add custom configuration to a charm (config.yaml)
  • Contains all the required meta-data to make it a valid charm.

Now, you should start with the prerequisites for this tutorial.

Prerequisites for this tutorial

  • The tutorial is performed on a Ubuntu 16.04.1 LTS 64 bit operating system.
  • We will make use of the "charm-tools" package to help us through the charm build process.
  • juju version is juju-2.X. If you run on earlier versions, you might need to deploy the hello-world charm from a "local repository" a bit different than stated in this tutorial.

The next step is to verify the juju installation.

Check your juju installation

Verify that juju is operational by running:

juju status

If nothing goes wrong, you are all set up OK.

If you fail here, follow this guide to install juju properly : https://jujucharms.com/docs/2.0/getting-started

Next step is to get charm-tools setup.

Install latest version of "charm-tools".

Even though you might succeed building a charm "manually" the charm-tools are essential to make the build process easy. Add the package repo to your apt-source by issuing the following commands:

sudo add-apt-repository ppa:juju/stable
sudo apt-get update
sudo apt-get install charm-tools

You now have charm-tools installed.

Creating the hello-world charm.

The charm name will be "hello-world" and will demonstrate a few things:

  1. Create the formal requirements files (meta information) of our hello-world charm.
  2. Implement four hooks that makes a charm useful: "install", "start", "stop", "config-changed"
  3. Verify (proof) the hello-world charm.
  4. Deploy the hello-world charm.
  5. Remove the hello-world charm.

Lets create some working directories and use charm-tools to start the development.

mkdir -p juju/charms
cd juju/charms
charm-create hello-world

A new directory named "hello-world" is created which contains the skeleton for our charm. Lets fill in some metadata for our charm to make it compliant with a good charm.

Edit the files README and copyright

cd hello-world
mv README.ex README
nano README
nano copyright

`

Edit metadata.yaml to look like this

name: hello-world
summary: The hello-world charm
maintainer: erik_lonroth <erik.lonroth@gmail.com>
description: |
  This is the hello-world charm.
tags:
  - misc

Add a custom service configuration option

Normally, you need to add some sort of configuration to your application/charm. This is covered in detail here: https://jujucharms.com/docs/2.1/charms-config

For the hello-world charm, we will have a string option in the file "config.yaml". The contents should be like this.

options:
  message:
    type: string
    default: "Hello World"
    description: "This is what a string option might look"

We shall use our option named "message" to display our message when our hook start is called.

Lets implement our hooks.

Implement the hooks (scripts)

The hook scripts we are about to create are:

install - is run for you to install packages and code etc.

start - is run when the application/charm is started.

stop - is run when stopping the application/charm.

config-changed - is run when configuration of a charm has been altered.

You need to create the hooks dir and create the files inside the "juju/charms/hello-world" directory:

mkdir hooks
cd hooks
touch install start stop config-changed

You should create the install hook code as follows:

#!/bin/bash
set -e
status-set maintenance "Installing zip package."
sudo apt -y install zip
juju-log "Installed zip"

You should create the start hook code as follows. Note how we use 'config-get' to access a service configuration option for our message.

#!/bin/bash
set -e
MESSAGE=$(config-get message)
status-set active "Started with message: $MESSAGE"

You should create the stop hook code as follows:

#!/bin/bash
status-set maintenance "Stopped for maintenance"

You should create the config-changed hook code as follows:

#!/bin/bash
set -e
juju-log "config-changed hook was run"

Make the scripts executable

chmod +x *

Build the charm

Verify that you made everything right with the charm

charm build hello-world

Deploy the charm from your local repository directory.

juju deploy ~/juju/charms/hello-world --series xenial

Watch the hello-world charm status as it comes alive (can take a few seconds)

juju status

Once its status is "active", lets play with your stop hook:

juju run --unit hello-world/0 'hooks/stop'

juju status

Then, test the start hook:

juju run --unit hello-world/0 'hooks/start'

juju status

You can also test to display the configs you added for the hello-world charm.

juju config hello-world

Congratulations! You have just finished the hello-world tutorial of building charms.

Now you should move on to learn the "reactive" way of doing this very same thing. For this, I've created the hello-world-reactive tutorial.

Clone this wiki locally