diff --git a/ydb/docs/en/core/_assets/fluent-bit-ydb-scheme.png b/ydb/docs/en/core/_assets/fluent-bit-ydb-scheme.png new file mode 100644 index 000000000000..faeb4307dc34 Binary files /dev/null and b/ydb/docs/en/core/_assets/fluent-bit-ydb-scheme.png differ diff --git a/ydb/docs/en/core/integrations/fluent-bit.md b/ydb/docs/en/core/integrations/fluent-bit.md new file mode 100644 index 000000000000..7502b1dee162 --- /dev/null +++ b/ydb/docs/en/core/integrations/fluent-bit.md @@ -0,0 +1,237 @@ +# Log records collection in a Kubernetes cluster using FluentBit and YDB + +This section presents the implementation of integration between the Kubernetes cluster log shipping tool - FluentBit, with subsequent saving for viewing or analysis in {{ ydb-short-name }}. + +## Введение + +FluentBit is a tool that can collect text data, manipulate it (change, transform, merge) and send it to various storage facilities for further processing. + +To deploy a scheme for delivering logs of running applications to Kubernetes using FluentBit and then saving them in YDB, you need to: + +* Create table in YDB + +* Configure [FluentBit](https://fluentbit.io) + +* Deploy [FluentBit](https://fluentbit.io) in Kubernetes cluster using [HELM](https://helm.sh) + +The work diagram looks like this: + +![FluentBit in Kubernetes cluster](../_assets/fluent-bit-ydb-scheme.png) +Figure 1 — Interaction diagram between FluentBit and YDB in the Kubernetes cluster + +In this diagram: + +* Application pods write logs to stdout/stderr + +* Text from stdout/stderr is saved as files on Kubernetes worker nodes + +* Pod with FluentBit + + * Mounts a folder with log files for itself + + * Reads the contents from them + + * Enriches posts with additional metadata + + * Saves records to YDB cluster + +## Creating a table in YDB + +On the selected YDB cluster, you need to run the following query: + +```sql +CREATE TABLE `fluent-bit/log` ( + `timestamp` Timestamp NOT NULL, + `file` Text NOT NULL, + `pipe` Text NOT NULL, + `message` Text NULL, + `message_parsed` JSON NULL, + `kubernetes` JSON NULL, + + PRIMARY KEY ( + `timestamp`, `input` + ) +) +``` + +Column purpose: + +* timestamp – the log timestamp + +* file – name of the source from which the log was read. In the case of Kubernetes, this will be the name of the file on the worker node in which the logs of a specific pod are written + +* pipe – stdout or stderr stream where application-level writing was done + +* message – the log message + +* message_parsed – a structured log message, if it could be parsed using the fluent-bit parsers + +* kubernetes – information about the pod, for example: name, namespace, logs and annotations + +Optionally, you can set TTL for table rows + +## FluentBit configuration + +It is necessary to replace the repository and image version: + +```yaml +image: + repository: ghcr.io/ydb-platform/fluent-bit-ydb + tag: v1.0.0 +``` + +In this image, a plugin library has been added that implements YDB support. Source code is available [here](https://github.com/ydb-platform/fluent-bit-ydb) + +The following lines define the rules for mounting log folders in FluentBit pods: + +```yaml +volumeMounts: + - name: config + mountPath: /fluent-bit/etc/conf + +daemonSetVolumes: + - name: varlog + hostPath: + path: /var/log + - name: varlibcontainers + hostPath: + path: /var/lib/containerd/containers + - name: etcmachineid + hostPath: + path: /etc/machine-id + type: File + +daemonSetVolumeMounts: + - name: varlog + mountPath: /var/log + - name: varlibcontainers + mountPath: /var/lib/containerd/containers + readOnly: true + - name: etcmachineid + mountPath: /etc/machine-id + readOnly: true +``` + +Also, you need to redefine the command and launch arguments: + +```yaml +command: + - /fluent-bit/bin/fluent-bit + +args: + - --workdir=/fluent-bit/etc + - --plugin=/fluent-bit/lib/out_ydb.so + - --config=/fluent-bit/etc/conf/fluent-bit.conf +``` + +And the pipeline itself for collecting, converting and delivering logs: + +```yaml +config: + inputs: | + [INPUT] + Name tail + Path /var/log/containers/*.log + multiline.parser cri + Tag kube.* + Mem_Buf_Limit 5MB + Skip_Long_Lines On + + filters: | + [FILTER] + Name kubernetes + Match kube.* + Keep_Log On + Merge_Log On + Merge_Log_Key log_parsed + K8S-Logging.Parser On + K8S-Logging.Exclude On + + [FILTER] + Name modify + Match kube.* + Remove time + Remove _p + + outputs: | + [OUTPUT] + Name ydb + Match kube.* + TablePath fluent-bit/log + Columns {".timestamp":"timestamp",".input":"file","log":"message","log_parsed":"message_structured","stream":"pipe","kubernetes":"metadata"} + ConnectionURL ${OUTPUT_YDB_CONNECTION_URL} + CredentialsToken ${OUTPUT_YDB_CREDENTIALS_TOKEN} +``` + +Blocks description: + +* Inputs. This block specifies where to read and how to parse logs. In this case, *.log files will be read from the /var/log/containers/ folder, which was mounted from the host + +* Filters. This block specifies how logs will be processed. In this case: for each log the corresponding metadata will be found (using the kubernetes filter), and unused fields (_p, time) will be cut out + +* Outputs. This block specifies where the logs will be sent. In this case, to the `fluent-bit/log` table in the {{ ydb-short-name }} cluster. Cluster connection parameters (ConnectionURL, CredentialsToken) are set using the corresponding environment variables – `OUTPUT_YDB_CONNECTION_URL`, `OUTPUT_YDB_CREDENTIALS_TOKEN` + +Environment variables are defined as follows: + +```yaml +env: + - name: OUTPUT_YDB_CONNECTION_URL + value: grpc://ydb-endpoint:2135/path/to/database + - name: OUTPUT_YDB_CREDENTIALS_TOKEN + valueFrom: + secretKeyRef: + key: token + name: fluent-bit-ydb-plugin-token +``` + +The secret authorization token must be created in advance in the cluster. For example, using the command: + +```sh +kubectl create secret -n ydb-fluent-bit-integration generic fluent-bit-ydb-plugin-token --from-literal=token= +``` + +## FluentBit deployment + +HELM is a way to package and install applications in a Kubernetes cluster. To deploy FluentBit, you need to add a chart repository using the command: + +```sh +helm repo add fluent https://fluent.github.io/helm-charts +``` + +Installing FluentBit on a Kubernetes cluster is done using the following command: + +```sh +helm upgrade --install fluent-bit fluent/fluent-bit \ + --version 0.37.1 \ + --namespace ydb-fluent-bit-integration \ + --create-namespace \ + --values values.yaml +``` + +## Verify the installation + +Check that fluent-bit has started by reading its logs (there should be no [error] level entries): + +```sh +kubectl logs -n ydb-fluent-bit-integration -l app.kubernetes.io/instance=fluent-bit +``` + +Check that there are records in the YDB table (they will appear approximately a few minutes after launching FluentBit): + +```sql +SELECT * FROM `fluent-bit/log` LIMIT 10 ORDER BY `timestamp` DESC +``` + +## Resource cleanup + +It is enough to remove the namespace with fluent-bit: + +```sh +kubectl delete namespace ydb-fluent-bit-integration +``` + +And a table with logs: + +```sql +DROP TABLE `fluent-bit/log` +``` diff --git a/ydb/docs/en/core/integrations/toc_i.yaml b/ydb/docs/en/core/integrations/toc_i.yaml new file mode 100644 index 000000000000..4aacc389736a --- /dev/null +++ b/ydb/docs/en/core/integrations/toc_i.yaml @@ -0,0 +1,3 @@ +items: +- name: Log records collection in a Kubernetes cluster using FluentBit and YDB + href: fluent-bit.md diff --git a/ydb/docs/en/core/integrations/toc_p.yaml b/ydb/docs/en/core/integrations/toc_p.yaml new file mode 100644 index 000000000000..5bfec4365def --- /dev/null +++ b/ydb/docs/en/core/integrations/toc_p.yaml @@ -0,0 +1,2 @@ +items: +- include: { mode: link, path: toc_i.yaml } \ No newline at end of file diff --git a/ydb/docs/en/core/toc_i.yaml b/ydb/docs/en/core/toc_i.yaml index 2f3bb66a90c5..53c6b335068c 100644 --- a/ydb/docs/en/core/toc_i.yaml +++ b/ydb/docs/en/core/toc_i.yaml @@ -23,6 +23,7 @@ items: # References - { name: YQL, include: { mode: link, path: yql/toc_p.yaml } } - { name: Compatibility with PostgreSQL, include: { mode: link, path: postgresql/toc_p.yaml } } +- { name: Integrations, include: { mode: link, path: integrations/toc_p.yaml } } - { name: Working with the YDB CLI, include: { mode: link, path: reference/ydb-cli/toc_p.yaml } } - { name: Working with the YDB SDK, include: { mode: link, path: reference/ydb-sdk/toc_p.yaml } } - { name: Development, include: { mode: link, path: development/toc_p.yaml } } diff --git a/ydb/docs/ru/core/_assets/fluent-bit-ydb-scheme.png b/ydb/docs/ru/core/_assets/fluent-bit-ydb-scheme.png new file mode 100644 index 000000000000..faeb4307dc34 Binary files /dev/null and b/ydb/docs/ru/core/_assets/fluent-bit-ydb-scheme.png differ diff --git a/ydb/docs/ru/core/integrations/fluent-bit.md b/ydb/docs/ru/core/integrations/fluent-bit.md new file mode 100644 index 000000000000..b8b5c085cf9c --- /dev/null +++ b/ydb/docs/ru/core/integrations/fluent-bit.md @@ -0,0 +1,238 @@ +# Сбор логов в кластере Kubernetes с помощью FluentBit и YDB + +В разделе представлена реализация интеграции между инструментом захвата логов кластера Kubernetes – FluentBit с последующим сохранением для просмотра или анализа в {{ ydb-short-name }}. + +## Введение + +FluentBit – инструмент, который может собирать текстовые данные, манипулировать ими (изменять, преобразовывать, объединять) и отправлять в различные хранилища для дальнейшей обработки. + +Чтобы развернуть схему доставки логов запущенных приложений в Kubernetes с помощью FluentBit с последующим сохранением их в YDB, необходимо: + +* Создать таблицу в YDB + +* Сконфигурировать [FluentBit](https://fluentbit.io) + +* Развернуть [FluentBit](https://fluentbit.io) в кластере через [HELM](https://helm.sh) + +Принципиальная схема работы выглядит следующим образом: + +![FluentBit in Kubernetes cluster](../_assets/fluent-bit-ydb-scheme.png) +Рисунок 1 — Схема взаимодействия FluentBit и YDB в Kubernetes кластере + +На этой схеме: + +* Поды приложений пишут логи в stdout/stderr + +* Текст из stdout/stderr сохраняется в виде файлов на worker нодах Kubernetes + +* Под с FluentBit + + * Монтирует под себя папку с лог-файлами + + * Вычитывает из них содержимое + + * Обогащает записи дополнительными метаданными + + * Сохраняет записи в YDB кластер + +## Создание таблицы + +В выбранном кластере YDB необходимо выполнить следующий запрос: + +```sql +CREATE TABLE `fluent-bit/log` ( + `timestamp` Timestamp NOT NULL, + `file` Text NOT NULL, + `pipe` Text NOT NULL, + `message` Text NULL, + `message_parsed` JSON NULL, + `kubernetes` JSON NULL, + + PRIMARY KEY ( + `timestamp`, `input` + ) +) +``` + +Предназначение колонок: + +* timestamp – временная метка лога + +* file – название источника, из которого прочитан лог. В случае Kubernetes это будет имя файла, на worker ноде, в который записываются логи определенного pod + +* pipe – stdout или stderr поток, куда была осуществлена запись на уровне приложения + +* message – непосредственно само сообщение лога + +* message_parsed – структурированное сообщение лога, если его удалось разобрать с помощью механизма парсеров в fluent-bit + +* kubernetes – некоторая информация о pod, например: название, неймспейс, логи и аннотации + +Опционально, можно установить TTL для строк таблицы (т.к. данных будет достаточно много) + +## Конфигурация FluentBit + + +Необходимо заменить репозиторий и версию образа: + +```yaml +image: + repository: ghcr.io/ydb-platform/fluent-bit-ydb + tag: v1.0.0 +``` + +В данном образе добавлена библиотека-плагин, реализующая поддержку YDB. Исходный код доступен [здесь](https://github.com/ydb-platform/fluent-bit-ydb) + +В следующих строках определены правила монтирования папок с логами в поды FluentBit: + +```yaml +volumeMounts: + - name: config + mountPath: /fluent-bit/etc/conf + +daemonSetVolumes: + - name: varlog + hostPath: + path: /var/log + - name: varlibcontainers + hostPath: + path: /var/lib/containerd/containers + - name: etcmachineid + hostPath: + path: /etc/machine-id + type: File + +daemonSetVolumeMounts: + - name: varlog + mountPath: /var/log + - name: varlibcontainers + mountPath: /var/lib/containerd/containers + readOnly: true + - name: etcmachineid + mountPath: /etc/machine-id + readOnly: true +``` + +Также, необходимо переопределить команду и аргументы запуска: + +```yaml +command: + - /fluent-bit/bin/fluent-bit + +args: + - --workdir=/fluent-bit/etc + - --plugin=/fluent-bit/lib/out_ydb.so + - --config=/fluent-bit/etc/conf/fluent-bit.conf +``` + +И сам пайплайн сбора, преобразования и доставки логов: + +```yaml +config: + inputs: | + [INPUT] + Name tail + Path /var/log/containers/*.log + multiline.parser cri + Tag kube.* + Mem_Buf_Limit 5MB + Skip_Long_Lines On + + filters: | + [FILTER] + Name kubernetes + Match kube.* + Keep_Log On + Merge_Log On + Merge_Log_Key log_parsed + K8S-Logging.Parser On + K8S-Logging.Exclude On + + [FILTER] + Name modify + Match kube.* + Remove time + Remove _p + + outputs: | + [OUTPUT] + Name ydb + Match kube.* + TablePath fluent-bit/log + Columns {".timestamp":"timestamp",".input":"file","log":"message","log_parsed":"message_structured","stream":"pipe","kubernetes":"metadata"} + ConnectionURL ${OUTPUT_YDB_CONNECTION_URL} + CredentialsToken ${OUTPUT_YDB_CREDENTIALS_TOKEN} +``` + +Описание ключей: + +* Inputs. В этом блоке указываются откуда считывать и как разбирать логи. В данном случае, будет осуществляться чтение файликов *.log из папки /var/log/containers/ , которая была смонтирована с хоста + +* Filters. В этом блоке указывается как будет осуществляться обработка логов. В данном случае: для каждого лога будут найдены соответствующие метаданные (в помощью kubernetes фильтра), а также, вырезаны неиспользуемые поля (_p, time) + +* Outputs. В этом блоке указывается куда будут отгружены логи. В данном случае в табличку `fluent-bit/log` в кластере {{ ydb-short-name }}. Параметры подключения к кластеру (ConnectionURL, CredentialsToken) задаются с помощью соответствующих переменных окружений – `OUTPUT_YDB_CONNECTION_URL`, `OUTPUT_YDB_CREDENTIALS_TOKEN` + +Переменные окружения определяются следующим образом: + +```yaml +env: + - name: OUTPUT_YDB_CONNECTION_URL + value: grpc://ydb-endpoint:2135/path/to/database + - name: OUTPUT_YDB_CREDENTIALS_TOKEN + valueFrom: + secretKeyRef: + key: token + name: fluent-bit-ydb-plugin-token +``` + +Секретный авторизационный токен необходимо создать заранее в кластере. Например, с помощью команды: + +```sh +kubectl create secret -n ydb-fluent-bit-integration generic fluent-bit-ydb-plugin-token --from-literal=token= +``` + +## Развертывание FluentBit + +HELM – способ пакетирования и установки приложений в кластере Kubernetes. Для развертывания FluentBit необходимо добавить репозиторий с чартом с помощью команды: + +```sh +helm repo add fluent https://fluent.github.io/helm-charts +``` + +Установка FluentBit в кластер Kubernetes выполняется с помощью следующей команды: + +```sh +helm upgrade --install fluent-bit fluent/fluent-bit \ + --version 0.37.1 \ + --namespace ydb-fluent-bit-integration \ + --create-namespace \ + --values values.yaml +``` + +## Проверяем установку + +Проверяем что fluent-bit запустился, читая его логи (должны отсутствовать записи уровня [error]): + +```sh +kubectl logs -n ydb-fluent-bit-integration -l app.kubernetes.io/instance=fluent-bit +``` + +Проверяем что записи в таблице YDB есть (появятся спустя примерно несколько минут после запуска FluentBit): + +```sql +SELECT * FROM `fluent-bit/log` LIMIT 10 ORDER BY `timestamp` DESC +``` + +## Очистка ресурсов + +Достаточно удалить namespace с установленным fluent-bit: + +```sh +kubectl delete namespace ydb-fluent-bit-integration +``` + +И таблицу с логами: + +```sql +DROP TABLE `fluent-bit/log` +``` \ No newline at end of file diff --git a/ydb/docs/ru/core/integrations/toc_i.yaml b/ydb/docs/ru/core/integrations/toc_i.yaml new file mode 100644 index 000000000000..8b0376cf0516 --- /dev/null +++ b/ydb/docs/ru/core/integrations/toc_i.yaml @@ -0,0 +1,3 @@ +items: +- name: Сбор логов в кластере Kubernetes с помощью FluentBit и YDB + href: fluent-bit.md diff --git a/ydb/docs/ru/core/integrations/toc_p.yaml b/ydb/docs/ru/core/integrations/toc_p.yaml new file mode 100644 index 000000000000..5bfec4365def --- /dev/null +++ b/ydb/docs/ru/core/integrations/toc_p.yaml @@ -0,0 +1,2 @@ +items: +- include: { mode: link, path: toc_i.yaml } \ No newline at end of file diff --git a/ydb/docs/ru/core/toc_i.yaml b/ydb/docs/ru/core/toc_i.yaml index bd5459b33d90..910fea61fcec 100644 --- a/ydb/docs/ru/core/toc_i.yaml +++ b/ydb/docs/ru/core/toc_i.yaml @@ -19,6 +19,7 @@ items: # References - { name: YQL, include: { mode: link, path: yql/toc_p.yaml } } - { name: Совместимость с PostgreSQL, include: { mode: link, path: postgresql/toc_p.yaml } } +- { name: Интеграции, include: { mode: link, path: integrations/toc_p.yaml } } - { name: Работа с YDB CLI, include: { mode: link, path: reference/ydb-cli/toc_p.yaml } } - { name: Работа с YDB SDK, include: { mode: link, path: reference/ydb-sdk/toc_p.yaml } } - { name: Работа с Kafka API, include: { mode: link, path: reference/kafka-api/toc_p.yaml } }