Skip to content

README.tr.md

Latest commit

 

History

History
183 lines (139 loc) · 6.93 KB

README.tr.md

File metadata and controls

183 lines (139 loc) · 6.93 KB

Kafka REST API (FastAPI) - Türkçe Dokümantasyon

İngilizce dokümantasyon için: README.md

Genel Bakış

Bu modül, FastAPI ile geliştirilmiş bir Kafka yönetim ve mesajlaşma REST API servisidir. Kafka broker, topic, producer, consumer, consumer group işlemleri ve kimlik doğrulama (JWT) sunar. Tüm işlemler JWT ile korunur. Uygulama, Docker ile kolayca dağıtılabilir ve GitHub Actions ile otomatik olarak kurulabilir.

Ana Özellikler

  • FastAPI tabanlı REST API: Kafka broker, topic, producer, consumer, consumer group yönetimi
  • JWT ile Kimlik Doğrulama: /token endpointi ile erişim token'ı alınır, tüm API'ler korumalıdır
  • Kullanıcı Arayüzü: Bootstrap tabanlı web arayüzü (index.html)
  • Kafka ile Tam Entegrasyon: Topic oluşturma, mesaj gönderme/alma, grup yönetimi
  • Dinamik Broker Tanımı: Kafka broker adresleri ortam değişkeninden veya Terraform state/S3 üzerinden otomatik alınabilir
  • Uzun Süreli Token: Kafka Connect gibi sistemler için 10 yıl geçerli token üretme scripti
  • Prometheus için Healthcheck: /health endpointi
  • Kolay Dağıtım: Dockerfile ve docker-compose ile hızlı kurulum
  • CI/CD: GitHub Actions ile otomatik kurulum ve test

Dizin ve Dosya Yapısı

Kimlik Doğrulama

  • Tüm API endpointleri JWT ile korunur.
  • /token endpointine kullanıcı adı ve şifre ile POST isteği atılır, access_token alınır.
  • API isteklerinde Authorization: Bearer header'ı zorunludur.
  • Uzun ömürlü token için: python generate_permanent_token.py komutu kullanılabilir.

auth

Temel API Endpointleri

Kimlik Doğrulama

  • POST /token: JWT token al token

Broker Yönetimi

  • GET /brokers: Tüm broker'ları listele brokers

Topic Yönetimi

  • POST /topics: Yeni topic oluştur
  • GET /topics: Tüm topic'leri listele
  • GET /topics/{topic}: Topic detayını al
  • PUT /topics/{topic}/config: Topic konfigürasyonunu güncelle
  • DELETE /topics/{topic}: Topic sil topics

Producer

  • POST /produce: Mesaj gönder producer

Consumer

  • POST /consume: Mesaj oku consumer

Consumer Group

  • GET /consumer-groups: Tüm consumer group'ları listele
  • GET /consumer-groups/{group_id}: Consumer group detayını al consumer_group

Healthcheck

  • GET /health: Servis sağlık kontrolü health

Kullanım Örneği

1. Docker ile Çalıştırma

docker-compose up -d

2. Token Alma

curl -X POST -d 'username=admin&password=admin123' http://localhost:2020/token

3. Broker Listeleme

curl -H "Authorization: Bearer <TOKEN>" http://localhost:2020/brokers

4. Topic Oluşturma

curl -X POST -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"name": "topic-1", "num_partitions": 3, "replication_factor": 2}' \
  http://localhost:2020/topics

5. Mesaj Gönderme

curl -X POST -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"topic": "topic-1", "value": "Merhaba Kafka!"}' \
  http://localhost:2020/produce

6. Mesaj Okuma

curl -X POST -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
  -d '{"topic": "topic-1", "group_id": "rest-api-consumer", "max_messages": 5}' \
  http://localhost:2020/consume

Ortam Değişkenleri ve Konfigürasyon

  • KAFKA_BOOTSTRAP_SERVERS: Kafka broker adresleri (virgül ile ayrılmış)
  • FETCH_BROKERS_FROM_TERRAFORM: true/false (Terraform state'ten broker çek)
  • AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY: S3 erişimi için
  • KAFKA_SECURITY_PROTOCOL, KAFKA_SASL_MECHANISM, KAFKA_SASL_USERNAME, KAFKA_SASL_PASSWORD: Güvenlik ayarları
  • API_USERNAME, API_PASSWORD, SECRET_KEY: API kimlik doğrulama ve JWT için

Ansible ile Otomatik Dağıtım ve S3 Entegrasyonu

  • Ansible playbook'ları, S3'teki Terraform state dosyasından Kafka Connect ve broker bilgilerini otomatik olarak çeker.
  • Envanter ve ortam dosyaları dinamik olarak oluşturulur.
  • Docker ve FastAPI uygulaması, bu bilgilerle otomatik olarak deploy edilir.
  • Tüm süreç GitHub Actions ile tam otomatikleştirilmiştir.

GitHub Actions ile Otomasyon

  • .github/workflows/ansible_kafka_api.yaml ile otomatik kurulum ve test
  • Her push'ta Docker içinde Ansible ile kurulum, envanter üretimi, S3'ten connect/broker bilgisi çekme, healthcheck ve playbook çalıştırma

actions

Web Arayüzü

  • http://localhost:2020 adresinden erişilebilir
  • Tüm işlemler arayüzden JWT ile güvenli şekilde yapılabilir

web

Güvenlik ve En İyi Pratikler

  • Varsayılan şifreleri değiştirin ve SECRET_KEY'i güçlü seçin
  • Token'ları kimseyle paylaşmayın, uzun ömürlü token'ları güvenli saklayın
  • Tüm trafik SSL ile korunmalıdır (prod ortamında reverse proxy önerilir)
  • Docker ve ortam değişkenlerini versiyon kontrolünde gizli tutun

Operasyonel Mükemmellik Hedefi

Bu servis, Kafka kümesi yönetimi için AdminClient tabanlı bir REST API sunar. Tüm işlemler, Section 2'de kurulan Kafka kümesine (bootstrap servers, security config) yapılır ve aynı bağlantı detayları kullanılır.

Docker ile Dağıtım

  • REST API servisi Docker container olarak paketlenmiştir.
  • Container, Section 2'deki Kafka kümesine bağlanacak şekilde konfigüre edilir (bootstrap servers, security).
  • API portu 2020 olarak dışa açılır ve erişilebilir olmalıdır.
  • Docker imajı oluşturma ve dağıtım adımları dokümantasyonda yer almaktadır.