NAME

WritingHooks - How to write a Juju charm hook

Writing a hook

We'll start with an example of a config-changed hook and break down the code piece by piece

  #!/usr/bin/env perl
  use charm;

use charm is the entrypoint to exposing charm routines useful for deploying the service. This provides facilities such as installing packages, printing logs, getting relation information, and configuring service level options.

  log "Start of charm authoring for config-changed";

The log facility uses juju-log as the utility for logging what's happening in your charm.

  my $port = run 'config-get port';

config-get routine will pull config options defined in config.yaml.

  # close existing bitlbee port

  log "Opening port for bitlbee";

  ( my $output = qq{BITLBEE_PORT=$port
  BITLBEE_OPTS="-F"
  BITLBEE_DISABLED=0
  BITLBEE_UPGRADE_DONT_RESTART=0
  } );

  file "/etc/default/bitlebee", content => $output;

path is exposed from Path::Tiny so anything that applies to that module works the same here.

  service 'bitlbee' => 'restart';

service_control is another helper for start/stopping services on the system where the charm is placed.

  run "open-port $port";

open_port exposes a port accessible publicly, and its opposite close_port will remove that accessibility.

Adding custom libraries

There are cases where you want to write reusable subroutines to be used throughout your charm hooks. charmkit will automatically search in your toplevel project searching for a lib directory. Similar to how you write Perl modules.

For example, your directory structure

The structure your project should look similar to:

  charm-project/
    hooks/
      install
      config-changed
      start
      stop
      upgrade-charm
    tests/
      00-basic.test
    lib/                # Add lib to toplevel charm directory
      bitlbee.pm
    t/
      01-test-bitlbee.t
    config.yaml
    metadata.yaml
    LICENSE
    README.md

Now in your hook file you can just call:

  #!/usr/bin/env perl
  use charm;
  use bitlbee;

  my $bb = bitlbee->new;
  $bb->syntax_check_config;

AUTHOR

Adam Stokes <adamjs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Adam Stokes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.