Интеграция Amazon MSK с ClickHouse

Примечание: Политика, показанная в видео, является избыточно разрешительной и предназначена только для быстрого начала работы. См. ниже рекомендации по настройке IAM по принципу наименьших привилегий.

Предварительные требования

Мы предполагаем:

• вы знакомы с ClickHouse Connector Sink, Amazon MSK и MSK Connectors. Рекомендуем руководство Amazon MSK Getting Started guide и MSK Connect guide.
• брокер MSK доступен из публичной сети. См. раздел Public Access в Developer Guide.

Официальный коннектор Kafka от ClickHouse для Amazon MSK

Соберите сведения для подключения

To connect to ClickHouse with HTTP(S) you need this information:

Parameter(s)	Description
HOST and PORT	Typically, the port is 8443 when using TLS or 8123 when not using TLS.
DATABASE NAME	Out of the box, there is a database named default, use the name of the database that you want to connect to.
USERNAME and PASSWORD	Out of the box, the username is default. Use the username appropriate for your use case.

The details for your ClickHouse Cloud service are available in the ClickHouse Cloud console. Select a service and click Connect:

Choose HTTPS. Connection details are displayed in an example curl command.

If you are using self-managed ClickHouse, the connection details are set by your ClickHouse administrator.

Шаги

1. Ознакомьтесь с ClickHouse Connector Sink.
2. Создайте экземпляр MSK.
3. Создайте и назначьте роль IAM.
4. Загрузите файл jar со страницы релизов ClickHouse Connector Sink (Release page).
5. Установите загруженный файл jar на странице Custom plugin консоли Amazon MSK.
6. Если коннектор взаимодействует с публичным экземпляром ClickHouse, включите доступ в интернет.
7. Укажите имя топика, имя хоста экземпляра ClickHouse и пароль в конфигурации.

connector.class=com.clickhouse.kafka.connect.ClickHouseSinkConnector
tasks.max=1
topics=<topic_name>
ssl=true
security.protocol=SSL
hostname=<hostname>
database=<database_name>
password=<password>
ssl.truststore.location=/tmp/kafka.client.truststore.jks
port=8443
value.converter.schemas.enable=false
value.converter=org.apache.kafka.connect.json.JsonConverter
exactlyOnce=true
username=default
schemas.enable=false

Рекомендуемые разрешения IAM (минимально необходимые привилегии)

Используйте наименьший набор разрешений, необходимых для вашей конфигурации. Начните с базового набора ниже и добавляйте дополнительные службы только в том случае, если вы их используете.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MSKClusterAccess",
      "Effect": "Allow",
      "Action": [
        "kafka:DescribeCluster",
        "kafka:GetBootstrapBrokers",
        "kafka:DescribeClusterV2",
        "kafka:ListClusters",
        "kafka:ListClustersV2"
      ],
      "Resource": "*"
    },
    {
      "Sid": "KafkaAuthorization",
      "Effect": "Allow",
      "Action": [
        "kafka-cluster:Connect",
        "kafka-cluster:DescribeCluster",
        "kafka-cluster:DescribeGroup",
        "kafka-cluster:DescribeTopic",
        "kafka-cluster:ReadData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "OptionalGlueSchemaRegistry",
      "Effect": "Allow",
      "Action": [
        "glue:GetSchema*",
        "glue:ListSchemas",
        "glue:ListSchemaVersions"
      ],
      "Resource": "*"
    },
    {
      "Sid": "OptionalSecretsManager",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue"
      ],
      "Resource": [
        "arn:aws:secretsmanager:<region>:<account-id>:secret:<your-secret-name>*"
      ]
    },
    {
      "Sid": "OptionalS3Read",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": "arn:aws:s3:::<your-bucket>/<optional-prefix>/*"
    }
  ]
}

• Используйте блок Glue только если вы применяете AWS Glue Schema Registry.
• Используйте блок Secrets Manager только если вы получаете учетные данные и truststore из Secrets Manager. Ограничьте область действия ARN.
• Используйте блок S3 только если вы загружаете артефакты (например, truststore) из S3. Ограничьте область действия bucket/префикса.

См. также: Рекомендации по работе с Kafka – IAM.

Настройка производительности

Один из способов повысить производительность — изменить размер пакета и количество записей, извлекаемых из Kafka, добавив следующее в конфигурацию worker:

consumer.max.poll.records=[NUMBER OF RECORDS]
consumer.max.partition.fetch.bytes=[NUMBER OF RECORDS * RECORD SIZE IN BYTES]

Конкретные значения, которые вы будете использовать, будут отличаться в зависимости от требуемого количества записей и их размера. Например, значения по умолчанию таковы:

consumer.max.poll.records=500
consumer.max.partition.fetch.bytes=1048576

Вы можете найти более подробную информацию (как по реализации, так и по другим аспектам) в официальной документации Kafka и Amazon MSK.

Заметки по сетевой конфигурации для MSK Connect

Чтобы MSK Connect мог подключаться к ClickHouse, мы рекомендуем размещать ваш кластер MSK в приватной подсети с подключённым Private NAT для доступа в интернет. Инструкции по настройке приведены ниже. Обратите внимание, что публичные подсети поддерживаются, но не рекомендуются из‑за необходимости постоянно назначать Elastic IP-адрес вашему ENI, подробнее об этом см. в документации AWS

1. Создайте приватную подсеть: Создайте новую подсеть в рамках вашего VPC и обозначьте её как приватную. Эта подсеть не должна иметь прямого доступа в интернет.
2. Создайте NAT-шлюз: Создайте NAT-шлюз в публичной подсети вашего VPC. NAT-шлюз позволяет инстансам в вашей приватной подсети подключаться к интернету или другим сервисам AWS, но предотвращает установку входящих подключений из интернета к этим инстансам.
3. Обновите таблицу маршрутизации: Добавьте маршрут, направляющий трафик в интернет к NAT-шлюзу.
4. Проверьте конфигурацию Security Groups и сетевых ACL: Настройте ваши security groups и сетевые ACL (Access Control Lists) так, чтобы они разрешали необходимый трафик.
   1. От рабочих ENI MSK Connect к брокерам MSK по TLS-порту (обычно 9094).
   2. От рабочих ENI MSK Connect к конечной точке ClickHouse: 9440 (нативный TLS) или 8443 (HTTPS).
   3. Разрешите входящий трафик на security group брокера от security group рабочих MSK Connect.
   4. Для самостоятельно развернутого (self-hosted) ClickHouse откройте порт, настроенный на вашем сервере (по умолчанию 8123 для HTTP).
5. Привяжите Security Groups к MSK: Убедитесь, что соответствующие security groups привязаны к вашему кластеру MSK и рабочим MSK Connect.
6. Подключение к ClickHouse Cloud:
   1. Публичная конечная точка + список разрешённых IP-адресов (IP allowlist): требует исходящего трафика через NAT из приватных подсетей.
   2. Приватное подключение, где доступно (например, VPC peering/PrivateLink/VPN). Убедитесь, что включены DNS-имена VPC и разрешение DNS (VPC DNS hostnames/resolution), и что DNS может разрешать приватную конечную точку.
7. Проверьте подключение (краткий чек‑лист):
   1. В среде коннектора убедитесь, что разрешается DNS-имя bootstrap для MSK и выполняется подключение по TLS к порту брокера.
   2. Установите TLS-подключение к ClickHouse на порт 9440 (или 8443 для HTTPS).
   3. Если используются сервисы AWS (Glue/Secrets Manager), разрешите исходящий трафик к их конечным точкам.