makeover

canonical · Sep 25, 2024 · f1492dd · f1492dd
1 parent 7968f74
commit f1492dd
Show file tree

Hide file tree

Showing 3 changed files with 84 additions and 84 deletions.
diff --git a/README.md b/README.md
@@ -1,25 +1,31 @@
-# Dqlite for Kubernetes
+# K8s-dqlite: Dqlite Backend for Kubernetes
 
 This project is a drop in replacement for etcd on Kubernetes.
 
-If you are looking for an in-memory database to replace etcd in your
-K8s cluster dqlite might be just right for you. Here is what you are getting:
+If you're looking for a lightweight, distributed, and in-memory database to replace etcd
+in your K8s cluster, dqlite might be the solution for you.
 
-- distributed sqlite
-- in-memory
-- high availability
-- almost zero ops
+## Key Features
+
+- Distributed SQlite: Uses dqlite as the backend
+- In-memory: Efficient and fast
+- High Availability: Built-in high availabilty with Raft
+- Minimal operations: Designed to be almost zero ops
 
 ## Building
 
-`k8s-dqlite` links with [`dqlite`](https://github.com/canonical/dqlite). It is recommended to build static binaries, by running:
+`k8s-dqlite` links with [`dqlite`](https://github.com/canonical/dqlite). To build the project, you can create static and dynamic binaries:
+
+### Static Build (Recommended)
 
 ```
 make static
 ./bin/static/k8s-dqlite --help
 ```
 
-If required, you can also build dynamically linked binaries (this requires the dqlite shared libraries and dependencies to be present when running `k8s-dqlite` afterwards):
+### Dynamic Build
+
+If you prefer dynamic binaries (which require dqlite shared libraries and dependencies to be present during runtime), use the following commands:
 
 ```
 make dynamic
@@ -28,19 +34,20 @@ make dynamic
 
 ## Installing
 
-Prepare a directory containing:
+1. Prepare a directory containing the necessary configuration files:
 
 - `init.yaml` with `Address: <host_IP>:<port_used_by_dqlite>`
 - `cluster.crt` and `cluster.key` pair.
 
-Here is a script to build you can use:
+2. Use the following script to generate the required files:
 
 ```
 mkdir -p /var/data/
 IP="127.0.0.1"
 PORT="29001"
 DNS=$(/bin/hostname)
 
+# Create init.yaml with the dqlite listening address
 echo "Address: $IP:$PORT" > /var/data/init.yaml
 mkdir -p /var/tmp/
 
@@ -52,20 +59,14 @@ openssl req -x509 -newkey rsa:4096 -sha256 -days 3650 -nodes -keyout /var/data/c
 chmod -R o-rwX /var/data
 ```
 
-You are now ready to start `k8s-dqlite` with:
+3. Start `k8s-dqlite` by running the following command:
 
 ```
 k8s-dqlite --storage-dir=/var/data/
 ```
 
-The `--listen` option allows you to set the endpoint where dqlite should listen to for connections from kubernetes API server.
-By default `k8s-dqlite` will be listening for connections at `tcp://127.0.0.1:12379`.
-
-The snap package takes care of this installation step so you may want to use the snap you build above:
-
-```
-sudo snap install ./k8s-dqlite_latest_amd64.snap --classic --dangerous
-```
+By default, `k8s-dqlite` listens for connections from the Kubernetes API server at `tcp://127.0.0.1:12379`.
+To change the address, use the `--listen` option.
 
 ## Configuring the API server
 
@@ -87,85 +88,34 @@ To point the API server to `k8s-dqlite` use the following arguments:
 
 ## Highly Available Dqlite
 
-The following steps allows one to setup a highly available dqlite backend.
-
-In the example below, we will setup a 3 node HA dqlite.
+K8s-qdlite supports high availability by using the Raft protocol.
+Below are the steps to set up a highly available dqlite cluster with 3 nodes.
 
-Steps:
+### Steps
 
-1. On the main node, make sure that this node is listening to the default network interface.
-2. On the joining node and after installing k8s-dqlite, you need to backup the dqlite data directory for example (`/var/data`).
-3. Delete the dqlite data directory.
-4. Copy the `cluster.crt` and `cluster.key` from the main node and place it into the joining node's `/var/data`.
-5. Create the `init.yaml` file with the following content
+1. On the main node, ensure that `k8s-dqlite` is listening to the default network interface.
+2. On each joining node, prepare the environment:
+   - Backup the dqlite data directory (`/var/data`).
+   - Remove the existing the dqlite data directory.
+3. Copy the `cluster.crt` and `cluster.key` from the main node and place it into the joining node's `/var/data`.
+4. Create the `init.yaml` file with the following content
 
   ```yaml
   Cluster:
   - <the ip of the main node>:29001
   Address: <ip of the joining node>:29001
   ```
 
-6. Start `k8s-dqlite` process
+5. Start the `k8s-dqlite` process on the joining node:
 
   ```shell
   k8s-dqlite --storage-dir=/var/data/
   ```
 
-7. Go to the main node and verify that the joining node is visible from the dqlite cluster.
+6. On the main node, verify that the joining node is connected to the dqlite cluster.
 
   ```shell
   dqlite -s file:///var/data/cluster.yaml -c /var/data/cluster.crt -k /var/data/cluster.key -f json k8s .cluster
   ```
 
-8. Repeat from step #2 to join another node.
-
-## Develop k8s-dqlite against an active MicroK8s instance
-
-1. Install development tools:
-
-    ```bash
-    sudo snap install go --classic
-    sudo apt update
-    sudo apt install build-essential -y
-    ```
-
-2. Clone k8s-dqlite repository:
-
-    ```bash
-    git clone https://github.com/canonical/k8s-dqlite
-    ```
-
-3. Install MicroK8s on the machine:
-
-    ```bash
-    sudo snap install microk8s --classic
-    ```
-
-4. Wait for MicroK8s to come up:
-
-    ```bash
-    sudo microk8s status --wait-ready
-    ```
-
-5. Stop k8s-dqlite included in the snap:
-
-    ```bash
-    sudo snap stop microk8s.daemon-k8s-dqlite --disable
-    ```
-
-6. Run k8s-dqlite from this repository:
-
-    ```bash
-    cd k8s-dqlite
-    make static
-    sudo ./bin/static/k8s-dqlite \
-      --storage-dir /var/snap/microk8s/current/var/kubernetes/backend \
-      --listen unix:///var/snap/microk8s/current/var/kubernetes/backend/kine.sock:12379
-    ```
-
-7. While developing and making changes to `k8s-dqlite`, just restart k8s-dqlite
-
-Note: When developing k8s-dqlite against Canonical Kubernetes use the following flags:
-
-- `--storage-dir /var/snap/k8s/common/var/lib/k8s-dqlite`
-- `--listen unix:///var/snap/k8s/common/var/lib/k8s-dqlite/k8s-dqlite.sock`
+7. Repeat steps 2–6 for any additional nodes you wish to join to the cluster.
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,50 @@
+# Develop k8s-dqlite against an active MicroK8s instance
+
+1. Install development tools:
+
+    ```bash
+    sudo snap install go --classic
+    sudo apt update
+    sudo apt install build-essential -y
+    ```
+
+2. Clone k8s-dqlite repository:
+
+    ```bash
+    git clone https://github.com/canonical/k8s-dqlite
+    ```
+
+3. Install MicroK8s on the machine:
+
+    ```bash
+    sudo snap install microk8s --classic
+    ```
+
+4. Wait for MicroK8s to come up:
+
+    ```bash
+    sudo microk8s status --wait-ready
+    ```
+
+5. Stop k8s-dqlite included in the snap:
+
+    ```bash
+    sudo snap stop microk8s.daemon-k8s-dqlite --disable
+    ```
+
+6. Run k8s-dqlite from this repository:
+
+    ```bash
+    cd k8s-dqlite
+    make static
+    sudo ./bin/static/k8s-dqlite \
+      --storage-dir /var/snap/microk8s/current/var/kubernetes/backend \
+      --listen unix:///var/snap/microk8s/current/var/kubernetes/backend/kine.sock:12379
+    ```
+
+7. While developing and making changes to `k8s-dqlite`, just restart k8s-dqlite
+
+Note: When developing k8s-dqlite against Canonical Kubernetes use the following flags:
+
+- `--storage-dir /var/snap/k8s/common/var/lib/k8s-dqlite`
+- `--listen unix:///var/snap/k8s/common/var/lib/k8s-dqlite/k8s-dqlite.sock`
diff --git a/docs/versioning.md b/docs/versioning.md
@@ -12,7 +12,7 @@ of three numbers: `MAJOR.MINOR.PATCH`. The version number is incremented based o
 K8s-dqlite versions are associated with one or more Kubernetes versions in use by the [MicroK8s](https://github.com/canonical/microk8s) and [Canonical Kubernetes](https://github.com/canonical/k8s-snap) project.
 Here is an overview that shows which k8s-dqlite version aligns with which supported Kubernetes version:
 
-| K8s-dqlite Tag     | K8s-dqlite branch  | Kubernetes Version |
+| K8s-dqlite Tag     | K8s-dqlite Branch  | Kubernetes Version |
 |--------------------|--------------------|--------------------|
 | 1.1.11             | v1.1               | 1.28-1.30          |
 | 1.2.0              | master             | 1.31               |