-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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
Showing
4 changed files
with
218 additions
and
24 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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"} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 | ||
``` |