diff --git a/README.md b/README.md index 2293319..4430de5 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,11 @@ - - -# 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 - - - -- [Read more](https://example.com) - -- [Contributing](CONTRIBUTING.md) - -- 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 \ No newline at end of file diff --git a/docs/deploy-etcd.md b/docs/deploy-etcd.md new file mode 100644 index 0000000..2b7442c --- /dev/null +++ b/docs/deploy-etcd.md @@ -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 ubuntu@22.04 Running +13 started 10.86.196.224 juju-6b619f-13 ubuntu@22.04 Running +14 started 10.86.196.143 juju-6b619f-14 ubuntu@22.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. + +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"} +``` \ No newline at end of file diff --git a/docs/manage-passwords.md b/docs/manage-passwords.md new file mode 100644 index 0000000..81b241b --- /dev/null +++ b/docs/manage-passwords.md @@ -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 +``` diff --git a/docs/set-up.md b/docs/set-up.md new file mode 100644 index 0000000..066bc87 --- /dev/null +++ b/docs/set-up.md @@ -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- | RUNNING | 10.86.196.118 (eth0) | | CONTAINER | 0 | ++---------------+---------+-----------------------+------+-----------+-----------+ +``` + +where `` 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 +``` \ No newline at end of file