Get started with Juju

Imagine your business requires a chat service, such as Mattermost (backed up by PostgreSQL), or a real-time data processing engine, such as Kapacitor (backed up by InfluxDB). To achieve this by hand would take you a lot of know-how, work, and time. Not so with Juju! In this tutorial you will learn how to achieve this in no time.

Contents:

Create the test environment

The instructions in this tutorial are based on an Ubuntu system. This section details how to quickly create an Ubuntu test environment on MS Windows and macOS using Multipass. This section is also useful for those that are already running Ubuntu, but would like to create an isolated test environment that can be easily removed once this tutorial has been completed.

First, install Multipass.

Then, start a virtual machine with 8 GB RAM, 2 CPU cores, and 20 GB disk allocated to it, as shown below. We’ve called ours my-tiny-cloud.

multipass launch -n my-tiny-cloud -m 8g -c 2 -d 20G

Multipass will confirm the creation:

Launched: my-tiny-cloud

At this point you will be able to enter a command-line with the shell command:

multipass shell my-tiny-cloud

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

ubuntu@my-tiny-cloud:~$

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.

If for whatever reason you need to interrupt this tutorial, we recommend running multipass stop my-tiny-cloud to stop the instance. When you resume, run multipass start my-tiny-cloud.

Install the Juju CLI client

We will now install the Juju CLI client via snap:

sudo snap install juju --classic

If the installation was successful, you will see a message similar to the one below:

juju 2.9.32 from Canonical✓ installed

Get access to cloud infrastructure

Juju supports a wide range of clouds—public or private, Kubernetes or not. To keep things simple, in this tutorial we will require nothing more than your local workstation, where you can create Kubernetes / non-Kubernetes cloud infrastructure with MicroK8s / LXD.

Expand to see the instructions for MicroK8s

Execute the code below to install and configure MicroK8s:

# Install Microk8s from snap:
sudo snap install microk8s --classic --channel=1.24

# Add the 'ubuntu' user to the Microk8s group:
sudo usermod -a -G microk8s ubuntu

# Give the 'ubuntu' user permissions to read the ~/.kube directory:
sudo chown -f -R ubuntu ~/.kube

# Create the 'microk8s' group:
newgrp microk8s

# Enable the necessary Microk8s addons:
microk8s enable hostpath-storage dns

Expand to see the instructions for LXD

LXD should be already installed in your Ubuntu system. Execute the code below to configure it:

lxd init --auto
lxc network set lxdbr0 ipv6.address none

Connect your cloud to Juju

Juju recognizes your MicroK8s / LXD cloud infrastructure automatically. You can already see it if you run:

juju clouds
Expand to see the output for MicroK8s
Cloud      Regions  Default    Type  Credentials  Source    Description
microk8s   1        localhost  k8s   1            built-in  A Kubernetes Cluster
Expand to see the output for LXD
Cloud      Regions  Default    Type  Credentials  Source    Description
localhost  1        localhost  lxd   1            built-in  LXD Container Hypervisor

Note: In the juju clouds output, the “Default” field stands for the default cloud region. This concept is relevant for public clouds. Here you can ignore the “localhost” value in that column.

For clouds where this step is not implicit, connecting the cloud to Juju is done via the juju add-cloud command.

At this point what you have there is just cloud infrastructure, an empty cloud. There are no resources being used yet.

Add your cloud credentials to Juju

You don’t need to add any credentials for MicroK8s / LXD explicitly.

For clouds where this step is not implicit, see How to add a cloud credential to the Juju client.

Install a Juju controller in your cloud

The code below bootstraps a controller named tutorial-controller into your cloud:

juju bootstrap <cloud name> tutorial-controller
Expand to see the code with the MicroK8s cloud name
juju bootstrap microk8s tutorial-controller
Expand to see the code with the LXD cloud name
juju bootstrap localhost tutorial-controller

Create a workspace on your cloud

The next step is to create a workspace on your cloud. We do this by creating a model, as shown below. We will name ours tutorial-model.

juju add-model tutorial-model

Deploy applications on your workspace

