Helpers Charm Helpers is a Python library that simplifies charm development by providing a rich collection of helpful utilities for: Interacting with the host machine and environment Responding to hook events Reading and writing charm

Tools The Charm Tools package is a collection of commands that assist with charm management. In particular, it allows charm authors to create charms. Installation Charm Tools can be installed on various platforms with the use of Snaps. The

hooks An application unit's direct action is entirely defined by its charm's hooks. Hooks are executable files in a charm's hooks directory; hooks with particular names (see below) will be invoked by the juju unit agent at particular times,

charms As a charm goes through its software life cycle it may become outdated if it is not maintained. Specifically, a charm may fail to deploy, relate, or execute defined configuration options. When this happens we will follow the below process

metadata The only file that must be present in a charm is metadata.yaml, in the root directory. A metadata file must be a valid yaml dictionary, containing at least the following fields: name is the charm name, which is used to form the charm

add Upgrade a Charm A charm can be changed at runtime with the upgrade-charm command. By default, it changes to the latest available version of the same charm; if --revision is specified, it changes to that revision of the same charm; and if --switch is specified

makes a Charm? Each charm is a structured bundle of files. Conceptually, charms are composed of metadata, configuration data, and hooks with some extra support files. Required files A charm requires only a single file in order to be considered valid by

promulgation To promulgate a Juju charm a member of the ~charmers Launchpad group will: Download the proposed charm (charm pull). Perform static analysis on the charm (charm proof). Ensure the charm has a bugs-url and homepage (charm set). If

unit is running a charm that agrees on how to implement the interface, the data will change and the hook will be run again. In all other cases - unit hooks, relation hooks for a different relation, relation hooks for a different remote unit in the same relation, and

charms that use terms Many applications require the acceptance of terms in order to be installed. Starting with Juju 2, charms can require a user accept its terms in order for it to be deployed. Because of the nature of terms, the user must have a

debug charm code, and there are also community written plugins that can help with the debugging process. Juju provides two commands, juju debug-log and juju debug-hooks, to help developers resolve problems in their code. The dhx debugging plugin improves

for the Charm author Actions are scripts, binaries, or other executables defined on a charm which may be invoked or queued remotely by the user on demand. For example, the Charm author might include a snapshot Action on a database Charm. See here for more

than writing Charms are built from layers. Layers let you build on the work of other charmers, whether that work is in the form of other charms that you can extend and modify or interfaces that are already built for you and know how to communicate with a remote

#1093): 1. charms may be different depending on target OS 2. can choose which charm to use; can deploy on a series that it doesn't claim to support 3. however, to have things 'just work', don't bother specifying anything and the charm will

Started with charm development This guide is for anyone wanting to creating the code that we call a charm; the part that does the work of installing and managing applications in a Juju model. Many charms exist in the [Juju Charm Store][charm store] already, but

for the charm author Leadership provides a mechanism whereby multiple units of an application can make use of a single, shared, authoritative source for charm-driven configuration settings. Every application deployed by Juju is guaranteed to have at most

Charm Tests Charm authors will have the best insight into whether or not a charm is working properly. It is up to the author to create tests that ensure quality and compatibility with other charms. The purpose of tests The intention of charm tests

with Docker You have a Docker container and you heard about Juju. Juju can deploy your Docker container to any cloud. This document will outline the best practices for using Juju to deploy Docker images. First things first This document

hooks reference Hooks are executable files in a charm’s hooks directory. Hooks are invoked by the Juju agent to trigger events in a charm. All the hooks must be written to be idempotent, meaning that there should be no difference from running

hook tool allows charms to discover important network related information. There are 2 key things a charm needs to know about its local units: What address to bind to What address to advertise for external access to the workload (ingress) For remote units, a charm

for the charm author Actions are executables associated with a charm that may be invoked by the user. For example, the charm author might include a snapshot action on a database charm. See Juju Actions on how to use actions. The user may pass arguments when

Charms and Bundles Review Tips and Criteria The goal is to welcome the contributor and help them have a good experience getting fixes into Ubuntu; your first response should be to thank them profusely. By making collaboration easier, we can hope to

for the Charm author Leadership provides a mechanism whereby multiple units of an application can make use of a single, shared, authoritative source for charm-driven configuration settings. Every application deployed by Juju is guaranteed to have at most

do all the other charms with the same role for the interface; and you should only expect to be able to read those settings set by the other charms with the counterpart role. Juju decides which applications can be related based on the interface names only. They have

icons for charms In order to make your charm recognisable in the Charm Store, it is best practice to add a unique and recognisable icon for it. This isn't as hard as it may seem, as this step by step guide will demonstrate. Icon specifications Before we start

creating a charm, you always have the option of doing it the traditional way by creating each hook, implementing each side of the interface you need for each relation your charm requires or provides, manage the dependencies, such as charm-helpers, that your

