diff options
| author | alextarazanov <alextarazanov@yandex-team.com> | 2022-08-10 16:12:33 +0300 |
|---|---|---|
| committer | alextarazanov <alextarazanov@yandex-team.com> | 2022-08-10 16:12:33 +0300 |
| commit | 50f75419ab107c5898ba27fb8ba565f87d7a3886 (patch) | |
| tree | 60b51e059d679755729d4d75b5a7f129dc1dda91 | |
| parent | 47782bc45c02bda33735f8d275730cb6227199f8 (diff) | |
| download | ydb-50f75419ab107c5898ba27fb8ba565f87d7a3886.tar.gz | |
[review] Check translate Add static credentials
31 files changed, 447 insertions, 328 deletions
diff --git a/ydb/docs/en/core/_assets/groups.svg b/ydb/docs/en/core/_assets/groups.svg new file mode 100644 index 0000000000..cb8c96f207 --- /dev/null +++ b/ydb/docs/en/core/_assets/groups.svg @@ -0,0 +1,3 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="421px" height="361px" viewBox="-0.5 -0.5 421 361" style="background-color: rgb(255, 255, 255);"><defs/><g><rect x="140" y="0" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 20px; margin-left: 141px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><span>ADMINS</span></div></div></div></div></foreignObject><text x="200" y="24" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">ADMINS</text></switch></g><path d="M 200 80 L 200 46.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 200 41.12 L 203.5 48.12 L 200 46.37 L 196.5 48.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="140" y="80" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 100px; margin-left: 141px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>DATABASE-ADMINS</span></div></div></div></div></div></foreignObject><text x="200" y="104" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">DATABASE-ADMINS</text></switch></g><path d="M 60 160 L 60 150 Q 60 140 70 140 L 160 140 Q 170 140 170 133.18 L 170 126.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 170 121.12 L 173.5 128.12 L 170 126.37 L 166.5 128.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="0" y="160" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 180px; margin-left: 1px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>ACCESS-ADMINS</span></div></div></div></div></div></div></foreignObject><text x="60" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">ACCESS-ADMINS</text></switch></g><path d="M 200 160 L 200 126.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 200 121.12 L 203.5 128.12 L 200 126.37 L 196.5 128.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="140" y="160" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 180px; margin-left: 141px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>DDL-ADMINS</span></div></div></div></div></div></div></div></foreignObject><text x="200" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">DDL-ADMINS</text></switch></g><path d="M 360 80 L 360 70 Q 360 60 350 60 L 210 60 Q 200 60 200 53.18 L 200 46.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 200 41.12 L 203.5 48.12 L 200 46.37 L 196.5 48.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="300" y="80" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 100px; margin-left: 301px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>DATA-WRITERS</span></div></div></div></div></div></div></div></foreignObject><text x="360" y="104" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">DATA-WRITERS</text></switch></g><path d="M 360 160 L 360 126.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 360 121.12 L 363.5 128.12 L 360 126.37 L 356.5 128.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="300" y="160" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 180px; margin-left: 301px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>DATA-READERS</span></div></div></div></div></div></div></div></foreignObject><text x="360" y="184" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">DATA-READERS</text></switch></g><path d="M 360 240 L 360 206.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 360 201.12 L 363.5 208.12 L 360 206.37 L 356.5 208.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 360 240 L 360 230 Q 360 220 350 220 L 240 220 Q 230 220 230 213.18 L 230 206.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 230 201.12 L 233.5 208.12 L 230 206.37 L 226.5 208.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="300" y="240" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 260px; margin-left: 301px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>METADATA-READERS</span></div></div></div></div></div></div></div></foreignObject><text x="360" y="264" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">METADATA-READERS</text></switch></g><path d="M 200 320 L 200 206.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 200 201.12 L 203.5 208.12 L 200 206.37 L 196.5 208.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 200 320 L 200 310 Q 200 300 210 300 L 350 300 Q 360 300 360 293.18 L 360 286.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 360 281.12 L 363.5 288.12 L 360 286.37 L 356.5 288.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><path d="M 200 320 L 200 270 Q 200 260 190 260 L 70 260 Q 60 260 60 250 L 60 206.37" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 60 201.12 L 63.5 208.12 L 60 206.37 L 56.5 208.12 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="140" y="320" width="120" height="40" rx="6" ry="6" fill="#ffffff" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 340px; margin-left: 141px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px ; white-space: pre"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><div style="font-family: "menlo" , "monaco" , "courier new" , monospace ; line-height: 18px"><span>USERS</span></div></div></div></div></div></div></div></foreignObject><text x="200" y="344" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">USERS</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file diff --git a/ydb/docs/en/core/cluster/access.md b/ydb/docs/en/core/cluster/access.md new file mode 100644 index 0000000000..f7cafcb764 --- /dev/null +++ b/ydb/docs/en/core/cluster/access.md @@ -0,0 +1,40 @@ +# Access management + +{{ ydb-short-name }} supports authentication by username and password. + +## Built-in groups {#builtin} + +A {{ ydb-short-name }} cluster has built-in groups that offer predefined sets of roles: + + Group | Description +--- | --- + `ADMINS` | Unlimited rights for the entire cluster schema. + `DATABASE-ADMINS` | Rights to create and delete databases (`CreateDatabase`, `DropDatabase`). + `ACCESS-ADMINS` | Rights to manage rights of other users (`GrantAccessRights`). + `DDL-ADMINS` | Rights to alter the database schema (`CreateDirectory`, `CreateTable`, `WriteAttributes`, `AlterSchema`, `RemoveSchema`). + `DATA-WRITERS` | Rights to change data (`UpdateRow`, `EraseRow`). + `DATA-READERS` | Rights to read data (`SelectRow`). + `METADATA-READERS` | Rights to read metadata without accessing data (`DescribeSchema` and `ReadAttributes`). + `USERS` | Rights to connect to databases (`ConnectDatabase`). + +All users are added to the `USERS` group by default. The `root` user is added to the `ADMINS` group by default. + +You can see how groups inherit permissions below. For example, the `DATA_WRITERS` group includes all the permissions from `DATA_READERS`: + + + +## Manage groups {#groups} + +To create, update, or delete a group, use the YQL operators: + +* [{#T}](../yql/reference/syntax/create-group.md). +* [{#T}](../yql/reference/syntax/alter-group.md). +* [{#T}](../yql/reference/syntax/drop-group.md). + +## Managing users {#users} + +To create, update, or delete a user, use the YQL operators: + +* [{#T}](../yql/reference/syntax/create-user.md). +* [{#T}](../yql/reference/syntax/alter-user.md). +* [{#T}](../yql/reference/syntax/drop-user.md). diff --git a/ydb/docs/en/core/cluster/toc_i.yaml b/ydb/docs/en/core/cluster/toc_i.yaml index 9ec6c11788..a8f321a6ee 100644 --- a/ydb/docs/en/core/cluster/toc_i.yaml +++ b/ydb/docs/en/core/cluster/toc_i.yaml @@ -1,6 +1,8 @@ items: - name: Deployment include: { mode: link, path: ../deploy/toc_p.yaml } +- name: Access management + href: access.md - name: Maintaining a cluster's disk subsystem include: { mode: link, path: ../maintenance/manual/toc_p.yaml } - name: Embedded UI diff --git a/ydb/docs/en/core/concepts/_includes/connect.md b/ydb/docs/en/core/concepts/_includes/connect.md deleted file mode 100644 index abeea412c9..0000000000 --- a/ydb/docs/en/core/concepts/_includes/connect.md +++ /dev/null @@ -1,106 +0,0 @@ -# Connecting to a database - -{% include [overlay/ui.md](connect_overlay/ui.md) %} - -To connect to the {{ ydb-short-name }} database from the {{ ydb-short-name }} CLI or an application using the {{ ydb-short-name }} SDK, you'll need to provide the following data: - -1. Endpoint. -1. Authentication information. -1. Database location. - -## Endpoint {#endpoint} - -An endpoint is a string structured as `protocol://host:port` and provided by a {{ ydb-short-name }} cluster owner for proper routing of client queries to its databases over the network infrastructure as well as for network connection initialization. Cloud databases display the endpoint in the management console on the required DB page and also normally provide it via the cloud CLI. In corporate environments, endpoint names {{ ydb-short-name }} are provided by the administration team or obtained in the internal cloud management console. - -{% include [overlay/endpoint.md](connect_overlay/endpoint.md) %} - -Examples: - -* `grpc://localhost:7135` is an unencrypted data transfer protocol (gRPC) with the server running on port 7135 of the same host as the client. -* `grpcs://ydb.somecorp-int.ru` is an encrypted data transfer protocol (gRPCs) with the server running on a host called ydb.somecorp-int.ru on the SomeCorp isolated corporate network and listening for connections on YDB default port 2135. -* `grpcs://ydb.serverless.yandexcloud.net:2135` is an encrypted data transfer protocol (gRPCs), public {{ yandex-cloud }} Serverless YDB server at ydb.serverless.yandexcloud.net, port 2135. - -{% include [overlay/endpoint_example.md](connect_overlay/endpoint_example.md) %} - -## Authentication information {#auth} - -Once a network connection is established, the server starts to accept client requests for processing supplied with authentication information. The server uses it to identify the client's account and to verify access to execute the query. - -The primary operation model assumes that there is a separate system for managing credentials and permissions: [IAM (Identity and Access Management)](https://en.wikipedia.org/wiki/Identity_management). IAM issues a token linked to the account, which the {{ ydb-short-name }} client passes to the server along with a request. The {{ ydb-short-name }} server accesses IAM to verify the token and permissions to perform the requested operation and caches the result. - -{{ ydb-short-name }} also supports username and password based authentication without interacting with IAM, but using this model in practice is limited to simple configurations, primarily local ones. - -### Authentication modes {#auth-modes} - -{{ ydb-short-name }} clients (CLI or SDK) support the following token selection modes to pass tokens in requests: - -* **Anonymous**: Empty token passed in a request. -* **Access Token**: Fixed token set as a parameter for the client (SDK or CLI) and passed in requests. -* **Refresh Token**: [OAuth token](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) of a user's personal account set as a parameter for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests. -* **Service Account Key**: Service account attributes and a signature key set as parameters for the client (SDK or CLI), which the client periodically sends to the IAM API in the background to rotate a token (obtain a new one) to pass in requests. -* **Metadata**: Client (SDK or CLI) periodically accesses a local service to rotate a token (obtain a new one) to pass in requests. - -Any owner of a valid token can get access to perform operations; therefore, the principal objective of the security system is to ensure that a token remains private and to protect it from being compromised. - -Authentication modes with token rotation, such as **Refresh Token** and **Service Account Key**, provide a higher level of security compared to the **Access Token** mode that uses a fixed token, since only secrets with a short validity period are transmitted to the {{ ydb-short-name }} server over the network. - -The highest level of security and performance is provided when using the **Metadata** mode, since it eliminates the need to work with secrets when deploying an application and allows accessing the IAM system and caching a token in advance, before running the application. - -When choosing the authentication mode among those supported by the server and environment, follow the recommendations below: - -* **You would normally use Anonymous** on self-deployed local {{ ydb-short-name }} clusters that are inaccessible over the network. -* **You would use Access Token** when other modes are not supported on server side or for setup/debugging purposes. It does not require that the client access IAM. However, if the IAM system supports an API for token rotation, fixed tokens issued by this IAM usually have a short validity period, which makes it necessary to update them manually in the IAM system on a regular basis. -* **Refresh Token** can be used when performing one-time manual operations under a personal account, for example, related to DB data maintenance, performing ad-hoc operations in the CLI, or running applications from a workstation. You can manually obtain this token from IAM once to have it last a long time and save it in an environment variable on a personal workstation to use automatically and with no additional authentication parameters on CLI launch. -* **Service Account Key** is mainly used for applications designed to run in environments where the **Metadata** mode is supported, when testing them outside these environments (for example, on a workstation). It can also be used for applications outside these environments, working as an analog of **Refresh Token** for service accounts. Unlike a personal account, service account access objects and roles can be restricted. -* **Metadata** is used when deploying applications in clouds. Currently, this mode is supported on virtual machines and in {{ sf-name }} {{ yandex-cloud }}. - -The token to specify in request parameters can be obtained in the IAM system that the specific {{ ydb-short-name }} deployment is associated with. In particular, {{ ydb-short-name }} in {{ yandex-cloud }} uses Yandex.Passport OAuth and {{ yandex-cloud }} service accounts. When using {{ ydb-short-name }} in a corporate context, a company's standard centralized authentication system may be used. - -{% include [overlay/auth_choose.md](connect_overlay/auth_choose.md) %} - -When using modes in which the {{ ydb-short-name }} client accesses the IAM system, the IAM URL that provides an API for issuing tokens can be set additionally. By default, existing SDKs and CLIs attempt to access the {{ yandex-cloud }} IAM API hosted at `iam.api.cloud.yandex.net:443`. - -## Database location {#database} - -Database location (`database`) is a string that defines where the queried database is located in the {{ ydb-short-name }} cluster. It has the [path to file]{% if lang == "en" %}(https://en.wikipedia.org/wiki/Path_(computing)){% endif %}{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Путь_к_файлу){% endif %} format and uses the `/` character as separator. It always starts with a `/`. - -A {{ ydb-short-name }} cluster may have multiple databases deployed, and their location is defined by the cluster configuration. Like the endpoint, `database` for cloud databases is displayed in the management console on the desired database page, and can also be obtained via the CLI of the cloud provider. - -For cloud solutions, databases are created and hosted on the {{ ydb-short-name }} cluster in self-service mode, with no need in involvement of the cluster owner or administrators. - -{% include [overlay/database.md](connect_overlay/database.md) %} - -{% note warning %} - -Applications should not in any way interpret the number and value of `database` directories, since they are set in the {{ ydb-short-name }} cluster configuration. When using {{ ydb-short-name }} in {{ yandex-cloud }}, `database` has the format `region_name/cloud_id/database_id`; however, this format may change going forward for new DBs. - -{% endnote %} - -Examples: - -* `/ru-central1/b1g8skpblkos03malf3s/etn01q5ko6sh271beftr` is a {{ yandex-cloud }} database with `etn01q3ko8sh271beftr` as ID deployed in the `b1g8skpbljhs03malf3s`cloud in the `ru-central1` region. -* `/local` is the default database for custom deployment [using Docker](../../getting_started/self_hosted/ydb_docker.md). - -{% include [overlay/database_example.md](connect_overlay/database_example.md) %} - -## Configuring connection parameters on the client {#client-config} - -For information about how to define connection parameters on the client, see the following articles: - -* [Connecting to and authenticating with a database in the {{ ydb-short-name }} CLI](../../reference/ydb-cli/connect.md). -* [Authentication in the {{ ydb-short-name }} SDK](../../reference/ydb-sdk/auth.md). - -## Additional information {#addition} - -### A root certificate for TLS {#tls-cert} - -When using an encrypted protocol ([gRPC over TLS](https://grpc.io/docs/guides/auth/), or gRPCS), a network connection can only be continued if the client is sure that it receives a response from the genuine server that it is trying to connect to, rather than someone in-the-middle intercepting its request on the network. This is assured by verifications through a [chain of trust]{% if lang == "en" %}(https://en.wikipedia.org/wiki/Chain_of_trust){% endif %}{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Цепочка_доверия){% endif %} which requires the client to have a root certificate installed to operate. - -The OS that the client runs on already include a set of root certificates from the world's major certification authorities. However, the {{ ydb-short-name }} cluster owner can use its own CA that is not associated with any of the global ones, which is often the case in corporate environments, and is almost always used for self-hosted deployment of clusters with connection encryption support. In this case, the cluster owner must somehow transfer its root certificate for use on the client side. This certificate may be installed in the operating system's certificate store where the client runs (manually by a user or by a corporate OS administration team) or built into the client itself (as is the case for {{ yandex-cloud }} in {{ ydb-short-name }} CLI and SDK). - -### API for getting IAM tokens {#token-refresh-api} - -For token rotation, the {{ ydb-short-name }} SDK and CLI use a gRPC request to the {{ yandex-cloud }} IAM API [IamToken - create]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/api-ref/grpc/iam_token_service#Create){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/api-ref/grpc/iam_token_service#Create){% endif %}. In **Refresh Token** mode, the token specified in the OAuth parameter is passed in the `yandex_passport_oauth_token` attribute. In **Service Account Key** mode, a short-lived JWT token is generated from the specified service account attributes and an encryption key and passed in the `jwt` property. The source code for generating the JWT is available as part of the SDK (for example, the `get_jwt()` method in the [Python code](https://github.com/ydb-platform/ydb-python-sdk/blob/main/ydb/iam/auth.py)). - -In the {{ ydb-short-name }} SDK and CLI, you can substitute the host used for accessing the API for obtaining tokens. This makes it possible to implement a similar API in corporate contexts. - diff --git a/ydb/docs/en/core/concepts/auth.md b/ydb/docs/en/core/concepts/auth.md new file mode 100644 index 0000000000..8e7fdad118 --- /dev/null +++ b/ydb/docs/en/core/concepts/auth.md @@ -0,0 +1,37 @@ +# Authentication + +Once a network connection is established, the server starts to accept client requests with authentication information for processing. The server uses it to identify the client's account and to verify access to execute the query. + +The following authentication modes are supported: + +* Anonymous access is enabled by default and available immediately when you [install the cluster](../deploy/index.md). +* Authentication through a third-party IAM provider, for example, [Yandex Identity and Access Management]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/){% endif %}. +* Authentication by [username and password](#static-credentions). + +{% include [overlay/auth_choose.md](_includes/connect_overlay/auth_choose.md) %} + +## Authenticating by username and password {#static-credentions} + +Authentication by username and password includes the following steps: + +1. The client accesses the database and presents their username and password to the {{ ydb-short-name }} authentication service. + + You can only use lower case Latin letters and digits in usernames. No restrictions apply to passwords (empty passwords can be used). +1. The authentication service passes authentication data to the {{ ydb-short-name }} authentication component. +1. The component validates authentication data. If the data matches, it generates a token and returns it to the authentication service. + + Tokens accelerate authentication and strengthen security. Tokens have a default lifetime of 12 hours. YDB SDK rotates tokens by accessing the authentication service. + + The username and hashed password are stored in the table inside the authentication component. The password is hashed by the [Argon2]{% if lang == "en" %}(https://en.wikipedia.org/wiki/Argon2){% endif %}{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Argon2){% endif %} method. In authentication mode, only the system administrator can use a username/password pair to access the table. +1. The authentication system returns the token to the client. +1. The client accesses the database, presenting their token as authentication data. + +To enable username/password authentication, use `true` in the `enforce_user_token_requirement` key of the cluster's [configuration file](../deploy/configuration/config.md#auth). + +To learn how to manage roles and users, see [{#T}](../cluster/access.md). + +<!-- ### API получения токенов IAM {#token-refresh-api} + +Для ротации токенов {{ ydb-short-name }} SDK и CLI используют gRPC-запрос к {{ yandex-cloud }} IAM API [IamToken - create]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/api-ref/grpc/iam_token_service#Create){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/api-ref/grpc/iam_token_service#Create){% endif %}. В режиме **Refresh Token** заданный параметром OAuth токен передается в атрибуте `yandex_passport_oauth_token`. В режиме **Service Account Key** на основании заданных атрибутов сервисной учетной записи и ключа шифрования формируется короткоживущий JWT-токен и передается в атрибуте `jwt`. Исходный код формирования JWT-токена доступен в составе SDK (например, метод `get_jwt()` в [коде на Python](https://github.com/ydb-platform/ydb-python-sdk/blob/main/ydb/iam/auth.py)). + +{{ ydb-short-name }} SDK и CLI позволяют подменить хост для обращения к API получения токенов, что дает возможность реализовать аналогичный API в корпоративных контекстах. --> diff --git a/ydb/docs/en/core/concepts/connect.md b/ydb/docs/en/core/concepts/connect.md index c0cae8a17b..6998161ae3 100644 --- a/ydb/docs/en/core/concepts/connect.md +++ b/ydb/docs/en/core/concepts/connect.md @@ -1,2 +1,42 @@ +# Connecting to a database -{% include [connect.md](_includes/connect.md) %} +To connect to a {{ ydb-short-name }} database from the {{ ydb-short-name }} CLI or an app running the {{ ydb-short-name }} SDK, specify your [endpoint](#endpoint) and [database path](#database). + +## Endpoint {#endpoint} + +An endpoint is a string structured as `protocol://host:port` and provided by a {{ ydb-short-name }} cluster owner for proper routing of client queries to its databases by way of a network infrastructure as well as for proper network connections. Cloud databases display the endpoint in the management console on the requisite DB page and also normally send it via the cloud provider's CLI. In corporate environments, endpoint names {{ ydb-short-name }} are provided by the administration team or obtained in the internal cloud management console. + +{% include [overlay/endpoint.md](_includes/connect_overlay/endpoint.md) %} + +Examples: + +* `grpc://localhost:7135` is an unencrypted data interchange protocol (gRPC) with the server running on port 7135 of the same host as the client. +* `grpcs://ydb.example.com` is an encrypted data interchange protocol (gRPCs) with the server running on the ydb.example.com host on an isolated corporate network and listening for connections on YDB default port 2135. +* `grpcs://ydb.serverless.yandexcloud.net:2135` is an encrypted data interchange protocol (gRPCs), public {{ yandex-cloud }} Serverless YDB server at ydb.serverless.yandexcloud.net, port 2135. + +## Database path {#database} + +Database path (`database`) is a string that defines where the queried database is located in the {{ ydb-short-name }} cluster. Has the [format]{% if lang == "en" %} (https://en.wikipedia.org/wiki/Path_(computing)){% endif %}{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Путь_к_файлу){% endif %} and uses the `/` character as separator. It always starts with a `/`. + +A {{ ydb-short-name }} cluster may have multiple databases deployed, with their paths determined by the cluster configuration. Like the endpoint, `database` for cloud databases is displayed in the management console on the desired database page, and can also be obtained via the CLI of the cloud provider. + +For cloud solutions, databases are created and hosted on the {{ ydb-short-name }} cluster in self-service mode, with no need in attendance of the cluster owner or administrators. + +{% include [overlay/database.md](_includes/connect_overlay/database.md) %} + +{% note warning %} + +Applications should not in any way interpret the number and value of `database` directories, since they are set in the {{ ydb-short-name }} cluster configuration. When using {{ ydb-short-name }} in {{ yandex-cloud }}, `database` has the format `region_name/cloud_id/database_id`; however, this format may change going forward for new DBs. + +{% endnote %} + +Examples: + +* `/ru-central1/b1g8skpblkos03malf3s/etn01q5ko6sh271beftr` is a {{ yandex-cloud }} database with `etn01q3ko8sh271beftr` as ID deployed in the `b1g8skpbljhs03malf3s` cloud in the `ru-central1` region. +* `/local` is the default database for custom deployment [using Docker](../getting_started/self_hosted/ydb_docker.md). + +## A root certificate for TLS {#tls-cert} + +When using an encrypted protocol ([gRPC over TLS](https://grpc.io/docs/guides/auth/), or gRPCS), a network connection can only be continued if the client is sure that it receives a response from the genuine server that it is trying to connect to, rather than someone in-between intercepting its request on the network. This is assured by verifications through a [chain of trust]{% if lang == "en" %}(https://en.wikipedia.org/wiki/Chain_of_trust){% endif %}{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Цепочка_доверия){% endif %}, for which you need to install a root certificate on your client. + +The OS that the client runs on already include a set of root certificates from the world's major certification authorities. However, the {{ ydb-short-name }} cluster owner can use its own CA that is not associated with any of the global ones, which is often the case in corporate environments, and is almost always used for self-deployment of clusters with connection encryption support. In this case, the cluster owner must somehow transfer its root certificate for use on the client side. This certificate may be installed in the operating system's certificate store where the client runs (manually by a user or by a corporate OS administration team) or built into the client itself (as is the case for {{ yandex-cloud }} in {{ ydb-short-name }} CLI and SDK). diff --git a/ydb/docs/en/core/concepts/toc_i.yaml b/ydb/docs/en/core/concepts/toc_i.yaml index fa3795c630..130c3394bd 100644 --- a/ydb/docs/en/core/concepts/toc_i.yaml +++ b/ydb/docs/en/core/concepts/toc_i.yaml @@ -1,15 +1,17 @@ items: - { name: Overview, href: index.md } -- { name: Terms and definitions, href: databases.md } -- { name: Connecting to and authenticating with a database, href: connect.md } -- { name: Data model and schema, href: datamodel.md } -- { name: Serverless and Dedicated operation modes, href: serverless_and_dedicated.md } -- { name: Data types, href: datatypes.md, hidden: true } # Deprecated -- { name: Transactions, href: transactions.md } -- { name: Secondary indexes, href: secondary_indexes.md } -- { name: Time to Live (TTL), href: ttl.md } -- { name: Scan queries, href: scan_query.md } -- { name: Database limits, href: limits-ydb.md } +- { name: Terms and definitions, href: databases.md } +- { name: Connecting to a database, href: connect.md } +- name: Authentication + href: auth.md +- { name: Data model and schema, href: datamodel.md } +- { name: Serverless and Dedicated operation modes, href: serverless_and_dedicated.md } +- { name: Data types, href: datatypes.md, hidden: true } # Deprecated +- { name: Transactions, href: transactions.md } +- { name: Secondary indexes, href: secondary_indexes.md } +- { name: Time to Live (TTL), href: ttl.md } +- { name: Scan queries, href: scan_query.md } +- { name: Database limits, href: limits-ydb.md } - name: YDB cluster items: - name: Overview @@ -17,4 +19,4 @@ items: - name: General YDB schema href: cluster/common_scheme_ydb.md - name: Disk subsystem of a cluster - href: cluster/distributed_storage.md
\ No newline at end of file + href: cluster/distributed_storage.md diff --git a/ydb/docs/en/core/deploy/configuration/config.md b/ydb/docs/en/core/deploy/configuration/config.md index fe2cf3e913..74fffbe172 100644 --- a/ydb/docs/en/core/deploy/configuration/config.md +++ b/ydb/docs/en/core/deploy/configuration/config.md @@ -6,7 +6,7 @@ This article describes the main groups of configurable parameters in this file. ## host_configs: Typical host configurations {#host-configs} -A YDB cluster consists of multiple nodes, and one or more typical server configurations are usually used for their deployment. To avoid repeating its description for each node, there is a `host_configs` section in the configuration file that lists the used configurations and assigned IDs. +A YDB cluster consists of multiple nodes, and one or more typical server configurations are usually used for their deployment. To avoid repeating its description for each node, there is a `host_configs` section in the configuration file that lists the used configurations and the assigned IDs. **Syntax** @@ -28,7 +28,7 @@ The `host_config_id` attribute specifies a numeric configuration ID. The `drive` **Examples** -One configuration with ID 1 and one SSD disk accessible via `/dev/disk/by-partlabel/ydb_disk_ssd_01`: +One configuration with ID 1, one SSD disk accessible via `/dev/disk/by-partlabel/ydb_disk_ssd_01`: ``` yaml host_configs: @@ -60,7 +60,7 @@ host_configs: ### Kubernetes features {#host-configs-k8s} -The YDB Kubernetes operator mounts NBS disks for Storage nodes at the path `/dev/kikimr_ssd_00`. To use them, the following `host_configs` configuration must be specified: +YDB Kubernetes operator mounts NBS disks for Storage nodes on the path `/dev/kikimr_ssd_00`. To use them, the following `host_configs` configuration must be specified: ``` yaml host_configs: @@ -70,7 +70,7 @@ host_configs: type: SSD ``` -The example configuration files provided with the YDB Kubernetes operator contain this section, and it does not need to be changed. +The configuration example files supplied as part of YDB Kubernetes operator contain such a section, and it does not need to be changed. ## hosts: Static cluster nodes {#hosts} @@ -78,16 +78,16 @@ This group lists the static cluster nodes on which the Storage processes run and - Numeric node ID - DNS host name and port that can be used to connect to a node on the IP network -- ID of the [standard host configuration](#host-configs) +- ID of the [typical host configuration](#host-configs) - Placement in a specific availability zone, rack -- Server inventory number (optional) +- Server serial number (optional) **Syntax** ``` yaml hosts: - host: <DNS host name> - host_config_id: <numeric ID of the standard host configuration> + host_config_id: <numeric ID of the typical host configuration> port: <port> # 19001 by default location: unit: <string with the server serial number> @@ -125,7 +125,7 @@ When deploying YDB with a Kubernetes operator, the entire `hosts` section is gen ## domains_config: Cluster domain {#domains-config} -This section contains the configuration of the YDB cluster root domain, including Blob Storage (binary object storage) and State Storage configurations. +This section contains the configuration of the YDB cluster root domain, including the [Blob Storage](#domains-blob) (binary object storage), [State Storage](#domains-state), and [authentication](#auth) configurations. **Syntax** @@ -135,6 +135,7 @@ domains_config: - name: <root domain name> storage_pool_types: <Blob Storage configuration> state_storage: <State Storage configuration> + security_config: <authentication configuration> ``` ### Blob Storage configuration {#domains-blob} @@ -150,10 +151,10 @@ The following [fault tolerance modes](../../cluster/topology.md) are available: | Mode | Description | --- | --- -| `none` | There is no redundancy. Applies for testing. | -| `block-4-2` | Redundancy factor of 1.5, applies to single data center clusters. | -| `mirror-3-dc` | Redundancy factor of 3, applies to multi-data center clusters. | -| `mirror-3dc-3-nodes` | Redundancy factor of 3. Applies for testing. | +| `none` | There is no redundancy. Applied for testing. | +| `block-4-2` | Redundancy with a factor of 1.5, applies to single data center clusters. | +| `mirror-3-dc` | Redundancy with a factor of 3, applies to multi data center clusters. | +| `mirror-3dc-3-nodes` | Redundancy with a factor of 3. Applied for testing. | **Syntax** @@ -162,7 +163,7 @@ The following [fault tolerance modes](../../cluster/topology.md) are available: - kind: <storage pool name> pool_config: box_id: 1 - encryption: <optional, specify 1 to encrypt data on the disk> + encryption: <optional, specify 1 to encrypt data on the disc> erasure_species: <fault tolerance mode name - none, block-4-2, or mirror-3-dc> kind: <storage pool name - specify the same value as above> pdisk_filter: @@ -177,11 +178,11 @@ Each database in the cluster is assigned at least one of the available storage p ### State Storage configuration {#domains-state} -State Storage is an independent in-memory storage for variable data that supports internal YDB processes. It stores data replicas on multiple assigned nodes. +State Storage is an independent in-memory storage for modifiable data that supports internal YDB processes. It stores data replicas on multiple assigned nodes. State Storage usually does not need scaling for better performance, so the number of nodes in it must be kept as small as possible taking into account the required level of fault tolerance. -State Storage availability is key for a YDB cluster because it affects all databases, regardless of which storage pools they use. To ensure fault tolerance of State Storage, its nodes must be selected to guarantee a working majority in case of expected failures. +State Storage availability is key for a YDB cluster because it affects all databases, regardless of which storage pools they use. To ensure fault tolerance of State Storage, its nodes must be selected in such a way as to guarantee a working majority in case of expected failures. The following guidelines can be used to select State Storage nodes: @@ -194,7 +195,6 @@ The following guidelines can be used to select State Storage nodes: When deploying State Storage on clusters that use multiple storage pools with a possible combination of fault tolerance modes, consider increasing the number of nodes and spreading them across different storage pools because unavailability of State Storage results in unavailability of the entire cluster. **Syntax** - ``` yaml state_storage: - ring: @@ -205,7 +205,25 @@ state_storage: Each State Storage client (for example, DataShard tablet) uses `nto_select` nodes to write copies of its data to State Storage. If State Storage consists of more than `nto_select` nodes, different nodes can be used for different clients, so you must ensure that any subset of `nto_select` nodes within State Storage meets the fault tolerance criteria. -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. +Odd numbers must be used for `nto_select` because using even numbers does not improve fault tolerance in comparison with the nearest smaller odd number. + +### Authentication configuration {#auth} + +The [authentication mode](../../concepts/auth.md) in the {{ ydb-short-name }} cluster is created in the `domains_config.security_config` section. + +Syntax: + +``` yaml +domains_config: + ... + security_config: + enforce_user_token_requirement: Bool + ... +``` + + Key | Description +--- | --- + `enforce_user_token_requirement` | Require a user token.</br>Acceptable values:</br><ul><li>`false`: Anonymous authentication mode, no token needed.</li><li>`true`: Username/password authentication mode. A valid user token is needed for authentication.</li></ul> ### Examples {#domains-examples} diff --git a/ydb/docs/en/core/getting_started/_includes/auth.md b/ydb/docs/en/core/getting_started/_includes/auth.md index 4dba70099c..3794c6f377 100644 --- a/ydb/docs/en/core/getting_started/_includes/auth.md +++ b/ydb/docs/en/core/getting_started/_includes/auth.md @@ -1,10 +1,9 @@ # Authentication - Getting started -A local YDB database with self-deployment does not require authentication, that is, runs in [anonymous mode](../../concepts/connect.md#auth-modes). +A local YDB database with self-deployment does not require authentication, that is, runs in [anonymous mode](../../concepts/auth.md). -Full information about all available authentication methods is given in the [DB connection](../../concepts/connect.md) article under "Concepts". +To learn every detail about available authentication methods, see [DB connection](../../concepts/connect.md) under Concepts. ## Learn more about YDB {#next} Go to [YDB CLI: Getting started](../cli.md) to learn more about YDB. - diff --git a/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_docker/01_intro.md b/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_docker/01_intro.md index b9628e3b6f..d414ea529e 100644 --- a/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_docker/01_intro.md +++ b/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_docker/01_intro.md @@ -9,14 +9,15 @@ As a result of completing the instructions below, you'll get a local YDB databas {% list tabs %} - gRPC - - [Endpoint](../../../../concepts/connect.md#endpoint): `grpc://localhost:2136` - - [Database location](../../../../concepts/connect.md#database): `/local` - - [Authentication](../../../../concepts/connect.md#auth-modes): Anonymous (without authentication) + + - [Endpoint](../../../../concepts/connect.md#endpoint): `grpc://localhost:2136` + - [Database path](../../../../concepts/connect.md#database): `/local` + - [Authentication](../../../../concepts/auth.md): Anonymous (no authentication) - gRPCs/TLS - - [Endpoint](../../../../concepts/connect.md#endpoint): `grpcs://localhost:2135` - - [Database location](../../../../concepts/connect.md#database): `/local` - - [Authentication](../../../../concepts/connect.md#auth-modes): Anonymous (without authentication) -{% endlist %} + - [Endpoint](../../../../concepts/connect.md#endpoint): `grpcs://localhost:2135` + - [Database path](../../../../concepts/connect.md#database): `/local` + - [Authentication](../../../../concepts/auth.md): Anonymous (no authentication) +{% endlist %} diff --git a/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_local.md b/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_local.md index 51674c68ab..efcb6a574f 100644 --- a/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_local.md +++ b/ydb/docs/en/core/getting_started/self_hosted/_includes/ydb_local.md @@ -8,7 +8,7 @@ As a result of completing the steps described below, you'll get a YDB database r - [Endpoint](../../../concepts/connect.md#endpoint): `grpc://localhost:2136` - [DB path](../../../concepts/connect.md#database): `/Root/test` -- [Authentication](../../../concepts/connect.md#auth-modes): Anonymous (no authentication) +- [Authentication](../../../concepts/auth.md): Anonymous (no authentication) ## Installation {#install} @@ -28,9 +28,7 @@ You can start a local YDB server with a disk or in-memory storage: - Disk storage - - {% include [_includes/storage-device-requirements.md](../../../_includes/storage-device-requirements.md) %} - - - During the first run of the script, an 80 GB file named `ydb.data` is created in the working directory. Make sure you have enough free space to create it. + - To store data on a disk, when you run the script for the first time, a 64GB `ydb.data` file is created in the working directory. Make sure there's enough disk space to create it. - Run the following command from the working directory: diff --git a/ydb/docs/en/core/reference/ydb-cli/_includes/connect.md b/ydb/docs/en/core/reference/ydb-cli/_includes/connect.md index 456fb2d56f..602b92b621 100644 --- a/ydb/docs/en/core/reference/ydb-cli/_includes/connect.md +++ b/ydb/docs/en/core/reference/ydb-cli/_includes/connect.md @@ -2,18 +2,18 @@ Most of the {{ ydb-short-name }} CLI commands relate to operations on a {{ ydb-short-name }} database and require establishing a connection to it to be executed. -The {{ ydb-short-name }} CLI determines what DB to connect to and what [authentication mode](../../../concepts/connect.md#auth-modes) to use based on information from the following sources (in order of priority): +The {{ ydb-short-name }} CLI uses the following sources to determine the database to connect to and the [authentication mode](../../../concepts/auth.md) to use with it (listed in descending priority): 1. The command line. 2. The profile set in the `--profile` command-line option. 3. Environment variables. 4. The activated profile. -For the {{ ydb-short-name }} CLI to try connecting to the DB after you completed these steps, make sure to specify the [Endpoint](../../../concepts/connect.md#endpoint) and [Database location](../../../concepts/connect.md#database). +For the {{ ydb-short-name }} CLI to try connecting to the database, these steps must result in the [endpoint](../../../concepts/connect.md#endpoint) and [database path](../../../concepts/connect.md#database). If all the steps are completed, but the {{ ydb-short-name }} CLI did not determine the authentication mode, requests will be sent to the {{ ydb-short-name }} server without adding authentication data. This may let you successfully work with locally deployed {{ ydb-short-name }} clusters that require no authentication. For all databases available over the network, such requests will be rejected by the server with an authentication error returned. -For possible situations when the {{ ydb-short-name }} CLI will not try to connect to a database, see the [Error messages](#errors) section below. +To learn about potential situations where the {{ ydb-short-name }} CLI won't try to connect to the database, see the [Error messages](#errors) below. ## Command line parameters {#command-line-pars} @@ -23,8 +23,8 @@ DB connection options in the command line are specified before defining the comm {{ ydb-cli }} <connection_options> <command> <command_options> ``` -- `-e, --endpoint <endpoint>` : [Endpoint](../../../concepts/connect.md#endpoint): The main connection parameter that allows finding the {{ ydb-short-name }} server on the network. If no port is specified, port 2135 is used. If no protocol is specified, gRPCs (with encryption) is used in {{ ydb-short-name }} CLI public builds. -- `-d, --database <database>` : [DB location](../../../concepts/connect.md#database). +- `-e, --endpoint <endpoint>` is the [endpoint](../../../concepts/connect.md#endpoint), that is, the main connection parameter that allows finding a {{ ydb-short-name }} server on the network. If no port is specified, port 2135 is used. If no protocol is specified, gRPCs (with encryption) is used in {{ ydb-short-name }} CLI public builds. +- `-d, --database <database>` is the [database path](../../../concepts/connect.md#database). {% include [auth/options.md](auth/options.md) %} @@ -32,7 +32,7 @@ DB connection options in the command line are specified before defining the comm If a certain connection parameter is not specified in the command line when calling the {{ ydb-short-name }} CLI, it tries to determine it by the [profile](../profile/index.md) set in the `--profile` command-line option. -The profile may define most variables similar to the options from the [Command line parameters](#command-line-pars) section. Their values are processed in the same way as command line parameters. +In the profile, you can define most of the variables that have counterparts in the [Command line parameters](#command-line-pars) section. Their values are processed in the same way as command line parameters. ## Parameters from environment variables {#env} @@ -48,23 +48,22 @@ If some connection parameter could not be determined in the previous steps, and ### Errors before attempting to establish a DB connection -If all the steps described in the beginning of this article are completed, but the [Endpoint](../../../concepts/connect.md#endpoint) is not determined, the command is aborted and an error message saying `Missing required option 'endpoint'` is returned. +If the CLI completed all the steps listed at the beginning of this article but failed to determine the [endpoint](../../../concepts/connect.md#endpoint), the command terminates with the error `Missing required option 'endpoint'`. -If all the steps described in the beginning of this article are completed, but the [DB location](../../../concepts/connect.md#database) is not identified, the command is aborted and an error message saying `Missing required option 'database'` is returned. +If the CLI completed all the steps listed at the beginning of this article but failed to determine the [database path](../../../concepts/connect.md#database), the command terminates with the error message `Missing required option 'database'`. If the authentication mode is known, but the necessary additional parameters are not, the command is aborted and an error message describing the issue is returned: -- `(No such file or directory) util/system/file.cpp:857: can't open "<filepath>" with mode RdOnly|Seq (0x00000028)`: Couldn't open and read the `<filepath>` file specified in one of the parameters with the file name and path. +- `(No such file or directory) util/system/file.cpp:857: can't open "<filepath>" with mode RdOnly|Seq (0x00000028)`: Couldn't open and read the file `<filepath>` specified in a parameter passing the file name and path. ## Additional parameters {#additional} -When using gRPCs (with encryption), you may need to [select a root certificate](../../../concepts/connect.md#tls-cert): +When using gRPCs (with encryption), you may need to [select a root certificate](../../../concepts/connect.md#tls-cert). -- `--ca-file <filepath>` : Root certificate PEM file for a TLS connection. +- `--ca-file <filepath>`: Root certificate PEM file for a TLS connection. Currently, root certificates are not stored in profiles and can only be defined by command line options. -## Verifying authentication {#whoami} +## Authentication {#whoami} The {{ ydb-short-name }} CLI [`discovery whoami`](../commands/discovery-whoami.md) auxiliary command lets you check the account that you actually used to authenticate with the server. - diff --git a/ydb/docs/en/core/reference/ydb-cli/profile/_includes/create.md b/ydb/docs/en/core/reference/ydb-cli/profile/_includes/create.md index c2af9f0446..bb17c67e05 100644 --- a/ydb/docs/en/core/reference/ydb-cli/profile/_includes/create.md +++ b/ydb/docs/en/core/reference/ydb-cli/profile/_includes/create.md @@ -14,13 +14,14 @@ or where `[profile_name]` is an optional name of the profile being created or updated. + The first step of the interactive scenario is different in the `init` and `profile create` commands: {% list tabs %} - Init - Outputs a list of existing profiles (if any) and prompts you to make a choice: Create a new or update the configuration of an existing profile: + Prints a list of existing profiles (if any) and prompts you to make a choice: Create a new or update the configuration of an existing profile: ```text Please choose profile to configure: @@ -32,7 +33,7 @@ The first step of the interactive scenario is different in the `init` and `profi If no profiles exist or you select option `1` in the previous step, the name of a profile to create is requested: ```text - Please enter name for a new profile: + Please enter name for a new profile: ``` If you enter the name of an existing profile at this point, the {{ ydb-short-name }} CLI proceeds to updating its parameters as if an option with the name of this profile was selected at once. @@ -40,7 +41,6 @@ The first step of the interactive scenario is different in the `init` and `profi - Profile Create If no profile name is specified in the command line, it is requested: - ```text Please enter configuration profile name to create or re-configure: ``` @@ -50,7 +50,7 @@ The first step of the interactive scenario is different in the `init` and `profi Next, you'll be prompted to sequentially perform the following actions with each connection parameter that can be saved in the profile: - Don't save -- Set a new value or Use - Set a new value or Use <value> +- Set a new value or Use <value> - Use current value (this option is available when updating an existing profile) ## Example @@ -59,53 +59,52 @@ Creating a new `mydb1` profile: 1. Run the command: - ```bash - {{ ydb-cli }} config profile create mydb1 - ``` + ```bash + {{ ydb-cli }} config profile create mydb1 + ``` -1. Specify the [endpoint](../../../../concepts/connect.md#endpoint) or don't save this parameter for the profile: +1. Enter the [endpoint](../../../../concepts/connect.md#endpoint) or don't save this parameter for the profile: - ```text - Pick desired action to configure endpoint: - [1] Set a new endpoint value - [2] Don't save endpoint for profile "mydb1" - Please enter your numeric choice: - ``` + ```text + Pick desired action to configure endpoint: + [1] Set a new endpoint value + [2] Don't save endpoint for profile "mydb1" + Please enter your numeric choice: + ``` -1. Enter the [DB name](../../../../concepts/connect.md#database) or don't save this parameter for the profile: +1. Enter the [database name](../../../../concepts/connect.md#database) or don't save this parameter for the profile: - ```text - Pick desired action to configure database: - [1] Set a new database value - [2] Don't save database for profile "mydb1" - Please enter your numeric choice: - ``` + ```text + Pick desired action to configure database: + [1] Set a new database value + [2] Don't save database for profile "mydb1" + Please enter your numeric choice: + ``` 1. Select the authentication mode or don't save this parameter for the profile: - ```text - Pick desired action to configure authentication method: - [1] Use IAM token (iam-token) cloud.yandex.com/docs/iam/concepts/authorization/iam-token - [2] Use OAuth token of a Yandex Passport user (yc-token) cloud.yandex.com/docs/iam/concepts/authorization/oauth-token - [3] Use metadata service on a virtual machine (use-metadata-credentials) cloud.yandex.com/docs/compute/operations/vm-connect/auth-inside-vm - [4] Use security account key file (sa-key-file) cloud.yandex.com/docs/iam/operations/iam-token/create-for-sa - [5] Don't save authentication data for profile "mydb1" - Please enter your numeric choice: - ``` + ```text + Pick desired action to configure authentication method: + [1] Use IAM token (iam-token) cloud.yandex.com/docs/iam/concepts/authorization/iam-token + [2] Use OAuth token of a Yandex Passport user (yc-token) cloud.yandex.com/docs/iam/concepts/authorization/oauth-token + [3] Use metadata service on a virtual machine (use-metadata-credentials) cloud.yandex.com/docs/compute/operations/vm-connect/auth-inside-vm + [4] Use security account key file (sa-key-file) cloud.yandex.com/docs/iam/operations/iam-token/create-for-sa + [5] Don't save authentication data for profile "mydb1" + Please enter your numeric choice: + ``` - If you are not sure what authentication mode to choose, see the [Authentication](../../../../getting_started/auth.md) article in the "Getting started" section. + If you are not sure what authentication mode to choose, use the recipe from [Authentication](../../../../getting_started/auth.md) under "Getting started". - All available authentication methods are described in [Connecting to and authenticating with a database](../../../../concepts/connect.md#auth-modes). The set of methods and text of the hints may differ from those given in this example. + All the available authentication methods are described in [{#T}](../../../../concepts/auth.md). The set of methods and text of the hints may differ from those given in this example. - If the method you choose involves specifying an additional parameter, you'll be prompted to enter it. For example, if you select `4` (Use service account key file): + If the method you choose involves specifying an additional parameter, you'll be prompted to enter it. For example, if you select `4` (Use service account key file): - ```text - Please enter Path to service account key file (sa-key-file): - ``` + ```text + Please enter Path to service account key file (sa-key-file): + ``` 1. In the last step, you'll be prompted to activate the created profile to be used by default. Choose 'n' (No) until you read the article about [Activating a profile and using the activated profile](../activate.md): - ```text - Activate profile "mydb1" to use by default? (current active profile is not set) y/n: n - ``` - + ```text + Activate profile "mydb1" to use by default? (current active profile is not set) y/n: n + ``` diff --git a/ydb/docs/en/core/reference/ydb-sdk/_includes/auth.md b/ydb/docs/en/core/reference/ydb-sdk/_includes/auth.md index afc91516dd..5e7ad96640 100644 --- a/ydb/docs/en/core/reference/ydb-sdk/_includes/auth.md +++ b/ydb/docs/en/core/reference/ydb-sdk/_includes/auth.md @@ -1,72 +1,72 @@ # Authentication in the SDK -As described in the article on [connecting to the {{ ydb-short-name }} server](../../../concepts/connect.md), with each request, the client should send an [authentication token](../../../concepts/connect.md#auth). The server verifies the authentication token and, if the authentication is successful, the request is authorized and executed, otherwise the `Unauthenticated` error is returned. +As we discussed in the [{{ ydb-short-name }} server connection](../../../concepts/connect.md) article, the client must add an [authentication token](../../../concepts/auth.md) to each request. The authentication token is checked by the server. If the authentication is successful, the request is authorized and executed. Otherwise, the `Unauthenticated` error returns. -The {{ ydb-short-name }} SDK uses an object that is responsible for generating these tokens. The SDK provides built-in methods for obtaining this object: +The {{ ydb-short-name }} SDK uses an object that is responsible for generating these tokens. SDK provides built-in methods for getting such an object: -1. Methods with parameters passed explicitly, each of the methods implements a certain [authentication mode](../../../concepts/connect.md#auth-modes). -2. A method that determines the authentication mode and the necessary parameters from environment variables. +1. The methods that pass parameters explicitly, with each method implementing a certain [authentication mode](../../../concepts/auth.md). +2. The method that determines the authentication mode and relevant parameters based on environmental variables. Usually, you create a token generation object before you initialize the {{ ydb-short-name }} driver, and you pass the object to the driver constructor as a parameter. The C++ and Go SDKs additionally let you work with multiple databases and token generation objects through a single driver. -If a token generation object is not defined, the driver won't add any authentication information to requests. This may let you successfully connect to locally deployed {{ ydb-short-name }} clusters with no mandatory authentication configured. If it is configured, DB requests without an authentication token will be rejected with an authentication error returned. +If the token generation object is not defined, the driver won't add any authentication data to the requests. This approach enables you to successfully connect to locally deployed {{ ydb-short-name }} clusters without enabling mandatory authentication. If you enable mandatory authentication, database requests without an authentication token will be rejected with an authentication error. ## Methods for creating token generation objects {#auth-provider} -You can click on any of the methods described below to go to the source code of the relevant example in the repository. You can also learn about the [authentication code recipes](../recipes/auth/index.md). +You can click any of the methods below to go to the source code of an example in the repository. You can also learn about the [authentication code recipes](../recipes/auth/index.md). {% list tabs %} - Python - | [Mode](../../../concepts/connect.md#auth-modes) | Method | - | ----- | ----- | - | Anonymous | [`ydb.AnonymousCredentials()`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/anonymous-credentials) | - | Access Token | [`ydb.AccessTokenCredentials( token )`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/access-token-credentials) | - | Metadata | [`ydb.iam.MetadataUrlCredentials()`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/metadata-credentials) | - | Service Account Key | [`ydb.iam.ServiceAccountCredentials.from_file(`</br> `key_file, iam_endpoint=None, iam_channel_credentials=None )`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/service-account-credentials) | - | Determined by environment variables | `ydb.construct_credentials_from_environ()` | + Mode | Method + ----- | ----- + Anonymous | [ydb.AnonymousCredentials()](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/anonymous-credentials) + Access Token | [ydb.AccessTokenCredentials( token )](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/access-token-credentials) + Metadata | [ydb.iam.MetadataUrlCredentials()](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/metadata-credentials) + Service Account Key | [ydb.iam.ServiceAccountCredentials.from_file(</br>key_file, iam_endpoint=None, iam_channel_credentials=None )](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/service-account-credentials) + Determined by environment variables | `ydb.construct_credentials_from_environ()` - Go - | [Mode](../../../concepts/connect.md#auth-modes) | Package | Method | - | ----- | ----- | ---- | - | Anonymous | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [`ydb.WithAnonymousCredentials()`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/anonymous_credentials) | - | Access Token | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [`ydb.WithAccessTokenCredentials( token )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/access_token_credentials) | - | Metadata | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [`yc.WithMetadataCredentials( ctx )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/metadata_credentials) | - | Service Account Key | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [`yc.WithServiceAccountKeyFileCredentials( key_file )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/service_account_credentials) | - | Determined by environment variables | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/go.mod) | [`environ.WithEnvironCredentials(ctx)`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/environ) | + Mode | Package | Method + ----- | ----- | ---- + Anonymous | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [ydb.WithAnonymousCredentials()](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/anonymous_credentials) + Access Token | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [ydb.WithAccessTokenCredentials( token )](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/access_token_credentials) + Metadata | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [yc.WithMetadataCredentials( ctx )](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/metadata_credentials) + Service Account Key | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [yc.WithServiceAccountKeyFileCredentials( key_file )](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/service_account_credentials) + Determined by environment variables | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/go.mod) | [environ.WithEnvironCredentials(ctx)](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/environ) - Java - | [Mode](../../../concepts/connect.md#auth-modes) | Method | - | ----- | ----- | - | Anonymous | [`com.yandex.ydb.core.auth.NopAuthProvider.INSTANCE`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/anonymous_credentials) | - | Access Token | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.IamTokenCredentialProvider`</br> `.builder()`</br> `.token(accessToken)`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/access_token_credentials) | - | Metadata | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.ComputeEngineCredentialProvider`</br> `.builder()`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/metadata_credentials) | - | Service Account Key | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.ApiKeyCredentialProvider`</br> `.builder()`</br> `.fromFile(Paths.get(saKeyFile))`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/service_account_credentials) | - | Determined by environment variables | [`com.yandex.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/environ/src/main/java/com/yandex/ydb/example) | + Mode | Method + ----- | ----- + Anonymous | [com.yandex.ydb.core.auth.NopAuthProvider.INSTANCE](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/anonymous_credentials) + Access Token | [com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(</br>yandex.cloud.sdk.auth.provider.IamTokenCredentialProvider</br>.builder()</br>.token(accessToken)</br>.build()</br>);](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/access_token_credentials) + Metadata | [com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(</br>yandex.cloud.sdk.auth.provider.ComputeEngineCredentialProvider</br>.builder()</br>.build()</br>);](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/metadata_credentials) + Service Account Key | [com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(</br>yandex.cloud.sdk.auth.provider.ApiKeyCredentialProvider</br>.builder()</br>.fromFile(Paths.get(saKeyFile))</br>.build()</br>);](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/service_account_credentials) + Determined by environment variables | [com.yandex.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/environ/src/main/java/com/yandex/ydb/example) - Node.js - | [Mode](../../../concepts/connect.md#auth-modes) | Method | - | ----- | ----- | - | Anonymous | [`new 'ydb-sdk'.AnonymousAuthService()`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/anonymous-credentials) | - | Access Token | [`new 'ydb-sdk'.TokenAuthService( accessToken, database )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/access-token-credentials) | - | Metadata | [`new 'ydb-sdk'.MetadataAuthService( database )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/metadata-credentials) | - | Service Account Key | [`new 'ydb-sdk'.getSACredentialsFromJson( saKeyFile )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/service-account-credentials) | - | Determined by environment variables | [`new 'ydb-sdk'.getCredentialsFromEnv( entryPoint, database, logger )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/environ) | + Mode | Method + ----- | ----- + Anonymous | [new 'ydb-sdk'.AnonymousAuthService()](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/anonymous-credentials) + Access Token | [new 'ydb-sdk'.TokenAuthService( accessToken, database )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/access-token-credentials) + Metadata | [new 'ydb-sdk'.MetadataAuthService( database )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/metadata-credentials) + Service Account Key | [new 'ydb-sdk'.getSACredentialsFromJson( saKeyFile )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/service-account-credentials) + Determined by environment variables | [new 'ydb-sdk'.getCredentialsFromEnv( entryPoint, database, logger )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/environ) - Rust - [Mode](../../../concepts/connect.md#auth-modes) | Method - ----- | ----- - Anonymous | ydb::StaticToken("") - Access Token | ydb::StaticToken(token) - Metadata | ydb::GCEMetadata, ydb::YandexMetadata - Service Account Key | не поддерживается - Determined by environment variables | не поддерживается - Execute external command | ydb.CommandLineYcToken (for example: ```ydb::CommandLineYcToken.from_cmd("yc iam create-token")```) + Mode | Method + ----- | ----- + Anonymous | ydb::StaticToken("") + Access Token | ydb::StaticToken(token) + Metadata | ydb::GCEMetadata, ydb::YandexMetadata + Service Account Key | not supported + Determined by environment variables | not supported + Execution of an external command | ydb.CommandLineYcToken (for example, to authenticate using an {{ yandex-cloud }} [IAM token]{% if lang == "ru"%}(https://cloud.yandex.ru/docs/iam/concepts/authorization/iam-token){% endif %}{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/concepts/authorization/iam-token){% endif %} from the developer's desktop ```ydb::CommandLineYcToken.from_cmd("yc iam create-token")```) {% endlist %} @@ -80,7 +80,7 @@ The following algorithm that is the same for all SDKs applies: 4. Otherwise, if the value of the `YDB_ACCESS_TOKEN_CREDENTIALS` environment variable is set, the **Access token** authentication mode is used, where the this variable value is passed. 5. Otherwise, the **Metadata** authentication mode is used. -If the last step of the algorithm is selecting the **Metadata** mode, you can deploy a working application on VMs and in Cloud Functions in {{ yandex-cloud }} without setting any environment variables. +If the last step of the algorithm is selecting the **Metadata** mode, you can deploy a working application on VMs and in {{ yandex-cloud }} Cloud Functions without setting any environment variables. ## Python SDK specifics @@ -95,5 +95,4 @@ The behavior of the Python SDK differs from the one described above. - Otherwise, if the value of the `YDB_TOKEN` environment variable is set, the **Access Token** authentication mode is used, where this variable value is passed. - Otherwise, if the value of the `SA_KEY_FILE` environment variable is set, the **System Account Key** authentication mode is used and the key is taken from the file whose name is specified in this variable. - Or else, no authentication information is added to requests. -2. If no object responsible for generating tokens is passed when initializing the driver, the [general procedure](#env) for reading environment variable values applies. - +2. If no object responsible for generating tokens is passed when initializing the driver, the [general procedure](#env) for reading environment variables applies. diff --git a/ydb/docs/en/core/reference/ydb-sdk/example/go/_includes/run_custom.md b/ydb/docs/en/core/reference/ydb-sdk/example/go/_includes/run_custom.md index 5e52124e69..96e0982f2d 100644 --- a/ydb/docs/en/core/reference/ydb-sdk/example/go/_includes/run_custom.md +++ b/ydb/docs/en/core/reference/ydb-sdk/example/go/_includes/run_custom.md @@ -1,6 +1,6 @@ -To run the example using any available YDB database, you need to know the [Endpoint](../../../../../concepts/connect.md#endpoint) and [Database location](../../../../../concepts/connect.md#database). +To run the example against any available YDB database, you need to know the [endpoint](../../../../../concepts/connect.md#endpoint) and the [database path](../../../../../concepts/connect.md#database). -If authentication is enabled in the database, you also need to choose the [authentication mode](../../../../../concepts/connect.md#auth-modes) and obtain secrets: a token or username/password. +If authentication is enabled in the database, you also need to select the [authentication mode](../../../../../concepts/auth.md) and get secrets (a token or username/password pair). Run the command as follows: @@ -9,11 +9,11 @@ Run the command as follows: go run ./basic -ydb="<endpoint>?database=<database>" ) ``` -, where +where -- `<endpoint>` is the [Endpoint](../../../../../concepts/connect.md#endpoint) -- `<database>` is the [DB location](../../../../../concepts/connect.md#database). -- `<auth_mode_var>` is the [Environment variable](../../../auth.md#env) that determines the authentication mode. +- `<endpoint>`: The [endpoint](../../../../../concepts/connect.md#endpoint). +- `<database>`: The [database path](../../../../../concepts/connect.md#database). +- `<auth_mode_var>`: The [environment variable](../../../auth.md#env) that determines the authentication mode. - `<auth_mode_value>` is the authentication parameter value for the selected mode. For example: @@ -23,5 +23,4 @@ For example: go run ./basic -ydb="grpcs://ydb.example.com:2135?database=/somepath/somelocation" ) ``` -{% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %} - +{% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %}
\ No newline at end of file diff --git a/ydb/docs/en/core/reference/ydb-sdk/example/java/_includes/run_custom.md b/ydb/docs/en/core/reference/ydb-sdk/example/java/_includes/run_custom.md index 6476fb9086..73a1abe153 100644 --- a/ydb/docs/en/core/reference/ydb-sdk/example/java/_includes/run_custom.md +++ b/ydb/docs/en/core/reference/ydb-sdk/example/java/_includes/run_custom.md @@ -1,6 +1,6 @@ -To run the example using any available YDB database, you need to know the [Endpoint](../../../../../concepts/connect.md#endpoint) and [Database location](../../../../../concepts/connect.md#database). +To run the example against any available YDB database, you need to know the [endpoint](../../../../../concepts/connect.md#endpoint) and the [database path](../../../../../concepts/connect.md#database). -If authentication is enabled in the database, you also need to choose the [authentication mode](../../../../../concepts/connect.md#auth-modes) and obtain secrets: a token or username/password. +If authentication is enabled in the database, you also need to select the [authentication mode](../../../../../concepts/auth.md) and get secrets (a token or username/password pair). Run the command as follows: @@ -11,9 +11,9 @@ Run the command as follows: where -- `<endpoint>` is the [Endpoint](../../../../../concepts/connect.md#endpoint) -- `<database>` is the [DB location](../../../../../concepts/connect.md#database). -- `<auth_mode_var`> is the [Environment variable](../../../auth.md#env) that determines the authentication mode. +- `<endpoint>`: The [endpoint](../../../../../concepts/connect.md#endpoint). +- `<database>`: The [database path](../../../../../concepts/connect.md#database). +- `<auth_mode_var>`: The [environment variable](../../../auth.md#env) that determines the authentication mode. - `<auth_mode_value>` is the authentication parameter value for the selected mode. For example: @@ -22,5 +22,4 @@ For example: YDB_ACCESS_TOKEN_CREDENTIALS="t1.9euelZqOnJuJlc..." java -jar examples/basic_example/target/ydb-basic-example.jar grpcs://ydb.example.com:2135?database=/somepath/somelocation ``` -{% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %} - +{% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %}
\ No newline at end of file diff --git a/ydb/docs/en/core/reference/ydb-sdk/example/java/index.md b/ydb/docs/en/core/reference/ydb-sdk/example/java/index.md index e935ebbd2b..922e8e2b05 100644 --- a/ydb/docs/en/core/reference/ydb-sdk/example/java/index.md +++ b/ydb/docs/en/core/reference/ydb-sdk/example/java/index.md @@ -2,9 +2,9 @@ This page contains a detailed description of the code of a [test app](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/basic_example) that is available as part of the {{ ydb-short-name }} [Java SDK](https://github.com/yandex-cloud/ydb-java-sdk). -## Downloading SDK Examples and running an example {#download} +## Downloading SDK Examples and running the example {#download} -The startup script below uses [Git](https://git-scm.com/downloads) and [Maven](https://maven.apache.org/download.html). +The following execution scenario is based on [Git](https://git-scm.com/downloads) and [Maven](https://maven.apache.org/download.html). Create a working directory and use it to run from the command line the command to clone the GitHub repository: @@ -12,7 +12,7 @@ Create a working directory and use it to run from the command line the command t git clone https://github.com/yandex-cloud/ydb-java-sdk ``` -Next, build the SDK Examples +Then build the SDK Examples ```bash ( cd ydb-java-sdk/examples && mvn package ) @@ -22,13 +22,13 @@ Next, from the same working directory, run the command to start the test app. Th {% include [run_options.md](_includes/run_options.md) %} -{% include [init.md](../_includes/steps/01_init.md) %} -Basic driver initialization parameters: +{% include [init.md](../_includes/steps/01_init.md) %} -* A connection string with information about the [endpoint](../../../../concepts/connect.md#endpoint) and [database](../../../../concepts/connect.md#database). The only required parameter. -* An [authentication provider](../../auth.md#auth-provider). If there is no direct indication, an [anonymous connection](../../../../concepts/connect.md#auth-modes) is used. -* [Session pool](../../recipes/session_pool_limit/index.md) settings. +Main driver initialization parameters +* A connection string containing details about an [endpoint](../../../../concepts/connect.md#endpoint) and [database](../../../../concepts/connect.md#database). This is the only parameter that is required. +* [Authentication](../../auth.md##auth-provider) provider. Unless explicitly specified, an [anonymous connection](../../../../concepts/auth.md) is used. +* [Session pool](../../recipes/session_pool_limit/index.md) settings App code snippet for driver initialization: @@ -40,7 +40,7 @@ GrpcTableRpc rpc = GrpcTableRpc.ownTransport(transport); this.tableClient = TableClient.newClient(rpc).build(); ``` -We recommend performing all YDB operations using the `SessionRetryContext` helper class that ensures a correct operation retry in the event of partial unavailability. Code snippet for initializing the retry context: +We recommend that you use the `SessionRetryContext` helper class for all your operations with the YDB: it ensures proper retries in case the database becomes partially unavailable. Sample code to initialize the retry context: ```java this.retryCtx = SessionRetryContext.create(tableClient).build(); @@ -89,7 +89,7 @@ private void createTables() { } ``` -You can use the `Session.DescribeTable()` method to output information about the table structure and make sure that it was properly created: +You can use the `Session.DescribeTable()` method to view information about the table structure and make sure that it was properly created: ```java private void describeTables() { @@ -109,10 +109,9 @@ private void describeTables() { }); } ``` - {% include [../steps/03_write_queries.md](../_includes/steps/03_write_queries.md) %} -Code snippet for inserting and updating data: +Code snippet for data insert/update: ```java private void upsertSimple() { @@ -162,7 +161,7 @@ private void selectSimple() { } ``` -As a result of executing the query, an object of the `DataQueryResult` class is generated. It may contain several sets obtained using the `getResultSet( <index> )` method. Since there was only one `SELECT` statement in the query, the result contains only one selection indexed as `0`. The given code snippet outputs the following text to the console at startup: +As a result of the query, an object of the `DataQueryResult` class is generated. It may contain several sets obtained using the `getResultSet( <index> )` method. Since there was only one `SELECT` statement in the query, the result contains only one selection indexed as `0`. The given code snippet prints the following text to the console at startup: ```bash 12:06:36.548 INFO App - --[ SelectSimple ]-- @@ -243,10 +242,9 @@ private void scanQueryWithParams(long seriesID, long seasonID) { {% include [multistep_transactions.md](../_includes/steps/09_multistep_transactions.md) %} -To ensure that the retry context works properly while executing transactions, perform each transaction entirely inside the callback passed to `SessionRetryContext`. The callback should return a response after the transaction is fully completed. - -Code template for using complex transactions in `SessionRetryContext` +To ensure interoperability between the transactions and the retry context, each transaction must wholly execute inside the callback passed to `SessionRetryContext`. The callback must return after the entire transaction is completed. +Code template for running complex transactions inside `SessionRetryContext` ```java private void multiStepTransaction(long seriesID, long seasonID) { retryCtx.supplyStatus(session -> { @@ -257,6 +255,7 @@ private void multiStepTransaction(long seriesID, long seasonID) { return CompletableFuture.completedFuture(Status.SUCCESS); }).join().expect("multistep transaction problem"); } + ``` The first step is to prepare and execute the first query: @@ -278,7 +277,7 @@ The first step is to prepare and execute the first query: )).join().expect("execute data query problem"); ``` -Next, we can perform some client processing of the data received: +After that, we can process the resulting data on the client side: ```java // Perform some client logic on returned values @@ -290,7 +289,7 @@ Next, we can perform some client processing of the data received: LocalDate toDate = fromDate.plusDays(15); ``` -And get the current `transaction id` for further work within a single transaction: +And get the current `transaction id` to continue processing within the same transaction: ```java // Get active transaction id @@ -367,3 +366,4 @@ private void tclTransaction() { } ``` + diff --git a/ydb/docs/en/core/reference/ydb-sdk/example/python/_includes/run_custom.md b/ydb/docs/en/core/reference/ydb-sdk/example/python/_includes/run_custom.md index f83c0bbda4..db3f073ac7 100644 --- a/ydb/docs/en/core/reference/ydb-sdk/example/python/_includes/run_custom.md +++ b/ydb/docs/en/core/reference/ydb-sdk/example/python/_includes/run_custom.md @@ -1,6 +1,6 @@ -To run the example using any available YDB database, you need to know the [Endpoint](../../../../../concepts/connect.md#endpoint) and [Database location](../../../../../concepts/connect.md#database). +To run the example against any available YDB database, you need to know the [endpoint](../../../../../concepts/connect.md#endpoint) and the [database path](../../../../../concepts/connect.md#database). -If authentication is enabled in the database, you also need to choose the [authentication mode](../../../../../concepts/connect.md#auth-modes) and obtain secrets: a token or username/password. +If authentication is enabled in the database, you also need to select the [authentication mode](../../../../../concepts/auth.md) and get secrets (a token or username/password pair). Run the command as follows: @@ -9,19 +9,17 @@ Run the command as follows: python3 ydb-python-sdk/examples/basic_example_v1/ -e <endpoint> -d <database> ``` -, where +where -- `<endpoint>` is the [Endpoint](../../../../../concepts/connect.md#endpoint) -- `<database>` is the [DB location](../../../../../concepts/connect.md#database). -- `<auth_mode_var>` is the [Environment variable](../../../auth.md#env) that determines the authentication mode. +- `<endpoint>`: The [endpoint](../../../../../concepts/connect.md#endpoint). +- `<database>`: The [database path](../../../../../concepts/connect.md#database). +- `<auth_mode_var>`: The [environment variable](../../../auth.md#env) that determines the authentication mode. - `<auth_mode_value>` is the authentication parameter value for the selected mode. For example: - ```bash YDB_ACCESS_TOKEN_CREDENTIALS="t1.9euelZqOnJuJlc..." \ python3 ydb-python-sdk/examples/basic_example_v1/ -e grpcs://ydb.example.com:2135 -d /path/db ) ``` {% include [../../_includes/pars_from_profile_hint.md](../../_includes/pars_from_profile_hint.md) %} - diff --git a/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/_includes/static.md b/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/_includes/static.md deleted file mode 100644 index 5d9a6a938d..0000000000 --- a/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/_includes/static.md +++ /dev/null @@ -1,10 +0,0 @@ -# Username and password based authentication - -{% include [work in progress message](../../_includes/addition.md) %} - -Below are examples of the code for authentication based on a username and token in different {{ ydb-short-name }} SDKs. - -{% list tabs %} - -{% endlist %} - diff --git a/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/static.md b/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/static.md index 6ee75b9186..66ac13d267 100644 --- a/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/static.md +++ b/ydb/docs/en/core/reference/ydb-sdk/recipes/auth/static.md @@ -1,2 +1,23 @@ +# Username and password based authentication -{% include [index.md](_includes/static.md) %} +{% include [work in progress message](../_includes/addition.md) %} + +Below are examples of the code for authentication based on a username and token in different {{ ydb-short-name }} SDKs. + +{% list tabs %} + +- C++ + + ```c++ + auto driverConfig = NYdb::TDriverConfig() + .SetEndpoint(endpoint) + .SetDatabase(database) + .SetCredentialsProviderFactory(NYdb::CreateLoginCredentialsProviderFactory({ + .User = "user", + .Password = "password", + })); + + NYdb::TDriver driver(driverConfig); + ``` + +{% endlist %} diff --git a/ydb/docs/en/core/toc_i.yaml b/ydb/docs/en/core/toc_i.yaml index 1b7b87de71..1c799bef84 100644 --- a/ydb/docs/en/core/toc_i.yaml +++ b/ydb/docs/en/core/toc_i.yaml @@ -16,7 +16,6 @@ items: - { name: Managing databases, include: { mode: link, path: db/toc_p.yaml } } - { name: Managing a cluster, include: { mode: link, path: cluster/toc_p.yaml } } - # References - { name: YQL, include: { mode: link, path: yql/toc_p.yaml } } - { name: Working with the YDB CLI, include: { mode: link, path: reference/ydb-cli/toc_p.yaml } } diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/alter-group.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/alter-group.md new file mode 100644 index 0000000000..1efdd71251 --- /dev/null +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/alter-group.md @@ -0,0 +1,13 @@ +# ALTER GROUP + +Adds/removes the group to/from a specific user. You can list multiple users under one operator. + +Syntax: + +```yql +ALTER GROUP role_name ADD USER user_name [, ... ] +ALTER GROUP role_name DROP USER user_name [, ... ] +``` + +* `role_name`: The name of the group. +* `user_name`: The name of the user. diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/alter-user.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/alter-user.md new file mode 100644 index 0000000000..2854518c3b --- /dev/null +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/alter-user.md @@ -0,0 +1,14 @@ +# ALTER USER + +Changes the user password. + +Syntax: + +```yql +ALTER USER user_name [ WITH ] option [ ... ] +``` + +* `user_name`: The name of the user. +* `option`: The password of the user: + * `PASSWORD 'password'` creates a user with the `password` password. The `ENCRYPTED` option is always enabled. + * `PASSWORD NULL` creates a user with an empty password. diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/create-group.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/create-group.md new file mode 100644 index 0000000000..b0b833e28c --- /dev/null +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/create-group.md @@ -0,0 +1,11 @@ +# CREATE GROUP + +Creates a group with the specified name. + +Syntax: + +```yql +CREATE GROUP group_name +``` + +* `group_name`: The name of the group. It may contain lowercase Latin letters and digits. diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/create-user.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/create-user.md new file mode 100644 index 0000000000..46bcc77744 --- /dev/null +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/create-user.md @@ -0,0 +1,14 @@ +# CREATE USER + +Creates a user with the specified name and password. + +Syntax: + +```yql +CREATE USER user_name [option] +``` + +* `user_name`: The name of the user. It may contain lowercase Latin letters and digits. +* `option`: The password of the user: + * `PASSWORD 'password'` creates a user with the `password` password. The `ENCRYPTED` option is always enabled. + * `PASSWORD NULL` creates a user with an empty password. diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/drop-group.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/drop-group.md new file mode 100644 index 0000000000..60abe72d75 --- /dev/null +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/drop-group.md @@ -0,0 +1,12 @@ +# DROP GROUP + +Deletes the specified group. You can list multiple groups under one operator. + +Syntax: + +```yql +DROP GROUP [ IF EXISTS ] group_name [, ...] +``` + +* `IF EXISTS`: Suppress an error if the group doesn't exist. +* `group_name`: The name of the group to be deleted. diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/drop-user.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/drop-user.md new file mode 100644 index 0000000000..3cb410a500 --- /dev/null +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/drop-user.md @@ -0,0 +1,12 @@ +# DROP USER + +Deletes the specified user. You can list multiple users under one operator. + +Syntax: + +```yql +DROP USER [ IF EXISTS ] user_name [, ...] +``` + +* `IF EXISTS`: Suppress an error if the user doesn't exist. +* `user_name`: The name of the user to be deleted. diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/toc_i.yaml b/ydb/docs/en/core/yql/reference/yql-core/syntax/toc_i.yaml index db6c5392e8..11b7c388de 100644 --- a/ydb/docs/en/core/yql/reference/yql-core/syntax/toc_i.yaml +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/toc_i.yaml @@ -1,16 +1,22 @@ items: -- { name: Overview, href: index.md } -- { name: Lexical structure, href: lexer.md } -- { name: Expressions, href: expressions.md } +- { name: Overview, href: index.md } +- { name: Lexical structure, href: lexer.md } +- { name: Expressions, href: expressions.md } - { name: ACTION, href: action.md } +- { name: ALTER GROUP, href: alter-group.md } - { name: ALTER TABLE, href: alter_table.md, when: feature_map_tables } +- { name: ALTER USER, href: alter-user.md } +- { name: CREATE GROUP, href: create-group.md } - { name: CREATE TABLE, href: create_table.md } +- { name: CREATE USER, href: create-user.md } - { name: DECLARE, href: declare.md } - { name: DELETE, href: delete.md, when: feature_map_tables } - { name: DISCARD, href: discard.md } +- { name: DROP GROUP, href: drop-group.md } - { name: DROP TABLE, href: drop_table.md } +- { name: DROP USER, href: drop-user.md } - { name: GROUP BY, href: group_by.md } -- { name: EXPORT and IMPORT, href: export_import.md, when: feature_mapreduce } +- { name: EXPORT and IMPORT, href: export_import.md, when: feature_mapreduce } - { name: FLATTEN, href: flatten.md } - { name: INSERT, href: insert_into.md } - { name: INTO RESULT, href: into_result.md } @@ -28,4 +34,4 @@ items: - { name: USE, href: use.md, when: feature_mapreduce } - { name: VALUES, href: values.md } - { name: WINDOW, href: window.md, when: feature_window_functions } -- { name: Unsupported statements, href: not_yet_supported.md } +- { name: Unsupported statements, href: not_yet_supported.md } diff --git a/ydb/docs/ru/core/concepts/auth.md b/ydb/docs/ru/core/concepts/auth.md index 6f8b229d5a..80a567c2c0 100644 --- a/ydb/docs/ru/core/concepts/auth.md +++ b/ydb/docs/ru/core/concepts/auth.md @@ -5,7 +5,7 @@ Поддерживаются следующие режимы аутентификации: * Анонимный доступ — включен по умолчанию и доступен сразу после [установки кластера](../deploy/index.md). -* Аутентификация с использованием стороннего IAM-провайдера, например [Yandex Identity and Access Management](https://cloud.yandex.ru/docs/iam/). +* Аутентификация с использованием стороннего IAM-провайдера, например [Yandex Identity and Access Management]{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/){% endif %}{% if lang == "ru" %}(https://cloud.yandex.ru/docs/iam/){% endif %}. * Аутентификация по [логину и паролю](#static-credentions). {% include [overlay/auth_choose.md](_includes/connect_overlay/auth_choose.md) %} @@ -22,7 +22,7 @@ Использование токена ускоряет процесс аутентификации и повышает безопасность. Время жизни токена по умолчанию 12 часов. Для ротации токенов YDB SDK самостоятельно обращается к сервису аутентификации. - Имя пользователя и хеш пароля хранятся в таблице внутри компонента аутентификации. Пароль хеширован методом [Argon2](https://ru.wikipedia.org/wiki/Argon2). В режиме аутентификации по логину и паролю доступ к таблице имеет только администратор системы. + Имя пользователя и хеш пароля хранятся в таблице внутри компонента аутентификации. Пароль хеширован методом [Argon2]{% if lang == "en" %}(https://en.wikipedia.org/wiki/Argon2){% endif %}{% if lang == "ru" %}(https://ru.wikipedia.org/wiki/Argon2){% endif %}. В режиме аутентификации по логину и паролю доступ к таблице имеет только администратор системы. 1. Сервис аутентификации возвращает токен клиенту. 1. Клиент обращается к БД, передавая в качестве аутентификационной информации токен. diff --git a/ydb/docs/ru/core/concepts/toc_i.yaml b/ydb/docs/ru/core/concepts/toc_i.yaml index 320adb2c0e..8142ff4fc6 100644 --- a/ydb/docs/ru/core/concepts/toc_i.yaml +++ b/ydb/docs/ru/core/concepts/toc_i.yaml @@ -4,7 +4,7 @@ items: - { name: Соединение с БД, href: connect.md } - name: Аутентификация href: auth.md -- name: Модель данных и схема +- name: Модель данных и схема include: { path: datamodel/toc_p.yaml, mode: link } - { name: Режимы работы Serverless и Dedicated, href: serverless_and_dedicated.md } - { name: Типы данных, href: datatypes.md, hidden: true } # Deprecated diff --git a/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md b/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md index 2feccf7436..bc23475b00 100644 --- a/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md +++ b/ydb/docs/ru/core/reference/ydb-sdk/_includes/auth.md @@ -21,41 +21,41 @@ Режим | Метод ----- | ----- - Anonymous | [`ydb.AnonymousCredentials()`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/anonymous-credentials) - Access Token | [`ydb.AccessTokenCredentials( token )`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/access-token-credentials) - Metadata | [`ydb.iam.MetadataUrlCredentials()`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/metadata-credentials) - Service Account Key | [`ydb.iam.ServiceAccountCredentials.from_file(`</br> `key_file, iam_endpoint=None, iam_channel_credentials=None )`](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/service-account-credentials) + Anonymous | [ydb.AnonymousCredentials()](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/anonymous-credentials) + Access Token | [ydb.AccessTokenCredentials( token )](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/access-token-credentials) + Metadata | [ydb.iam.MetadataUrlCredentials()](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/metadata-credentials) + Service Account Key | [ydb.iam.ServiceAccountCredentials.from_file(</br>key_file, iam_endpoint=None, iam_channel_credentials=None )](https://github.com/yandex-cloud/ydb-python-sdk/tree/master/examples/service-account-credentials) Определяется по переменным окружения | `ydb.construct_credentials_from_environ()` - Go Режим | Пакет | Метод ----- | ----- | ---- - Anonymous | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [`ydb.WithAnonymousCredentials()`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/anonymous_credentials) - Access Token | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [`ydb.WithAccessTokenCredentials( token )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/access_token_credentials) - Metadata | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [`yc.WithMetadataCredentials( ctx )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/metadata_credentials) - Service Account Key | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [`yc.WithServiceAccountKeyFileCredentials( key_file )`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/service_account_credentials) - Определяется по переменным окружения | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/go.mod) | [`environ.WithEnvironCredentials(ctx)`](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/environ) + Anonymous | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [ydb.WithAnonymousCredentials()](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/anonymous_credentials) + Access Token | [ydb-go-sdk/v3](https://github.com/ydb-platform/ydb-go-sdk/blob/master/go.mod) | [ydb.WithAccessTokenCredentials( token )](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/access_token_credentials) + Metadata | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [yc.WithMetadataCredentials( ctx )](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/metadata_credentials) + Service Account Key | [ydb-go-yc](https://github.com/ydb-platform/ydb-go-yc/blob/master/go.mod) | [yc.WithServiceAccountKeyFileCredentials( key_file )](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/service_account_credentials) + Определяется по переменным окружения | [ydb-go-sdk-auth-environ](https://github.com/ydb-platform/ydb-go-sdk-auth-environ/blob/master/go.mod) | [environ.WithEnvironCredentials(ctx)](https://github.com/ydb-platform/ydb-go-examples/tree/master/cmd/auth/environ) - Java Режим | Метод ----- | ----- - Anonymous | [`com.yandex.ydb.core.auth.NopAuthProvider.INSTANCE`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/anonymous_credentials) - Access Token | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.IamTokenCredentialProvider`</br> `.builder()`</br> `.token(accessToken)`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/access_token_credentials) - Metadata | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.ComputeEngineCredentialProvider`</br> `.builder()`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/metadata_credentials) - Service Account Key | [`com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(`</br> `yandex.cloud.sdk.auth.provider.ApiKeyCredentialProvider`</br> `.builder()`</br> `.fromFile(Paths.get(saKeyFile))`</br> `.build()`</br>`);`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/service_account_credentials) - Определяется по переменным окружения | [`com.yandex.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();`](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/environ/src/main/java/com/yandex/ydb/example) + Anonymous | [com.yandex.ydb.core.auth.NopAuthProvider.INSTANCE](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/anonymous_credentials) + Access Token | [com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(</br>yandex.cloud.sdk.auth.provider.IamTokenCredentialProvider</br>.builder()</br>.token(accessToken)</br>.build()</br>);](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/access_token_credentials) + Metadata | [com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(</br>yandex.cloud.sdk.auth.provider.ComputeEngineCredentialProvider</br>.builder()</br>.build()</br>);](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/metadata_credentials) + Service Account Key | [com.yandex.ydb.auth.iam.CloudAuthProvider.newAuthProvider(</br>yandex.cloud.sdk.auth.provider.ApiKeyCredentialProvider</br>.builder()</br>.fromFile(Paths.get(saKeyFile))</br>.build()</br>);](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/service_account_credentials) + Определяется по переменным окружения | [com.yandex.ydb.auth.iam.CloudAuthHelper.getAuthProviderFromEnviron();](https://github.com/yandex-cloud/ydb-java-sdk/tree/master/examples/auth/environ/src/main/java/com/yandex/ydb/example) - Node.js Режим | Метод ----- | ----- - Anonymous | [`new 'ydb-sdk'.AnonymousAuthService()`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/anonymous-credentials) - Access Token | [`new 'ydb-sdk'.TokenAuthService( accessToken, database )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/access-token-credentials) - Metadata | [`new 'ydb-sdk'.MetadataAuthService( database )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/metadata-credentials) - Service Account Key | [`new 'ydb-sdk'.getSACredentialsFromJson( saKeyFile )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/service-account-credentials) - Определяется по переменным окружения | [`new 'ydb-sdk'.getCredentialsFromEnv( entryPoint, database, logger )`](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/environ) + Anonymous | [new 'ydb-sdk'.AnonymousAuthService()](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/anonymous-credentials) + Access Token | [new 'ydb-sdk'.TokenAuthService( accessToken, database )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/access-token-credentials) + Metadata | [new 'ydb-sdk'.MetadataAuthService( database )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/metadata-credentials) + Service Account Key | [new 'ydb-sdk'.getSACredentialsFromJson( saKeyFile )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/service-account-credentials) + Определяется по переменным окружения | [new 'ydb-sdk'.getCredentialsFromEnv( entryPoint, database, logger )](https://github.com/ydb-platform/ydb-nodejs-sdk/tree/main/examples/auth/environ) - Rust @@ -66,7 +66,7 @@ Metadata | ydb::GCEMetadata, ydb::YandexMetadata Service Account Key | не поддерживается Определяется по переменным окружения | не поддерживается - Выполнение внешней команды | ydb.CommandLineYcToken (например, для авторизации с помощью [IAM-токена](https://cloud.yandex.ru/docs/iam/concepts/authorization/iam-token) {{ yandex-cloud }} с компьютера разработчика ```ydb::CommandLineYcToken.from_cmd("yc iam create-token")```) + Выполнение внешней команды | ydb.CommandLineYcToken (например, для авторизации с помощью [IAM-токена]{% if lang == "ru"%}(https://cloud.yandex.ru/docs/iam/concepts/authorization/iam-token){% endif %}{% if lang == "en" %}(https://cloud.yandex.com/en/docs/iam/concepts/authorization/iam-token){% endif %} {{ yandex-cloud }} с компьютера разработчика ```ydb::CommandLineYcToken.from_cmd("yc iam create-token")```) {% endlist %} |
