new kafka api doc

kafka api doc

7 files changed, 160 insertions, 0 deletions

diff --git a/ydb/docs/ru/core/concepts/topic.md b/ydb/docs/ru/core/concepts/topic.md
index 73432440db..fd20eb8c05 100644
--- a/ydb/docs/ru/core/concepts/topic.md
+++ b/ydb/docs/ru/core/concepts/topic.md
@@ -144,3 +144,10 @@
 Так как длительный простой важного читателя может привести к использованию всего свободного места хранения данных непрочитанными сообщениями, необходимо следить за отставанием чтения важных читателей
 
 {% endnote %}
+
+## Протоколы для работы с топиками {#topic-protocols}
+
+Для работы с топиками используется YDB SDK (см. [Работа с топиками](../reference/ydb-sdk/topic.md)).
+
+Также ограниченно поддержан протокол Kafka API версии 3.4.0. (см. [Работа с Kafka API](../reference/kafka-api/index.md)).
+
diff --git a/ydb/docs/ru/core/reference/kafka-api/constraints.md b/ydb/docs/ru/core/reference/kafka-api/constraints.md
new file mode 100644
index 0000000000..ba1b1680ca
--- /dev/null
+++ b/ydb/docs/ru/core/reference/kafka-api/constraints.md
@@ -0,0 +1,9 @@
+Поддержка протокола Kafka версии 3.4.0 осуществляется в ограниченном объеме:
+
+1. Разрешены только аутентифицированные подключения.
+2. Поддержана только SASL/PLAIN-аутентификация.
+3. Не поддержано сжатие сообщений.
+4. В чтении поддержан только Manual Partition Assignment, [метод assign](https://kafka.apache.org/35/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html#assign(java.util.Collection)), без использования групп партиций консьюмеров.
+5. Не поддержаны транзакции.
+6. Не поддержаны DDL операции. Для осуществления DDL-операций пользуйтесь [YDB SDK](../ydb-sdk/index.md) или [YDB CLI](../ydb-cli/index.md).
+7. Не поддержана проверка схемы данных.
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/kafka-api/examples.md b/ydb/docs/ru/core/reference/kafka-api/examples.md
new file mode 100644
index 0000000000..3c6ea56c9f
--- /dev/null
+++ b/ydb/docs/ru/core/reference/kafka-api/examples.md
@@ -0,0 +1,127 @@
+# Примеры использования Kafka API
+
+В этой статье приведены примеры использования Kafka API для работы с [топиками](../../concepts/topic.md).
+
+Перед выполнением примеров [создайте топик](../ydb-cli/topic-create.md) и [добавьте читателя](../ydb-cli/topic-consumer-add.md).
+
+## Примеры работы с топиками
+
+В примерах используются:
+
+ * `ydb:9093` — имя хоста.
+ * `/Root/Database` — название базы данных.
+ * `/Root/Database/Topic` — имя топика.
+ * `user@/Root/Database` — имя пользователя. Имя пользователя указывается полностью и включает название базы данных.
+ * `*****` — пароль пользователя.
+
+
+## Запись данных в топик
+
+### Запись через Kafka Java SDK
+
+В этом примере приведен фрагмент кода для записи в топик через Kafka API.
+
+  ```java
+  String HOST = "ydb:9093";
+  String TOPIC = "/Root/Database/Topic";
+  String USER = "user@/Root/Database";
+  String PASS = "*****";
+
+  Properties props = new Properties();
+  props.put("bootstrap.servers", HOST);
+  props.put("acks", "all");
+
+  props.put("key.serializer", StringSerializer.class.getName());
+  props.put("key.deserializer", StringDeserializer.class.getName());
+  props.put("value.serializer", StringSerializer.class.getName());
+  props.put("value.deserializer", StringDeserializer.class.getName());
+
+  props.put("security.protocol", "SASL_SSL");
+  props.put("sasl.mechanism", "PLAIN");
+  props.put("sasl.jaas.config", PlainLoginModule.class.getName() + " required username=\"" + USER + "\" password=\"" + PASS + "\";");
+
+  props.put("compression.type", "none");
+
+  Producer<String, String> producer = new KafkaProducer<>(props);
+  producer.send(new ProducerRecord<String, String>(TOPIC, "msg-key", "msg-body"));
+  producer.flush();
+  producer.close();
+  ```
+
+### Запись через Logstash
+
+Для настройки [Logstash](https://github.com/elastic/logstash) используйте следующие параметры:
+
+  ```
+  output {
+    kafka {
+      codec => json
+      topic_id => "/Root/Database/Topic"
+      bootstrap_servers => "ydb:9093"
+      compression_type => none
+      security_protocol => SASL_SSL
+      sasl_mechanism => PLAIN
+      sasl_jaas_config => "org.apache.kafka.common.security.plain.PlainLoginModule required username='user@/Root/Database' password='*****';"
+    }
+  }
+  ```
+
+### Запись через Fluent Bit
+
+Для настройки [Fluent Bit](https://github.com/fluent/fluent-bit) используйте следующие параметры:
+
+  ```
+  [OUTPUT]
+    name                          kafka
+    match                         *
+    Brokers                       ydb:9093
+    Topics                        /Root/Database/Topic
+    rdkafka.client.id             Fluent-bit
+    rdkafka.request.required.acks 1
+    rdkafka.log_level             7
+    rdkafka.security.protocol     SASL_SSL
+    rdkafka.sasl.mechanism        PLAIN
+    rdkafka.sasl.username         user@/Root/Database
+    rdkafka.sasl.password         *****
+  ```
+
+## Чтение данных из топика
+
+### Чтение данных из топика через Kafka Java SDK
+
+В этом примере приведен фрагмент кода для чтения данных из топика через Kafka API.
+
+```java
+  String HOST = "ydb:9093";
+  String TOPIC = "/Root/Database/Topic";
+  String USER = "user@/Root/Database";
+  String PASS = "*****";
+
+  Properties props = new Properties();
+  props.put("bootstrap.servers", HOST);
+  props.put("auto.offset.reset", "earliest"); // to read from start
+  props.put("check.crcs", false);
+
+  props.put("key.deserializer", StringDeserializer.class.getName());
+  props.put("value.deserializer", StringDeserializer.class.getName());
+
+  props.put("security.protocol", "SASL_SSL");
+  props.put("sasl.mechanism", "PLAIN");
+  props.put("sasl.jaas.config", PlainLoginModule.class.getName() + " required username=\"" + USER + "\" password=\"" + PASS + "\";");
+
+  Consumer<String, String> consumer = new KafkaConsumer<>(props);
+
+  List<PartitionInfo> partitionInfos = consumer.partitionsFor(TOPIC);
+  List<TopicPartition> topicPartitions = new ArrayList<>();
+
+  for (PartitionInfo partitionInfo : partitionInfos) {
+      topicPartitions.add(new TopicPartition(partitionInfo.topic(), partitionInfo.partition()));
+  }
+  consumer.assign(topicPartitions);
+
+  while (true) {
+      ConsumerRecords<String, String> records = consumer.poll(1000);
+      for (ConsumerRecord<String, String> record : records) {
+          System.out.println(record.key() + ":" + record.value());
+      }
+  }
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/kafka-api/index.md b/ydb/docs/ru/core/reference/kafka-api/index.md
new file mode 100644
index 0000000000..b55d7c3726
--- /dev/null
+++ b/ydb/docs/ru/core/reference/kafka-api/index.md
@@ -0,0 +1,7 @@
+# Kafka API
+
+YDB поддерживает работу с топиками по протоколу [Kafka версия 3.4.0](https://kafka.apache.org/34/documentation.html). 
+
+[Ограничения использования Kafka API](constraints.md)
+
+[Примеры использования Kafka API](examples.md)
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/kafka-api/toc_i.yaml b/ydb/docs/ru/core/reference/kafka-api/toc_i.yaml
new file mode 100644
index 0000000000..978f1c136c
--- /dev/null
+++ b/ydb/docs/ru/core/reference/kafka-api/toc_i.yaml
@@ -0,0 +1,5 @@
+items:
+  - name: Ограничения
+    href: constraints.md
+  - name: Примеры использования
+    href: examples.md
\ No newline at end of file
diff --git a/ydb/docs/ru/core/reference/kafka-api/toc_p.yaml b/ydb/docs/ru/core/reference/kafka-api/toc_p.yaml
new file mode 100644
index 0000000000..3e62ad228b
--- /dev/null
+++ b/ydb/docs/ru/core/reference/kafka-api/toc_p.yaml
@@ -0,0 +1,4 @@
+items:
+- name: Обзор
+  href: index.md
+- 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 402a141881..3dfa49a5a8 100644
--- a/ydb/docs/ru/core/toc_i.yaml
+++ b/ydb/docs/ru/core/toc_i.yaml
@@ -23,6 +23,7 @@ items:
 - { name: Совместимость с PostgreSQL,              include: { mode: link, path: postgresql/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 } }
 - name: Разработка
   # hidden: true
   items: