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

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

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

build from layers When 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

is easier 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

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

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

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

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

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,

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

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

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

Completely devoid of CLI examples. Kindly 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

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

rationalize with authors-hook-environment.md 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

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

Add images To add (notes from PR #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

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

Primitives The network-get 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

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

Relations lifecycle A unit's scope consists of the group of units that are transitively connected to that unit within a particular relation. So, for a globally-scoped relation, that means every unit of each service in the relation; for a

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

hooks Not everything works the first time, and sometimes even when it seems to work, things don't happen quite as you expected. Juju provides commands to help developers debug charm code, and there are also community written plugins that

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

interface The mysql interface is provided 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:

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

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

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

is a relation? Relationships in Juju are a loosely typed definition of how applications should interact with one another. The definition of a relationship is handled through an interface, and does not restrict the user to a traditional

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

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

layer 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

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

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

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

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

status As of version 1.24 of Juju, a unit can report its status as one of the following: | Status | colour in GUI* | Meaning | | :----------- | :------------- |

errors If any of your hooks returns a non-zero exit code, juju will stop managing the unit directly and will wait for user intervention. This is a Bad Thing, and you should make every effort to avoid it, because the average user may not be in

a layer by example In this document, we 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.

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

layers Interface layers are perhaps the most misunderstood type of layer, and are responsible for the communication that transpires over a relation between two applications. This type of layer encapsulates a single “interface

applications An application is upgraded 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,

How to... Juju is provides 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

Building Layers While 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

Critical: Improve examples Juju Resources A Juju resource is additional content/files 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 Many applications require binary resources to complete the install process. While it is possible for a charm to download this software from package repositories or other locations, some charms may be deployed in data centers with

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

Add 'centos' and 'windows' stuff to series talk Review whether Juju should go to the store when pointing to a local dir with non-existant charm. It did not for me but the old version of this doc said it should.

us We'd love to hear about how you're using Juju, whether it's at the smallest of scales or the largest. Our team is always approachable and can usually be found in the following locations: Our YouTube channel hosts the Juju Show and

Critical: review required Managing relationships Few applications you might want to run can do so completely independently - most of them rely on some other software components to be present and running too (e.g. a database). There would be

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

Juju Actions are required for Juju Benchmarking and knowledge of them is assumed in this section. With the introduction of Actions, you are now able to write repeatable, reliable, composable benchmarks. This allows you to perform the

and CentOS Juju 1.24.0 has initial support for CentOS as a deployment OS (the Juju client software is already supported on CentOS - see the Install Documentation page). This is experimental and has a number of known issues. However, most of

relations Implicit relations allow for interested applications to gather lifecycle-oriented events and data about other applications without expecting or requiring any modifications on the part of the author of the other

is Juju? Juju is a state-of-the-art, open source modelling tool for operating software in the cloud. Juju allows you to deploy, configure, manage, maintain, and scale cloud applications quickly and efficiently on public clouds, as well as on

Check more complex bundles after the release of 2.0 Review required Refactor (e.g. advanced usage/information should go in a sub-page) Refactor (e.g. using vs creating) Add example portraying bundle overlay Using

Quickstart The quickstart utility was used with earlier versions (1.x) of Juju. It was designed to help users quickly deploy charms and bundles with those versions of Juju and allowed editing and management of various different Juju

concepts The Juju client The Juju client is command line interface (CLI) software that is used to manage Juju, whether as an administrator or as a regular user. It is installed, via an APT package ('juju'), onto your personal workstation.

applications Applications are composed of one or more application units. An application unit runs the application's software and is the smallest entity managed by Juju. Application units are typically run in an isolated container on a

Still WIP: needs refinement and further details Remove default model? Image for GCE Dashboard with resources Image commented out due to inconsistent behaviour This tutorial is top-heavy with GUI stuff. Consider a

Critical: review required (e.g. "state server") Removing applications, units, and machines Juju can sanely and efficiently remove something when you no longer need it. This section looks at how to remove applications, units, and machines. To

Juju Distinct from deploying 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

Variables Juju Client These variables are available on the juju client in order to change its default behavior. GOCOOKIES The default location of the Go cookies file is ~/.go-cookies. This variable can change

JAAS from the command line The Juju controller you already have running in JAAS can also be used from the command line, giving you powerful, fast access to perform common operations. In order to use the command line, you will first need to

started with Juju Juju works with public clouds, private clouds, and locally with LXD. A central Juju controller (machine) is used to process all of the events that occur between the Juju client and the workload machines. The instructions

some screenshots show 'services' rather than 'applications' The Juju GUI Juju has a graphical user interface (GUI) available to help with the tasks of managing and monitoring your Juju environment. From Juju 2.0 onwards, unless you

Notes History This page details all available release notes for the 2.x series of Juju. The release notes for the 1.x series are available here. ^# Juju 2.3.1 A new release of Juju is here, 2.3.1. This is primarily a bug fix release which

Logs from the machines/applications Troubleshooting Juju does a brilliant job at simplifying the deployment of big software at scale. But trying to accommodate every variation of model, cloud and connection is a huge challenge, and one that

Configuration When deploying an 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

applications By design, Juju operates a very secure environment for deploying your applications. Even if you have deployed applications, they won't be publicly available unless you explicitly make them so. To allow public access

configuration Introduction A 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

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. As an operator, you may find

a MAAS cloud Juju works closely with MAAS to deliver the same experience on bare metal that you would get by using any other cloud. Note that the Juju 2.x series is compatible with both the 1.x and 2.x series of MAAS. Add a MAAS cloud Use

A Customized Hook Debugging Environment Plugin DHX is a plugin -- scripts that extend the functionality of Juju -- which allows you to fully and automatically customize the machines created by Juju, making developing and debugging hooks as

Update 'juju status' output to show release versions CMR scenario #1 This page refers to Cross model relations. See that page for background information. In this example, we build a simple CMR infrastructure in step by step fashion,

bug tracking: https://pad.lv/1708212 bug tracking: https://pad.lv/1709507 bug tracking: https://pad.lv/1709508 Using Juju Storage Certain applications can benefit from advanced storage configurations and if a charm exists for

hooks 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,

Revise Juju agent versions (e.g. 2.3-alpha1.1) Installing Ceph Here we present one way to install a rudimentary Ceph cluster with Juju backed by an AWS cloud. See Ceph documentation to find out more about Ceph. Below, we install three Ceph

on upgrading Juju software This is an addendum to the main page describing Juju software upgrades: Upgrading Juju software. Agent software and related components In general, the upgrade of the agent software is independent of the

applications Juju deploys units of an 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

metrics gathering with Prometheus Overview While it is 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

The Scaling Back section should 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

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

Notes History for 1.x series This section details all the available release notes for the 1.x stable series of Juju The versions covered here are: ^# juju-core 1.25.5 A stable release of Juju, juju-core 1.25.5, is now available. This

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

the Oracle public cloud Juju has built-in support for Oracle Compute, Oracle's public cloud. This means that there is no need to add the Oracle cloud to Juju. An exception to this is if you have an Oracle Compute trial account. Both types

Warning: Ubuntu release versions hardcoded General review required (exact commands and their output especially) Subnet in the walkthrough and the example/screenshots do not correspond Some command output is CLI and some

add details on remote access possible reorganisation or splitting of the doc required Using LXD as a cloud LXD provides a fast, powerful, self-contained and largely configuration-free way to experiment with Juju. Using lightweight LXC

Figure out the 'block command' situation (including CLI help text). See 'Restricting command usage' section. The old page lives on. Need examples for each command. Controllers A Juju controller is the management node of a

Update 'juju status' output to show release versions CMR scenario #2 This page refers to Cross model relations. See that page for background information. In this example, we supply a CMR infrastructure "out of the box" with a few nimble

Previous warning (add-model): "For 'ec2' and 'openstack' cloud types, the access and secret keys need to be provided." I tested ec2 and did not need to do this. OpenStack? Juju models A Juju model is an environment associated with a

Command reference You can get a list of the currently used commands by entering juju help commands from the commandline. The currently understood commands are listed here, with usage and examples. Click on the expander to see details for each

a "Manual" cloud Juju caters for the case where you may not be able to access a more traditional cloud in a straightforward way; maybe you can't create additional instances, or perhaps your cloud is really a collection of disparate

Units Each node that Juju manages is referred to as a "unit". Generally speaking, when using Juju you interact with the applications at the application level. There are times when working directly with units is useful though,

Needs a rewrite Applications High Availability (HA) Distribution groups Juju works with your cloud to ensure that, in the event of an IaaS outage, not all units of an application will go down at the same time, maximising your application's

allow you to choose the hardware (or virtual hardware) to which your applications will be deployed, e.g. by specifying the amount of RAM you want them to have. This is particularly useful for making sure that

Stuff on user-added models (ssh key and credentials) Check the functionality of admin user access level. This currently appears to do nothing (not destroy models, nor backups) Users and models This section is about understanding

Check accuracy of key table Confirm 'all' harvest mode state. Seems it should be "'Dead' or 'Unknown'" OR "a combination of modes 'destroyed' and 'unknown'". Provide an example of using model-defaults to set a per-region