store policy This document serves to record the policies around charms and bundles included in the charm store, and the management of said collection. Charms and bundles in the store are peer-reviewed by the community and are considered ready

charms that use storage The storage feature can be implemented in any charm running on Juju version 1.25 or later. For applications that can take advantage of block storage or other types of storage there are two additional storage hooks for the

charms offline Clouds that do not enjoy a connection to the internet can nonetheless make use of Juju charms provided that local copies of the charms are prepared in advance. Examples of common offline clouds are LXD, MAAS, and OpenStack. These

Juju Charm Store Juju includes a charm store where charms and bundles can be uploaded, released (published), and optionally shared with other users. The charm store is broken down into two main sections: Recommended and Community. Recommended charms have

used to build a charm can have a layer.yaml file. The top layer (the one actually invoked from the command line) must. These tell the generator what do, ranging from which base layers, to which interfaces to include. They also allow for the inclusion of specialized

Review Process Reviewing a Juju Charm is a process that can easily be broken down into the following parts: Identifying what to review Setting up a branch of the charm Charm Information Review Charm Deployment, Configuration and

by the mysql charm, and is required by a number of charms currently in the Charm Store and elsewhere which would like to use or actually require a MySQL database. Hook Implementation: relation-joined In theory When the mysql charm is notified of a “relation

Practice for Charm Authors This document is to capture charm best practices from the community. We expect devops to be strongly opinionated, therefore some strong opinions don't make sense as policy, but do make sense to share with others to

a charm author Juju makes deploying cloud applications spectacularly easy. One of the key components of the Juju ecosystem that makes this possible is the wealth of quality, reliable charms enabling users to quickly and reliably deploy all sorts of

configuration The charm author can use the optional config.yaml file to define a charm's configuration. This file also becomes available to the end user if they choose to download the charm in order to inspect it. If this file is used, it must

first charm starts here! Okay, so you have read up all the background info on what a charm is, how it works, and what parts of the charm do what, now it is time to dust off your favourite code editor (no arguments please) and get charming! Although it is

of installing the charm - downloading it, unpacking it and calling the install hook.The unit may transition to the maintenance state at any time, in any hook. The maintenance state implies that the unit has no reason to think that it will not provide service soon.

over the charm directory. This means that it's generally safe to juju ssh into the unit and use it as though you were the sole administrator; juju will only take back control of the directory when explicitly requested, in response to either juju resolved or

with the upgrade-charm command, where the upgrade candidate is known as the revision. The default channel is naturally the channel of the currently deployed charm. !!! Note: It is possible, though unlikely, that the revision is older than that of the

tools to make charming easier for developers. While the documentation provides generic information how to write charms, this section gives specific information for developers. Charm with Docker Do you have an idea for something to add here? Check out how to

building from charm layers is a quick and easy process most of the time, occasionally things surface which are not immediately obvious to us as the end user. Thankfully layers are straightforward and simple to debug. Environment Variables Often times, unexpected

that a charm can make use of or may require in order to run. There are three ways to examine resources: Charm resources Application resources Unit resources Each of these will be explained below. Also see Developer resources in the Charm

is possible for a charm to download this software from package repositories or other locations, some charms may be deployed in data centers with restrictive firewalls that do not allow access to all areas of the Internet. It may also be desirable to more strictly

Cycle When charming with the reactive framework, it’s possible to use developer-created states and boolean logic to run code when the states represent something meaningful to your deployment, such as when a database is connected, and when it is available, or

with non-existant charm. It did not for me but the old version of this doc said it should. Review required. Channnels especially This page is too long. It should contain just basic stuff and link to sub-pages. Hardcoded: Ubuntu

the various Juju Charmer Summits. The Juju Show is broadcast regularly, and features the latest developments, community news, demos and guest speakers. Send us a message on Twitter using #jujucharms. Join us on IRC. We can be found on the juju channel on

built in to each charm which allow them to communicate. Unless you are writing charms, there is no need to go into detail on hooks, but these are the parts that make creating relationships between applications so easy. The charm for WordPress, for example, knows

new in 2.3 The major new features in this release are summarised below. If you're new to Juju, begin by going through our Getting started guide first. For details on these features, and other improvements not listed here, see the 2.3 release

into a charm Use this if you bundle benchmarking as part of your application, or if the benchmark suite for your application runs on the same machine. Load generation charm Use this if your charm requires software to be run externally across a

a charm on CentOS is no different than deploying one on Ubuntu or Windows. The only thing that needs to change is the series which is "centos7". For example, from Launchpad: bash juju deploy lp:~me/centos7/charm or from a local charm: bash juju

application's charm. Implicit relationships are named in the reserved juju-* namespace. Both the relation name and interface names provided by Juju are prefixed with juju-. Charms attempting to provide new relationships in this namespace will trigger

