service-catalog/manifests/helm/flink-sql-gateway/0.1.0/README.md

Flink SQL Gateway Helm Chart

Apache Flink SQL Gateway를 쉽게 배포하기 위한 Helm Chart입니다. 외부 Python 클라이언트 접근에 최적화되어 있습니다.

📋 개요

이 Helm Chart는 다음 구성 요소를 배포합니다:

필수 컴포넌트 (항상 배포됨)

• Flink Session Cluster: SQL Gateway가 연결할 Flink 클러스터
• Flink SQL Gateway: SQL 쿼리를 실행할 수 있는 REST API 서버
• Service: SQL Gateway 접근을 위한 Kubernetes 서비스
• RBAC: Flink 리소스 관리를 위한 권한 설정
• ConfigMap: SQL Gateway 설정

선택적 컴포넌트 (설정으로 활성화)

• SQL Client Pod: 대화형 SQL 클라이언트 (sqlClient.enabled: true)
• Kafka Integration: Kafka 연동 설정 (kafka.enabled: true)
• SQL Scripts ConfigMap: SQL 스크립트 모음 (SQL Client 활성화 시)

🏗️ 아키텍처

외부 Python 클라이언트 접근 (권장)

┌──────────────────┐
│  Python Client   │
│  (External)      │
└──────────────────┘
         │
         ▼ HTTP REST API
┌──────────────────┐
│   SQL Gateway    │
│   (REST API)     │
│   Port: 8083     │
└──────────────────┘
         │
         ▼ SQL 실행 요청
┌─────────────────────┐
│  Flink Session      │
│  Cluster            │
│  (Data Processing)  │
└─────────────────────┘
         │
         ▼ 데이터 처리 (선택적)
┌─────────────────┐
│   Kafka Cluster │
│   (Streaming)   │
└─────────────────┘

내부 SQL Client 사용 (선택적)

┌──────────────────┐
│   SQL Client     │
│   (Pod)          │
└──────────────────┘
         │
         ▼ SQL 쿼리 전송
┌──────────────────┐
│   SQL Gateway    │
│   (REST API)     │
└──────────────────┘
         │
         ▼ SQL 실행 요청
┌─────────────────────┐
│  Flink Session      │
│  Cluster            │
└─────────────────────┘

주요 특징:

• 외부 Python 클라이언트 최적화: Port Forward를 통한 직접 REST API 접근
• 유연한 구성: 필요한 컴포넌트만 선택적 배포
• Session Mode: 대화형 SQL 개발 환경 제공
• 검증된 안정성: YAML 파싱 오류 해결 및 템플릿 검증 완료

🚀 빠른 시작

1. 사전 요구사항

• Kubernetes 클러스터
• Helm 3.x
• Flink Kubernetes Operator 설치됨
• Strimzi Kafka Operator 설치됨 (Kafka 사용 시)

2. 설치

기본 설치 (외부 Python 클라이언트용 - 권장)

# 최소 리소스로 기본 설치
helm install flink-sql-gateway ./ \
  --namespace flink-sql-gateway \
  --create-namespace

# 외부 Python 클라이언트용 최적화 설치 (권장)
helm install flink-sql-gateway ./ \
  --namespace flink-sql-gateway \
  --create-namespace \
  --values ./custom-values.yaml

고급 설치 옵션

# SQL Client 포함 설치 (대화형 SQL 사용)
helm install flink-sql-gateway ./ \
  --namespace flink-sql-gateway \
  --create-namespace \
  --set sqlClient.enabled=true

# Kafka 연동 포함 설치
helm install flink-sql-gateway ./ \
  --namespace flink-sql-gateway \
  --create-namespace \
  --set kafka.enabled=true \
  --set kafka.user.password="your-kafka-password"

# 완전한 환경 설치 (모든 컴포넌트)
helm install flink-sql-gateway ./ \
  --namespace flink-sql-gateway \
  --create-namespace \
  --values ./custom-values.yaml \
  --set sqlClient.enabled=true \
  --set kafka.enabled=true \
  --set kafka.user.password="your-kafka-password"

