Skip to content

Commit

Permalink
minor fixes (yugabyte#4716)
Browse files Browse the repository at this point in the history
schoudhury authored and deeps1991 committed Jul 22, 2020
1 parent 1ec75df commit 5111ae4
Showing 9 changed files with 51 additions and 88 deletions.
4 changes: 2 additions & 2 deletions docs/content/latest/admin/yb-ts-cli.md
Original file line number Diff line number Diff line change
@@ -128,11 +128,11 @@ $ ./bin/yb-ts-cli [ --server_address=<host>:<port> ] set_flag [ --force ] <flag>

{{< note title="Important" >}}

The `set_flag` command changes the in-memory value of the specified flag, atomically, for a running process and can alter its behavior. **The change does NOT persist across restarts.**
The `set_flag` command changes the in-memory value of the specified flag, atomically, for a running server and can alter its behavior. **The change does NOT persist across restarts.**

In practice, there are some flags that are runtime safe to change (runtime-settable) and some that are not. For example, the bind address of the server cannot be changed at runtime, since the server binds just once at startup. While most of the flags are probably runtime-settable, we need to review the flags and note in the configuration pages which flags are not runtime-settable. (See GitHub issue [#3534](https://github.com/yugabyte/yugabyte-db/issues/3534)).

One typical operational flow is that you can use this to modify runtime flags in memory and then out of band also modify the configuration file that the server uses to start. This allows for flags to be changed on running processes, without executing a restart of the process.
One typical operational flow is that you can use this to modify runtime flags in memory and then out of band also modify the configuration file that the server uses to start. This allows for flags to be changed on running servers, without executing a restart of the server.

{{< /note >}}

Original file line number Diff line number Diff line change
@@ -2,7 +2,7 @@
title: ycqlsh - YCQL shell for YugabyteDB
headerTitle: ycqlsh
linkTitle: ycqlsh
description: Use the YCQL shell (cqlsh) to interact with YugabyteDB.
description: Use the YCQL shell (ycqlsh) to interact with YugabyteDB.
aliases:
- /develop/tools/cqlsh/
- /latest/develop/tools/cqlsh/
20 changes: 10 additions & 10 deletions docs/content/latest/architecture/concepts/universe.md
Original file line number Diff line number Diff line change
@@ -15,7 +15,7 @@ isTocNested: true
showAsideToc: true
---

A YugabyteDB universe is a group of nodes (VMs, physical machines, or containers) that collectively function as a highly available and resilient database.
A YugabyteDB universe is a group of nodes (VMs, physical machines, or containers) that collectively function as a resilient and scalable distributed database.

{{< note title="Note" >}}

@@ -33,19 +33,19 @@ The universe can be deployed in a variety of configurations depending on busines

A YugabyteDB *universe* can consist of one or more namespaces. Each of these namespaces can contain one or more user tables.

YugabyteDB automatically shards, replicates and load-balances these tables across the nodes in the universe, while respecting user-intent such as cross-AZ or region placement requirements, desired replication factor, and so on. YugabyteDB automatically handles failures (e.g., node, process, AZ or region failures), and re-distributes and re-replicates data back to desired levels across the remaining available nodes while still respecting any data placement requirements.
YugabyteDB automatically shards, replicates and load balances these tables across the nodes in the universe, while respecting user intent such as cross-AZ or region placement requirements, desired replication factor, and so on. YugabyteDB automatically handles failures (such as node, disk, AZ or region failures), and re-distributes and re-replicates data back to desired levels across the remaining available nodes while still respecting any replica placement requirements.

### YSQL

Namespaces in YSQL are referred to as **databases** and are logically the same as in other RDBMS databases (such as PostgreSQL).
Namespaces in YSQL are referred to as **databases** and are logically the same as in other RDBMS (such as PostgreSQL).

### YCQL

A namespace in YCQL is referred to as a **keyspace** and is logically the same as a keyspace in Apache Cassandra's CQL.

## Processes and services
## Component services

A universe comprises of two sets of processes, **YB-TServer** and **YB-Master**. The YB-TServer and YB-Master processes form two respective distributed services using [Raft](https://raft.github.io/) as a building block. High availability (HA) of both these services is achieved by the failure-detection, leader election and data replication mechanisms in the Raft implementation.
A universe comprises of two sets of servers, **YB-TServer** and **YB-Master**. These sets of YB-TServer and YB-Master servers form two respective distributed services using [Raft](https://raft.github.io/) as a building block. High availability (HA) of both these services is achieved by the failure detection, leader election and data replication mechanisms in the Raft implementation.

{{< note title="Note" >}}

@@ -55,17 +55,17 @@ YugabyteDB is architected to not have any single point of failure.

These serve different purposes as described below.

### YB-TServer process
### YB-TServer

The **YB-TServer** (aka the *YugabyteDB Tablet Server*) processes are responsible for hosting/serving user data (for example, tables). They deal with all the user queries.
The **YB-TServer** (aka the *YugabyteDB Tablet Server*) service is responsible for hosting/serving user data (for example, tables). They deal with all the user queries.

For details, see [YB-TServer](../yb-tserver).

### YB-Master process
### YB-Master

The **YB-Master** (aka the *YugabyteDB Master Server*) processes are responsible for keeping system metadata, coordinating system-wide operations, such as create/alter/drop tables, and initiating maintenance operations such as load balancing.
The **YB-Master** (aka the *YugabyteDB Master Server*) service is responsible for keeping system metadata, coordinating system-wide operations, such as create/alter/drop tables, and initiating maintenance operations such as load balancing.

For details, see [YB-TServer](../yb-tserver).
For details, see [YB-Master](../yb-master).

Below is an illustration of a simple 4-node YugabyteDB universe:

68 changes: 15 additions & 53 deletions docs/content/latest/architecture/concepts/yb-tserver.md
Original file line number Diff line number Diff line change
@@ -14,88 +14,50 @@ isTocNested: true
showAsideToc: true
---

The YB-TServer (short for YugabyteDB Tablet Server) Service is the service that does the actual IO for end
user requests in a YugabyteDB cluster. Recall from the previous section that data for a table is split, or sharded, into tablets. Each tablet is composed of one or more tablet-peers, depending on the replication factor. And each YB-TServer hosts one or more tablet-peers.
The YB-TServer (short for YugabyteDB Tablet Server) service is responsible for the actual IO for end user requests in a YugabyteDB cluster. Recall from the previous section that data for a table is split, or sharded, into tablets. Each tablet is composed of one or more tablet-peers, depending on the replication factor. And each YB-TServer hosts one or more tablet-peers.

Note: We will refer to the “tablet-peers hosted by a YB-TServer” simply as the “tablets hosted by a
YB-TServer”.
Note: We will refer to the “tablet-peers hosted by a YB-TServer” simply as the “tablets hosted by a YB-TServer”.

Below is a pictorial illustration of this in the case of a 4-node YugabyteDB universe, with one table
that has 16 tablets and a replication factor of 3.
Below is a pictorial illustration of this in the case of a 4-node YugabyteDB universe, with one table that has 16 tablets and a replication factor of 3.

![tserver_overview](/images/architecture/tserver_overview.png)

The tablet-peers corresponding to each tablet hosted on different YB-TServers form a Raft group and
replicate data between each other. The system shown above comprises of 16 independent Raft groups.
The details of this replication are covered in a previous section on replication.
The tablet-peers corresponding to each tablet hosted on different YB-TServers form a Raft group and replicate data between each other. The system shown above comprises of 16 independent Raft groups. The details of this replication are covered in a previous section on replication.

Within each YB-TServer, there is a lot of cross-tablet intelligence built in to maximize resource
efficiency. Below are just some of the ways the YB-TServer coordinates operations across tablets
hosted by it:
Within each YB-TServer, there is a lot of cross-tablet intelligence built in to maximize resource efficiency. Below are just some of the ways the YB-TServer coordinates operations across tablets hosted by it:

## Server-global block cache

The block cache is shared across the different tablets in a given
YB-TServer. This leads to highly efficient memory utilization in cases when one tablet is read more
often than others. For example, one table may have a read-heavy usage pattern compared to
others. The block cache will automatically favor blocks of this table as the block cache is global
across all tablet-peers.
The block cache is shared across the different tablets in a given YB-TServer. This leads to highly efficient memory utilization in cases when one tablet is read more often than others. For example, one table may have a read-heavy usage pattern compared to others. The block cache will automatically favor blocks of this table as the block cache is global across all tablet-peers.

## Space amplification

YugabyteDB's compactions are size tiered.
Size tier compactions have the advantage of lower disk write (IO) amplification when compared to level compactions.
There's sometimes concern that size-tiered compactions have higher space amplification (that it needs 50% space head room).

This is not true in YugabyteDB because each table is broken into several tablets and concurrent compactions across
tablets are throttled to a certain maximum. Therefore the typical space amplification in YugabyteDB tends to be in the 10-20% range.
YugabyteDB's compactions are size tiered. Size tier compactions have the advantage of lower disk write (IO) amplification when compared to level compactions. There may be a concern that size-tiered compactions have higher space amplification (that it needs 50% space head room). This is not true in YugabyteDB because each table is broken into several tablets and concurrent compactions across tablets are throttled to a certain maximum. Therefore the typical space amplification in YugabyteDB tends to be in the 10-20% range.

## Throttled compactions

The compactions are throttled across tablets in a given YB-TServer to
prevent compaction storms. This prevents the often dreaded high foreground latencies during a
compaction storm.
The compactions are throttled across tablets in a given YB-TServer to prevent compaction storms. This prevents the often dreaded high foreground latencies during a compaction storm.

The default policy makes sure that doing a compaction is worthwhile.
The algorithm tries to make sure that the files being compacted are not too disparate in terms of size.
For example, it does not make sense to compact a 100GB file with a 1GB file to produce a 101GB file,
that would be a lot of unnecessary IO for less gain.
The default policy makes sure that doing a compaction is worthwhile. The algorithm tries to make sure that the files being compacted are not too disparate in terms of size. For example, it does not make sense to compact a 100GB file with a 1GB file to produce a 101GB file, that would be a lot of unnecessary IO for less gain.

## Small and large compaction queues

Compactions are prioritized into large and small compactions with
some prioritization to keep the system functional even in extreme IO patterns.
Compactions are prioritized into large and small compactions with some prioritization to keep the system functional even in extreme IO patterns.

In addition to throttling controls for compactions, YugabyteDB does a variety
of internal optimizations to minimize impact of compactions on foreground latencies.
One such is a prioritized queue to give priority to small compactions over large compactions
to make sure the number of SSTable files for any tablet stays as low as possible.
In addition to throttling controls for compactions, YugabyteDB does a variety of internal optimizations to minimize impact of compactions on foreground latencies. One such is a prioritized queue to give priority to small compactions over large compactions to make sure the number of SSTable files for any tablet stays as low as possible.

### Manual compactions

YugabyteDB allows compactions to be externally triggered on a table using the [`compact_table`](../../../admin/yb-admin/#compact-table) command in the [`yb-admin` utility](../../../admin/yb-admin).
This can be useful for cases when new data is not coming into the system for a table anymore,
users want to reclaim disk space due to overwrites/deletes that have already happened or due to TTL expiry.
YugabyteDB allows compactions to be externally triggered on a table using the [`compact_table`](../../../admin/yb-admin/#compact-table) command in the [`yb-admin` utility](../../../admin/yb-admin). This can be useful for cases when new data is not coming into the system for a table anymore, users want to reclaim disk space due to overwrites/deletes that have already happened or due to TTL expiry.

### Server-global memstore limit

Tracks and enforces a global size across the memstores for
different tablets. This makes sense when there is a skew in the write rate across tablets. For
example, the scenario when there are tablets belonging to multiple tables in a single YB-TServer and
one of the tables gets a lot more writes than the other tables. The write heavy table is allowed to
grow much larger than it could if there was a per-tablet memory limit, allowing good write efficiency.
Tracks and enforces a global size across the memstores for different tablets. This makes sense when there is a skew in the write rate across tablets. For example, the scenario when there are tablets belonging to multiple tables in a single YB-TServer and one of the tables gets a lot more writes than the other tables. The write heavy table is allowed to grow much larger than it could if there was a per-tablet memory limit, allowing good write efficiency.

### Auto-sizing of block cache/memstore

The block cache and memstores represent some of the larger
memory-consuming components. Since these are global across all the tablet-peers, this makes memory
management and sizing of these components across a variety of workloads very easy. In fact, based on
the RAM available on the system, the YB-TServer automatically gives a certain percentage of the
total available memory to the block cache, and another percentage to memstores.
The block cache and memstores represent some of the larger memory-consuming components. Since these are global across all the tablet-peers, this makes memory management and sizing of these components across a variety of workloads very easy. In fact, based on the RAM available on the system, the YB-TServer automatically gives a certain percentage of the total available memory to the block cache, and another percentage to memstores.

### Striping tablet load uniformly across data disks

On multi-SSD machines, the data (SSTable) and
WAL (Raft write-ahead log) for various tablets of tables are evenly distributed across the attached
disks on a *per-table basis*. This ensures that each disk handles an even amount of load for each
table.
On multi-SSD machines, the data (SSTable) and WAL (Raft write-ahead log) for various tablets of tables are evenly distributed across the attached disks on a *per-table basis*. This ensures that each disk handles an even amount of load for each table.
Original file line number Diff line number Diff line change
@@ -16,7 +16,7 @@ showAsideToc: true

As discussed before, YugabyteDB is a CP database (consistent and partition tolerant), but achieves very high availability (HA). It achieves this HA by having an active replica that is ready to take over as a new leader in a matter of seconds after the failure of the current leader and serve requests.

If a node fails, it causes the outage of the processes running on it. These would be a YB-TServer and the YB-Master (if one was running on that node). Let us look at what happens in each of these cases.
If a node fails, it causes the outage of the servers running on it. These would be a YB-TServer and the YB-Master (if one was running on that node). Let us look at what happens in each of these cases.

## YB-TServer failure

4 changes: 2 additions & 2 deletions docs/content/latest/deploy/multi-dc/2dc-deployment.md
Original file line number Diff line number Diff line change
@@ -32,15 +32,15 @@ Follow the steps below to set up a 2DC deployment using either unidirectional (a

To create the producer universe, follow these steps.

1. Create the “yugabyte-producer” universe.
1. Create the “yugabyte-producer” universe using the [Manual deployment](../../manual-deployment) steps.

2. Create the the tables for the APIs being used.

### Consumer universe

To create the consumer universe, follow these steps.

1. Create the “yugabyte-consumer” universe.
1. Create the “yugabyte-consumer” universe using the [Manual deployment](../../manual-deployment) steps.

2. Create the tables for the APIs being used.

6 changes: 3 additions & 3 deletions docs/content/latest/deploy/multi-dc/3dc-deployment.md
Original file line number Diff line number Diff line change
@@ -19,7 +19,7 @@ showAsideToc: true

{{< /tip >}}

Three data center deployments of YugabyteDB are essentially a natural extension of the three availability zone (AZ) deployments documented in the [Manual deployment](../../../deploy/manual-deployment/) section. Equal number of nodes are now placed in each data center of the three data centers. Inside a single data center, a multi-AZ deployment is recommended to ensure resilience against zone failures. This approach works fine for any odd number of AZs or data centers. Given YugabyteDB's distributed consensus-based replication which requires majority quorum for continuous availability of write requests, deploying a single cluster across an even number of AZs or data centers is not recommended.
Three data center deployments of YugabyteDB are essentially a natural extension of the three availability zone (AZ) deployments documented in the [Manual deployment](../../manual-deployment/) section. Equal number of nodes are now placed in each data center of the three data centers. Inside a single data center, a multi-AZ deployment is recommended to ensure resilience against zone failures. This approach works fine for any odd number of AZs or data centers. Given YugabyteDB's distributed consensus-based replication which requires majority quorum for continuous availability of write requests, deploying a single cluster across an even number of AZs or data centers is not recommended.

## Example scenario

@@ -40,7 +40,7 @@ Follow the [installation instructions](../../../deploy/manual-deployment/install

## 2. Start YB-Masters

Run the `yb-master` server on each of the nodes as shown below. Note how multiple directories can be provided to the `--fs_data_dirs` flag. Replace the [`--rpc_bind_addresses`](../../../reference/configuration/yb-master/#rpc-bind-addresses) value with the private IP address of the host as well as the set the `--placement_cloud`,`--placement_region` and `--placement_zone` values appropriately.
Run the [yb-master](../../../reference/configuration/yb-master/) server on each of the nodes as shown below. Note how multiple directories can be provided to the `--fs_data_dirs` flag. Replace the [`--rpc_bind_addresses`](../../../reference/configuration/yb-master/#rpc-bind-addresses) value with the private IP address of the host as well as the set the `--placement_cloud`,`--placement_region` and `--placement_zone` values appropriately.

```sh
$ ./bin/yb-master \
@@ -60,7 +60,7 @@ For the full list of configuration flags, see the [YB-Master reference](../../..

## 3. Start YB-TServers

Run the `yb-tserver` server on each node as shown below . Note that all of the master addresses have to be provided using the [`--tserver_master_addrs`](../../../reference/configuration/yb-master/#tserver-master-addrs) flag. Replace the [`--rpc_bind_addresses`](../../../reference/configuration/yb-tserver/#rpc-bind-addresses) value with the private IP address of the host as well as the set the `placement_cloud`,`placement_region` and `placement_zone` values appropriately.
Run the [yb-tserver](../../../reference/configuration/yb-tserver/) server on each node as shown below . Note that all of the master addresses have to be provided using the [`--tserver_master_addrs`](../../../reference/configuration/yb-master/#tserver-master-addrs) flag. Replace the [`--rpc_bind_addresses`](../../../reference/configuration/yb-tserver/#rpc-bind-addresses) value with the private IP address of the host as well as the set the `placement_cloud`,`placement_region` and `placement_zone` values appropriately.

```sh
$ ./bin/yb-tserver \
7 changes: 4 additions & 3 deletions docs/content/latest/faq/general.md
Original file line number Diff line number Diff line change
@@ -33,10 +33,11 @@ YugabyteDB is developed and distributed as an [Apache 2.0 open source project](h

## What makes YugabyteDB unique?

YugabyteDB is a transactional database that brings together three must-have needs of cloud-native microservices, namely SQL as a flexible query language, low-latency read performance and globally-distributed write scalability.
YugabyteDB is a transactional database that brings together 4 must-have needs of cloud native apps, namely SQL as a flexible query language, low-latency performance, continuous availability and globally-distributed scalability. Other databases do not serve all 4 of these needs simultaneously.

- Monolithic SQL databases offer SQL and low-latency reads but do not have ability to scale writes across multiple nodes and/or regions.
- Distributed NoSQL databases offer performance and write scalability but give up on SQL semantics such as multi-key access, ACID transactions and strong consistency.
- Monolithic SQL databases offer SQL and low-latency reads but neither have ability to tolerate failures nor can scale writes across multiple nodes, zones, regions and clouds.

- Distributed NoSQL databases offer read performance, high availability and write scalability but give up on SQL features such as relational data modeling and ACID transactions.

YugabyteDB feature highlights are listed below.

26 changes: 13 additions & 13 deletions docs/content/latest/manage/change-cluster-config.md
Original file line number Diff line number Diff line change
@@ -20,7 +20,7 @@ Sometimes there might be a need to move a YugabyteDB universe deployed on a set
- updating the instance images on a regular basis (for example, AMI rehydration in AWS).
- moving to a different set of zones, regions, or data centers.

This page provides the steps needed to perform such a data move in an online manner from the initial setup to the final setup as described below. This tutorial assumes that you are familiar with the [YugabyteDB process architecture](../../architecture/concepts/universe/).
This page provides the steps needed to perform such a data move in an online manner from the initial setup to the final setup as described below. This tutorial assumes that you are familiar with the [YugabyteDB architecture](../../architecture/concepts/universe/).

## Example scenario

@@ -49,8 +49,8 @@ We will transform the universe into the following final setup:

This is to ensure that we do not inadvertently cause any further under replication on top of ongoing failures.

- All YB-Master processes are running and able to talk to each other. This can be verified by checking the master UI (ex., *http://`node1`:7000/*) and ensure the `Masters` tab shows those three with one in the `LEADER` for `RAFT Role`.
- All of the YB-TServer processes are running and heartbeating to the master leader. This can be verified by checking the master UI (ex., *http://`node1`:7000/tablet-servers*) which lists all the tablet servers in `ALIVE` state.
- All YB-Master servers are running and able to talk to each other. This can be verified by checking the master UI (ex., *http://`node1`:7000/*) and ensure the `Masters` tab shows those three with one in the `LEADER` for `RAFT Role`.
- All of the YB-TServer servers are running and heartbeating to the master leader. This can be verified by checking the master UI (ex., *http://`node1`:7000/tablet-servers*) which lists all the tablet servers in `ALIVE` state.

### Ensure new machines are ready

@@ -63,9 +63,9 @@ Use these two steps to configure the six new machines:
- Follow the [System configuration](../../deploy/manual-deployment/system-config/) instructions for system setup.
- Install [YugabyteDB Software](../../deploy/manual-deployment/install-software/) on each new machine.

## 2. Start YB-Master processes
## 2. Start YB-Master servers

Run the command below to bring up the new YB-Master process on the new master nodes `node7`, `node8` and `node9`. When the `master_addresses` parameter is not set, this master process starts running without joining any existing master quorum. These nodes will be added to the master quorum in a later step.
Run the command below to bring up the new YB-Master server on the new master nodes `node7`, `node8` and `node9`. When the `master_addresses` parameter is not set, this master server starts running without joining any existing master quorum. These nodes will be added to the master quorum in a later step.

```sh
~/master/bin/yb-master \
@@ -77,11 +77,11 @@ Run the command below to bring up the new YB-Master process on the new master no
The `master_addresses` parameter should not be set for these new masters.
{{< /note >}}

Refer to [starting master processes](../../../../deploy/manual-deployment/start-masters/) for further parameters and options.
Refer to [starting master servers](../../../../deploy/manual-deployment/start-masters/) for further parameters and options.

## 3. Start YB-TServer processes
## 3. Start YB-TServer servers

Run the following command to bring up the `tserver` processes on all the new nodes `node7`, `node8`, `node9`, `node10`, `node11` and `node12`.
Run the following command to bring up the `tserver` servers on all the new nodes `node7`, `node8`, `node9`, `node10`, `node11` and `node12`.

```sh
export MASTERS=node1:7100,node2:7100,node3:7100,node7:7100,node8:7100,node9:7100
@@ -91,13 +91,13 @@ export MASTERS=node1:7100,node2:7100,node3:7100,node7:7100,node8:7100,node9:7100
>& /mnt/d0/yb-tserver.out &
```

Refer to [starting `tserver` processes](../../../../deploy/manual-deployment/start-tservers/) for further parameters and options.
Refer to [starting `tserver` servers](../../../../deploy/manual-deployment/start-tservers/) for further parameters and options.

{{< note title="Note" >}}
The `tserver_master_addrs` parameter includes the new master IPs as well, so that they can keep heartbeating/reporting to the new master even after the old masters are removed from master quorum.
{{< /note >}}

Now that the YB-TServer processes are running, we should verify that all the twelve tservers (six old and six new) are heartbeating to the master leader. Go to *http://`node1`:7000/tablet-servers* and confirm that twelve servers are in `ALIVE` status.
Now that the YB-TServer servers are running, we should verify that all the twelve tservers (six old and six new) are heartbeating to the master leader. Go to *http://`node1`:7000/tablet-servers* and confirm that twelve servers are in `ALIVE` status.

## 4. Perform data move

@@ -192,16 +192,16 @@ On a new masters’ UI page, ensure that all the new tablet servers are reportin

## 6. Update master addresses on tservers

The `tserver_master_addrs` parameter for all the new tserver processes needs to be set to the list of three new master IPs `node7:7100,node8:7100,node9:7100` for future use.
The `tserver_master_addrs` parameter for all the new tserver servers needs to be set to the list of three new master IPs `node7:7100,node8:7100,node9:7100` for future use.

{{< note title="Tip" >}}
Updating master addresses is needed in case the yb-tserver process is restarted.
Updating master addresses is needed in case the yb-tserver server is restarted.
{{< /note >}}

## 7. Cleanup

The old nodes are not part of the universe any more and can be shutdown.
Once the old tserver processes are terminated, you can cleanup the blacklist from the master configuration using the command below.
Once the old tserver servers are terminated, you can cleanup the blacklist from the master configuration using the command below.

```sh
~/master/bin/yb-admin -master_addresses $MASTERS change_blacklist REMOVE node1:9100 node2:9100 node3:9100 node4:9100 node5:9100 node6:9100

0 comments on commit 5111ae4

Please sign in to comment.