in Juju's 'charms'. This knowledge can then be shared between team members, reused everywhere from laptops to virtual machines and cloud, and shared with other organisations. The charm defines everything you all collaboratively know about deploying

Creating Bundles Charms are seldom deployed in isolation. Even MediaWiki needs to be connected to a database. Instead, charms are mostly used to model more complex deployments, potentially including many different applications and connections. A Bundle is an

charms that collect metrics Knowing an application's configuration isn’t enough to effectively operate and manage it. Consider that a well-designed application will have as few configurable parameters as possible. Operators will want to know more

quickly deploy charms and bundles with those versions of Juju and allowed editing and management of various different Juju clouds. The functionality provided by juju quickstart is not supported or required in the current version of Juju. Most of this functionality

users. Charms The magic behind Juju is a collection of software components called Charms. They contain all the instructions necessary for deploying and configuring cloud-based applications. The charms publicly available in the online Charm Store

will be writing a charm layer for Vanilla. Vanilla is an open source, themeable, pluggable, and multi-lingual forum software, which enables communities to host a forum for discussion topics at scale. Powered by PHP and MySQL, Vanilla is a fine example of a

implies that every charm author need be aware of any and all applications a deployment might wish to depend on, even if the other application can operate without any explicit cooperation. For example a logging application may only require access to the container level

either as 'charms' or as 'bundles'. Charms are singular applications, such as Haproxy or PostgreSQL, whereas bundles are a curated collection of charms and their relationships. Bundles are ideal for deploying OpenStack, for instance, or Kubernetes. It's also

that relation. Charms are written to handle this, but be aware that the other application may no longer work as expected. To remove relations between deployed applications, see Charm relations. This is the order of events for removing an

of the primary charm that provides that interface. However, it does cover both sides (provides and requires) of the relation and turns the two-way key-value store that are Juju relations under-the-hood into a full-fledged API for interacting with charms supporting

and authors-charm-writing.md Hook tools Units deployed with Juju have a suite of tooling available to them, called ‘hook tools’. These commands provide the charm developer with a consistent interface to take action on the units behalf, such as opening ports,

and managing Juju Charms, there are many Juju commands which deal with the management of Juju itself, covering actions from disabling certain commands to enabling high availability for the Juju controller. These topics are covered in the pages listed under this

set a local charms directory that Juju would search when deploying an application. The equivalent --repository=/path/to/charms switch (with juju deploy) was also available. Both the environment variable and the switch are no longer functional in

register jimm.jujucharms.com This command will open a new window in your default web browser and use Ubuntu SSO to authorise your account. If the browser doesn't open, you can manually copy and paste the unique authorisation URL from the command output. After

from the Charm Store. Press the green '+' symbol in the middle of the web UI to search for applications in the Charm Store. You will see a list of available charms and bundles with a description of each. Select a charm or bundle to learn more about it. When

in its own charm. Once installed, the GUI will talk with Juju over a websocket to provide a real-time interface with the applications installed, the units that comprise them, and the machines available. Additionally, the GUI can talk with the charm store in

at https://jujucharms.com/docs/2.3/reference-install. Those subscribed to a snap channel should be automatically upgraded. If you’re using the PPA or Homebrew, you should see an upgrade available. For highlights of this release, please see the documentation

yaml mysql: charm: cs:mysql-57 series: xenial os: ubuntu charm-origin: jujucharms charm-name: mysql charm-rev: 57 exposed: false application-status: current: waiting message: waiting for machine since: 18 May 2017

application, the charm you use will often support or even require specific configuration options to be set. Juju provides tools to help manage these options and respond to changes over the lifetime of the application deployment. These options apply to the

using the relevant charm. Once deployed, the application still cannot be accessed by the public, so you would run: bash juju expose wordpress Juju will then take the steps necessary to adjust firewall rules and any other settings to expose the application via its

Charm often will require access to specific options or configuration. Charms allow for the manipulation of the various configuration options which the charm author has chosen to expose. juju provides tools to help manage these options and respond to

"7" What does a charm measure? The measurements collected by a charm are declared in its metrics.yaml. For example: yaml metrics: users: type: gauge description: Number of users tokens: type: gauge description: Number of active tokens For a more

deploying Juju charms and/or bundles to your MAAS cloud. Continue with Juju by visiting the Models and Introduction to Juju Charms pages.

great for running charms and while developing and debugging those charms, many developers prefer to tweak things such as their editor or bash configurations, or install additional tools and debugging libraries. Doing this each time on a new machine spun up by Juju is

Status Scale Charm Store Rev OS Notes mysql 5.7.19 active 1 mysql jujucharms 58 ubuntu Unit Workload Agent Machine Public address Ports Message mysql/0* active idle 0 54.81.205.47 3306/tcp Ready Machine

