SensusAgent/docs/kafka_ssl.md

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

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

## Обзор

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

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

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

```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. Настройка через переменные окружения

```bash
# Основные настройки
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

```yaml
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 для генерации сертификатов:

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

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

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

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

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

```yaml
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
```

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

```bash
# Проверка доступности 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 сертификат

### Отладка:

```bash
# Включите 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