[DPE-5778] add docs

README.md

@@ -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

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
+```
+
+>This command is useful for checking the status of your Juju model, including
+> the applications and machines it hosts. Helpful information it displays
+> includes IP addresses, ports, state, etc. The output of this command updates
+> once every other second. 
+
+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`.
+
+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"}
+```

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. 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 admin-password=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 admin-password=secret:ctbirhuutr9sr8mgrmpg
+```

docs/set-up.md

@@ -0,0 +1,118 @@
+# 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](#heading--set-up-lxd)
+* [Set up Juju](#heading--set-up-juju)
+* [Set kernel parameters](#heading--kernel-parameters)
+
+---
+
+<a href="#heading--set-up-lxd"><h2 id="heading--set-up-lxd"> Set up LXD </h2></a>
+
+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 OpenSearch 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 |
++------+-------+------+------+------+-----------+
+```
+
+<a href="#heading--set-up-juju"><h2 id="heading--set-up-juju"> Set up Juju </h2></a>
+
+[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
+```