Say that embedded Dqlite is deprecated in favor of embedded etcd for K3s

2026-09-25 04:28:15 +00:00 · 2020-09-09 16:52:15 -07:00
parent db00647aaf
commit 5d84dd4872
3 changed files with 25 additions and 6 deletions
@@ -7,7 +7,7 @@ The ability to run Kubernetes using a datastore other than etcd sets K3s apart f

 * If your team doesn't have expertise in operating etcd, you can choose an enterprise-grade SQL database like MySQL or PostgreSQL
 * If you need to run a simple, short-lived cluster in your CI/CD environment, you can use the embedded SQLite database
-* If you wish to deploy Kubernetes on the edge and require a highly available solution but can't afford the operational overhead of managing a database at the edge, you can use K3s's embedded HA datastore built on top of DQLite (currently experimental)
+* If you wish to deploy Kubernetes on the edge and require a highly available solution but can't afford the operational overhead of managing a database at the edge, you can use K3s's embedded HA datastore built on top of embedded etcd (currently experimental)

 K3s supports the following datastore options:

@@ -16,7 +16,7 @@ K3s supports the following datastore options:
 * [MySQL](https://www.mysql.com/) (certified against version 5.7)
 * [MariaDB](https://mariadb.org/) (certified against version 10.3.20)
 * [etcd](https://etcd.io/) (certified against version 3.3.15)
-* Embedded [DQLite](https://dqlite.io/) for High Availability (experimental)
+* Embedded etcd for High Availability (experimental)

 ### External Datastore Configuration Parameters
 If you wish to use an external datastore such as PostgreSQL, MySQL, or etcd you must set the `datastore-endpoint` parameter so that K3s knows how to connect to it. You may also specify parameters to configure the authentication and encryption of the connection. The below table summarizes these parameters, which can be passed as either CLI flags or environment variables.
@@ -94,5 +94,6 @@ K3S_DATASTORE_KEYFILE='/path/to/client.key' \
 k3s server
 ```

-### Embedded DQLite for HA (Experimental)
-K3s's use of DQLite is similar to its use of SQLite. It is simple to set up and manage. As such, there is no external configuration or additional steps to take in order to use this option. Please see [High Availability with Embedded DB (Experimental)]({{<baseurl>}}/k3s/latest/en/installation/ha-embedded/) for instructions on how to run with this option.
+### Embedded etcd for HA (Experimental)
+
+Please see [High Availability with Embedded DB (Experimental)]({{<baseurl>}}/k3s/latest/en/installation/ha-embedded/) for instructions on how to run with this option.
@@ -3,9 +3,15 @@ title: "High Availability with Embedded DB (Experimental)"
 weight: 40
 ---

-As of v1.0.0, K3s is previewing support for running a highly available control plane without the need for an external database. This means there is no need to manage an external etcd or SQL datastore in order to run a reliable production-grade setup. 
+K3s is previewing support for running a highly available control plane without the need for an external database. This means there is no need to manage an external etcd or SQL datastore.

-This architecture is achieved by embedding a dqlite database within the K3s server process. DQLite is short for "distributed SQLite." According to https://dqlite.io, it is "*a fast, embedded, persistent SQL database with Raft consensus that is perfect for fault-tolerant IoT and Edge devices.*" This makes it a natural fit for K3s.
+In K3s 1.0.0, Dqlite was used as the experimental embedded database. In K3s v1.19.1+, embedded etcd is used.
+
+Please note that upgrades from experimental Dqlite to experimental embedded etcd are not supported. If you attempt an upgrade it will not succeed and data will be lost.
+
+### Embedded etcd (Experimental)
+
+_Available as of K3s v1.19.1_

 To run K3s in this mode, you must have an odd number of server nodes. We recommend starting with three nodes.

@@ -20,3 +26,13 @@ K3S_TOKEN=SECRET k3s server --server https://<ip or hostname of server1>:6443
 ```

 Now you have a highly available control plane. Joining additional worker nodes to the cluster follows the same procedure as a single server cluster.
+
+### Embedded Dqlite (Deprecated)
+
+> **Warning:** Experimental etcd replaced experimental Dqlite in the K3s v1.19.1 release. This is a breaking change. Please note that upgrades from experimental Dqlite to experimental embedded etcd are not supported. If you attempt an upgrade it will not succeed and data will be lost.
+
+As of v1.0.0, K3s previewed support for running a highly available control plane without the need for an external database.
+
+This architecture is achieved by embedding a Dqlite database within the K3s server process. DQLite is short for "distributed SQLite." According to https://dqlite.io, it is "*a fast, embedded, persistent SQL database with Raft consensus that is perfect for fault-tolerant IoT and Edge devices.*"
+
+To run K3s with the embedded Dqlite database, follow the same steps as the [embedded etcd database](#embedded-etcd-experimental) using a K3s release between v1.0.0 and v1.19.1.
@@ -8,3 +8,5 @@ This section describes how to upgrade your K3s cluster.
 [Upgrade basics]({{< baseurl >}}/k3s/latest/en/upgrades/basic/) describes several techniques for upgrading your cluster manually. It can also be used as a basis for upgrading through third-party Infrastructure-as-Code tools like [Terraform](https://www.terraform.io/).

 [Automated upgrades]({{< baseurl >}}/k3s/latest/en/upgrades/automated/) describes how to perform Kubernetes-native automated upgrades using Rancher's [system-upgrade-controller](https://github.com/rancher/system-upgrade-controller).
+
+> The experimental embedded Dqlite data store was deprecated in K3s v1.19.1. Please note that upgrades from experimental Dqlite to experimental embedded etcd are not supported. If you attempt an upgrade it will not succeed and data will be lost.