Using Kubernetes with localhost

Juju is an Open Source Charmed Operator Framework. It helps you move from configuration management to application management and has two main components:

  • Charmed Operator Lifecycle Manager (OLM) - a hybrid-cloud application management and orchestration system that helps you from Day 0 to Day 2. Deploy, configure, scale, integrate, maintain and manage Kubernetes native, container-native and VM-native applications – and the relations between them.

    • Charmed Operators, packaged as “Charms”, are software that encapsulate a single application and all the code and know-how it takes to operate it on Kubernetes or machines.
  • Charmed Operator SDK - a guide to help you build Charmed Operators for use with the Charmed OLM.

This guide introduces you to Juju and charmed operators deployment on a local Ubuntu machine. If you are using MS Windows or macOS you can still follow this tutorial by installing Multipass. By the end of this guide you will have a running web application backed by a database.

Alternatively, if you would like to start with Juju on Kubernetes, please follow the Getting Started on Kubernetes guide.

The following sections provide a basic overview of using Juju, from installation to deploying and relating charmed operator.

  1. Create the test environment
    MS Windows and macOS users. Optional step for Ubuntu users.
  2. Install Juju CLI
  3. Create a local cloud
  4. Bootstrap the Juju OLM controller
  5. Deploy a charmed operator
  6. Relate charmed operators

1. Creating the test environment

The instructions in this tutorial are based on an Ubuntu system. This section details how to quickly create a test environment on MS Windows and macOS using a virtual machine deployed by Multipass.

This section is also useful for those that are already running Ubuntu, but would like to create an isolated test environment that could be easily removed.

Info: Multipass is a tool for quickly running virtual machines from any host operating system. This will allow you to create a fully-isolated test environment that won’t impact your host system.

Install Multipass

You can find system specific information on how to install Multipass at
It only takes a few minutes!

Create a virtual machine

To start a virtual machine microcloud that has 8 GB RAM allocated to it, execute:

multipass launch -n microcloud -m 8g -c 2 -d 20G 

Multipass will confirm the creation:

Launched: microcloud

Once multipass has downloaded the latest Long Term Support version of the Ubuntu operating system, you will be able to enter a command-line with the shell command:

multipass shell microcloud

This gives you access to the shell (you may see a different prompt, depending on the version installed):


You are now ready to follow the rest of this guide in our newly created Ubuntu machine. All commands should be typed in this shell. Once you are done, you can run ‘$ multipass destroy microcloud’ and uninstall Multipass to remove any trace of this guide.

2. Install Juju CLI

We will install Juju CLI via a snap package: this is the easiest and fastest way to get started with Juju. We also provide installation instruction on several other systems.

Other installation methods
You can find a comprehensive list of all the ways you have to install Juju at

The following command will install Juju CLI:

sudo snap install juju --classic

If the installation was successful, you will see the following message:

juju 2.8.10 from Canonical✓ installed

3. Create a local cloud

We will use LXD for creating a cloud on the localhost. LXD should be already installed in your Ubuntu system.

Info: LXD is a system container and virtual machine manager. Juju uses it to instantiate the containers need for the app.

Need to install LXD? Visit the LXD docs for installation instructions.

Configure LXD

Juju speaks directly to the local LXD daemon, which also requires lxd group membership.

newgrp lxd
sudo adduser $USER lxd

LXD then needs to be configured for its environment:

lxd init --auto

Verify that the localhost cloud is available

Our localhost cloud is now established. We can verify that by running juju clouds:

juju clouds

Juju should have detected the presence of LXD and has added it as the localhost cloud:

localhost             1  localhost        lxd         LXD Container Hypervisor

4. Bootstrap the Juju controller

Juju uses an active software agent, called the controller, to manage applications. The controller is installed on a machine through the bootstrap process:

juju bootstrap localhost overlord

During the bootstrap process, Juju connects with the cloud, then provision a machine to install the controller on, then install it.

Creating Juju controller "overlord" on localhost/localhost
Looking for packaged Juju agent version 2.6.8 for amd64

5. Deploying a charmed operator: Hello Juju!

The first workload that you’ll deploy is a simple web application. You’ll deploy an application that uses the Flask microframework to send “Hello Juju!” via HTTP.

juju deploy hello-juju

The charmed operator name hello-juju is resolved into an actual charmed operator version by contacting the This charmed operator is then downloaded by the controller and used as the source of the application that was created with the same name:

Located charm "cs:hello-juju-4".
Deploying charm "cs:hello-juju-4".

The next step is to use juju expose to configure the necessary security groups and firewall rules and make the hello-world application publicly available over the network:

juju expose hello-juju

Checking the deployment

Now that a workload is in place, use juju status to inspect what is happening. It can take a few minutes for the application to start up, but once it’s ready, the output will show that the status of the hello-juju app is active:

juju status

This outputs:

Model    Controller  Cloud/Region         Version  SLA          Timestamp
default  overlord    localhost/localhost  2.8.10   unsupported  16:24:04+12:00

