mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-05-15 17:43:37 +00:00
Add older-installations for ha prior to v1.0.0 and update main ha page
- Add an older-installations page, a child of the Installation main section to address older k3s versions different method for bringing up servers - Modify the main HA install page so that we no longer list anything as experimental -- Also update the page so we remove the Cluster Datastore Options section, compact this into a modified section of step 2 for bring up the master (server) nodes -- Fix any wording, modify text so it's more readable and easier to follow.
This commit is contained in:
David Nuzik
@@ -1,12 +1,13 @@
|
||||
---
|
||||
title: "High Availability (HA) Install (Experimental)"
|
||||
title: "High Availability (HA) Install"
|
||||
weight: 30
|
||||
---
|
||||
|
||||
>**Important:** High-Availability (HA) was introduced in the v0.10.0 release of k3s and is _experimental_. Our v1.0 release plans to support HA in production environments. HA should currently only be used for testing purposes in non-production environments.
|
||||
>**Note:** k3s does not utilize etcd by default so only a 2-node cluster is needed for HA at a minimum. The following will guide you through setting up a 2-node cluster with PostgreSQL. You could optionally add one or more nodes for additional redundancy. In the future we plan to add support for additional database providers.
|
||||
>**Note:** Official support for High-Availability (HA) was introduced in our v1.0.0 release. HA may work on older releases but has limited support. Older versions of k3s bring up master nodes slightly differently. Reference [this]({{< baseurl >}}/k3s/latest/en/installation/older-installations/) page for more information.
|
||||
|
||||
For production environments that cannot tolerate down time, we recommend installing k3s in a high-availability configuration so that you can always access your cluster. This procedure walks you through setting up a 2-node cluster with k3s with an external PostgreSQL database. As of v0.10.0 release (Experimental HA) we are supporting PostgreSQL 10.7 and 11.5
|
||||
>k3s servers do not utilize a quorum for leader election and so only a 2-node cluster is needed for HA at a minimum. You could optionally add one or more server nodes for additional redundancy.
|
||||
|
||||
For production environments that cannot tolerate down time, we recommend installing k3s in a high-availability configuration so that you can always access your cluster. This procedure walks you through setting up a 2-server cluster with k3s with an external database for the cluster datastore.
|
||||
|
||||
# Recommended Architecture
|
||||
|
||||
@@ -19,35 +20,121 @@ The external database shown should be a single endpoint k3s can access. The work
|
||||
|
||||
Installation Outline
|
||||
--------------------
|
||||
1. Create backend database (PostgreSQL)
|
||||
2. Create master nodes
|
||||
1. Create backend database (PostgreSQL, MySQL, or etcd)
|
||||
2. Create server (master) nodes
|
||||
3. Join worker nodes
|
||||
|
||||
### Create Database for Cluster Datastore
|
||||
The first step for setting up High Availability (HA) is to create the database for the backend (cluster datastore). As of v0.10.0 release (Experimental HA) we are currently supporting PostgreSQL 10.7-R1 thru 11.5-R1.
|
||||
You will first need to create the database for the backend (cluster datastore). k3s must have a single endpoint it can reach to talk to the database.
|
||||
|
||||
Here is a list of supported backend databases as of our v1.0.0 release:
|
||||
|
||||
* PostgreSQL 10.7 and 11.5
|
||||
* MySQL 5.7
|
||||
* etcd 3.3.15
|
||||
|
||||
### Create Master Nodes
|
||||
Following the [Node Requirements]({{< baseurl >}}/k3s/latest/en/installation/node-requirements/) page, provision at least two machines.
|
||||
The sections below will indicate what you need to run (depending on the type of database) to bring the server (master) nodes up.
|
||||
|
||||
On the first machine, run the following command to install k3s and connect it to the database.
|
||||
>**Note:** You may wish to taint the server (master) nodes. They will run the kubelet and be scheduleable. If you wish to do this, you can use the `--node-taint` flag. For example `--node-taint key=value:NoExecute`.
|
||||
|
||||
>**Note:** You may wish to taint the master nodes. They will run the kubelet by default and be scheduleable. You can only add node labels and taints during the install process. If you wish to do this, use the `--node-taint` flag. For example `--node-taint key1=value1:NoExecute` the following examples do not include this flag.
|
||||
>If your server (master) node pool will be auto-scaling, we recommend using the `--cluster-secret` flag instead of the default node-token. For example, this will make it easier to write user-data. The examples we provide use this flag.
|
||||
|
||||
>If your master node pool will be auto-scaling, we recommend using the `--cluster-secret` flag instead of the default node-token. For example, this will make it easier to write user-data. The following examples include this optional flag.
|
||||
|
||||
{{% tabs %}}
|
||||
{{% tab "PostgreSQL" %}}
|
||||
|
||||
>**Note:** If you do not specify a DSN (data source name), for example if you only supply `--storage-endpoint='postgres://'` then the server will attempt to connect with the following:
|
||||
|
||||
> * Connect to `localhost` using the `postgres` user.
|
||||
> * Use `postgres` as the password.
|
||||
> * Create a database with the name `kubernetes`.
|
||||
|
||||
> If you specify a database name and it does not exist, then the server will attempt to create it.
|
||||
> For more information about the Postgres driver DSN, please refer to https://godoc.org/github.com/lib/pq
|
||||
|
||||
### Secure Method
|
||||
Run the following command on each server to install k3s and connect it to the database securely.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' --cluster-secret='mysecret' --bootstrap-save
|
||||
```
|
||||
|
||||
The cluster-secret can contain any Unicode, although you should avoid single and double quotes and make sure the contents are terminal-friendly.
|
||||
|
||||
Note: You may want to provide the database password and cluster-secret temporarily via a file or environment variable then destroy it or clear your bash history so the password is no longer exposed in plain text on the machine.
|
||||
|
||||
On the second machine, run the following command. Since we ran the first node with the `--bootstrap-save` flag the second and any additional machines will now automatically bootstrap HA.
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' \
|
||||
--cluster-secret='mysecret' \
|
||||
--storage-cafile ca.crt \
|
||||
--storage-certfile postgres.crt \
|
||||
--storage-keyfile postgres.key
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname'
|
||||
|
||||
The above command will use these certificates to generate the tls config to communicate with postgres securely.
|
||||
|
||||
### Insecure Method
|
||||
Run the following command on each server to install k3s and connect it to the database insecurely.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='postgres://username:password@hostname:5432/dbname' --cluster-secret='mysecret'
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "MySQL" %}}
|
||||
|
||||
>**Note:** If you do not specify a DSN (data source name), for example if you only supply `--storage-endpoint='mysql://'` then the server will attempt to connect with the following:
|
||||
|
||||
> * Connect to the MySQL socket at `/var/run/mysqld/mysqld.sock` using the `root` user.
|
||||
> * Use no password.
|
||||
> * Create a database with the name `kubernetes`.
|
||||
|
||||
> If you specify a database name and it does not exist, then the server will attempt to create it.
|
||||
> For more information about the MySQL driver DSN, please refer to https://github.com/go-sql-driver/mysql#dsn-data-source-name
|
||||
|
||||
### Secure Method
|
||||
Run the following command on each server to install k3s and connect it to the database securely.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='mysql://username:password@tcp(hostname:3306)/dbname' \
|
||||
--cluster-secret='mysecret' \
|
||||
--storage-cafile ca.crt \
|
||||
--storage-certfile mysql.crt \
|
||||
--storage-keyfile mysql.key
|
||||
|
||||
|
||||
```
|
||||
The above command will use these certificates to generate the tls config to communicate with mysql securely.
|
||||
|
||||
### Insecure Method
|
||||
Run the following command on each server to install k3s and connect it to the database insecurely.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='mysql://username:password@tcp(hostname:3306)/dbname' --cluster-secret='mysecret'
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% tab "etcd" %}}
|
||||
|
||||
### Secure Method
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint="https://hostname:2379" \
|
||||
--cluster-secret='mysecret' \
|
||||
--storage-cafile ca.crt \
|
||||
--storage-certfile etcd.crt \
|
||||
--storage-keyfile etcd.key
|
||||
```
|
||||
The above command will use these certificates to generate the tls config to communicate with etcd securely.
|
||||
|
||||
### Insecure Method
|
||||
Run the following command on each server to install k3s and connect it to the database insecurely.
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='http://hostname:2379' --cluster-secret='mysecret'
|
||||
```
|
||||
|
||||
{{% /tab %}}
|
||||
{{% /tabs %}}
|
||||
|
||||
|
||||
>**Note:** The cluster-secret can contain any Unicode, although you should avoid single and double quotes and make sure the contents are terminal-friendly. You should use a strong password.
|
||||
>You may want to provide the database password and cluster-secret temporarily via a file or environment variable then destroy it or clear your bash history so the password is no longer exposed in plain text on the machine.
|
||||
|
||||
Ensure that both of the nodes are in a Ready state such as with `k3s kubectl get nodes`
|
||||
|
||||
@@ -64,99 +151,3 @@ Provide the IP or DNS in place of `<master_node>` this can be any one master nod
|
||||
|
||||
Note: You may want to provide the cluster-secret temporarily via a file or environment variable then destroy it or clear your bash history so the password is no longer exposed in plain text on the machine.
|
||||
|
||||
# Cluster Datastore Options
|
||||
|
||||
>**Note:** As of v0.10.0 release (Experimental HA) we are currently supporting PostgreSQL 10.7-R1 thru 11.5-R1.
|
||||
|
||||
k3s can support various storage backends including: SQLite (default), MySQL, Postgres, and etcd, this enhancement depends on the following arguments that can be passed to k3s server:
|
||||
|
||||
* `--storage-endpoint` _value_
|
||||
|
||||
Specify etcd, Mysql, Postgres, or Sqlite (default) data source name [$`K3S_STORAGE_ENDPOINT`]
|
||||
|
||||
* `--storage-cafile` _value_
|
||||
|
||||
SSL Certificate Authority file used to secure storage backend communication [$`K3S_STORAGE_CAFILE`]
|
||||
|
||||
* `--storage-certfile` _value_
|
||||
|
||||
SSL certification file used to secure storage backend communication [$`K3S_STORAGE_CERTFILE`]
|
||||
|
||||
* `--storage-keyfile` _value_
|
||||
|
||||
SSL key file used to secure storage backend communication [$`K3S_STORAGE_KEYFILE`]
|
||||
|
||||
### MySQL
|
||||
|
||||
To use k3s with MySQL storage backend, you can specify the following for insecure connection:
|
||||
|
||||
```
|
||||
--storage-endpoint="mysql://"
|
||||
```
|
||||
By default the server will attempt to connect to mysql using the mysql socket at `/var/run/mysqld/mysqld.sock` using the root user and with no password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN.
|
||||
|
||||
To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example:
|
||||
|
||||
```
|
||||
--storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest"
|
||||
```
|
||||
|
||||
This command will attempt to connect to MySQL on host `192.168.1.100` on port `3306` with username `k3suser` and password `k3spass` and k3s will automatically create a new database with the name `k3stest` if it doesn't exist, for more information about the MySQL driver data source name, please refer to https://github.com/go-sql-driver/mysql#dsn-data-source-name
|
||||
|
||||
To connect to MySQL securely, you can use the following example:
|
||||
```
|
||||
--storage-endpoint="mysql://k3suser:k3spass@tcp(192.168.1.100:3306)/k3stest" \
|
||||
--storage-cafile ca.crt \
|
||||
--storage-certfile mysql.crt \
|
||||
--storage-keyfile mysql.key
|
||||
```
|
||||
The above command will use these certificates to generate the tls config to communicate with mysql securely.
|
||||
|
||||
|
||||
### Postgres
|
||||
|
||||
Connection to postgres can be established using the following command:
|
||||
|
||||
```
|
||||
--storage-endpoint="postgres://"
|
||||
```
|
||||
|
||||
By default the server will attempt to connect to postgres on localhost with using the `postgres` user and with `postgres` password, k3s will also create a database with the name `kubernetes` if the database is not specified in the DSN.
|
||||
|
||||
To override the method of connection, user/pass, and database name, you can provide a custom DSN, for example:
|
||||
|
||||
```
|
||||
--storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest"
|
||||
```
|
||||
|
||||
This command will attempt to connect to Postgres on host `192.168.1.100` on port `5432` with username `k3suser` and password `k3spass` and k3s will automatically create a new database with the name `k3stest` if it doesn't exist, for more information about the Postgres driver data source name, please refer to https://godoc.org/github.com/lib/pq
|
||||
|
||||
To connect to Postgres securely, you can use the following example:
|
||||
|
||||
```
|
||||
--storage-endpoint="postgres://k3suser:k3spass@192.168.1.100:5432/k3stest" \
|
||||
--storage-certfile postgres.crt \
|
||||
--storage-keyfile postgres.key \
|
||||
--storage-cafile ca.crt
|
||||
```
|
||||
|
||||
The above command will use these certificates to generate the tls config to communicate with postgres securely.
|
||||
|
||||
### etcd
|
||||
|
||||
Connection to etcd3 can be established using the following command:
|
||||
|
||||
```
|
||||
--storage-endpoint="https://127.0.0.1:2379"
|
||||
```
|
||||
The above command will attempt to connect insecurely to etcd on localhost with port `2379`, you can connect securely to etcd using the following command:
|
||||
|
||||
```
|
||||
--storage-endpoint="https://127.0.0.1:2379" \
|
||||
--storage-cafile ca.crt \
|
||||
--storage-certfile etcd.crt \
|
||||
--storage-keyfile etcd.key
|
||||
```
|
||||
|
||||
The above command will use these certificates to generate the tls config to communicate with etcd securely.
|
||||
|
||||
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: "Installations Prior to v1.0.0"
|
||||
weight: 50
|
||||
---
|
||||
|
||||
>**Note:** Running k3s v1.0.0 or newer is recommended as it has official support for PostgreSQL, MySQL, and etcd. v0.10.0 introduced support for PostgreSQL 10.7 and 11.5 only. Older versions did not have any official support for any external databases.
|
||||
|
||||
>In v1.0.0 the method for adding master nodes is easier. If you are running a version of k3s older than v1.0.0 use these instructions for adding additional servers. Otherwise, the process is unchanged such as for joining workers (agents) to the cluster.
|
||||
|
||||
First, create your initial master, for example:
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='value_here' --cluster-secret='mysecret' --bootstrap-save
|
||||
```
|
||||
|
||||
Then, add additional masters:
|
||||
|
||||
```
|
||||
curl -fL https://get.k3s.io | sh -s - server --storage-endpoint='value_here'
|
||||
```
|
||||
|
||||
Substitute the value for `--storage-endpoint` with different strings for PostgreSQL, MySQL, or etcd accordingly. Below are examples of the `--storage-endpoint` flag for each type of database:
|
||||
|
||||
### PostgreSQL
|
||||
|
||||
```
|
||||
--storage-endpoint='postgres://username:password@hostname:5432/dbname'
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
```
|
||||
--storage-endpoint='mysql://username:password@tcp(hostname:3306)/dbname''
|
||||
```
|
||||
|
||||
### etcd
|
||||
|
||||
```
|
||||
--storage-endpoint='https://etcd_hostname:2379'
|
||||
```
|
||||
Reference in New Issue
Block a user