yugabyted
YugabyteDB uses a two-server architecture, with YB-TServers managing the data and YB-Masters managing the metadata. However, this can introduce a burden on new users who want to get started right away. To manage YugabyteDB for testing and learning purposes, you can use yugabyted. yugabyted acts as a parent server across the YB-TServer and YB-Masters servers. yugabyted also provides a UI similar to the YugabyteDB Anywhere UI, with a data placement map and metrics dashboard.
The yugabyted
executable file is located in the YugabyteDB home's bin
directory.
For examples of using yugabyted to deploy single- and multi-node clusters, see Examples.
Not recommended for production
Note that yugabyted is not recommended for production deployments. For production deployments with fully-distributed multi-node clusters, useyb-tserver
and yb-master
directly. Refer to Deploy YugabyteDB.
macOS Monterey
macOS Monterey enables AirPlay receiving by default, which listens on port 7000. This conflicts with YugabyteDB and causes yugabyted start
to fail. Use the --master_webserver_port flag when you start the cluster to change the default port number, as follows:
./bin/yugabyted start --master_webserver_port=9999
Alternatively, you can disable AirPlay receiving, then start YugabyteDB normally, and then, optionally, re-enable AirPlay receiving.
Syntax
yugabyted [-h] [ <command> ] [ <flags> ]
- command: command to run
- flags: one or more flags, separated by spaces.
Example
$ ./bin/yugabyted start
Online help
You can access command-line help for yugabyted
by running one of the following examples from the YugabyteDB home:
$ ./bin/yugabyted -h
$ ./bin/yugabyted -help
For help with specific yugabyted
commands, run 'yugabyted [ command ] -h'. For example, you can print the command-line help for the yugabyted start
command by running the following:
$ ./bin/yugabyted start -h
Commands
The following commands are available:
start
Use the yugabyted start
command to start a one-node YugabyteDB cluster for running YSQL and YCQL workloads in your local environment.
Note that to use encryption in transit, OpenSSL must be installed on the nodes.
Syntax
Usage: yugabyted start [flags]
Examples:
-
Create a local single-node cluster:
./bin/yugabyted start
-
Create a local single-node cluster with encryption in transit and authentication:
./bin/yugabyted start --secure
-
Create a single-node locally and join other nodes that are part of the same cluster:
./bin/yugabyted start --join=host:port,[host:port]
Flags
- -h | --help
- Print the command-line help and exit.
- --advertise_address bind-ip
- IP address or local hostname on which yugabyted will listen.
- --join master-ip
- The IP address of the existing yugabyted server that the new yugabyted server will join, or if the server was restarted, rejoin.
- --config config-file
- Yugabyted configuration file path. Refer to Advanced flags.
- --base_dir base-directory
- The directory where yugabyted stores data, configurations, and logs. Must be an absolute path.
- --data_dir data-directory
- The directory where yugabyted stores data. Must be an absolute path. Can be configured to a directory different from the one where configurations and logs are stored.
- --log_dir log-directory
- The directory to store yugabyted logs. Must be an absolute path. This flag controls where the logs of the YugabyteDB nodes are stored.
- --background bool
- Enable or disable running yugabyted in the background as a daemon. Does not persist on restart. Default:
true
- --cloud_location cloud-location
- Cloud location of the yugabyted node in the format
cloudprovider.region.zone
. This information is used for multi-zone, multi-region, and multi-cloud deployments of YugabyteDB clusters. - --fault_tolerance fault_tolerance
- Determines the fault tolerance constraint to be applied on the data placement policy of the YugabyteDB cluster. This flag can accept the following values: none, zone, region, cloud.
- --ui bool
- Enable or disable the webserver UI. Default:
false
- --secure
- Enable encryption in transit and authentication for the node.
- Encryption in transit requires SSL/TLS certificates for each node in the cluster.
- When starting a local single-node cluster, a certificate is automatically generated for the cluster.
- When deploying a node in a multi-node cluster, you need to generate the certificate for the node using the
--cert generate_server_certs
command and copy it to the node before you start the node using the--secure
flag, or the node creation will fail.
- When deploying a node in a multi-node cluster, you need to generate the certificate for the node using the
- When authentication is enabled, the default user and password is
yugabyte
andyugabyte
in YSQL, andcassandra
andcassandra
in YCQL. - For examples creating secure local multi-node, multi-zone, and multi-region clusters, refer to Examples.
Advanced flags
Advanced flags can be set by using the configuration file in the --config
flag. The advanced flags support for the start
command is as follows:
- --ycql_port ycql-port
- The port on which YCQL will run.
- --ysql_port ysql-port
- The port on which YSQL will run.
- --master_rpc_port master-rpc-port
- The port on which YB-Master will listen for RPC calls.
- --tserver_rpc_port tserver-rpc-port
- The port on which YB-TServer will listen for RPC calls.
- --master_webserver_port master-webserver-port
- The port on which YB-Master webserver will run.
- --tserver_webserver_port tserver-webserver-port
- The port on which YB-TServer webserver will run.
- --webserver_port webserver-port
- The port on which main webserver will run.
- --callhome bool
- Enable or disable the call home feature that sends analytics data to Yugabyte. Default:
true
. - --master_flags master_flags
- Specify extra master flags as a set of key value pairs. Format (key=value,key=value).
- --tserver_flags tserver_flags
- Specify extra tserver flags as a set of key value pairs. Format (key=value,key=value).
- --ysql_enable_auth bool
- Enable or disable YSQL authentication. Default:
false
. - If the
YSQL_PASSWORD
environment variable exists, then authentication mode is automatically set totrue
. - --use_cassandra_authentication bool
- Enable or disable YCQL authentication. Default:
false
. - If the
YCQL_USER
orYCQL_PASSWORD
environment variables exist, then authentication mode is automatically set totrue
. - Note that the corresponding environment variables have higher priority than the command-line flags.
- --initial_scripts_dir initial-scripts-dir
- The directory from where yugabyted reads initialization scripts.
- Script format - YSQL
.sql
, YCQL.cql
. - Initialization scripts are executed in sorted name order.
Deprecated flags
- --daemon bool
- Enable or disable running yugabyted in the background as a daemon. Does not persist on restart. Default:
true
. - --listen bind-ip
- The IP address or localhost name to which yugabyted will listen.
configure
Use the yugabyted configure
command to do the following:
- Configure the data placement policy of the cluster.
- Enable or disable encryption at rest.
Syntax
Usage: yugabyted configure [command] [flags]
Commands
The following subcommands are available for yugabyted configure
command:
data_placement
Use the yugabyted configure data_placement
subcommand to set or modify placement policy of the nodes of the deployed cluster.
For example, you would use the following command to create a multi-zone YugabyteDB cluster:
./bin/yugabyted configure data_placement --fault_tolerance=zone
data_placement flags
- -h | --help
- Print the command-line help and exit.
- --fault_tolerance fault-tolerance
- Specify the fault tolerance for the cluster. This flag can accept one of the following values: zone, region, cloud. For example, when the flag is set to zone (
--fault_tolerance=zone
), yugabyted applies zone fault tolerance to the cluster, placing the nodes in three different zones, if available. - --constraint_value data-placement-constraint-value
- Specify the data placement for the YugabyteDB cluster. This is an optional flag. The flag takes comma-separated values in the format
cloud.region.zone
. - --rf replication-factor
- Specify the replication factor for the cluster. This is an optional flag which takes a value of
3
or5
. - --config config-file
- The path to the configuration file of the yugabyted server.
- --data_dir data-directory
- The data directory for the yugabyted server.
- --base_dir base-directory
- The base directory for the yugabyted server.
- --log_dir log-directory
- The log directory for the yugabyted server.
encrypt_at_rest
Use the yugabyted configure encrypt_at_rest
subcommand to enable or disable encryption at rest for the deployed cluster.
To use encryption at rest, OpenSSL must be installed on the nodes.
For example, to enable encryption at rest for a deployed YugabyteDB cluster, execute the following:
./bin/yugabyted configure encrypt_at_rest --enable
To disable encryption at rest for a YugabyteDB cluster which has encryption at rest enabled, execute the following:
./bin/yugabyted configure encrypt_at_rest --disable
encrypt_at_rest flags
- -h | --help
- Print the command-line help and exit.
- --disable disable
- Disable encryption at rest for the cluster. There is no need to set a value for the flag. Use
--enable
or--disable
flag to toggle encryption features on a YugabyteDB cluster. - --enable enable
- Enable encryption at rest for the cluster. There is no need to set a value for the flag. Use
--enable
or--disable
flag to toggle encryption features on a YugabyteDB cluster. - --config config-file
- The path to the configuration file of the yugabyted server.
- --data_dir data-directory
- The data directory for the yugabyted server.
- --base_dir base-directory
- The base directory for the yugabyted server.
- --log_dir log-directory
- : The log directory for the yugabyted server.
cert
Use the yugabyted cert
command to create TLS/SSL certificates for deploying a secure YugabyteDB cluster.
Syntax
Usage: yugabyted cert [command] [flags]
Commands
The following subcommands are available for the yugabyted cert
command:
generate_server_certs
Use the yugabyted cert generate_server_certs
subcommand to generate keys and certificates for the specified hostnames.
For example, to create node server certificates for hostnames 127.0.0.1, 127.0.0.2, 127.0.0.3, execute the following command:
./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1,127.0.0.2,127.0.0.3
Flags
- -h | --help
- Print the command-line help and exit.
- --hostnames hostnames
- Hostnames of the nodes to be added in the cluster. Mandatory flag.
- --config config-file
- The path to the configuration file of the yugabyted server.
- --data_dir data-directory
- The data directory for the yugabyted server.
- --base_dir base-directory
- The base directory for the yugabyted server.
- --log_dir log-directory
- The log directory for the yugabyted server.
stop
Use the yugabyted stop
command to stop a YugabyteDB cluster.
Syntax
Usage: yugabyted stop [flags]
Flags
- -h | --help
- Print the command-line help and exit.
- --config config-file
- The path to the configuration file of the yugabyted server that needs to be stopped.
- --data_dir data-directory
- The data directory for the yugabyted server that needs to be stopped.
- --base_dir base-directory
- The base directory for the yugabyted server that needs to be stopped.
- --log_dir log-directory
- The log directory for the yugabyted server that needs to be stopped.
destroy
Use the yugabyted destroy
command to delete a cluster.
Syntax
Usage: yugabyted destroy [flags]
Flags
- -h | --help
- Print the command-line help and exit.
- --config config-file
- The path to the configuration file of the yugabyted server that needs to be destroyed.
- --data_dir data-directory
- The data directory for the yugabyted server that needs to be destroyed.
- --base_dir base-directory
- The base directory for the yugabyted server that needs to be destroyed.
- --log_dir log-directory
- The log directory for the yugabyted server that needs to be destroyed.
status
Use the yugabyted status
command to check the status.
Syntax
Usage: yugabyted status [flags]
Flags
- -h | --help
- Print the command-line help and exit.
- --config config-file
- The path to the configuration file of the yugabyted server whose status is desired.
- --data_dir data-directory
- The data directory for the yugabyted server whose status is desired.
- --base_dir base-directory
- The base directory for the yugabyted server whose status is desired.
- --log_dir log-directory
- The log directory for the yugabyted server whose status is desired.
version
Use the yugabyted version
command to check the version number.
Syntax
Usage: yugabyted version [flags]
Flags
- -h | --help
- Print the command-line help and exit.
- --config config-file
- The path to the configuration file of the yugabyted server whose version is desired.
- --data_dir data-directory
- The data directory for the yugabyted server whose version is desired.
- --base_dir base-directory
- The base directory for the yugabyted server whose version is desired.
- --log_dir log-directory
- The log directory for the yugabyted server whose version is desired.
collect_logs
Use the yugabyted collect_logs
command to generate a zipped file with all logs.
Syntax
Usage: yugabyted collect_logs [flags]
Flags
- -h | --help
- Print the command-line help and exit.
- --stdout stdout
- Redirect the
logs.tar.gz
file's content to stdout. For example,docker exec \<container-id\> bin/yugabyted collect_logs --stdout > yugabyted.tar.gz
- --config config-file
- The path to the configuration file of the yugabyted server whose logs are desired.
- --data_dir data-directory
- The data directory for the yugabyted server whose logs are desired.
- --base_dir base-directory
- The base directory for the yugabyted server whose logs are desired.
- --log_dir log-directory
- The log directory for the yugabyted server whose logs are desired.
connect
Use the yugabyted connect
command to connect to the cluster using ysqlsh or ycqlsh.
Syntax
Usage: yugabyted connect [command] [flags]
Commands
The following subcommands are available for the yugabyted connect
command:
ysql
Use the yugabyted connect ysql
subcommand to connect to YugabyteDB with ysqlsh.
ycql
Use the yugabyted connect ycql
subcommand to connect to YugabyteDB with ycqlsh.
Flags
- -h | --help
- Print the command-line help and exit.
- --config config-file
- The path to the configuration file of the yugabyted server to connect to.
- --data_dir data-directory
- The data directory for the yugabyted server to connect to.
- --base_dir base-directory
- The base directory for the yugabyted server to connect to.
- --log_dir log-directory
- The log directory for the yugabyted server to connect to.
demo
Use the yugabyted demo
command to use the demo Northwind sample dataset with YugabyteDB.
Syntax
Usage: yugabyted demo [command] [flags]
Commands
The following subcommands are available for the yugabyted demo
command:
connect
Use the yugabyted demo connect
subcommand to load the Northwind sample dataset into a new yb_demo_northwind
SQL database, and then open the ysqlsh
prompt for the same database.
destroy
Use the yuagbyted demo destroy
subcommand to shut down the yugabyted single-node cluster and remove data, configuration, and log directories. This subcommand also deletes the yb_demo_northwind
database.
Flags
- -h | --help
- Print the help message and exit.
- --config config-file
- The path to the configuration file of the yugabyted server to connect to or destroy.
- --data_dir data-directory
- The data directory for the yugabyted server to connect to or destroy.
- --base_dir base-directory
- The base directory for the yugabyted server to connect to or destroy.
- --log_dir log-directory
- The log directory for the yugabyted server to connect to or destroy.
Environment variables
In the case of multi-node deployments, all nodes should have similar environment variables.
Changing the values of the environment variables after the first run has no effect.
YSQL
Set YSQL_PASSWORD
to use the cluster in enforced authentication mode.
The following are combinations of environment variables and their uses:
-
YSQL_PASSWORD
Update the default yugabyte user's password.
-
YSQL_PASSWORD, YSQL_DB
Update the default yugabyte user's password and create
YSQL_DB
named DB. -
YSQL_PASSWORD, YSQL_USER
Create
YSQL_USER
named user and DB with passwordYSQL_PASSWORD
. -
YSQL_USER
Create
YSQL_USER
named user and DB with passwordYSQL_USER
. -
YSQL_USER, YSQL_DB
Create
YSQL_USER
named user with passwordYSQL_USER
andYSQL_DB
named DB. -
YSQL_DB
Create
YSQL_DB
named DB. -
YSQL_USER, YSQL_PASSWORD, YSQL_DB
Create
YSQL_USER
named user with passwordYSQL_PASSWORD
andYSQL_DB
named DB.
YCQL
Set YCQL_USER
or YCQL_PASSWORD
to use the cluster in enforced authentication mode.
The following are combinations of environment variables and their uses:
-
YCQL_PASSWORD
Update the default cassandra user's password.
-
YCQL_PASSWORD, YCQL_KEYSPACE
Update the default cassandra user's password and create
YCQL_KEYSPACE
named keyspace. -
YCQL_PASSWORD, YCQL_USER
Create
YCQL_USER
named user and DB with passwordYCQL_PASSWORD
. -
YCQL_USER
Create
YCQL_USER
named user and DB with passwordYCQL_USER
. -
YCQL_USER, YCQL_KEYSPACE
Create
YCQL_USER
named user with passwordYCQL_USER
andYCQL_USER
named keyspace. -
YCQL_KEYSPACE
Create
YCQL_KEYSPACE
named keyspace. -
YCQL_USER, YCQL_PASSWORD, YCQL_KEYSPACE
Create
YCQL_USER
named user with passwordYCQL_PASSWORD
andYCQL_KEYSPACE
named keyspace.
Examples
To deploy any type of secure cluster (that is, using the --secure
flag) or use encryption at rest, OpenSSL must be installed on your machine.
Destroy a local cluster
If you are running YugabyteDB on your local computer, you can't run more than one cluster at a time. To set up a new local YugabyteDB cluster using yugabyted, first destroy the currently running cluster.
To destroy a local single-node cluster, use the destroy command as follows:
./bin/yugabyted destroy
To destroy a local multi-node cluster, use the destroy
command with the --base_dir
flag set to the base directory path of each of the nodes. For example, for a three node cluster, you would execute commands similar to the following:
./bin/yugabyted destroy --base_dir=/tmp/ybd1
./bin/yugabyted destroy --base_dir=/tmp/ybd2
./bin/yugabyted destroy --base_dir=/tmp/ybd3
./bin/yugabyted destroy --base_dir=$HOME/yugabyte-2.17.3.0/node1
./bin/yugabyted destroy --base_dir=$HOME/yugabyte-2.17.3.0/node2
./bin/yugabyted destroy --base_dir=$HOME/yugabyte-2.17.3.0/node3
If the cluster has more than three nodes, execute a destroy --base_dir=<path to directory>
command for each additional node until all nodes are destroyed.
Create a single-node cluster
Create a single-node cluster with a given base directory. Note the need to provide a fully-qualified directory path for the base_dir
parameter.
./bin/yugabyted start --advertise_address=127.0.0.1 \
--base_dir=/Users/username/yugabyte-2.17.3.0/data1
To create secure single-node cluster with encryption in transit and authentication enabled, add the --secure
flag as follows:
./bin/yugabyted start --secure --advertise_address=127.0.0.1 \
--base_dir=/Users/username/yugabyte-2.17.3.0/data1
When authentication is enabled, the default user and password is yugabyte
and yugabyte
in YSQL, and cassandra
and cassandra
in YCQL.
Create certificates for a secure local multi-node cluster
Secure clusters use encryption in transit, which requires SSL/TLS certificates for each node in the cluster. Generate the certificates using the --cert generate_server_certs
command and then copy them to the respective node base directories before you create a secure local multi-node cluster.
Create the certificates for SSL and TLS connection:
./bin/yugabyted cert generate_server_certs --hostnames=127.0.0.1,127.0.0.2,127.0.0.3
Certificates are generated in the <HOME>/var/generated_certs/<hostname>
directory.
Copy the certificates to the respective node's <base_dir>/certs
directory:
cp $HOME/var/generated_certs/127.0.0.1/* $HOME/yugabyte-2.17.3.0/node1/certs
cp $HOME/var/generated_certs/127.0.0.2/* $HOME/yugabyte-2.17.3.0/node2/certs
cp $HOME/var/generated_certs/127.0.0.3/* $HOME/yugabyte-2.17.3.0/node3/certs
Create a local multi-node cluster
To create a cluster with multiple nodes, you first create a single node, and then create additional nodes using the --join
flag to add them to the cluster. If a node is restarted, you would also use the --join
flag to rejoin the cluster.
To create a secure multi-node cluster, ensure you have generated and copied the certificates for each node.
To create a cluster without encryption and authentication, omit the --secure
flag.
To create the cluster, do the following:
-
Start the first node by running the following command:
./bin/yugabyted start --secure --advertise_address=127.0.0.1 \ --base_dir=$HOME/yugabyte-2.17.3.0/node1 \ --cloud_location=aws.us-east-1.us-east-1a
-
On macOS, configure loopback addresses for the additional nodes as follows:
sudo ifconfig lo0 alias 127.0.0.2 sudo ifconfig lo0 alias 127.0.0.3
-
Add two more nodes to the cluster using the
--join
flag, as follows:./bin/yugabyted start --secure --advertise_address=127.0.0.2 \ --join=127.0.0.1 \ --base_dir=$HOME/yugabyte-2.17.3.0/node2 \ --cloud_location=aws.us-east-1.us-east-1b ./bin/yugabyted start --secure --advertise_address=127.0.0.3 \ --join=127.0.0.1 \ --base_dir=$HOME/yugabyte-2.17.3.0/node3 \ --cloud_location=aws.us-east-1.us-east-1c
Create a multi-zone cluster
To create a secure multi-zone cluster:
-
Start the first node by running the
yugabyted start
command, using the--secure
flag and passing in the--cloud_location
and--fault_tolerance
flags to set the node location details, as follows:./bin/yugabyted start --secure --advertise_address=<host-ip> \ --cloud_location=aws.us-east-1.us-east-1a \ --fault_tolerance=zone
-
Create certificates for the second and third virtual machine (VM) for SSL and TLS connection, as follows:
./bin/yugabyted cert generate_server_certs --hostnames=<IP_of_VM_2>,<IP_of_VM_3>
-
Manually copy the generated certificates in the first VM to the second and third VM, as follows:
-
Copy the certificates for the second VM from
$HOME/var/generated_certs/<IP_of_VM_2>
in the first VM to$HOME/var/certs
in the second VM. -
Copy the certificates for the third VM from
$HOME/var/generated_certs/<IP_of_VM_3>
in first VM to$HOME/var/certs
in the third VM.
-
-
Start the second and the third node on two separate VMs using the
--join
flag, as follows:./bin/yugabyted start --secure --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-east-1.us-east-1b \ --fault_tolerance=zone
./bin/yugabyted start --secure --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-east-1.us-east-1c \ --fault_tolerance=zone
To create a multi-zone cluster:
-
Start the first node by running the
yugabyted start
command, passing in the--cloud_location
and--fault_tolerance
flags to set the node location details, as follows:./bin/yugabyted start --advertise_address=<host-ip> \ --cloud_location=aws.us-east-1.us-east-1a \ --fault_tolerance=zone
-
Start the second and the third node on two separate VMs using the
--join
flag, as follows:./bin/yugabyted start --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-east-1.us-east-1b \ --fault_tolerance=zone
./bin/yugabyted start --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-east-1.us-east-1c \ --fault_tolerance=zone
After starting the yugabyted processes on all the nodes, configure the data placement constraint of the cluster as follows:
./bin/yugabyted configure data_placement --fault_tolerance=zone
The preceding command automatically determines the data placement constraint based on the --cloud_location
of each node in the cluster. If there are three or more zones available in the cluster, the configure
command configures the cluster to survive at least one availability zone failure. Otherwise, it outputs a warning message.
The replication factor of the cluster defaults to 3.
You can set the data placement constraint manually using the --constraint_value
flag, which takes the comma-separated value of cloud.region.zone
. For example:
./bin/yugabyted configure data_placement --fault_tolerance=zone \
--constraint_value=aws.us-east-1.us-east-1a,aws.us-east-1.us-east-1b,aws.us-east-1.us-east-1c \
You can set the replication factor of the cluster manually using the --rf
flag. For example:
./bin/yugabyted configure data_placement --fault_tolerance=zone \
--constraint_value=aws.us-east-1.us-east-1a,aws.us-east-1.us-east-1b,aws.us-east-1.us-east-1c \
--rf=3
Create a multi-region cluster
To create a secure multi-region cluster:
-
Start the first node by running the
yugabyted start
command, using the--secure
flag and passing in the--cloud_location
and--fault_tolerance
flags to set the node location details, as follows:./bin/yugabyted start --secure --advertise_address=<host-ip> \ --cloud_location=aws.us-east-1.us-east-1a \ --fault_tolerance=region
-
Create certificates for the second and third virtual machine (VM) for SSL and TLS connection, as follows:
./bin/yugabyted cert generate_server_certs --hostnames=<IP_of_VM_2>,<IP_of_VM_3>
-
Manually copy the generated certificates in the first VM to the second and third VM:
- Copy the certificates for the second VM from
$HOME/var/generated_certs/<IP_of_VM_2>
in the first VM to$HOME/var/certs
in the second VM. - Copy the certificates for third VM from
$HOME/var/generated_certs/<IP_of_VM_3>
in first VM to$HOME/var/certs
in the third VM.
- Copy the certificates for the second VM from
-
Start the second and the third node on two separate VMs using the
--join
flag, as follows:./bin/yugabyted start --secure --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-west-1.us-west-1a \ --fault_tolerance=region
./bin/yugabyted start --secure --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-central-1.us-central-1a \ --fault_tolerance=region
To create a multi-region cluster:
-
Start the first node by running the
yugabyted start
command, pass in the--cloud_location
and--fault_tolerance
flags to set the node location details as follows:./bin/yugabyted start --advertise_address=<host-ip> \ --cloud_location=aws.us-east-1.us-east-1a \ --fault_tolerance=region
-
Start the second and the third node on two separate VMs using the
--join
flag, as follows:./bin/yugabyted start --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-west-1.us-west-1a \ --fault_tolerance=region
./bin/yugabyted start --advertise_address=<host-ip> \ --join=<ip-address-first-yugabyted-node> \ --cloud_location=aws.us-central-1.us-central-1a \ --fault_tolerance=region
After starting the yugabyted processes on all nodes, configure the data placement constraint of the cluster as follows:
./bin/yugabyted configure data_placement --fault_tolerance=region
The preceding command automatically determines the data placement constraint based on the --cloud_location
of each node in the cluster. If there are three or more regions available in the cluster, the configure
command configures the cluster to survive at least one availability region failure. Otherwise, it outputs a warning message.
The replication factor of the cluster defaults to 3.
You can set the data placement constraint manually using the --constraint_value
flag, which takes the comma-separated value of cloud.region.zone
. For example:
./bin/yugabyted configure data_placement \
--fault_tolerance=region \
--constraint_value=aws.us-east-1.us-east-1a,aws.us-west-1.us-west-1a,aws.us-central-1.us-central-1a
You can set the replication factor of the cluster manually using the --rf
flag. For example:
./bin/yugabyted configure data_placement \
--fault_tolerance=region \
--constraint_value=aws.us-east-1.us-east-1a,aws.us-west-1.us-west-1a,aws.us-central-1.us-central-1a \
--rf=3
Enable and disable encryption at rest
To enable encryption at rest in a deployed local cluster, run the following command:
./bin/yugabyted configure encrypt_at_rest \
--enable \
--base_dir=$HOME/yugabyte-2.17.3.0/node1
To enable encryption at rest in a deployed multi-zone or multi-region cluster, run the following command from any VM:
./bin/yugabyted configure encrypt_at_rest --enable
To disable encryption at rest in a local cluster with encryption at rest enabled, run the following command:
./bin/yugabyted configure encrypt_at_rest \
--disable \
--base_dir=$HOME/yugabyte-2.17.3.0/node1
To disable encryption at rest in a multi-zone or multi-region cluster with this type of encryption enabled, run the following command from any VM:
./bin/yugabyted configure encrypt_at_rest --disable
Pass additional flags to YB-TServer
Create a single-node cluster and set additional flags for the YB-TServer process:
./bin/yugabyted start --tserver_flags="pg_yb_session_timeout_ms=1200000,ysql_max_connections=400"
Upgrade a YugabyteDB cluster
To use the latest features of the database and apply the latest security fixes, upgrade your YugabyteDB cluster to the latest release.
Upgrading an existing YugabyteDB cluster that was deployed using yugabyted includes the following steps:
-
Stop the running YugabyteDB node using the
yugabyted stop
command. -
Start the new yugabyted process by executing the
yugabyted start
command. Use the previously configured--base_dir
when restarting the instance.
Repeat the steps on all the nodes of the cluster, one node at a time.
Upgrade a cluster from single to multi zone
The following steps assume that you have a running YugabyteDB cluster deployed using yugabyted
, and have downloaded the update:
-
Stop the first node by using
yugabyted stop
command:./bin/yugabyted stop
-
Start the YugabyteDB node by using
yugabyted start
command by providing the necessary cloud information as follows:./bin/yugabyted start --advertise_address=<host-ip> \ --cloud_location=aws.us-east-1.us-east-1a \ --fault_tolerance=zone
-
Repeat the previous step on all the nodes of the cluster, one node at a time. If you are deploying the cluster on your local computer, specify the base directory for each node using the
--base-dir
flag. -
After starting all nodes, specify the data placement constraint on the cluster using the following command:
./bin/yugabyted configure data_placement --fault_tolerance=zone
To manually specify the data placement constraint, use the following command:
./bin/yugabyted configure data_placement \ --fault_tolerance=zone \ --constraint_value=aws.us-east-1.us-east-1a,aws.us-east-1.us-east-1b,aws.us-east-1.us-east-1c \ -rf=3