App         Version  Status  Scale  Charm       Store       Rev  OS      Notes
hello-juju           active      1  hello-juju  jujucharms    4  ubuntu  
Unit           Workload  Agent  Machine  Public address  Ports   Message
hello-juju/0*  active    idle   0   80/tcp  
Machine  State    DNS            Inst id        Series  AZ  Message
0        started  juju-646ac9-0  bionic      Running

Connecting to the application

The juju status output above provided the “Public address” of the hello-juju/0 unit as and its Ports column as 80/tcp. Let’s connect!


If the connection was successful, you will see:

Hello Juju!

6. Relating another application: adding PostgreSQL to the deployment

Relations are Juju’s defining concept and its main point of difference with other systems in its class. They enable the simplicity, security and stability offered by the whole project.

The hello-juju web server maintains a count for each greeting that it has sent out via the /greetings endpoint.


Which outputs:

{"greetings": 2}

By default, this state is maintained within a SQLite database that is set up by the hello-juju charmed operator itself. In this section, we will deploy a PostgreSQL database and relate it to our hello-juju charmed operator.

To deploy the PostgreSQL database, we will use the same deploy command:

juju deploy postgresql

Which outputs:

Located charm "cs:postgresql-199".
Deploying charm "cs:postgresql-199".

The PostgreSQL charm may take a few moments to be deployed. You can check the status of the deployment by running:

juju status

When ready, the field status will ready active. You should wait for the charm deployment to finish before following the next steps.

To relate the two charmed operators, all we need to do is run:

juju relate postgresql:db hello-juju

The applications will auto-configure themselves. You now have a web application and a database deployed and ready to use without having to deal with application specific configuration!

Find more information about relations and how they work.

Re-checking the deployment status

Now that the new application and a relation are in place, the juju status output has expanded.

juju status --relations

Add the --relations option include relations information:

Model    Controller  Cloud/Region         Version  SLA          Timestamp
default  overlord    localhost/localhost  2.8.10   unsupported  16:24:04+12:00

App         Version  Status  Scale  Charm       Store       Rev  OS      Notes
hello-juju           active      1  hello-juju  jujucharms    3  ubuntu  
postgresql  10.10    active      1  postgresql  jujucharms  199  ubuntu
Unit           Workload  Agent  Machine  Public address  Ports    Message
hello-juju/0*  active    idle   0   80/tcp  
postgresql/0*  active    idle   0   5432/tcp  Live master (10.10)
Machine  State    DNS            Inst id        Series  AZ  Message
0        started  juju-646ac9-0  bionic      Running
1        started  juju-646ac9-1  bionic      Running

Relation provider       Requirer                Interface    Type     Message
postgresql:coordinator  postgresql:coordinator  coordinator  peer
postgresql:db           hello-juju:db           pgsql        regular
postgresql:replication  postgresql:replication  pgpeer       peer

@nottrobin any suggestions for embedding JS? I would like to include the following external resources in this page ideally:

<script id="asciicast-267811" src="" async></script>
<script src=""></script>

Both scripts have been added the discourse theme. You should be able to use either the cards or asciinema now.

Hi timclicks!

Thanks for writing this introduction to Juju!

The second paragraph of the “About relations and how they work” section seems to be truncated. It currently ends “postgresql then sends the”…

Also, might it be worth extending this tutorial a little to explain how to cleanly destroy / “undeploy” that which has been deployed in the guide?


Sorry about that, I’ve finished the sentence.

That’s a good point. I’ll add that to today’s TODO list.

I’m curious if you could extend this “hello-juju” and bring in interfaces for “http/website”? This would enable a continued example also with TLS/SSL - perhaps with ssl-termination-proxy or nginx or apache2 - this is as for most real world scenarios nowdays needs to implement this to be more than just a development example.

Bring in some letsencrypt into the equation and it will be awesome =D

Really good idea. Adding a relation on the provides side will be useful also.

1 Like

The relations, interfaces, endpoints is still much of a mystery to me and the documentation on the topic is also tough.

Much could be done here to simplify…

Very well done, thank you !
If I’m not wrong:

$ juju ssh hello-unit/0

should be:

$ juju ssh hello-juju/0


You’re very right. I’ll make the change now. [Edit: done!]

Thank you for contributing. Welcome to the community!

1 Like

if you have ufw enabled, then containers may not be able to communicate with lxd’s api.

In order to allow the containers to the lxd host use:

sudo ufw allow in on $(lxc network list --format csv | grep ,YES, | tr ',' '\n' | head -n 1)
1 Like

That’s a very useful contribution. Thanks for taking the time to to mention it.

Are we supposed to run this command lxd init --auto as root or normal user?
Running the command using normal user, fails due to permission error.

The document is missing the following command after lxd init --auto:

lxc network set lxdbr0 ipv6.address none

This is mentioned in the ascii capture but not in the doc. As a result:

$ juju bootstrap localhost overlord
ERROR profile "default": juju does not support IPv6. Disable IPv6 in LXD via:
	lxc network set lxdbr0 ipv6.address none
and run the command again

I’d like to propose some updates to this documentation, having followed its steps from beginning to end.

The prompt I get is:


I suggest for this last line:

It can take a few minutes for the application to start up, but once it’s ready, the output will show that the status of the hello-juju app is active:

1 Like link is broken

1 Like