Add docs for YDB Federated Query + Connector deployment (#1895)

Co-authored-by: Ivan Blinkov <[email protected]>
Co-authored-by: uzhastik <[email protected]>

12 files changed, 374 insertions, 11 deletions

diff --git a/ydb/docs/ru/core/concepts/datamodel/external_data_source.md b/ydb/docs/ru/core/concepts/datamodel/external_data_source.md
index 69c036ac4e0..62d8fd1526a 100644
--- a/ydb/docs/ru/core/concepts/datamodel/external_data_source.md
+++ b/ydb/docs/ru/core/concepts/datamodel/external_data_source.md
@@ -2,7 +2,7 @@
 
 {% note warning %}
 
-Данная функциональность находится в режиме "Preview".
+Данная функциональность находится в режиме "Experimental".
 
 {% endnote %}
 
diff --git a/ydb/docs/ru/core/concepts/federated_query/_assets/architecture.png b/ydb/docs/ru/core/concepts/federated_query/_assets/architecture.png
new file mode 100644
index 00000000000..6a835c26803
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/federated_query/_assets/architecture.png
diff --git a/ydb/docs/ru/core/concepts/federated_query/architecture.md b/ydb/docs/ru/core/concepts/federated_query/architecture.md
new file mode 100644
index 00000000000..3df1f6ea599
--- /dev/null
+++ b/ydb/docs/ru/core/concepts/federated_query/architecture.md
@@ -0,0 +1,36 @@
+# Aрхитектура системы обработки федеративных запросов
+
+## Внешние источники данных и внешние таблицы
+
+Ключевым элементом системы обработки федеративных запросов {{ ydb-full-name }} является понятие [внешнего источника данных](../datamodel/external_data_source.md) (external data source). В качестве таких источников могут выступать реляционные СУБД, объектные хранилища и другие системы хранения данных. При обработке федеративного запроса {{ ydb-short-name }} потоково вычитывает данные из внешних систем и позволяет выполнять над ними точно такой же спектр операций, что и для локальных данных.
+
+Для того, чтобы работать с данными, размещёнными во внешних системах, {{ ydb-short-name }} должна располагать информацией о внутренней структуре этих данных (например, о количестве, названиях и типах столбцов в таблицах). Некоторые источники предоставляют подобную метаинформацию о данных вместе с самими данными, тогда как для работы с другими, несхематизированными источниками требуется задание этой метаинформации извне. Последней цели служат [внешние таблицы](../datamodel/external_table.md) (external tables).
+
+Зарегистрировав в {{ ydb-short-name }} внешние источники данных и (в случае необходимости) внешние таблицы, клиент может приступать к описанию федеративных запросов.
+
+## Коннекторы {#connectors}
+
+В ходе выполнения федеративных запросов {{ ydb-short-name }} необходимо обращаться по сети к сторонним системам хранения данных, для чего приходится использовать их клиентские библиотеки. Появление таких зависимостей негативно сказывается на объёме кодовой базы, времени компиляции и размере бинарных файлов {{ ydb-short-name }}, а также на стабильности всего продукта в целом. 
+
+Перечень поддерживаемых источников данных для федеративных запросов постоянно расширяется. 
+Наиболее популярные источники, такие как [S3](s3), поддерживаются {{ ydb-short-name }} нативно. Однако не всем пользователям требуется поддержка одновременно всех источников. Её можно включить опционально с помощью  _коннекторов_ - специальных микросервисов, реализующих унифицированный интерфейс доступа к внешним источникам данных.
+
+В функции коннекторов входят:
+
+* Трансляция YQL-запросов в запросы на языке, специфичном для внешнего источника (например, в запросы на другом диалекте SQL или в обращения к HTTP API).
+* Организация сетевых соединений с источниками данных.
+* Конвертация данных, извлечённых из внешних источников, в колоночное представление в формате [Arrow IPC Stream](https://arrow.apache.org/docs/format/Columnar.html#serialization-and-interprocess-communication-ipc), поддерживаемом {{ ydb-short-name }}.
+
+![Архитектура YDB Federated Query](_assets/architecture.png "Архитектура YDB Federated Query" =640x)
+
+Таким образом, благодаря коннекторам формируется слой абстракции, скрывающий от {{ ydb-short-name }} специфику внешних источников данных. Лаконичность интерфейса коннектора позволяет легко расширять перечень поддерживаемых источников, внося минимальные изменения в код {{ ydb-short-name }}.
+
+Пользователи могут развернуть [один из готовых коннекторов](../../deploy/manual/connector.md) или написать свою реализацию на любом языке программирования по [gRPC спецификации](https://github.com/ydb-platform/ydb/tree/main/ydb/library/yql/providers/generic/connector/api).
+
+## Перечень поддерживаемых внешних источников данных {#supported-datasources}
+
+| Источник | Поддержка |
+| -------- | --------- |
+| [S3](https://aws.amazon.com/ru/s3/) | Встроенная в `ydbd` |
+| [ClickHouse](https://clickhouse.com/) | Через коннектор [fq-connector-go](../../deploy/manual/connector.md#fq-connector-go) |
+| [PostgreSQL](https://www.postgresql.org/) | Через коннектор [fq-connector-go](../../deploy/manual/connector.md#fq-connector-go) |
diff --git a/ydb/docs/ru/core/concepts/federated_query/index.md b/ydb/docs/ru/core/concepts/federated_query/index.md
index ab85cceb7dd..f240d77cc74 100644
--- a/ydb/docs/ru/core/concepts/federated_query/index.md
+++ b/ydb/docs/ru/core/concepts/federated_query/index.md
@@ -6,14 +6,11 @@
 
 {% endnote %}
 
+Федеративные запросы - это способ получать информацию из различных источников данных без необходимости переноса данных этих источников внутрь {{ ydb-full-name }}. В настоящее время федеративные запросы поддерживают взаимодействие с базами данных ClickHouse, PostgreSQL и с хранилищами данных класса S3. При помощи YQL запросов вы сможете обращаться к этим базам данных без необходимости дублирования данных между системами.
 
-Федеративные запросы - это способ получать информацию из различных источников данных без необходимости переноса данных этих источников внутрь {{ ydb-full-name }}. Федеративные запросы поддерживают взаимодействие с базами данных ClickHouse, PostgreSQL и с хранилищами данных класса S3 ({{ objstorage-name }}). При помощи YQL запросов вы сможете обращаться к этим базам данных без необходимости дублирования данных между системами.
+Для работы с данными, хранящимися во внешних СУБД, достаточно создать [внешний источник данных](../datamodel/external_data_source.md). Для работы с несхематизированными данными, хранящимися в бакетах S3 нужно дополнительно создать [внешнюю таблицу](../datamodel/external_table.md). В обоих случаях необходимо предварительно создать объекты-[секреты](../datamodel/secrets.md), хранящие конфиденциальные данные, необходимые для аутентификации во внешних системах.
 
-Для работы с данными, хранящимися во внешних СУБД, достаточно создать [внешний источник данных](../datamodel/external_data_source.md). Для работы с несхематизированными данными, хранящимися в бакетах S3 ({{objstorage-full-name}}) нужно дополнительно создать объект [внешнюю таблицу](../datamodel/external_table.md). В обоих случаях необходимо предварительно создать объекты-[секреты](../datamodel/secrets.md), хранящие конфиденциальные данные, необходимые для аутентификации во внешних системах.
-
-Подробная информация про работу с различными источниками данных приведена в соответствующих разделах:
+Вы сможете узнать о внутреннем устройстве системы обработки федеративных запросов в разделе об [архитектуре](./architecture.md). Подробная информация про работу с различными источниками данных приведена в соответствующих разделах:
 - [ClickHouse](clickhouse.md).
 - [PostgreSQL](postgresql.md).
-- [S3 ({{objstorage-full-name}})](s3/external_table.md).
-
-
+- [S3](s3/external_table.md).
diff --git a/ydb/docs/ru/core/concepts/federated_query/toc_i.yaml b/ydb/docs/ru/core/concepts/federated_query/toc_i.yaml
index d9b8fafc212..0a8ada4f7bd 100644
--- a/ydb/docs/ru/core/concepts/federated_query/toc_i.yaml
+++ b/ydb/docs/ru/core/concepts/federated_query/toc_i.yaml
@@ -1,5 +1,6 @@
 items:
 - { name: Обзор,                                  href: index.md }
+- { name: Архитектура,                            href: architecture.md }
 - { name: Работа с базами данных PostgreSQL,      href: postgresql.md }
 - { name: Работа с базами данных ClickHouse,      href: clickhouse.md }
 - name: Работа с бакетами S3
diff --git a/ydb/docs/ru/core/deploy/manual/_images/ydb_fq_onprem.png b/ydb/docs/ru/core/deploy/manual/_images/ydb_fq_onprem.png
new file mode 100644
index 00000000000..95e896e3b9c
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/_images/ydb_fq_onprem.png
diff --git a/ydb/docs/ru/core/deploy/manual/connector.md b/ydb/docs/ru/core/deploy/manual/connector.md
new file mode 100644
index 00000000000..21df1031528
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/connector.md
@@ -0,0 +1,185 @@
+# Развёртывание коннекторов ко внешним источникам данных
+
+{% note warning %}
+
+Данная функциональность находится в режиме "Experimental".
+
+{% endnote %}
+
+[Коннекторы](../../concepts/federated_query/architecture.md#connectors) - специальные микросервисы, предоставляющие {{ ydb-full-name }} универсальную абстракцию доступа ко внешним источникам данных. Коннекторы выступают в качестве точек расширения системы обработки [федеративных запросов](../../concepts/federated_query/index.md) {{ ydb-full-name }}. В данном руководстве мы рассмотрим особенности развёртывания коннекторов в режиме on-premise.
+
+## fq-connector-go {#fq-connector-go}
+
+Коннектор `fq-connector-go` реализован на языке Go; его исходный код размещён на [GitHub](https://github.com/ydb-platform/fq-connector-go). Он обеспечивает доступ к следующим источникам данных:
+
+* [ClickHouse](https://clickhouse.com/)
+* [PostgreSQL](https://www.postgresql.org/)
+
+Коннектор может быть установлен с помощью бинарного дистрибутива или с помощью Docker-образа.
+
+### Запуск из бинарного дистрибутива
+
+Для установки коннектора на физический или виртуальный Linux-сервер без средств контейнерной виртуализации используйте бинарные дистрибутивы.
+
+1. На [странице с релизами](https://github.com/ydb-platform/fq-connector-go/releases) коннектора выберите последний релиз, скачайте архив для подходящей вам платформы и архитектуры. Так выглядит команда для скачивания коннектора версии `v0.2.4` под платформу Linux и архитектуру процессора `amd64`:
+    ```bash
+    mkdir /tmp/connector && cd /tmp/connector
+    wget https://github.com/ydb-platform/fq-connector-go/releases/download/v0.2.4/fq-connector-go-v0.2.4-linux-amd64.tar.gz
+    tar -xzf fq-connector-go-v0.2.4-linux-amd64.tar.gz
+    ```
+
+1. Если на сервере ещё не были развёрнуты узлы {{ ydb-short-name }}, создайте директории для хранения исполняемых и конфигурационных файлов:
+
+    ```bash
+    sudo mkdir -p /opt/ydb/bin /opt/ydb/cfg
+    ```
+
+1. Разместите разархивированные исполняемый и конфигурационный файлы коннектора в только что созданные директории:
+    ```bash
+    sudo cp fq-connector-go /opt/ydb/bin
+    sudo cp fq-connector-go.yaml /opt/ydb/cfg
+    ```
+
+1. В [рекомендуемом режиме использования](../../deploy/manual/deploy-ydb-federated-query.md#general-scheme) коннектор развёртывается на тех же серверах, что и динамические узлы {{ ydb-short-name }}, следовательно, шифрование сетевых соединений между ними *не требуется*. Однако если вам всё же необходимо включить шифрование, [подготовьте пару TLS-ключей](../manual/deploy-ydb-on-premises.md#tls-certificates) и пропишите пути до публичного и приватного ключа в поля `connector_server.tls.cert` и `connector_server.tls.key` конфигурационного файла `fq-connector-go.yaml`:
+    ```yaml
+    connector_server:
+      # ...
+      tls:
+        cert: "/opt/ydb/certs/fq-connector-go.crt"
+        key: "/opt/ydb/certs/fq-connector-go.key"
+    ```
+1. В случае, если внешние источники данных используют TLS, для организации шифрованных соединений с ними коннектору потребуется корневой или промежуточный сертификат удостоверяющего центра (Certificate Authority, CA), которым были подписаны сертификаты источников. На Linux-серверах обычно предустанавливается некоторое количество корневых сертификатов CA. Для ОС Ubuntu список поддерживаемых CA можно вывести следующей командой:
+    ```bash
+    awk -v cmd='openssl x509 -noout -subject' '/BEGIN/{close(cmd)};{print | cmd}' < /etc/ssl/certs/ca-certificates.crt
+    ```
+    Если на сервере отсутствует сертификат нужного CA, скопируйте его в специальную системную директорию и обновите список сертификатов:
+    ```bash
+    sudo cp root_ca.crt /usr/local/share/ca-certificates/
+    sudo update-ca-certificates
+    ```
+
+1. Вы можете запустить сервис вручную или с помощью systemd.
+
+    {% list tabs %}
+
+    - Вручную
+
+        Запустите сервис из консоли следующей командой:
+        ```bash
+        /opt/ydb/bin/fq-connector-go server -c /opt/ydb/cfg/fq-connector-go.yaml
+        ```
+
+    - С использованием systemd
+
+        Вместе с бинарным дистрибутивом fq-connector-go распространяется [пример](https://github.com/ydb-platform/fq-connector-go/blob/main/examples/systemd/fq-connector-go.service) конфигурационного файла (юнита) для системы инициализации `systemd`. Скопируйте юнит в директорию `/etc/systemd/system`, активизируйте и запустите сервис:
+
+        ```bash
+        cd /tmp/connector
+        sudo cp fq-connector-go.service /etc/systemd/system/
+        sudo systemctl enable fq-connector-go.service
+        sudo systemctl start fq-connector-go.service
+        ```
+
+        В случае успеха сервис должен перейти в состояние `active (running)`. Проверьте его следующей командой:
+        ```bash
+        sudo systemctl status fq-connector-go 
+        ● fq-connector-go.service - YDB FQ Connector Go
+            Loaded: loaded (/etc/systemd/system/fq-connector-go.service; enabled; vendor preset: enabled)
+            Active: active (running) since Thu 2024-02-29 17:51:42 MSK; 2s ago
+        ```
+
+        Логи сервиса можно прочитать с помощью команды:
+        ```bash
+        sudo journalctl -u fq-connector-go.service
+        ```
+    {% endlist %}
+
+### Запуск в Docker {#fq-connector-go-docker}
+
+1. Для запуска коннектора используйте официальный [Docker-образ](https://github.com/ydb-platform/fq-connector-go/pkgs/container/fq-connector-go). Он уже содержит [конфигурационный файл](https://github.com/ydb-platform/fq-connector-go/blob/main/app/server/config/config.prod.yaml) сервиса. Запустить сервис с настройками по умолчанию можно следующей командой: 
+
+    ```bash
+    docker run -d \
+        --name=fq-connector-go \
+        -p 2130:2130 \
+        ghcr.io/ydb-platform/fq-connector-go:latest
+    ```
+
+    На порту 2130 публичного сетевого интерфейса вашего хоста запустится слушающий сокет GRPC-сервиса коннектора. В дальнейшем сервер {{ ydb-short-name }} должен будет установить соединение именно с этим сетевым адресом.
+
+1. При необходимости изменения конфигурации подготовьте конфигурационный файл [по образцу](#fq-connector-go-config) и примонтируйте его к контейнеру:
+
+    ```bash
+    docker run -d \
+        --name=fq-connector-go \
+        -p 2130:2130 \
+        -v /path/to/config.yaml:/opt/ydb/cfg/fq-connector-go.yaml
+        ghcr.io/ydb-platform/fq-connector-go:latest
+    ```
+
+1. В [рекомендуемом режиме использования](../../deploy/manual/deploy-ydb-federated-query.md#general-scheme) коннектор развёртывается на тех же серверах, что и динамические узлы {{ ydb-short-name }}, следовательно, шифрование сетевых соединений между ними *не требуется*. Но если вам всё же необходимо включить шифрование между {{ ydb-short-name }} и коннектором, [подготовьте пару TLS-ключей](../manual/deploy-ydb-on-premises.md#tls-certificates) и пропишите пути до публичного и приватного ключа в секции конфигурационного файла `connector_server.tls.cert` и `connector_server.tls.key` соответственно:
+
+    ```yaml
+    connector_server:
+      # ...
+      tls:
+        cert: "/opt/ydb/certs/fq-connector-go.crt"
+        key: "/opt/ydb/certs/fq-connector-go.key"
+    ```
+    При запуске контейнера примонтируйте внутрь него директорию с парой TLS-ключей так, чтобы они оказались доступны для процесса `fq-connector-go` по путям, указанным в конфигурационном файле: 
+
+    ```bash
+    docker run -d \
+        --name=fq-connector-go \
+        -p 2130:2130 \
+        -v /path/to/config.yaml:/opt/ydb/cfg/fq-connector-go.yaml
+        -v /path/to/keys/:/opt/ydb/certs/
+        ghcr.io/ydb-platform/fq-connector-go:latest
+    ```
+
+1. В случае, если внешние источники данных используют TLS, для организации шифрованных соединений с ними коннектору потребуется корневой или промежуточный сертификат удостоверяющего центра (Certificate Authority, CA), которым были подписаны сертификаты источников. Docker-образ для коннектора базируется на образе дистрибутива Alpine Linux, который уже содержит некоторое количество сертификатов от доверенных CA. Проверить наличие нужного CA в списке предустановленных можно следующей командой:
+
+    ```bash
+    docker run -it --rm ghcr.io/ydb-platform/fq-connector-go sh
+    # далее в консоли внутри контейнера:
+    apk add openssl
+    awk -v cmd='openssl x509 -noout -subject' ' /BEGIN/{close(cmd)};{print | cmd}' < /etc/ssl/certs/ca-certificates.crt
+    ```
+
+    Если TLS-ключи для источников выпущены CA, не входящим в перечень доверенных, необходимо добавить сертификат этого CA в системные пути контейнера с коннектором. Сделать это можно, например, собрав собственный Docker-образ на основе имеющегося. Для этого подготовьте следующий `Dockerfile`: 
+
+    ```Dockerfile
+    FROM ghcr.io/ydb-platform/fq-connector-go:latest
+
+    USER root
+
+    RUN apk --no-cache add ca-certificates openssl
+    COPY root_ca.crt /usr/local/share/ca-certificates
+    RUN update-ca-certificates
+    ```
+
+    Поместите `Dockerfile` и корневой сертификат CA в одной папке, зайдите в неё и соберите образ следующей командой:
+    ```bash
+    docker build -t fq-connector-go_custom_ca .
+    ```
+
+    Новый образ `fq-connector-go_custom_ca` можно использовать для развёртывания сервиса с помощью команд, приведённых выше.
+
+### Конфигурация {#fq-connector-go-config}
+
+Актуальный пример конфигурационного файла сервиса `fq-connector-go` можно найти в [репозитории](https://github.com/ydb-platform/fq-connector-go/blob/main/app/server/config/config.prod.yaml). 
+
+| Параметр | Назначение |
+|----------|------------|
+| `connector_server` | Обязательная секция. Содержит настройки основного GPRC-сервера, выполняющего доступ к данным. |
+| `connector_server.endpoint.host` | Хостнейм или IP-адрес, на котором запускается слушающий сокет сервиса. |
+| `connector_server.endpoint.port` | Номер порта, на котором запускается слушающий сокет сервиса. |
+| `connector_server.tls` | Опциональная секция. Заполняется, если требуется включение TLS-соединений для основного GRPC-сервиса `fq-connector-go`. По умолчанию сервис запускается без TLS. |
+| `connector_server.tls.key` | Полный путь до закрытого ключа шифрования. |
+| `connector_server.tls.cert` | Полный путь до открытого ключа шифрования. |
+| `logger` | Опциональная секция. Содержит настройки логирования. |
+| `logger.log_level` | Уровень логгирования. Допустимые значения: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL`. Значение по умолчанию: `INFO`. |
+| `logger.enable_sql_query_logging` | Для источников данных, поддерживающих SQL, включает логирование транслированных запросов. Допустимые значения: `true`, `false`. **ВАЖНО**: включение этой опции может привести к печати конфиденциальных пользовательских данных в логи. Значение по умолчанию: `false`. |
+| `paging` | Опциональная секция. Содержит настройки алгоритма разбиения извлекаемого из источника потока данных на Arrow-блоки. На каждый запрос в коннекторе создаётся очередь из заранее подготовленных к отправке на сторону {{ ydb-short-name }} блоков данных. Аллокации Arrow-блоков формируют наиболее существенный вклад в потребление оперативной памяти процессом `fq-connector-go`. Минимальный объём памяти, необходимый коннектору для работы, можно приблизительно оценить по формуле $Mem = 2 \cdot Requests \cdot BPP \cdot PQC$, где $Requests$ — количество одновременно выполняемых запросов, $BPP$ — параметр `paging.bytes_per_page`, а $PQC$  — параметр `paging.prefetch_queue_capacity`. |
+| `paging.bytes_per_page` | Максимальное количество байт в одном блоке. Рекомендуемые значения - от 4 до 8 МиБ, максимальное значение - 48 МиБ. Значение по умолчанию: 4 МиБ. |
+| `paging.prefetch_queue_capacity` | Количество заранее вычитываемых блоков данных, которые хранятся в адресном пространстве коннектора до обращения YDB за очередным блоком данных. В некоторых сценариях бóльшие значения данной настройки могут увеличить пропускную способность, но одновременно приведут и к большему потреблению оперативной памяти процессом. Рекомендуемые значения - не менее 2. Значение по умолчанию: 2. | 
diff --git a/ydb/docs/ru/core/deploy/manual/deploy-ydb-federated-query.md b/ydb/docs/ru/core/deploy/manual/deploy-ydb-federated-query.md
new file mode 100644
index 00000000000..0ff89e63293
--- /dev/null
+++ b/ydb/docs/ru/core/deploy/manual/deploy-ydb-federated-query.md
@@ -0,0 +1,59 @@
+# Развёртывание YDB с функцией Federated Query
+
+{% note warning %}
+
+Данная функциональность находится в режиме "Experimental".
+
+{% endnote %}
+
+## Общая схема инсталляции{#general-scheme}
+
+{{ ydb-full-name }} может выполнять [федеративные запросы](../../concepts/federated_query/index.md) ко внешним источникам (например, объектным хранилищам или реляционным СУБД) без необходимости перемещения их данных непосредственно в {{ ydb-short-name }}. В данном разделе мы рассмотрим изменения, которые необходимо внести в конфигурацию {{ ydb-short-name }} и окружающую инфраструктуру для включения функциональности федеративных запросов. 
+
+{% note info %}
+
+Для организации доступа к некоторым из источников данных требуется развёртывание специального микросервиса - [коннектора](../../concepts/federated_query/architecture.md#connectors). Ознакомьтесь c [перечнем поддерживаемых источников](../../concepts/federated_query/architecture.md#supported-datasources), чтобы понять, требуется ли вам установка коннектора.
+
+{% endnote %}
+ 
+Кластер {{ ydb-short-name }} и внешние источники данных в варианте production-инсталляции должны развёртываться на разных физических или виртуальных серверах, в том числе в облаках. Если для доступа к определённому источнику требуется развёртывание коннектора, это необходимо сделать на тех же серверах, на которых развёрнуты динамические узлы {{ ydb-short-name }}. Иными словами, на каждый процесс `ydbd`, работающий в режиме динамического узла, должен приходиться один локальный процесс коннектора. 
+
+При этом должны выполняться следующие требования:
+* внешний источник данных должен быть доступен по сети для запросов со стороны {{ ydb-short-name }} или со стороны коннектора (при его наличии);
+* коннектор должен быть доступен по сети для запросов со стороны {{ ydb-short-name }} (что достигается тривиальным образом благодаря работе этих процессов на одном и том же хосте).
+
+![Инсталляция {{ ydb-short-name }} FQ](_images/ydb_fq_onprem.png "Инсталляция {{ ydb-short-name }} FQ" =1024x)
+
+{% note info %}
+
+В настоящее время мы не поддерживаем развёртывание коннектора в {{k8s}}, но планируем добавить её в ближайшем будущем.
+
+{% endnote %}
+
+## Пошаговое руководство
+
+1. Выполните шаги инструкции по развёртыванию динамического узла {{ ydb-short-name }} до [подготовки конфигурационных файлов](./deploy-ydb-on-premises.md#config) включительно.
+1. Если для доступа к нужному вам источнику требуется развернуть коннектор, сделайте это [согласно инструкции](./connector.md).
+1. Если для доступа к нужному вам источнику трубуется развернуть коннектор, в конфигурационном файле {{ ydb-short-name }} в секции `query_service_config` добавьте подсекцию `generic` по приведённому ниже образцу. В полях `connector.endpoint.host` и `connector.endpoint.port` укажите сетевой адрес коннектора (по умолчанию `localhost` и `2130`). При совместном размещении коннектора и динамического узла {{ ydb-short-name }} на одном сервере установка шифрованных соединений между ними *не требуется*, но в случае необходимости вы можете включить шифрование, передав значение `true` в поле `connector.use_ssl` и указав путь до сертификата CA, использованного для подписи TLS-ключей коннектора, в `connector.ssl_ca_crt`:
+    ```yaml
+    query_service_config:
+        generic:
+            connector:
+                endpoint:
+                    host: localhost                 # имя хоста, где развернут коннектор
+                    port: 2130                      # номер порта для слушающего сокета коннектора
+                use_ssl: false                      # флаг, включающий шифрование соединений
+                ssl_ca_crt: "/opt/ydb/certs/ca.crt" # (опционально) путь к сертификату CA
+            default_settings:
+                - name: DateTimeFormat
+                  value: string
+                - name: UsePredicatePushdown
+                  value: "true"
+    ```
+1. В конфигурационном файле {{ ydb-short-name }} добавьте секцию `feature_flags` следующего содержания:
+    ```yaml
+    feature_flags:
+        enable_external_data_sources: true
+        enable_script_execution_operations: true
+    ```
+1. Продолжайте развёртывание динамического узла {{ ydb-short-name }} по [инструкции](./deploy-ydb-on-premises.md). 
diff --git a/ydb/docs/ru/core/deploy/manual/toc_i.yaml b/ydb/docs/ru/core/deploy/manual/toc_i.yaml
index e4c6085fb11..e8bd5584b77 100644
--- a/ydb/docs/ru/core/deploy/manual/toc_i.yaml
+++ b/ydb/docs/ru/core/deploy/manual/toc_i.yaml
@@ -1,5 +1,9 @@
 items:
 #- name: Обзор
 #  href: concepts.md
-- name: Развертывание
+- name: Развертывание YDB
   href: deploy-ydb-on-premises.md
+- name: Развертывание YDB с функцией Federated Query
+  href: deploy-ydb-federated-query.md
+- name: Развертывание коннектора
+  href: connector.md
diff --git a/ydb/docs/ru/core/deploy/toc_i.yaml b/ydb/docs/ru/core/deploy/toc_i.yaml
index 9c6d94948ad..e907ba76574 100644
--- a/ydb/docs/ru/core/deploy/toc_i.yaml
+++ b/ydb/docs/ru/core/deploy/toc_i.yaml
@@ -1,6 +1,6 @@
 items:
 - name: VM / Baremetal
-  href: manual/deploy-ydb-on-premises.md
+  include: { mode: link, path: manual/toc_p.yaml }
 - name: Развертывание одноузлового кластера
   include: { mode: link, path: ../getting_started/self_hosted/toc_p.yaml }
 - name: Конфигурация
diff --git a/ydb/docs/ru/core/getting_started/self_hosted/_images/ydb_fq_docker.png b/ydb/docs/ru/core/getting_started/self_hosted/_images/ydb_fq_docker.png
new file mode 100644
index 00000000000..be30ef33709
--- /dev/null
+++ b/ydb/docs/ru/core/getting_started/self_hosted/_images/ydb_fq_docker.png
diff --git a/ydb/docs/ru/core/getting_started/self_hosted/_includes/ydb_docker.md b/ydb/docs/ru/core/getting_started/self_hosted/_includes/ydb_docker.md
index 35040bf807a..b9cf4076ba9 100644
--- a/ydb/docs/ru/core/getting_started/self_hosted/_includes/ydb_docker.md
+++ b/ydb/docs/ru/core/getting_started/self_hosted/_includes/ydb_docker.md
@@ -97,6 +97,8 @@ docker run -d --rm --name ydb-local -h localhost \
 `-v`: Монтировать директории хост-системы в контейнер в виде `<директория хост-системы>:<директория монтирования в контейнере>`. Контейнер YDB использует следующие директории монтирования:
 - `/ydb_data`: Размещение данных. Если данная директория не смонтирована, то контейнер будет запущен без сохранения данных на диск хост-системы.
 - `/ydb_certs`: Размещение сертификатов для TLS соединения. Запущенный контейнер запишет туда сертификаты, которые вам нужно использовать для клиентского подключения с использованием TLS. Если данная директория не смонтирована, то вы не сможете подключиться по TLS, так как не будете обладать информацией о сертификате.
+
+`-p`: Опубликовать порты контейнера на хост-системе. Все применяемые порты должны быть явно перечислены, даже если используются значения по умолчанию.
 `-e`: Задать переменные окружения в виде `<имя>=<значение>`. Контейнер YDB использует следующие переменные окружения:
 - `YDB_DEFAULT_LOG_LEVEL`: Уровень логирования. Допустимые значения: `CRIT`, `ERROR`, `WARN`, `NOTICE`, `INFO`. По умолчанию `NOTICE`.
 - `GRPC_PORT`: Порт для нешифрованных соединений. По умолчанию 2136.
@@ -108,7 +110,7 @@ docker run -d --rm --name ydb-local -h localhost \
 - `POSTGRES_USER` - создать пользователя с указанным логином, используется для подключения через postgres-протокол.
 - `POSTGRES_PASSWORD` - задать пароль пользователя для подключения через postgres-протокол.
 - `YDB_TABLE_ENABLE_PREPARED_DDL` - временная опция, нужна для запуска Postgres-слоя совместимости, в будущем будет удалена.
-`-p`: Опубликовать порты контейнера на хост-системе. Все применяемые порты должны быть явно перечислены, даже если используются значения по умолчанию.
+- `FQ_CONNECTOR_ENDPOINT` - задать сетевой адрес коннектора ко внешним источникам данных для обработки [федеративных запросов](../../../concepts/federated_query/index.md). Формат строки `scheme://host:port`, где допустимыми значениями `scheme` могут быть `grpcs` (указывает на подключение к коннектору по протоколу TLS) или `grpc` (подключение без шифрования).
 
 {% include [_includes/storage-device-requirements.md](../../../_includes/storage-device-requirements.md) %}
 
@@ -166,3 +168,82 @@ docker run --rm -it --entrypoint cat {{ ydb_local_docker_image }} LICENSE
 ```bash
 docker run --rm -it --entrypoint cat {{ ydb_local_docker_image }} THIRD_PARTY_LICENSES
 ```
+
+## Запуск {{ ydb-short-name }} Federated Query в Docker
+
+{% note warning %}
+
+Данная функциональность находится в режиме "Experimental".
+
+{% endnote %}
+
+В данном разделе рассматривается пример тестовой инсталляции {{ ydb-full-name }}, сконфигурированной для выполнения [федеративных запросов](../../../concepts/federated_query/index.md) к внешним источникам данных. Подключение {{ ydb-full-name }} к некоторым из источников требует развертывания специального микросервиса - [коннектора](../../../concepts/federated_query/architecture.md#connectors). Ниже мы воспользуемся инструментом оркестрации `docker-compose` для локального запуска Docker-контейнеров с тремя сервисами: 
+
+* {{ ydb-short-name }} в одноузловой конфигурации;
+* PostgreSQL (в качестве примера источника данных);
+* Коннектор [fq-connector-go](../../../deploy/manual/connector.md#fq-connector-go).
+
+![YDB FQ in Docker](../_images/ydb_fq_docker.png "YDB FQ in Docker" =320x)
+
+{% note info %}
+
+В данном руководстве запросы к {{ ydb-short-name }} выполняются через [Embedded UI](../../../maintenance/embedded_monitoring/index.md). Возможность выполнения запросов через [{{ ydb-short-name }} CLI](../../../reference/ydb-cli/index.md) появится в ближайшем будущем.
+
+{% endnote %}
+
+1. Установите `docker-compose` подходящим вам [способом](https://github.com/docker/compose?tab=readme-ov-file#where-to-get-docker-compose). 
+
+1. Скачайте [пример](https://github.com/ydb-platform/fq-connector-go/blob/main/examples/docker-compose/docker-compose.yaml) файла `docker-compose.yaml` и запустите контейнеры:
+
+    ```bash
+    mkdir /tmp/fq && cd /tmp/fq
+    wget https://raw.githubusercontent.com/ydb-platform/fq-connector-go/main/examples/docker-compose.yaml
+    docker-compose pull
+    docker-compose up -d
+    ```
+
+1. Инициализируйте любым удобным вам способом данные внутри развернутого в контейнере источника, например, подключившись к нему через CLI:
+    ```bash
+    docker exec -it fq-example-postgresql psql -d fq --user admin -c "
+        DROP TABLE IF EXISTS example;
+        CREATE TABLE example (id integer, col1 text, col2 integer);
+        INSERT INTO example VALUES (1, 'a', 10), (2, 'b', 20), (3, 'c', 30), 
+                                   (4, 'd', 40), (5, 'e', 50), (6, NULL, 1);"
+    ```
+
+1. Откройте в браузере страницу `http://hostname:8765/monitoring/tenant?schema=%2Flocal&name=%2Flocal`, где `hostname` - сетевое имя хоста, на котором развёрнуты контейнеры ([ссылка для localhost](http://localhost:8765/monitoring/tenant?schema=%2Flocal&name=%2Flocal)). Вы попадёте в Embedded UI базы данных `/local` локально развернутого инстанса {{ ydb-short-name }}. В панели для запросов введите код, регистрирующий базу данных `fq` из локального инстанса PostgreSQL в качестве внешнего источника данных для {{ ydb-short-name }}:
+
+    ```sql
+    -- Создаётся секрет, содержащий пароль "password" пользователя admin базы данных PostgreSQL
+    CREATE OBJECT pg_local_password (TYPE SECRET) WITH (value = password);
+
+    CREATE EXTERNAL DATA SOURCE pg_local WITH (
+        SOURCE_TYPE="PostgreSQL",                   -- тип источника данных
+        DATABASE_NAME="fq",                         -- имя базы данных
+        LOCATION="postgresql:5432",                 -- сетевой адрес источника (в данном случае соответствует
+                                                    -- имени сервиса в файле docker-compose.yaml)
+        AUTH_METHOD="BASIC",                        -- режим аутентификации по логину и паролю                 
+        LOGIN="admin",                              -- логин для доступа к источнику
+        PASSWORD_SECRET_NAME="pg_local_password",   -- имя секрета, содержащего пароль пользователя
+        USE_TLS="FALSE",                            -- признак применения источником TLS-шифрования
+        PROTOCOL="NATIVE"                           -- протокол доступа к источнику данных
+    );
+    ```
+
+1. В селекторе типов запросов внизу страницы выберите `Query type: YQL Script` и нажмите кнопку `Run`. Запрос должен завершиться успешно.
+
+1. Затем введите запрос, непосредственно извлекающий данные из таблицы `example` базы данных `fq` локального инстанса PostgreSQL:
+
+    ```sql
+    SELECT * FROM pg_local.example;
+    ```
+
+1. В селекторе типов запросов внизу страницы выберите `Query type: YQL - QueryService` и нажмите кнопку `Run`. На экране появятся данные таблицы, созданной во внешнем источнике несколькими шагами ранее. 
+
+Успешное выполнение последнего запроса демонстрирует работоспособность всей цепочки преобразований данных: пользователь {{ ydb-short-name }} формулирует YQL-запрос к внешней базе данных PostgreSQL, {{ ydb-short-name }} обращается к коннектору по внутреннему API, коннектор генерирует запрос на диалекте PostgreSQL, извлекает данные из внешнего источника, и передаёт их в {{ ydb-short-name }} для отображения. Точно таким же образом в одном YQL-запросе можно обратиться сразу к нескольким источникам разных типов одновременно, извлечь и объдинить данные и совместно их проанализировать. 
+
+{% note info %}
+
+О дополнительных опциях запуска коннектора можно узнать в [руководстве по развертыванию](../../../deploy/manual/connector.md#fq-connector-go-docker). В качестве внешних источников данных можно использовать любое хранилище или базу данных из перечня [поддерживаемых](../../../concepts/federated_query/architecture.md#supported-datasources).
+
+{% endnote %}