/ 
App-CharmKit-0.017
River stage zero No dependents
/ App::CharmKit::Manual::WritingHooks

NAME

App::CharmKit::Manual::WritingHooks - How to write hooks using CharmKit

VERSION

version 0.017

Creating a hook

$ charmkit generate config-changed

This places a templated hook in src/hooks/ where all hook development resides.

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 = 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
} );

path('/etc/default/bitlbee')->spew_utf8($output);

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

service_control('bitlbee', 'restart');

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

open_port($port);

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

Further reading

There are several helpers exposed automatically in order to simply the writing of hooks. To see what helpers are available look at the module documentation:

AUTHOR

Adam Stokes <adamjs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 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.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.