3. 외부 Python 클라이언트 접근 (권장)

Port Forward 설정

# SQL Gateway API 접근
kubectl port-forward -n flink-sql-gateway svc/flink-sql-gateway 8083:8083

# Flink Web UI 접근 (선택적)
kubectl port-forward -n flink-sql-gateway svc/flink-session-cluster-rest 8081:8081

Python 클라이언트 예제

import requests
import json

# SQL Gateway 연결
gateway_url = "http://localhost:8083"

# 1. 세션 생성
response = requests.post(f"{gateway_url}/v1/sessions")
session_handle = response.json()["sessionHandle"]
print(f"Session created: {session_handle}")

# 2. SQL 실행
sql_request = {
    "statement": "SHOW TABLES"
}
response = requests.post(
    f"{gateway_url}/v1/sessions/{session_handle}/statements",
    json=sql_request
)
operation_handle = response.json()["operationHandle"]

# 3. 결과 조회
result_response = requests.get(
    f"{gateway_url}/v1/sessions/{session_handle}/operations/{operation_handle}/result/0"
)
print("Query result:", result_response.json())

4. 내부 SQL Client 접근 (선택적)

# SQL Client에 연결 (sqlClient.enabled=true인 경우)
kubectl exec -it flink-sql-client -n flink-sql-gateway -- \
  /opt/flink/bin/sql-client.sh gateway \
  --endpoint http://flink-sql-gateway:8083

⚙️ 설정

주요 설정 항목

파라미터	설명	기본값	custom-values.yaml
global.namespace	배포할 네임스페이스	flink-sql-gateway	flink-sql-gateway
global.image.repository	Flink 이미지 저장소	paasup/flink-sql	paasup/flink-sql
global.image.tag	Flink 이미지 태그	1.20-kafka	1.20-kafka
sessionCluster.enabled	Session Cluster 활성화	true	true
sqlGateway.enabled	SQL Gateway 활성화	true	true
sqlClient.enabled	SQL Client 활성화	false	false
kafka.enabled	Kafka 연동 활성화	false	false

리소스 설정 비교

기본 설정 (values.yaml)

# 최소 리소스 - 테스트용
sessionCluster:
  jobManager:
    resources:
      memory: 1024m
      cpu: 0.5
  taskManager:
    resources:
      memory: 2048m
      cpu: 1
  flinkConfiguration:
    taskmanager.numberOfTaskSlots: "2"

sqlGateway:
  resources:
    requests:
      memory: 512Mi
      cpu: 0.25
    limits:
      memory: 1Gi
      cpu: 0.5

최적화 설정 (custom-values.yaml)

# 외부 Python 클라이언트용 최적화 - 프로덕션 권장
sessionCluster:
  jobManager:
    resources:
      memory: 2048m  # 2배 증가
      cpu: 1         # 2배 증가
  taskManager:
    resources:
      memory: 4096m  # 2배 증가
      cpu: 2         # 2배 증가
  flinkConfiguration:
    taskmanager.numberOfTaskSlots: "4"  # 2배 증가

sqlGateway:
  resources:
    requests:
      memory: 1Gi    # 2배 증가
      cpu: 0.5       # 2배 증가
    limits:
      memory: 2Gi    # 2배 증가
      cpu: 1         # 2배 증가

# SQL Client 비활성화 (외부 Python 클라이언트 사용)
sqlClient:
  enabled: false

Kafka 설정 (선택적)

kafka:
  enabled: true
  bootstrapServers: "kafka-cluster-kafka-external-bootstrap.kafka.svc.cluster.local:9094"
  topics:
    input:
      name: test.input
    output:
      name: test.output
  user:
    name: flink-sql-gateway
    password: "your-kafka-password"
    # 또는 External Secret 사용
    externalSecret:
      enabled: true
      secretName: "kafka-user-credentials"
      usernameKey: "username"
      passwordKey: "password"

External Secret 설정

