README

juju

juju is devops distilled.

Juju enables you to use Charms to deploy your application architectures to EC2, OpenStack, Azure, HP your data center and even your own Ubuntu based laptop. Moving between environments is simple giving you the flexibility to switch hosts whenever you want — for free.

For more information, see the docs.

Getting started

juju is written in Go (http://golang.org), a modern, compiled, statically typed, concurrent language. This document describes how to build juju from source.

If you are looking for binary releases of juju, they are available from the Juju stable PPA, https://launchpad.net/~juju/+archive/stable, and can be installed with:

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

Setting GOPATH

When working with the source of Go programs, you should define a path within your home directory (or other workspace) which will be your GOPATH. GOPATH is similar to Java's CLASSPATH or Python's ~/.local. GOPATH is documented online at http://golang.org/pkg/go/build/ and inside the go tool itself

go help gopath

Various conventions exist for naming the location of your GOPATH, but it should exist, and be writable by you. For example

export GOPATH=${HOME}/work
mkdir $GOPATH

will define and create $HOME/work as your local GOPATH. The go tool itself will create three subdirectories inside your GOPATH when required; src, pkg and bin, which hold the source of Go programs, compiled packages and compiled binaries, respectively.

Setting GOPATH correctly is critical when developing Go programs. Set and export it as part of your login script.

Add $GOPATH/bin to your PATH, so you can run the go programs you install:

PATH="$GOPATH/bin:$PATH"

Getting juju

The easiest way to get the source for juju is to use the go get command.

go get -d -v github.com/juju/juju/...

This command will checkout the source of juju and inspect it for any unmet Go package dependencies, downloading those as well. go get will also build and install juju and its dependencies. To checkout without installing, use the -d flag. More details on the go get flags are available using

go help get

At this point you will have the git local repository of the juju source at $GOPATH/github.com/juju/juju. The source for any dependent packages will also be available inside $GOPATH. You can use git pull --rebase, or the less convenient go get -u github.com/juju/juju/... to update the source from time to time. If you want to know more about contributing to juju, please read the CONTRIBUTING companion to this file.

Installing prerequisites

You can use make install-dependencies or, if you prefer to install them manually, check the Makefile target.

This will add some PPAs to ensure that you can install the required golang and mongodb-server versions for precise onwards, in addition to the other dependencies.

Building juju

go install -v github.com/juju/juju/...

Will build juju and install the binary commands into $GOPATH/bin. It is likely if you have just completed the previous step to get the juju source, the install process will produce no output, as the final executables are up-to-date.

If you do see any errors, there is a good chance they are due to changes in juju's dependencies. See the Dependency management section of CONTRIBUTING for more information on getting the dependencies right.

Using juju

After following the steps above you will have the juju client installed in GOPATH/bin/juju. You should ensure that this version of juju appears earlier in your path than any packaged versions of juju, or older Python juju commands. You can verify this using

which juju

You should be able to bootstrap a local environment now with the following (Note: the use of sudo for bootstrap here is only required for the local provider because it uses LXC, which requires root privileges)

juju init
juju switch local
sudo juju bootstrap

--upload-tools

The juju client program, and the juju 'tools' are deployed in lockstep. When a release of juju is made, the compiled tools matching that version of juju are extracted and uploaded to a known location. This consumes a release version number, and implies that no tools are available for the next, development, version of juju. Therefore, when using the development version of juju you will need to pass an additional flag, --upload-tools to instruct the juju client to build a set of tools from source and upload them to the environment as part of the bootstrap process.

juju bootstrap -e your-environment --upload-tools {--debug}

Installing bash completion for juju

make install-etc

Will install Bash completion for juju cli to /etc/bash_completion.d/juju. It does dynamic completion for commands requiring service, unit or machine names (like e.g. juju status , juju ssh , juju terminate-machine <machine#>, etc), by parsing cached juju status output for speedup. It also does command flags completion by parsing juju help ... output.

Documentation

Overview

    Juju is devops distilled.

    Project homepage: https://github.com/juju/juju

    For more information please refer to the README file in this directory.

    Source Files

    Directories

    Path Synopsis
    api
    leadership
    Package leadership implements the client to the analog leadership service.
    Package leadership implements the client to the analog leadership service.
    meterstatus
    Package meterstatus contains an implementation of the api facade to watch the meter status of a unit for changes and return the current meter status.
    Package meterstatus contains an implementation of the api facade to watch the meter status of a unit for changes and return the current meter status.
    metricsadder
    Package metricsadder contains an implementation of the api facade to add metrics to the state.
    Package metricsadder contains an implementation of the api facade to add metrics to the state.
    metricsmanager
    The metricsmanager package contains implementation for an api facade to access metrics functions within state
    The metricsmanager package contains implementation for an api facade to access metrics functions within state
    service
    Package service provides access to the service api facade.
    Package service provides access to the service api facade.
    agent
    The machine package implements the API interfaces used by the machine agent.
    The machine package implements the API interfaces used by the machine agent.
    common/storagecommon
    Package storagecommon provides common storage-related services for API server facades.
    Package storagecommon provides common storage-related services for API server facades.
    environmentmanager
    The environmentmanager package defines an API end point for functions dealing with envionments.
    The environmentmanager package defines an API end point for functions dealing with envionments.
    machine
    The machiner package implements the API interface used by the machiner worker.
    The machiner package implements the API interface used by the machiner worker.
    meterstatus
    Package meterstatus provides the meter status API facade.
    Package meterstatus provides the meter status API facade.
    metricsender
    Package metricsender contains functions for sending metrics from a state server to a remote metric collector.
    Package metricsender contains functions for sending metrics from a state server to a remote metric collector.
    metricsender/wireformat
    Package wireformat defines the format that will be used to send metric batches to the collector and receive updates.
    Package wireformat defines the format that will be used to send metric batches to the collector and receive updates.
    metricsmanager
    Package metricsmanager contains the implementation of an api endpoint for calling metrics functions in state.
    Package metricsmanager contains the implementation of an api endpoint for calling metrics functions in state.
    resumer
    The resumer package implements the API interface used by the resumer worker.
    The resumer package implements the API interface used by the resumer worker.
    service
    Package service contains api calls for functionality related to deploying and managing services and their related charms.
    Package service contains api calls for functionality related to deploying and managing services and their related charms.
    storage
    Package storage provides an API server facade for managing storage entities.
    Package storage provides an API server facade for managing storage entities.
    systemmanager
    The systemmanager package defines an API end point for functions dealing with systems as a whole.
    The systemmanager package defines an API end point for functions dealing with systems as a whole.
    uniter
    The uniter package implements the API interface used by the uniter worker.
    The uniter package implements the API interface used by the uniter worker.
    Package audit records auditable events
    Package audit records auditable events
    cloudinit
    The cloudinit package implements a way of creating a cloud-init configuration file.
    The cloudinit package implements a way of creating a cloud-init configuration file.
    providerinit
    This package offers userdata in a gzipped format to be used by different cloud providers
    This package offers userdata in a gzipped format to be used by different cloud providers
    providerinit/renderers
    The renderers package implements a way to encode the userdata depending on the OS and the provider.
    The renderers package implements a way to encode the userdata depending on the OS and the provider.
    cmd
    juju/storage
    The storage command provides a storage management interface, for manipulating and inspecting storage entities (volumes, filesystems, charm storage).
    The storage command provides a storage management interface, for manipulating and inspecting storage entities (volumes, filesystems, charm storage).
    jujud/agent
    agent contains jujud's machine agent.
    agent contains jujud's machine agent.
    kvm
    lxc
    environmentserver
    imagemetadata
    The imagemetadata package supports locating, parsing, and filtering Ubuntu image metadata in simplestreams format.
    The imagemetadata package supports locating, parsing, and filtering Ubuntu image metadata in simplestreams format.
    simplestreams
    The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
    The simplestreams package supports locating, parsing, and filtering metadata in simplestreams format.
    tools
    The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format.
    The tools package supports locating, parsing, and filtering Ubuntu tools metadata in simplestreams format.
    The feature package defines the names of the current feature flags.
    The feature package defines the names of the current feature flags.
    This package contains functional tests only.
    This package contains functional tests only.
    The provider package holds constants identifying known provider types.
    The provider package holds constants identifying known provider types.
    all
    dummy
    The dummy provider implements an environment provider for testing purposes, registered with environs under the name "dummy".
    The dummy provider implements an environment provider for testing purposes, registered with environs under the name "dummy".
    ec2
    gce
    rpc
    jsoncodec
    The jsoncodec package provides a JSON codec for the rpc package.
    The jsoncodec package provides a JSON codec for the rpc package.
    Package state enables reading, observing, and changing the state stored in MongoDB of a whole environment managed by juju.
    Package state enables reading, observing, and changing the state stored in MongoDB of a whole environment managed by juju.
    backups
    Package backups contains all the stand-alone backup-related functionality for juju state.
    Package backups contains all the stand-alone backup-related functionality for juju state.
    lease
    The lease package exists to implement distributed lease management on top of mgo/txn, and to expose assert operations that allow us to gate other mgo/txn transactions on lease state.
    The lease package exists to implement distributed lease management on top of mgo/txn, and to expose assert operations that allow us to gate other mgo/txn transactions on lease state.
    presence
    The presence package implements an interface for observing liveness of arbitrary keys (agents, processes, etc) on top of MongoDB.
    The presence package implements an interface for observing liveness of arbitrary keys (agents, processes, etc) on top of MongoDB.
    watcher
    The watcher package provides an interface for observing changes to arbitrary MongoDB documents that are maintained via the mgo/txn transaction package.
    The watcher package provides an interface for observing changes to arbitrary MongoDB documents that are maintained via the mgo/txn transaction package.
    Package storage defines structures and functions relating to charm storage.
    Package storage defines structures and functions relating to charm storage.
    Package testcharms holds a corpus of charms for testing.
    Package testcharms holds a corpus of charms for testing.
    The upgrades package provides infrastructure to upgrade previous Juju deployments to the current Juju version.
    The upgrades package provides infrastructure to upgrade previous Juju deployments to the current Juju version.
    ssh
    Package ssh contains utilities for dealing with SSH connections, key management, and so on.
    Package ssh contains utilities for dealing with SSH connections, key management, and so on.
    The version package implements version parsing.
    The version package implements version parsing.
    charmdir
    Package charmdir provides the manifold that coordinates the availability of a charm directory among workers.
    Package charmdir provides the manifold that coordinates the availability of a charm directory among workers.
    dependency
    The dependency package exists to address a general problem with shared resources and the management of their lifetimes.
    The dependency package exists to address a general problem with shared resources and the management of their lifetimes.
    diskmanager
    Package diskmanager defines a worker that periodically lists block devices on the machine it runs on.
    Package diskmanager defines a worker that periodically lists block devices on the machine it runs on.
    gate
    package gate provides a mechanism by which independent workers can wait for one another to finish a task, without introducing explicit dependencies between those workers.
    package gate provides a mechanism by which independent workers can wait for one another to finish a task, without introducing explicit dependencies between those workers.
    metrics/collect
    Package collect provides a worker that executes the collect-metrics hook periodically, as long as the workload has been started (between start and stop hooks).
    Package collect provides a worker that executes the collect-metrics hook periodically, as long as the workload has been started (between start and stop hooks).
    metrics/sender
    Package sender contains the implementation of the metric sender manifold.
    Package sender contains the implementation of the metric sender manifold.
    metrics/spool
    Package spool contains the implementation of a worker that extracts the spool directory path from the agent config and enables other workers to write and read metrics to and from a the spool directory using a writer and a reader.
    Package spool contains the implementation of a worker that extracts the spool directory path from the agent config and enables other workers to write and read metrics to and from a the spool directory using a writer and a reader.
    storageprovisioner
    Package storageprovisioner provides a worker that manages the provisioning and deprovisioning of storage volumes and filesystems, and attaching them to and detaching them from machines.
    Package storageprovisioner provides a worker that manages the provisioning and deprovisioning of storage volumes and filesystems, and attaching them to and detaching them from machines.
    uniter/hook
    hook provides types that define the hooks known to the Uniter
    hook provides types that define the hooks known to the Uniter
    uniter/relation
    relation implements persistent local storage of a unit's relation state, and translation of relation changes into hooks that need to be run.
    relation implements persistent local storage of a unit's relation state, and translation of relation changes into hooks that need to be run.
    uniter/runner/context
    Package context contains the ContextFactory and Context definitions.
    Package context contains the ContextFactory and Context definitions.
    uniter/runner/jujuc
    The worker/uniter/runner/jujuc package implements the server side of the jujuc proxy tool, which forwards command invocations to the unit agent process so that they can be executed against specific state.
    The worker/uniter/runner/jujuc package implements the server side of the jujuc proxy tool, which forwards command invocations to the unit agent process so that they can be executed against specific state.
    uniter/storage
    Package storage contains the storage subsystem for the uniter, responding to changes in storage attachments (lifecycle, volume/filesystem details) by queuing hooks and managing the storage attachments' lifecycle.
    Package storage contains the storage subsystem for the uniter, responding to changes in storage attachments (lifecycle, volume/filesystem details) by queuing hooks and managing the storage attachments' lifecycle.