and if a charm exists for such an application Juju can declare such requirements both at deploy time and during the lifetime of the application. The level of sophistication is limited by the charm; a charm may support multiple storage options (e.g.

are run When a charm is deployed onto a unit, the raw charm is extracted into a directory; this directory is known as the charm directory. It's owned and operated by juju, and juju sometimes temporarily cedes control of it to user code, by running a hook inside

Status Scale Charm Store Rev OS Notes ceph-mon 10.2.9 active 3 ceph-mon jujucharms 18 ubuntu ceph-osd 10.2.9 active 3 ceph-osd jujucharms 252 ubuntu Unit Workload Agent Machine Public address Ports

client software. Charms Charms and agent versions are orthogonal to one another. There is no necessity to upgrade charms before or after an upgrade of the agents. Running workloads Workloads running are independent of Juju so a downtime maintenance window is not

application from a charm. The simplest way to do this is bash juju deploy mysql which will take the latest version of the MySQL charm straight from the store and create a single application unit. By default, Juju creates a unit of an application named after the

possible to write charms that collect metrics about charms, it is also possible to collect metrics about Juju itself. Starting with Juju 2.1 each Juju controller provides an HTTPS endpoint to expose Prometheus metrics. To feed these metrics into Prometheus, you must

just reference charms-destroy.html (remove-unit) Scaling applications One of the killer features of computing in the cloud is that it (should) seamlessly allow you to scale up or down your applications to meet your needs and whims. Juju not only makes it simple to

an AWS VPC This is in connection with Juju and Fan networking where an AWS user may wish to create an additional VPC (virtual private network). Note that only older AWS accounts will actually require a new VPC in order for Juju to

proxy to download charm from state server Lp 1556207 * Xenial juju 1.25.3 unable to deploy to lxc containers Lp 1557345 * Provider/maas bridge script is not idempotent Lp 1553915 * Unable to bootstrap lxd provider on s390x Lp 1554675 * Gce invalid

Actions Juju charms can describe actions that users can take on deployed applications. Actions are scripts that can be triggered on a unit via the command line. Parameters for an action are passed as a map, either defined in a YAML file or given through the UI,

Juju uses charms to install applications, the Ubuntu series you need are those that the charms were written for. If unsure, it is recommended to add the two most recent LTS releases. !!! Note: At time of writing, Trusty and Xenial are the two most recent

in the Juju charm store. It is a good idea to test your new model. How about a MediaWiki site? bash juju deploy cs:bundle/wiki-simple This will fetch a 'bundle' from the Juju store. A bundle is a pre-packaged set of applications, in this case 'MediaWiki', and a

(= "") The charm series Details: Juju supports adding machines using provider-specific machine instances (EC2 instances, OpenStack servers, MAAS nodes, etc.); existing machines running a supported operating system (see "manual provisioning" below),

for your own charms. Prerequisites Juju's support for LXD currently works only with Ubuntu 16.04 (Xenial). Install LXD: bash sudo apt install lxd newgrp lxd Alternate backing file-system LXD can optionally use an alternative file-system for containers. We

a matter for the charms, and is covered in a separate topic,charm HA. ^# Restricting command usage A controller administrator is responsible for granting permissions to users registered with a controller. This can be done by restricting what sorts of

for a model Charm constraints can be managed at the model level. This will affect all charms used in the model unless overridden by constraints set at the application level. Constraints are used to select minimum requirements for any future machines

Status Scale Charm Store Rev OS Notes mysql 5.7.19 active 1 mysql jujucharms 58 ubuntu Unit Workload Agent Machine Public address Ports Message mysql/0* active idle 0 10.87.144.223 3306/tcp Ready Machine

default, using a charm to deploy an application will automatically create a machine first and then deploy the new application. With a manual cloud, you need to create your machines in advance, so Juju will need to know which of the machines you wish to target when

in a hook context. Charm authors can use the run command to develop and debug scripts that run in hooks. For example, to run uname on every instance: bash juju run "uname -a" --all Or to run uptime on some instances: bash juju run "uptime" --machine=2 juju run

As long as the charm and the charm's application are well written, you can rest assured that IaaS downtime will not affect your application. !!! Note: See High Availability for details on enabling high availability for the controller. Commands you already

for the 'mariadb' charm have already been set to 8 cpu-cores for example, you can ignore that constraint at deploy time with: bash juju deploy mariadb --constraints "mem=4G cores=" In the event that a constraint cannot be met, the unit will not be deployed. !!! Note:

user must first log in to http://jujucharms.com at least once before attempting to log in to Juju as an external user The user must install Juju on the machine from which they will access the controller On the

no-proxy=jujucharms.com It is also possible to specify a list of key-value pairs: bash juju model-config test-mode=true enable-os-upgrade=false !!! Note: Juju does not currently check that the provided key is a valid setting, so make sure you spell it