Skip to main content

External DB

Datastore options​

Experimental

RKE2 officially supports Embedded etcd, other external datastores are experimental.

  • Embedded Etcd
    Embedded Etcd is the default datastore, and will be used if no other datastore configuration is present.
  • Embedded SQLite
    SQLite cannot be used on clusters with multiple servers.
  • External Database
    The following external datastores:
    • etcd (certified against version 3.5.4)
    • MySQL (certified against versions 5.7 and 8.0)
    • MariaDB (certified against version 10.6.8)
    • PostgreSQL (certified against versions 12.16, 13.12, 14.9 and 15.4)
Prepared Statement Support

RKE2 requires prepared statements support from the DB. This means that connection poolers such as PgBouncer may require additional configuration to work with RKE2.

SQLite Configuration Parameters​

If you wish to use SQLite as the database for your RKE2 server, you must set disable-etcd option without a server option for RKE2 to knows that it needs to disable etcd and run with SQLite.

External Datastore Configuration Parameters​

If you wish to use an external datastore such as PostgreSQL, MySQL, or etcd you must set the datastore-endpoint config so that RKE2 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 options:

OptionsEnvironment VariableDescription
datastore-endpointRKE2_DATASTORE_ENDPOINTSpecify a PostgreSQL, MySQL, or etcd connection string. This is a string used to describe the connection to the datastore. The structure of this string is specific to each backend and is detailed below.
datastore-cafileRKE2_DATASTORE_CAFILETLS Certificate Authority (CA) file used to help secure communication with the datastore. If your datastore serves requests over TLS using a certificate signed by a custom certificate authority, you can specify that CA using this parameter so that the RKE2 client can properly verify the certificate.
datastore-certfileRKE2_DATASTORE_CERTFILETLS certificate file used for client certificate based authentication to your datastore. To use this feature, your datastore must be configured to support client certificate based authentication. If you specify this parameter, you must also specify the datastore-keyfile parameter.
datastore-keyfileRKE2_DATASTORE_KEYFILETLS key file used for client certificate based authentication to your datastore. See the previous datastore-certfile parameter for more details.

Datastore Endpoint Format and Functionality​

As mentioned, the format of the value passed to the datastore-endpoint parameter is dependent upon the datastore backend. The following details this format and functionality for each supported external datastore.

A typical datastore-endpoint option for PostgreSQL has the following format:

postgres://username:password@hostname:port/database-name

More advanced configuration parameters are available. For more information on these, please see https://godoc.org/github.com/lib/pq.

If you specify a database name and it does not exist, the server will attempt to create it.

If you only supply postgres:// as the endpoint, RKE2 will attempt to do the following:

  • Connect to localhost using postgres as the username and password
  • Create a database named kubernetes

Single Server with SQLite​

1. Set disable-etcd without the server parameter in the config file​

disable-etcd: true

2. Install RKE2​

curl -sfL https://get.rke2.io | sh -

3. Enable rke2-server service​

systemctl enable rke2-server.service

4. start the rke2-server service​

systemctl start rke2-server.service

You can follow the server starting by kubectl get nodes to see the server get the Ready status. See Cluster access for more info about how to access RKE2.

External database​

1. Create an External Datastore​

You will first need to create an external datastore for the cluster. See the Datastore options section for more details.

2. Launch Server Nodes​

RKE2 requires two or more server nodes for this HA configuration. See the Requirements guide for minimum machine requirements.

When starting the rke2-server service on these nodes, you must set the datastore-endpoint option in the config so that RKE2 knows how to connect to the external datastore. The token option can also be used to set a deterministic token when adding nodes. When empty, this token will be generated automatically for further use.

For example, a config.yaml like the following could be used to config RKE2 with a MySQL database as the external datastore and set a token:

note

The RKE2 config file needs to be created manually. You can do that by running touch /etc/rancher/rke2/config.yaml as a privileged user.

datastore-endpoint: "mysql://username:password@tcp(hostname:3306)/database-name"
token: SECRET

The datastore endpoint format differs based on the database type. For details, refer to the section on datastore endpoint formats.

To configure TLS certificates when launching server nodes, refer to the datastore configuration section.

By default, server nodes will be schedulable and thus your workloads can get launched on them. If you wish to have a dedicated control plane where no user workloads will run, you can use taints.

Once you've started the rke2-server process on all server nodes, ensure that the cluster has come up properly with kubectl get nodes. You should see your server nodes in the Ready state.

3. Optional: Join Additional Server Nodes​

The same example config in Step 2 can be used to join additional server nodes, where the token from the first node needs to be used.

If the first server node was started without the token option, the token value can be retrieved from any server already joined to the cluster:

cat /var/lib/rancher/rke2/server/token

then you can install the second server with the server address in the config with the step 2:

server: https://you-first-server-node-address:9345
datastore-endpoint: "mysql://username:password@tcp(hostname:3306)/database-name"
token: SECRET

There are a few config flags that must be the same in all server nodes:

  • Network related flags: cluster-dns, cluster-domain, cluster-cidr, service-cidr
  • Flags controlling the deployment of certain components: disable-helm-controller and any component passed to disable
  • Feature related flags: secrets-encryption
note

Ensure that you retain a copy of this token as it is required when restoring from backup and adding nodes.

4. Optional: Join Agent Nodes​

Because RKE2 server nodes are schedulable by default, agent nodes are not required for a RKE2 cluster. However, you may wish to have dedicated agent nodes to run your apps and services.

You just need to specify the URL the agent should register to (either one of the server IPs or a fixed registration address) and the token it should use in the config file.

server: https://you-first-server-node-address:9345
token: SECRET

and then you can install the agent:

curl -sfL https://get.rke2.io | INSTALL_RKE2_TYPE="agent" sh -