Tutorial

Whether you have experience with Etcd databases, Juju orchestration, or neither, this tutorial will walk you through the essential aspects of deploying and operating Charmed Etcd.

What you’ll need

What you’ll do

  • Install and set up LXD and Juju

  • Deploy a small Charmed Etcd cluster

  • Connect to the cluster through a unit

Install and initialise LXD

The simplest way to get started with charmed etcd is to set up a local LXD cloud. LXD is a system container and virtual machine manager that comes pre-installed on Ubuntu. Juju interfaces with LXD to control the containers on which charmed etcd runs.

Verify if your Ubuntu system already has LXD installed with the command which lxd. If there is no output, then install LXD with

sudo snap install lxd

After installation, lxd init is run to perform post-installation tasks. For this tutorial, the default parameters are preferred and the network bridge should be set to have no IPv6 addresses since Juju does not support IPv6 addresses with LXD:

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

You can list all LXD containers by executing the command lxc list. At this point in the tutorial, none should exist, so you’ll only see this as output:

+------+-------+------+------+------+-----------+
| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS |
+------+-------+------+------+------+-----------+

Install and set up Juju

Juju is an Operator Life cycle Manager (OLM) for clouds, bare metal, LXD or Kubernetes. We will be using it to deploy and manage charmed etcd.

As with LXD, Juju is installed using a snap package:

sudo snap install juju

Juju already has a built-in knowledge of LXD and how it works, so there is no additional setup or configuration needed, however, because Juju 3.x is a strictly confined snap, and is not allowed to create a ~/.local/share directory, we need to create it manually.

mkdir -p ~/.local/share

To list the clouds available to Juju, run the following command:

juju clouds

The output will look as follows:

Clouds available on the client:
Cloud      Regions  Default    Type  Credentials  Source    Description
localhost  1        localhost  lxd   1            built-in  LXD Container Hypervisor

Notice that Juju already has a built-in knowledge of LXD and how it works, so there is no need for additional setup. A controller will be used to deploy and control charmed etcd.

Run the following command to bootstrap a Juju controller named dev-controller on LXD:

juju bootstrap localhost dev-controller

This bootstrapping process can take several minutes depending on your system resources. The Juju controller exists within an LXD container. You can verify this by entering the command lxc list.

This will output the following:

+---------------+---------+-----------------------+------+-----------+-----------+
|     NAME      |  STATE  |         IPV4          | IPV6 |   TYPE    | SNAPSHOTS |
+---------------+---------+-----------------------+------+-----------+-----------+
| juju-<id>     | RUNNING | 10.86.196.118 (eth0)  |      | CONTAINER | 0         |
+---------------+---------+-----------------------+------+-----------+-----------+

where <id> is a unique combination of numbers and letters such as 9d7e4e-0

Set up a unique model for this tutorial named etcd:

juju add-model etcd

You can now view the model you created above by entering the juju status command. You should see the following:

juju status
Model  Controller      Cloud/Region         Version  SLA          Timestamp
etcd   dev-controller  localhost/localhost  3.6.0    unsupported  17:26:15Z

Deploy etcd

To deploy charmed etcd, all you need to do is run the following command:

juju deploy charmed-etcd -n 3 --channel 3.6/stable

Note

The -n flag is optional and specifies the number of units to deploy. In this case, we are deploying three units of charmed etcd.

We recommend deploying at least three units for high availability.

The command will fetch the charm from Charmhub and deploy 3 units to the LXD cloud. This process can take several minutes depending on your machine.

You can track the progress by running:

watch juju status --color

When the application is ready, juju status will show something similar to the sample output below:

Model  Controller      Cloud/Region         Version  SLA          Timestamp
etcd   dev-controller  localhost/localhost  3.6.11   unsupported  09:26:33Z

App           Version  Status  Scale  Charm         Channel     Rev  Exposed  Message
charmed-etcd  3.6.5    active      3  charmed-etcd  3.6/stable  119  no

Unit             Workload     Agent      Machine  Public address  Ports     Message
charmed-etcd/0*  active       idle       0        10.235.251.189  2379/tcp
charmed-etcd/1   active       idle       1        10.235.251.17   2379/tcp
charmed-etcd/2   active       idle       2        10.235.251.134  2379/tcp

Machine  State    Address         Inst id        Base          AZ     Message
0        started  10.235.251.189  juju-313564-0  ubuntu@24.04         Running
1        started  10.235.251.17   juju-313564-1  ubuntu@24.04         Running
2        started  10.235.251.134  juju-313564-2  ubuntu@24.04         Running

To exit the juju status screen, enter Ctrl + C.

Access etcd

You can access etcd with a command line client like etcdctl or via REST API.

To confirm that the API is reachable, we can use curl to make a request to one of the nodes. If it returns a JSON string with the etcd server version, it is healthy.

user@host:~$
curl -L http://10.235.251.189:2379/version
{"etcdserver":"3.6.5","etcdcluster":"3.6.0","storage":"3.6.0"}

Next steps

Now that your cluster is set up, you can check how-to guides such as: