SensusAgent/docs/kafka_ssl.md

Kafka SSL поддержка в SensusAgent

Автор: Сергей Антропов, сайт: https://devops.org.ru

Обзор

SensusAgent теперь поддерживает SSL/TLS подключения к Kafka для обеспечения безопасной передачи метрик. Эта функциональность позволяет использовать зашифрованные соединения между агентом и Kafka брокером.

Конфигурация SSL

1. Настройка в config.yaml

kafka:
  enabled: true
  brokers: ["10.99.0.90:9093"]  # SSL порт
  topic: "sensus.metrics"
  client_id: "sensusagent"
  enable_tls: false  # Устаревшая настройка, используйте ssl_enabled
  timeout: "5s"
  
  # SSL настройки
  ssl_enabled: true
  ssl_keystore_location: "/var/ssl/private/kafka.client.keystore.jks"
  ssl_keystore_password: "kafka123"
  ssl_key_password: "kafka123"
  ssl_truststore_location: "/var/ssl/private/kafka.client.truststore.jks"
  ssl_truststore_password: "kafka123"
  ssl_client_auth: "none"  # none, required, requested
  ssl_endpoint_identification_algorithm: "https"  # https, none

2. Настройка через переменные окружения

# Основные настройки
KAFKA_BROKERS=kafka:9093
KAFKA_TOPIC=sensus.metrics
KAFKA_CLIENT_ID=sensusagent

# SSL настройки
KAFKA_SSL_ENABLED=true
KAFKA_SSL_KEYSTORE_PASSWORD=kafka123
KAFKA_SSL_KEY_PASSWORD=kafka123
KAFKA_SSL_TRUSTSTORE_PASSWORD=kafka123
KAFKA_SSL_CLIENT_AUTH=none
KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM=https

Параметры SSL конфигурации

Параметр	Описание	Возможные значения	По умолчанию
ssl_enabled	Включение SSL подключения	true, false	false
ssl_keystore_location	Путь к клиентскому keystore	Путь к файлу	/var/ssl/private/kafka.client.keystore.jks
ssl_keystore_password	Пароль keystore	Строка	kafka123
ssl_key_password	Пароль приватного ключа	Строка	kafka123
ssl_truststore_location	Путь к клиентскому truststore	Путь к файлу	/var/ssl/private/kafka.client.truststore.jks
ssl_truststore_password	Пароль truststore	Строка	kafka123
ssl_client_auth	Требование аутентификации клиента	none, required, requested	none
ssl_endpoint_identification_algorithm	Алгоритм идентификации endpoint	https, none	https

Docker конфигурация

1. В docker-compose.yml

sensus-agent:
  environment:
    KAFKA_SSL_ENABLED: "true"
    KAFKA_SSL_KEYSTORE_PASSWORD: "kafka123"
    KAFKA_SSL_KEY_PASSWORD: "kafka123"
    KAFKA_SSL_TRUSTSTORE_PASSWORD: "kafka123"
    KAFKA_SSL_CLIENT_AUTH: "none"
    KAFKA_SSL_ENDPOINT_IDENTIFICATION_ALGORITHM: "https"
  volumes:
    - ./kafka-ssl:/var/ssl/private:ro

2. Структура SSL сертификатов

kafka-ssl/
├── kafka.client.keystore.jks    # Клиентский keystore
├── kafka.client.truststore.jks  # Клиентский truststore
├── kafka.server.keystore.jks    # Серверный keystore (для брокера)
├── kafka.server.truststore.jks  # Серверный truststore (для брокера)
├── ca-cert                       # CA сертификат
└── ca-key                        # CA приватный ключ

Генерация SSL сертификатов

Используйте скрипт из SensusInfra для генерации сертификатов:

cd ../SensusInfra
./kafka-ssl/generate-ssl.sh

Безопасность

Рекомендации для production:

1. Измените пароли по умолчанию - никогда не используйте kafka123 в production
2. Используйте сильные пароли - минимум 16 символов с различными типами символов
3. Ограничьте доступ к сертификатам - установите права доступа 600
4. Регулярно обновляйте сертификаты - установите напоминание о сроке действия
5. Используйте ssl_client_auth: "required" для строгой аутентификации

Пример безопасной конфигурации:

kafka:
  ssl_enabled: true
  ssl_client_auth: "required"
  ssl_endpoint_identification_algorithm: "https"
  ssl_keystore_password: "StrongPassword123!@#"
  ssl_key_password: "StrongPassword123!@#"
  ssl_truststore_password: "StrongPassword123!@#"

Диагностика

Логи SSL подключения

При включенном SSL в логах будут отображаться:

INFO kafka ssl enabled endpoint_identification=https client_auth=none
INFO kafka connected brokers=[kafka:9093] topic=sensus.metrics ssl_enabled=true

Проверка подключения

# Проверка доступности SSL порта
telnet kafka 9093

# Проверка сертификатов
keytool -list -keystore kafka-ssl/kafka.client.keystore.jks -storepass kafka123

Устранение неполадок

Частые проблемы:

1. "SSL handshake failed"

   • Проверьте правильность паролей
   • Убедитесь, что сертификаты не истекли
   • Проверьте соответствие CN в сертификате

2. "Connection refused"

   • Убедитесь, что используете SSL порт (9093)
   • Проверьте, что Kafka брокер настроен на SSL

3. "Certificate verification failed"

   • Установите ssl_endpoint_identification_algorithm: "none" для тестирования
   • Проверьте, что truststore содержит правильный CA сертификат

Отладка:

# Включите debug логирование
LOG_LEVEL=debug

# Проверьте конфигурацию
docker exec sensus-agent cat /bin/agent/config.yaml

Миграция с обычного подключения

1. Сгенерируйте SSL сертификаты
2. Обновите config.yaml или переменные окружения
3. Измените порт с 9092 на 9093
4. Установите ssl_enabled: true
5. Перезапустите агент

Совместимость

• Kafka версии: 2.8+ (рекомендуется 3.0+)
• Go версия: 1.19+
• kafka-go библиотека: последняя версия

Поддержка

При возникновении проблем:

1. Проверьте логи агента
2. Убедитесь в правильности конфигурации
3. Проверьте доступность Kafka брокера
4. Обратитесь к документации Kafka SSL