We’ve got our workspace. Let’s start deploying applications. In Juju, that is done via small pieces of software called ‘Charmed Operators’, or ‘charms’. Charms act as translators between Juju and applications so that you can very easily perform any application operation you want. More concretely, if you want to deploy an application, all you have to do is:

juju deploy <charm name>

When you run this, Juju will pull the charm from Charmhub and then install the application on your cloud.

Small caveat: At present you need to choose between a Kubernetes and a non-Kubernetes charm version, depending on whether your cloud infrastructure is Kubernetes or not.

Expand to deploy Mattermost and PostgreSQL on MicroK8s

Let’s deploy Mattermost, an application that provides a chat service:

juju deploy mattermost-k8s

When deployed, this outputs:

Located charm "mattermost-k8s" in charm-store, revision 20
Deploying "mattermost-k8s" from charm-store charm "mattermost-k8s", revision 20 in channel stable

You can observe the deployment status with the following command:

watch -c juju status --format short --color

But Mattermost requires a database service. Let’s install PostgreSQL to provide this service:

juju deploy postgresql-k8s

When deployed, this outputs:

Located charm "postgresql-k8s" in charm-store, revision 9
Deploying "postgresql" from charm-store charm "postgresql-k8s", revision 9 in channel stable

That’s it. Your applications are now deployed.

Expand to deploy Kapacitor and InfluxDB on LXD

Let’s deploy Kapacitor, an application that provides real time analytics:

juju deploy kapacitor

When deployed, this outputs:

Located charm "kapacitor" in charm-hub, revision 1
Deploying "kapacitor" from charm-hub charm "kapacitor", revision 1 in channel stable on xenial

You can observe the deployment status with the following command:

watch -c juju status --format short --color

But Kapacitor requires a database service. Let’s install InfluxDB to provide this service:

juju deploy influxdb

When deployed, this outputs:

Located charm "influxdb" in charm-hub, revision 24
Deploying "influxdb" from charm-hub charm "influxdb", revision 24 in channel stable on focal

That’s it. Your applications are now deployed.

Integrate your applications

We’ve deployed two applications that look like they need to work together. However, currently, they don’t. We need to integrate them. In Juju, integrating applications is a first class operation:

juju relate <application 1> <application 2>
Expand to relate Mattermost and PostgreSQL on MicroK8s
juju relate mattermost-k8s postgresql-k8s:db

You can again observe the deployment status with the following command:

watch -c juju status --format short --color

That’s it. Your applications now know about each other and are ready to work together.

Expand to relate Kapacitor and InfluxDB on LXD
juju relate kapacitor influxdb

You can again observe the deployment status with the following command:

watch -c juju status --format short --color

That’s it. Your applications now know about each other and are ready to work together.

Test your deployment

You’ve integrated your applications. You now have a functional working system. Time to try it out!

Expand to test your Mattermost deployment on MicroK8s

Execute the code below to get the IP address of your Mattermost pod:

microk8s kubectl get pods -n tutorial-model

Now, use the IP address as shown below to check that the application is running:

curl <IP address>/api/v4/system/ping

You should see the following:

{"AndroidLatestVersion":"","AndroidMinVersion":"","DesktopLatestVersion":"","DesktopMinVersion":"","IosLatestVersion":"","IosMinVersion":"","status":"OK"}

Congratulations, your Mattermost application is ready to use!

Expand to test your Kapacitor deployment on LXD

Execute the code below to get the IP address of your Kapacitor instance:

juju status

Now, use the IP address as shown below to check that the application is running:

curl -G 'http://<IP address>/kapacitor/v1/ping'

You should see the following:

| Code | Meaning |
| ---- | ------- |
| 204  | Success |

Congratulations, your Kapacitor application is ready to use!

Destroy your test environment

Once you are done, you can run the code below to stop and delete your Multipass test environment.

# Stop your instance
multipass stop my-tiny-cloud

# Delete your instance permanently
multipass delete --purge my-tiny-cloud 

You can also uninstall Multipass to remove any trace of this guide.

Next steps

This tutorial has introduced you to the basic things you can do with Juju. But there is a lot more to explore:

If you are wondering… visit…
“How do I…?” Juju OLM How-to docs
“What is…?” Juju OLM Reference docs
“Why…?”, “So what?” Juju OLM Explanation docs