kafka:
  user:
    externalSecret:
      enabled: true
      secretName: "flink-sql-gateway"  # Kafka namespace의 기존 secret
      usernameKey: "username"
      passwordKey: "password"

📝 사용 예시

1. 테이블 생성

-- 소스 테이블 생성
CREATE TABLE test_input (
    id STRING,
    message STRING,
    timestamp_field TIMESTAMP(3),
    WATERMARK FOR timestamp_field AS timestamp_field - INTERVAL '5' SECOND
) WITH (
    'connector' = 'kafka',
    'topic' = 'test.input',
    'properties.bootstrap.servers' = 'kafka-cluster-kafka-external-bootstrap.kafka.svc.cluster.local:9094',
    'properties.group.id' = 'flink-sql-gateway',
    'properties.security.protocol' = 'SASL_SSL',
    'properties.sasl.mechanism' = 'SCRAM-SHA-512',
    'properties.sasl.jaas.config' = 'org.apache.kafka.common.security.scram.ScramLoginModule required username="flink-sql-gateway" password="YOUR_PASSWORD";',
    'properties.ssl.truststore.location' = '/opt/flink/certs/truststore.jks',
    'properties.ssl.truststore.password' = 'changeit',
    'properties.ssl.truststore.type' = 'JKS',
    'format' = 'json',
    'json.timestamp-format.standard' = 'ISO-8601'
);

2. SQL 쿼리 실행

-- 간단한 필터링 쿼리
INSERT INTO test_output
SELECT 
    id,
    CONCAT('Processed: ', message) as processed_message,
    timestamp_field as original_timestamp,
    CURRENT_TIMESTAMP as processing_time
FROM test_input
WHERE LENGTH(message) > 5;

🔧 관리

업그레이드

helm upgrade flink-sql-gateway . \
  --namespace flink-sql-gateway \
  --values values.yaml

제거

helm uninstall flink-sql-gateway --namespace flink-sql-gateway

상태 확인

# Helm 릴리스 상태
helm status flink-sql-gateway -n flink-sql-gateway

# Pod 상태
kubectl get pods -n flink-sql-gateway

# FlinkDeployment 상태
kubectl get flinkdeployment -n flink-sql-gateway

# 로그 확인
kubectl logs -n flink-sql-gateway -l app=flink-sql-gateway

🐛 문제 해결

일반적인 문제

1. SQL Gateway 연결 실패

   # Gateway 상태 확인
   kubectl get deployment flink-sql-gateway -n flink-sql-gateway
   kubectl logs -n flink-sql-gateway -l app=flink-sql-gateway
   
   # Port Forward 확인
   kubectl port-forward -n flink-sql-gateway svc/flink-sql-gateway 8083:8083
   curl http://localhost:8083/v1/info
   

2. Python 클라이언트 연결 실패

   # 연결 테스트
   import requests
   try:
       response = requests.get("http://localhost:8083/v1/info", timeout=5)
       print("SQL Gateway 연결 성공:", response.json())
   except requests.exceptions.ConnectionError:
       print("Port Forward가 실행 중인지 확인하세요")
   except requests.exceptions.Timeout:
       print("SQL Gateway가 시작되지 않았을 수 있습니다")
   

3. Flink Session Cluster 시작 실패

   # FlinkDeployment 상태 확인
   kubectl describe flinkdeployment flink-session-cluster -n flink-sql-gateway
   

4. Kafka 연결 오류

   • Kafka 사용자 비밀번호 확인
   • 인증서 설정 확인
   • 네트워크 연결 확인

디버깅 명령어

# 전체 환경 상태 확인
kubectl get all -n flink-sql-gateway

# 이벤트 확인
kubectl get events -n flink-sql-gateway --sort-by='.lastTimestamp'

# Helm 템플릿 확인
helm template flink-sql-gateway . --values values.yaml

📚 참고 자료

• Apache Flink Documentation
• Flink SQL Gateway Documentation
• Flink Kubernetes Operator
• Helm Documentation