Merge pull request #2 from anton-bobkov/docs-feature-security-cluster-scheme

Replaced the cluster scheme diagram with a directory structure

Author: anton-bobkov

ydb/docs/en/core/concepts/datamodel/index.md

@@ -1,8 +1,29 @@
-# Data model and schema
+# Cluster structure
 
-This section describes the entities that {{ ydb-short-name }} uses within DBs. The {{ ydb-short-name }} core lets you flexibly implement various storage primitives, so new entities may appear in the future.
+This section describes the {{ ydb-short-name }} entities.
 
-{{ ydb-short-name }} is a relational database where the data is stored in [tables](table.md) with each table consisting of rows and columns. Database objects in {{ ydb-short-name }} can be organized into a hierarchy of [folders](dir.md).
+## {{ ydb-short-name }} cluster scheme {#cluster-scheme}
+
+{{ ydb-short-name }} cluster scheme is a hierarchical namespace of a {{ ydb-short-name }} cluster. The only root element of this namespace is a **cluster scheme root**. A root of the cluster scheme can be a directory or a root database. Children elements of the cluster scheme root can be [databases](../../concepts/glossary.md#database) or other [scheme objects](../../concepts/glossary.md#scheme-object). Scheme objects can use nested directories to form a hierarchy.
+
+```plaintext
+Cluster scheme root/
+├── Database 1/
+│   ├── Table 1
+│   ├── Directory 1/
+│   │   ├── Table 2
+│   │   └── Table 3
+│   └── Directory 2/
+│       ├── Directory 3/
+│       │   └── ...
+│       └── ...
+└── Database 2/
+    └── ...
+```
+
+## Data model
+
+Scheme objects in {{ ydb-short-name }} databases:
 
 * [Folder](dir.md)
 * [Table](table.md)

ydb/docs/en/core/concepts/glossary.md

@@ -18,9 +18,20 @@ Like in most database management systems, a **database** in {{ ydb-short-name }}
 
 Another essential characteristic of {{ ydb-short-name }} databases is that they typically have dedicated compute resources allocated to them. Hence, creating an additional database is usually done externally by [DevOps engineers](../devops/index.md) or automation rather than via a SQL query.
 
+{{ ydb-short-name }} has the following database types:
+
+- [tenant databases](#tenant-database)
+- [root databases](#root-database)
+
+#### Tenant database {#tenant-database}
+
+A **tenant database** is a logical container with an independent namespace for user-defined objects within the database.
+
+Tenant databases are completely isolated from each other — they are processed by separate [database nodes](#database-node), they have separate [storage groups](#storage-group), and they can have separate [users](#access-user) with different [access rights](#access-right) and [access levels](#access-level).
+
 #### Root database {#root-database}
 
-A **root database** is a system database created for {{ ydb-short-name }}'s internal purposes at the root of the cluster scheme. This database contains service data such as [users], [access levels](#access-level) and [access rights](#access-right), tenant databases, and more.
+A **root database** is a system database created for {{ ydb-short-name }}'s internal purposes at the [root of the cluster scheme](#scheme-root). This database contains service data such as [users](#access-user), [access levels](#access-level) and [access rights](#access-right), [tenant databases](#tenant-database), and more.
 
 ### Node {#node}
 
@@ -263,6 +274,22 @@ An **authentication token** or **auth token** is a token that {{ ydb-short-name
 
 {{ ydb-short-name }} supports various [authentication modes](../security/authentication.md) and token types.
 
+### Cluster scheme {#scheme}
+
+A **{{ ydb-short-name }} cluster scheme** is a hierarchical namespace of a {{ ydb-short-name }} cluster. The only root element of this namespace is a [cluster scheme root](#scheme-root). A root of the cluster scheme can be a [directory](#folder) or a [root database](#root-database). Children elements of the cluster scheme root can be [databases](#database) or other [scheme objects](#scheme-object). Scheme objects can use nested directories to form a hierarchy.
+
+### Database scheme {#scheme-database}
+
+A **database scheme** is a subset of the hierarchical namespace of a {{ ydb-short-name }} cluster that belongs to a database.
+
+### Database root {#scheme-database-root}
+
+A **database root** is a path to a database in a {{ ydb-short-name }} cluster scheme. This path acts as a root for database scheme objects.
+
+### Scheme root {#scheme-root}
+
+A **scheme root** is a root element of a [{{ ydb-short-name }} cluster scheme](datamodel/index.md#cluster-scheme). Children elements of the cluster scheme root can be [databases](#database) or other [scheme objects](#scheme-object).
+
 ### Scheme object {#scheme-object}
 
 A database schema consists of **scheme objects**, which can be databases, [tables](#table) (including [external tables](#external-table)), [topics](#topic), [folders](#folder), and so on.

ydb/docs/en/core/reference/configuration/auth_config.md

@@ -24,7 +24,7 @@ Default value: `true`
 Valid values:
 
 - `true` – internal users are added only to the [root database](../../concepts/glossary.md#root-database).
-- `false` – internal users are added to the root and to tenant databases.
+- `false` – internal users are added to the root and to [tenant databases](../../concepts/glossary.md#tenant-database).
 
 Default value: `true`
     ||

ydb/docs/en/core/reference/configuration/index.md

@@ -125,7 +125,7 @@ When deploying {{ ydb-short-name }} with a Kubernetes operator, the entire `host
 
 ## domains_config: Cluster domain {#domains-config}
 
-This section contains the configuration of the {{ ydb-short-name }} cluster root domain, including the [Blob Storage](#domains-blob) (binary object storage), [State Storage](#domains-state), and [authentication](#auth) configurations.
+This section contains the configuration of the {{ ydb-short-name }} cluster root domain, including the [Blob Storage](#domains-blob) (binary object storage) and [State Storage](#domains-state) configurations.
 
 ### Syntax
 
@@ -207,168 +207,6 @@ Each State Storage client (for example, DataShard tablet) uses `nto_select` node
 
 Odd numbers must be used for `nto_select` because using even numbers does not improve fault tolerance in comparison to the nearest smaller odd number.
 
-## Authentication configuration {#auth}
-
-The [authentication mode](../../security/authentication.md) in the {{ ydb-short-name }} cluster is created in the `domains_config.security_config` section.
-
-### Syntax
-
-```yaml
-domains_config:
-  ...
-  security_config:
-    # authentication mode settings
-    enforce_user_token_requirement: false
-    enforce_user_token_check_requirement: false
-    default_user_sids: <SID list for anonymous requests>
-    all_authenticated_users: <group SID for all authenticated users>
-    all_users_group: <group SID for all users>
-
-    # initial security settings
-    default_users: <initial list of users>
-    default_groups: <initial list of groups>
-    default_access: <initial permissions>
-
-    # настройки привилегий
-    viewer_allowed_sids: <list of SIDs enabled for YDB UI access>
-    monitoring_allowed_sids: <list of SIDs enabled for tablet administration>
-    administration_allowed_sids: <list of SIDs enabled for storage administration>
-    register_dynamic_node_allowed_sids: <list of SIDs enabled for database node registration>
-  ...
-```
-
-| Key | Description |
---- | ---
-| `enforce_user_token_requirement` | Require a user token.<br/>Acceptable values:<br/><ul><li>`false`: Anonymous authentication mode, no token needed (used by default if the parameter is omitted).</li><li>`true`: Username/password authentication mode. A valid user token is needed for authentication.</li></ul> |
-
-### Examples {#domains-examples}
-
-{% list tabs %}
-
-- `block-4-2`
-
-   ```yaml
-   domains_config:
-     domain:
-     - name: Root
-       storage_pool_types:
-       - kind: ssd
-         pool_config:
-           box_id: 1
-           erasure_species: block-4-2
-           kind: ssd
-           pdisk_filter:
-           - property:
-             - type: SSD
-           vdisk_kind: Default
-     state_storage:
-     - ring:
-         node: [1, 2, 3, 4, 5, 6, 7, 8]
-         nto_select: 5
-       ssid: 1
-
-
-- `mirror-3-dc`
-
-   ```yaml
-   domains_config:
-     domain:
-     - name: global
-       storage_pool_types:
-       - kind: ssd
-         pool_config:
-           box_id: 1
-           erasure_species: mirror-3-dc
-           kind: ssd
-           pdisk_filter:
-           - property:
-             - type: SSD
-           vdisk_kind: Default
-     state_storage:
-     - ring:
-         node: [1, 2, 3, 4, 5, 6, 7, 8, 9]
-         nto_select: 9
-       ssid: 1
-   ```
-
-- `none` (without fault tolerance)
-
-   ```yaml
-   domains_config:
-     domain:
-     - name: Root
-       storage_pool_types:
-       - kind: ssd
-         pool_config:
-           box_id: 1
-           erasure_species: none
-           kind: ssd
-           pdisk_filter:
-           - property:
-             - type: SSD
-           vdisk_kind: Default
-     state_storage:
-     - ring:
-         node:
-         - 1
-         nto_select: 1
-       ssid: 1
-   ```
-
-- Multiple pools
-
-   ```yaml
-   domains_config:
-     domain:
-     - name: Root
-       storage_pool_types:
-       - kind: ssd
-         pool_config:
-           box_id: '1'
-           erasure_species: block-4-2
-           kind: ssd
-           pdisk_filter:
-           - property:
-             - {type: SSD}
-           vdisk_kind: Default
-       - kind: rot
-         pool_config:
-           box_id: '1'
-           erasure_species: block-4-2
-           kind: rot
-           pdisk_filter:
-           - property:
-             - {type: ROT}
-           vdisk_kind: Default
-       - kind: rotencrypted
-         pool_config:
-           box_id: '1'
-           encryption_mode: 1
-           erasure_species: block-4-2
-           kind: rotencrypted
-           pdisk_filter:
-           - property:
-             - {type: ROT}
-           vdisk_kind: Default
-       - kind: ssdencrypted
-         pool_config:
-           box_id: '1'
-           encryption_mode: 1
-           erasure_species: block-4-2
-           kind: ssdencrypted
-           pdisk_filter:
-           - property:
-             - {type: SSD}
-           vdisk_kind: Default
-     state_storage:
-     - ring:
-         node: [1, 16, 31, 46, 61, 76, 91, 106]
-         nto_select: 5
-       ssid: 1
-   ```
-
-{% endlist %}
-
 ## Actor system {#actor-system}
 
 The CPU resources are mainly used by the actor system. Depending on the type, all actors run in one of the pools (the `name` parameter). Configuring is allocating a node's CPU cores across the actor system pools. When allocating them, please keep in mind that PDisks and the gRPC API run outside the actor system and require separate resources.

ydb/docs/en/core/security/index.md

@@ -8,11 +8,11 @@ This section of {{ ydb-short-name }} documentation covers security-related aspec
 
     When a [user](../concepts/glossary.md#access-user) connects to a {{ ydb-short-name }} database, {{ ydb-short-name }} first identifies the user's account. This process is called [authentication](./authentication.md). Based on the authentication data, a user then goes through [authorization](./authorization.md) — a process that verifies whether a user has sufficient [access rights](../concepts/glossary.md#access-right) and [access levels](../concepts/glossary.md#access-level) to perform user operations.
 
-    {{ ydb-short-name }} supports both internal [users](./authorization.md#user) and external users from third-party directory services. After passing [authentication](./authentication.md), a {{ ydb-short-name }} cluster identifies users by [SIDs](./authorization.md#sid). A SID is a string that contains a username and auth domain.
+    {{ ydb-short-name }} supports both internal [users](./authorization.md#user) and external users from third-party directory services. After passing [authentication](./authentication.md), a user gets a [SID](./authorization.md#sid) that the {{ ydb-short-name }} cluster uses for user identification and access control.
 
     [Access rights](./authorization.md#right) in {{ ydb-short-name }} are tied to [access objects](../concepts/glossary.md#access-object) using [access control lists (ACL)](../concepts/glossary.md#access-control-list). The ACL format is described in [{#T}](./short-access-control-notation.md).
 
-    {{ ydb-short-name }} uses [access level lists](../concepts/glossary.md#access-level-list) to manage [access subject](../concepts/glossary.md#access-subject) privileges that are not related to [scheme objects](../concepts/glossary.md#scheme-object).
+    {{ ydb-short-name }} uses [access levels](../concepts/glossary.md#access-level) to manage [access subject](../concepts/glossary.md#access-subject) privileges that are not related to [scheme objects](../concepts/glossary.md#scheme-object). Access levels are granted to users in [access level lists](../concepts/glossary.md#access-level-list).
 
     [Built-in security](./builtin-security.md) is configured automatically by default when the {{ ydb-short-name }} cluster is started for the first time. This process adds a [superuser](./builtin-security.md#superuser) and a set of [roles](./builtin-security.md#role) for convenient user access management.
 

ydb/docs/ru/core/concepts/datamodel/index.md

@@ -1,40 +1,29 @@
-# Модель данных и схема
+# Структура кластера
 
-В разделе собраны описания сущностей, которыми оперирует {{ ydb-short-name }} в рамках БД. Ядро {{ ydb-short-name }} позволяет гибко реализовывать различные примитивы хранения, поэтому возможно появление в будущем новых сущностей.
+В разделе собраны описания сущностей, которыми оперирует {{ ydb-short-name }}.
 
 ## Схема кластера {{ ydb-short-name }} {#cluster-scheme}
 
-Схема кластера {{ ydb-short-name }} — логическая древовидная структура кластера {{ ydb-short-name }}. Корневым элементом схемы кластера {{ ydb-short-name }} является **корень схемы кластера**. Дочерними элементами корня схемы кластера являются [базы данных](../../concepts/glossary.md#database). В свою очередь базы данных содержат [схемные объекты](../../concepts/glossary.md#scheme-object), которые образуют произвольную иерархию с помощью вложенных директорий.
-
-```mermaid
-flowchart
-
-subgraph Корень схемы кластера
-    subgraph База данных 1
-        o1[Схемный объект 1]
-        o2[Схемный объект 2]
-        el1[...]
-        o3[Схемный объект N]
-    end
-    subgraph База данных 2
-        o4[Схемный объект 1]
-        o5[Схемный объект 2]
-        el2[...]
-        o6[Схемный объект N]
-    end
-    subgraph База данных N
-        o7[Схемный объект 1]
-        o8[Схемный объект 2]
-        el3[...]
-        o9[Схемный объект N]
-    end
-end
-
+Схема кластера {{ ydb-short-name }} — это иерархическое пространство имён кластера {{ ydb-short-name }}. Единственным корневым элементом этого пространства имён является **корень схемы кластера**. Корнем схемы кластера может выступать как директория, так и корневая база. Дочерними элементами корня схемы кластера выступают [базы данных](../../concepts/glossary.md#database) или другие [схемные объекты](../../concepts/glossary.md#scheme-object), которые образуют произвольную иерархию с помощью вложенных директорий.
+
+```plaintext
+Корень схемы кластера/
+├── База данных 1/
+│   ├── Таблица 1
+│   ├── Директория 1/
+│   │   ├── Таблица 2
+│   │   └── Таблица 3
+│   └── Директория 2/
+│       ├── Директория 3/
+│       │   └── ...
+│       └── ...
+└── База данных 2/
+    └── ...
 ```
 
 ## Модель данных
 
-{{ ydb-short-name }} – это реляционная база данных, в которой данные хранятся в таблицах, состоящих из рядов и колонок. Объекты баз данных {{ ydb-short-name }} могут быть организованы в иерархию директорий.
+Схемные объекты баз данных {{ ydb-short-name }}:
 
 * [Директории](dir.md)
 * [Таблицы](table.md)