изменение расположения документации
This commit is contained in:
Левченко Людмила Алексеевна
@@ -0,0 +1,244 @@
|
||||
# Подключение и работа с кластером Kafka (тариф Base)
|
||||
|
||||
Раздел содержит описание способов подключения к управлению кластером Kafka. Поддерживаются два типа подключения:
|
||||
- `SASL_PLAINTEXT` - незашифрованное;
|
||||
- `SASL_SSL` - зашифрованное (через SSL-сертификат).
|
||||
|
||||
Также в разделе приведены примеры работы с клиентскими утилитами и базовые операции администрирования.
|
||||
|
||||
## Предварительные требования
|
||||
|
||||
Для начала работы с кластером Kafka необходимо выполнить предварительную настройку:
|
||||
|
||||
1. **Установить клиент Kafka** - скачивается дистрибутив Kafka (например, kafka_2.13-4.2.0) и распаковывается в удобную директорию;
|
||||
2. **Установить среду выполнения Java** - для работы необходимо установить среду выполнения, с помощью команды: `sudo apt install openjdk-17-jre-headless`. Рекомендуется использовать версию OpenJDK 17 или выше;
|
||||
3. **Доступ к брокерам** - адреса брокеров (bootstrap servers) предоставляются после развертывания кластера;
|
||||
4. **Учетные данные**:
|
||||
- **Имя пользователя (username)** - стандартное значение client;
|
||||
- **Пароль** - предоставляется после развертывания кластера.
|
||||
5. **Корневой сертификат (для SSL-подключения)** - сертификат для зашифрованного подключения предоставляется файлом при заказе сервиса Kafka.
|
||||
|
||||
## Структура клиентского дистрибутива
|
||||
|
||||
После распаковки архива Kafka в директории bin доступны основные скрипты для управления:
|
||||
|
||||
| Скрипт | Назначение |
|
||||
| --------------------------- | -------------------------------------------------- |
|
||||
| `kafka-topics.sh` | Управление топиками (создание, удаление, просмотр) |
|
||||
| `kafka-console-producer.sh` | Отправка сообщений в топик |
|
||||
| `kafka-console-consumer.sh` | Чтение сообщений из топика |
|
||||
| `kafka-consumer-groups.sh` | Управление консьюмер-группами |
|
||||
| `kafka-configs.sh` | Изменение конфигурации топиков и других объектов |
|
||||
| `kafka-acls.sh` | Управление списками доступа (ACL) |
|
||||
|
||||
В разделе ниже приведены примеры использования скриптов.
|
||||
|
||||
Подробное описание операций с данными и другими скриптами приведено в [официальной документации Kafka](https://kafka.apache.org/42/getting-started/introduction/). Дополнительную информацию можно получить, выполнив любой скрипт с флагом --help:
|
||||
|
||||
```
|
||||
./kafka-topics.sh --help
|
||||
```
|
||||
|
||||
#### Конфигурационные файлы клиента
|
||||
|
||||
Для подключения к Kafka используется файл настроек **client.properties**, который содержит параметры аутентификации, протокола и его механизмов (рекомендуются SCRAM_SHA_512 и SCRAM_SHA_256).
|
||||
|
||||
## Незашифрованное подключение (SASL_PLAINTEXT)
|
||||
|
||||
Создается файл **client.properties** со следующим содержимым:
|
||||
|
||||
```
|
||||
sasl.mechanism=SCRAM-SHA-512
|
||||
security.protocol=SASLPLAINTEXT
|
||||
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \
|
||||
username="client" \
|
||||
password="вашпароль";
|
||||
```
|
||||
|
||||
::: warning Примечание
|
||||
Для незашифрованного подключения (SASL_PLAINTEXT) используется порт 9091;
|
||||
:::
|
||||
|
||||
## Зашифрованное подключение (SASL_SSL)
|
||||
|
||||
Для зашифрованного подключения (в production-средах рекомендуется использовать именно его) дополнительно требуется корневой сертификат и хранилище доверенных сертификатов (truststore).
|
||||
|
||||
::: warning Примечание
|
||||
Для зашифрованного подключения (SASL_SSL) используется порт 9092.
|
||||
:::
|
||||
|
||||
### Шаг 1. Создание truststore
|
||||
|
||||
С помощью утилиты **keytool** выполняется импорт сертификата в хранилище:
|
||||
|
||||
```
|
||||
keytool -importcert -storetype PKCS12 -keystore /путь/к/трастстору/truststore.jks -alias myalias -file ca.crt -storepass любойвашпароль -keypass любойвашпароль
|
||||
```
|
||||
|
||||
Параметры:
|
||||
|
||||
- **keystore** - путь к создаваемому хранилищу;
|
||||
- **alias** - псевдоним сертификата в хранилище;
|
||||
- **file** - путь к загруженному корневому сертификату;
|
||||
- **storepass** - пароль для доступа к хранилищу;
|
||||
- **keypass** - пароль для доступа к ключу.
|
||||
|
||||
### Шаг 2. Настройка client.properties
|
||||
|
||||
В файл **client.properties** добавляются параметры SSL:
|
||||
|
||||
```
|
||||
sasl.mechanism=SCRAM-SHA-512
|
||||
security.protocol=SASLSSL
|
||||
sasl.jaas.config=org.apache.kafka.common.security.scram.ScramLoginModule required \
|
||||
username="client" \
|
||||
password="вашпароль";
|
||||
ssl.truststore.location=/путь/к/трастстору/truststore.jks
|
||||
ssl.truststore.password=парольотхранилища
|
||||
```
|
||||
|
||||
## Работа с кластером Kafka
|
||||
|
||||
### Создание топиков
|
||||
|
||||
```
|
||||
./kafka-topics.sh --bootstrap-server <IP машины 0>:9092,<IP машины 1>:9092,<IP машины X>:9092 --command-config ../config/client.properties --create --topic <имя топика> --partitions <количество партиций> --replication-factor <значение> --config min.insync.replicas=<значение>
|
||||
```
|
||||
|
||||
**Ознакомиться с рекомендациями по настройке топиков можно в разделе [Настройка топиков](./base-tier-topics-guide.md).**
|
||||
|
||||
По умолчанию топик создаётся с --partitions 10 --replication-factor 3 --config min.insync.replicas=2, поэтому, если нет необходимости создавать топик со специфическими настройками, эти флаги в команде можно не указывать.
|
||||
|
||||
### Просмотр списка топиков
|
||||
|
||||
Выполняется команда с указанием брокеров и файла конфигурации:
|
||||
|
||||
```
|
||||
./kafka-topics.sh --bootstrap-server <IP_брокера_0>:9092,<IP_брокера_1>:9092,<IP_брокера_2>:9092 --command-config ~/client.properties --list
|
||||
```
|
||||
|
||||
Параметры:
|
||||
|
||||
- **bootstrap-server** - список брокеров кластера (адреса и порты);
|
||||
command-config - путь к файлу с настройками клиента;
|
||||
- **list** - вывод списка топиков.
|
||||
|
||||
### Отправка сообщения в топик
|
||||
|
||||
Выполняется команда с указанием брокеров, файла конфигурации и топика:
|
||||
|
||||
```
|
||||
./kafka-console-producer.sh --bootstrap-server <IP_брокера_0>:9092,<IP_брокера_1>:9092,<IP_брокера_2>:9092 --command-config~/client.properties --topic test-topic
|
||||
```
|
||||
|
||||
После выполнения команды сообщения вводятся построчно. Для завершения используется сочетание клавиш Ctrl+C.
|
||||
|
||||
### Чтение сообщений из топика
|
||||
|
||||
Выполняется команда с указанием топика и, при необходимости, consumer group:
|
||||
|
||||
```
|
||||
./kafka-console-consumer.sh --bootstrap-server <IP_брокера_0>:9092,<IP_брокера_1>:9092,<IP_брокера_2>:9092 --command-config~/client.properties --topic test-topic --from-beginning --group my-new-consumer-group
|
||||
```
|
||||
|
||||
Параметры:
|
||||
|
||||
- **from-beginning**- чтение всех сообщений с начала (при отсутствии параметра чтение начинается с новых сообщений);
|
||||
- **group** - название consumer group, которая создастся автоматически.
|
||||
|
||||
## Управление пользователями и доступом
|
||||
|
||||
### Рекомендации к созданию пароля
|
||||
|
||||
**Длина пароля (рекомендуемая):**
|
||||
|
||||
- для учётной записи пользователя - не менее 12 знаков;
|
||||
- для учётных записей администраторов, технических и служебных учётных записей - не менее 16 знаков.
|
||||
|
||||
**Сложность пароля:** рекомендуется использовать уникальный пароль, содержащий символы как минимум трёх из четырёх указанных ниже групп (при отсутствии технических ограничений):
|
||||
|
||||
- буквы латинского алфавита в верхнем регистре (A-Z);
|
||||
- буквы латинского алфавита в нижнем регистре (a-z);
|
||||
- цифры (0-9);
|
||||
- специальные символы и знаки пунктуации (например, `!@#$%^&*(),.?`).
|
||||
|
||||
**Периодичность смены:** рекомендуемая периодичность смены пароля - не реже одного раза в год.
|
||||
|
||||
### Создание пользователей
|
||||
|
||||
Для удобства можно написать скрипт, который создает пользователя сразу для двух методов шифрования - SHA-256 и SHA-512:
|
||||
|
||||
```
|
||||
#!/bin/bash
|
||||
username="имя_пользователя"
|
||||
password="сгенерированный_пароль"
|
||||
bootstrap="<IP_брокера_0>:9092,<IP_брокера_1>:9092,<IP_брокера_X>:9092"
|
||||
|
||||
/opt/kafka/bin/kafka-configs.sh \
|
||||
--bootstrap-server $bootstrap \
|
||||
--alter \
|
||||
--add-config SCRAM-SHA-256=[password="$password"] \
|
||||
--command-config /opt/kafka/config/client.properties \
|
||||
--entity-type users \
|
||||
--entity-name $username
|
||||
|
||||
/opt/kafka/bin/kafka-configs.sh \
|
||||
--bootstrap-server $bootstrap \
|
||||
--alter \
|
||||
--add-config SCRAM-SHA-512=[password="$password"] \
|
||||
--command-config /opt/kafka/config/client.properties \
|
||||
--entity-type users \
|
||||
--entity-name $username
|
||||
```
|
||||
|
||||
**Запуск скрипта:**
|
||||
|
||||
```
|
||||
sudo ./kafka-user-add.sh
|
||||
```
|
||||
|
||||
### Просмотр данных о пользователе
|
||||
|
||||
Для просмотра информации о существующих пользователях выполняется команда:
|
||||
|
||||
```
|
||||
sudo ./kafka-console-consumer.sh --bootstrap-server <IP_брокеров>:9092 --describe --command-config ../config/client.properties --entity-type users
|
||||
```
|
||||
|
||||
### Управление consumer groups
|
||||
|
||||
Consumer Group создается автоматически при обращении к ней. Например, при чтении сообщений из топика с указанием этой consumer group:
|
||||
|
||||
```
|
||||
sudo ./kafka-console-consumer.sh --bootstrap-server <IP_брокеров>:9092 --command-config ../config/client.properties --topic test-topic --group test-group --from-beginning
|
||||
```
|
||||
|
||||
### Просмотр списка ACL
|
||||
|
||||
Действия с ACL из командной строки осуществляются скриптом kafka-acls.sh. Пример просмотра списка ACL:
|
||||
|
||||
```
|
||||
sudo ./kafka-acls.sh --bootstrap-server <IP_брокера_0>:9092,<IP_брокера_1>:9092,<IP_брокера_X>:9092 --command-config ../config/client.properties --list
|
||||
```
|
||||
|
||||
## Администрирование кластера
|
||||
|
||||
#### Изменение объема RAM
|
||||
|
||||
Для изменения объема оперативной памяти, выделенной под Kafka, направляется обращение в техническую поддержку с указанием требуемого объема RAM.
|
||||
|
||||
#### Изменение количества брокеров
|
||||
|
||||
Выполняется также через обращение в техническую поддержку.
|
||||
|
||||
Брокеров в кластере рекомендуется поддерживать **нечетным** для корректной работы механизмов выборов лидера.
|
||||
|
||||
После добавления брокера выполняется перераспределение существующих партиций с учетом нового узла с помощью утилиты **kafka-reassign-partitions.sh:**
|
||||
|
||||
```
|
||||
./kafka-reassign-partitions.sh --bootstrap-server <адреса_брокеров> --generate --topics-to-move-json-file topics.json --broker-list "0,1,2" --execute
|
||||
```
|
||||
|
||||
::: warning Примечание
|
||||
Операция перераспределения партиций требует времени и может создавать дополнительную нагрузку на кластер. Выполнение рекомендуется в период наименьшей активности.
|
||||
:::
|
||||
Reference in New Issue
Block a user