Getting started¶

Introduction¶

This tutorial gets you started with using juju to deploy services. A later tutorial will show you how to write a charm. To complete this walkthrough, you should have access credentials to a dedicated computing environment such as what is offered by a virtualized cloud hosting environment (see below).

Juju has been designed for environments which can provide a new machine with an Ubuntu cloud operating system image on-demand. This includes services such as Amazon EC2 , HP Cloud or RackSpace.

The environment should also provide a permanent storage facility such as Amazon S3.

The only environments supported are EC2, OpenStack, MAAS, and LXC containers.

Installation¶

The juju team's Personal Package Archive (PPA) installation is currently the preferred installation mechanism for juju. To install juju from the PPA, execute the following in a shell:

sudo add-apt-repository -y ppa:juju/pkgs
sudo apt-get update && sudo apt-get install juju

Note that for stable minor versions of juju one can use a stable release PPA. These only receive important bug fixes. So for v0.6 one can use:

sudo add-apt-repository ppa:juju/0.6

The stable release PPA's are used in stable releases of Ubuntu when the juju-origin setting of the environment (such as ~/.juju/environments.yaml) is set to ppa.

The juju environment can now be configured. Juju also requires a keypair, if you do not have one you can generate a pair with the command:

ssh-keygen -t rsa -b 2048

Configuring your environment using EC2¶

Run the command-line utility with no arguments to create a sample environment:

juju bootstrap

This will create the file ~/.juju/environments.yaml, which will look something like this:

default: sample
environments:
  sample:
    type: ec2
    control-bucket: juju-faefb490d69a41f0a3616a4808e0766b
    admin-secret: 81a1e7429e6847c4941fda7591246594
    default-series: precise
    juju-origin: ppa
    ssl-hostname-verification: true

This is a sample environment configured to run with EC2 machines and S3 permanent storage. To make this environment actually useful, you will need to tell juju about an AWS access key and secret key. To do this, you can either set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables (as usual for other EC2 tools) or you can add access-key and secret-key options to your environments.yaml. For example:

default: sample.ec2 # if no environment is specified, use this one
environments:
  sample.ec2:
    type: ec2
    access-key: YOUR-ACCESS-KEY-GOES-HERE
    secret-key: YOUR-SECRET-KEY-GOES-HERE
    control-bucket: juju-faefb490d69a41f0a3616a4808e0766b
    admin-secret: 81a1e7429e6847c4941fda7591246594
    default-series: precise
    juju-origin: ppa
    ssl-hostname-verification: true

The S3 bucket does not need to exist already.

Configuring a local environment¶

Juju can also run services on your local machine via LXC. This means you can quickly deploy and prototype on your laptop and -- when ready -- deploy on the cloud. While this has some advantages it also has some drawbacks.

• Most local machines aren't configured to use LXC out of the box. With Juju versions earlier than v0.6, this may require a reboot and for some network configurations a bit of manual set up. The network bridging that is necessary might not be ideal for some users. Note that in v0.6 the networking has been simplified greatly by using LXC's built in network.
• The first juju bootstrap will take a long time, as up to 300MB of Ubuntu server packages are downloaded. These are cached so subsequent deployments are very fast, but the initial set up might take longer. In v0.6 and later, the official Ubuntu Cloud images are used, which reduces the download to around 200MB.
• juju debug-log isn't as useful as tailing $data-dir/${USERNAME}-${JUJU_ENV}/machine-agent.log
• Services that are running don't necessarily appear in netstat.
• Services that require complex networking like OpenStack and Ceph will not run in LXC, you will need real hardware for those.

First, have juju report it's version:

juju --version

Then install the dependencies juju needs.

v0.6 and later:

sudo apt-get install lxc apt-cacher-ng libzookeeper-java zookeeper

v0.5:

sudo apt-get install libvirt-bin lxc apt-cacher-ng libzookeeper-java zookeeper

Next, generate a key if you don't have one already:

ssh-keygen -t rsa

pre v0.6 users only Then you need to add yourself to the libvirtd group:

sudo usermod -a -G libvirtd <YOUR_USER>

To make the above take effect, you need to log out and back in. A reboot may also be necessary to allow libvirt to create the bridge interfaces. LXC will create its bridges on install, so v0.6 and later should not require a reboot.

Next configure your local environment:

In ~/.juju/environments.yaml, add a section for type "local":

default: sample.lxc # if no environment is specified, use this one
environments:
  sample.lxc:
    type: local
    control-bucket: juju-a14dfae3830142d9ac23c499395c2785999
    admin-secret: 6608267bbd6b447b8c90934167b2a294999
    default-series: precise
    juju-origin: ppa
    data-dir: /home/jorge/whatever

The data-dir is going to be where the juju agents keep transient data. control-bucket and admin-secret are arbitrary, simple strings. .. what are control-buck and admin-secret used for? .. does data-dir respect ~, for example ~/juju/lxc? .. Could we get more explaination of that these attributes actually mean? They seem magical.

After this you can then:

juju bootstrap

This step should be relatively quick. The first time you deploy services, it might take quite some time to spin up the first container. Pre v0.6, it's doing a netinstall and building a chroot for the container, which downloads about 300MB of packages. In v0.6 and later, the Ubuntu cloud images are used, so it must still download a single 200MB+ tarball. Subsequent bootstraps should be much quicker. You can then locally deploy the charms:

juju deploy mysql
juju deploy wordpress
juju add-relation wordpress mysql

Juju will return immediately and will set up the different services in the background. As mentioned above, this may take some time the first time round. You can check the deployment status by running:

juju status

While juju is deploying the different services, their "agent-state:" field will say "pending". When a service is fully deployed, its "agent-state:" field should change to "started". Juju should return something like this in status when all services are started:

machines:
  0:
    agent-state: running
    dns-name: localhost
    instance-id: local
    instance-state: running
services:
  mysql:
    charm: cs:precise/mysql-3
    relations:
      db:
      - wordpress
    units:
      mysql/0:
        agent-state: started
        machine: 2
        public-address: 10.0.3.99
  wordpress:
    charm: cs:precise/wordpress-3
    exposed: false
    relations:
      db:
      - mysql
    units:
      wordpress/0:
        agent-state: started
        machine: 1
        public-address: 10.0.3.24

This report says:

1. The environment is lxc (instance-id: local) and is the lxc container is alive (instance-state: running).
2. Two services have been deployed: mysql and wordpress (services: mysql: *, services: wordpress: *)
3. mysql was deployed via a charm from the Juju Charm Store that was specific to the "precise" version of Ubuntu (charm: cs:precise/mysql).
4. wordpress was deployed via a charm from the Juju Charm Store that was specific to the "precise" version of Ubuntu (charm: cs:precise/wordpress).
5. mysql is the database for the wordpress service (services: mysql: relations: db: wordpress).
6. wordpress requires a database mysql (services: wordpress: relations: db: mysql)

#. The mysql service has a single "unit" mysql/0 (services: mysql: units: mysql/0) which is running on machine 0 (services: mysql: units: machine: 2) with IP address 10.0.3.99 (services: mysql: units: public-address: 10.0.3.99). Since this environment is actually an lxc container, its running locally on your computer.

#. The wordpress service has a single unit wordpress/0 (services: wordpress: units: wordpress/0) which is running on machine 1 (services: mysql: units: machine: 2) with IP address 10.0.3.24 (services: mysql: units: public-address: 10.0.3.24). Since this environment is actually an lxc container, its running locally on your computer.

1. The wordpress service is not yet "exposed" (services: wordpress: exposed: false). This means the user can't use it yet.

As of Juju v0.6, there is no need to expose your service, though it may be required in the future:

juju expose wordpress # opens the public ports for the service, in this case port 80

In this example, navigating the browser to 10.0.3.24 should take you to the wordpress configuration page. Note that the mysql service is not exposed and therefore is not publically accessible.

Enabling logging option.:

juju debug-log

Configuring several environments¶

You can specify several environments in ~/.juju/environments.yaml:

default: local
environments:
  amazon:
    type: ec2
    access-key: YOUR-ACCESS-KEY-GOES-HERE
    secret-key: YOUR-SECRET-KEY-GOES-HERE
    control-bucket: juju-faefb490d69a41f0a3616a4808e0766b
    admin-secret: 81a1e7429e6847c4941fda7591246594
    default-series: precise
    juju-origin: ppa
    ssl-hostname-verification: true
  local:
    type: local
    control-bucket: juju-a14dfae3830142d9ac23c499395c2785999
    admin-secret: 6608267bbd6b447b8c90934167b2a294999
    default-series: precise
    juju-origin: ppa
    data-dir: /home/jorge/whatever

You can then explicitly bootstrap a given environment:

juju bootstrap --environment amazon
juju deploy -eamazon mysql
juju deploy -elocal mysql

and so on ..