Skip to content

Commit

Permalink
[DPE-5778] add docs (#11)
Browse files Browse the repository at this point in the history
This PR adds user documentation for setting up and installing Charmed
etcd and rotating the password of the admin user in Charmed etcd.
  • Loading branch information
reneradoi authored Dec 11, 2024
1 parent 6ff42c1 commit 3ee3949
Show file tree
Hide file tree
Showing 4 changed files with 218 additions and 24 deletions.
33 changes: 9 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,11 @@
<!--
Avoid using this README file for information that is maintained or published elsewhere, e.g.:
* metadata.yaml > published on Charmhub
* documentation > published on (or linked to from) Charmhub
* detailed contribution guide > documentation or CONTRIBUTING.md
Use links instead.
-->

# charmed-etcd-operator

Charmhub package name: operator-template
More information: https://charmhub.io/charmed-etcd-operator

Describe your charm in one or two sentences.
## Description
The Charmed etcd Operator deploys and operates the [etcd](https://etcd.io)
software on VMs and machine clusters. The Operator in this repository is a
Python project installing and managing etcd installed from the [etcd Snap](https://snapcraft.io/charmed-etcd),
providing lifecycle management and handling events (install, start, etc).

## Other resources

<!-- If your charm is documented somewhere else other than Charmhub, provide a link separately. -->

- [Read more](https://example.com)

- [Contributing](CONTRIBUTING.md) <!-- or link to other contribution documentation -->

- See the [Juju SDK documentation](https://juju.is/docs/sdk) for more information about developing and improving charms.
Further documentation can be found in these documents:
- setup: docs/set-up.md
- deployment: docs/deploy-etcd.md
- manage passwords: docs/manage-passwords.md
58 changes: 58 additions & 0 deletions docs/deploy-etcd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# Deploy etcd

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

```shell
juju deploy charmed-etcd -n 3 --channel 3.5/edge
```

>**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](https://charmhub.io/charmed-etcd?channel=3.5/edge)
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:

```shell
juju status --watch 1s
```

> See also: [`juju status` command](https://juju.is/docs/juju/juju-status)
When the application is ready, `juju status` will show something similar to the sample output below:

```shell
Model Controller Cloud/Region Version SLA Timestamp
etcd dev-controller localhost/localhost 3.6.0 unsupported 17:26:19Z

App Version Status Scale Charm Channel Rev Exposed Message
charmed-etcd active 3 charmed-etcd 3.5/edge 1 no

Unit Workload Agent Machine Public address Ports Message
charmed-etcd/0 active idle 12 10.86.196.210
charmed-etcd/1 active idle 13 10.86.196.224
charmed-etcd/2* active idle 14 10.86.196.143

Machine State Address Inst id Base AZ Message
12 started 10.86.196.210 juju-6b619f-12 [email protected] Running
13 started 10.86.196.224 juju-6b619f-13 [email protected] Running
14 started 10.86.196.143 juju-6b619f-14 [email protected] 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.

In this tutorial, we will use `curl` with the REST API. Get the IP of an etcd node
from the output of juju status (any of the nodes should work fine), and run the
following command to connect to the etcd cluster:

```shell
curl -L http://10.86.196.143:2379/version
{"etcdserver":"3.5.16","etcdcluster":"3.5.0"}
```
34 changes: 34 additions & 0 deletions docs/manage-passwords.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
# Manage Passwords
When we accessed etcd earlier in this tutorial, we didn't need to include a
password in the HTTP request. But in order to read or write data in etcd, we
need to authenticate ourselves.

Typically, this can be done using a username and TLS certificate. But for now
we can also use charmed etcd's internal admin user `root`. This user is only for
internal use, and it is created automatically by charmed etcd.

We will go through setting a user-defined password for the admin user and
configuring it to charmed etcd.

First, create a secret in `Juju` containing your password:

```shell
juju add-secret mysecret root=changeme
```

You will get the `secret-id` as response. Make note of this, as we will need to
configure it to charmed etcd soon:
```shell
secret:ctbirhuutr9sr8mgrmpg
```

Now we grant our secret to charmed etcd:
```shell
juju grant-secret mysecret charmed-etcd
```

As final step, we configure the secret to charmed etcd, using the previously noted
`secret-id`:
```shell
juju config charmed-etcd system-users=secret:ctbirhuutr9sr8mgrmpg
```
117 changes: 117 additions & 0 deletions docs/set-up.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
# Set up the environment

In this step, we will set up a development environment with the required components for deploying Charmed etcd.

## Summary
* [Set up LXD](#set-up-lxd)
* [Set up Juju](#set-up-juju)

---

## Set up LXD

The simplest way to get started with charmed etcd is to set up a local LXD cloud.
[LXD](https://documentation.ubuntu.com/lxd/en/latest/) 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

```shell
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:

```shell
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:

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

## Set up Juju

[Juju](https://juju.is/docs/juju) is an Operator Lifecycle 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:

```shell
sudo snap install juju --channel 3.6/stable --classic
```

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](https://snapcraft.io/docs/classic-confinement),
and is not allowed to create a `~/.local/share` directory, we need to create it
manually.

```shell
mkdir -p ~/.local/share
```

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

```shell
juju clouds
```

The output will look as follows:

```shell
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:

```shell
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:

```shell
+---------------+---------+-----------------------+------+-----------+-----------+
| 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`:

```shell
juju add-model etcd
```

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

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

0 comments on commit 3ee3949

Please sign in to comment.