Catalog 가이드

Messaging

이 페이지의 내용

기록 구조#

Messaging은 현재 Kafka를 지원합니다.

단위	stly 리소스	내용
Cluster	`messaging-clusters`	논리 Kafka Cluster. 이름·handle·요약·설명·환경 설명
Topic	`kafka-topics`	Cluster에 속한 Topic. Partition 수·보존 설정·Message Definition·사용 설명
사용 설명	`kafka-usages`	Topic을 발행(`producer`)·소비(`consumer`)하는 애플리케이션

Cluster 이름과 handle은 Organization 안에서, Topic 이름은 같은 Cluster 안에서 고유합니다. handle은 주소 이름을 참고합니다.

Web UI#

Queues → 새 Cluster에서 Cluster를 등록하고, Cluster 상세에서 새 Topic으로 Topic을 추가합니다. Topic 편집 화면에서 Message Definition과 사용 설명을 함께 기록합니다.

Cluster#

{"name": "main-kafka", "handle": "main-kafka", "product": "kafka", "summary": "주문 이벤트용 Kafka Cluster"}

stly messaging-clusters create --input cluster.json

product는 kafka만 받습니다.

Topic과 Message Definition#

{
  "name": "order-events",
  "summary": "주문 상태 변경 이벤트",
  "partition_count": 6,
  "message_definitions": [
    {"name": "OrderStatusChanged", "description": "주문 상태가 바뀔 때 발행합니다.",
     "key": {"mode": "used", "encoding": "string", "description": "주문 ID"},
     "value_encoding": "json", "value_description": "변경된 주문 상태",
     "value_schema": "{\"type\":\"object\",\"required\":[\"order_id\",\"status\"],\"properties\":{\"order_id\":{\"type\":\"string\"},\"status\":{\"type\":\"string\"}}}",
     "header_description": "", "external_references": [],
     "examples": [{"name": "결제 완료", "description": "", "value_json": "{\"order_id\":\"50ECYsM55Ec\",\"status\":\"paid\"}"}]}
  ],
  "usages": [
    {"direction": "producer", "application_name": "orders-service", "description": "주문 상태가 바뀌면 발행합니다.", "consumer_group": null, "service_id": "1I6Nc76wEPd"}
  ]
}

stly kafka-topics validate --operation create --cluster 6SNzehzO7oI --input topic.json
stly kafka-topics create --cluster 6SNzehzO7oI --input topic.json

value_schema는 JSON Schema 원문 문자열이며 value_encoding이 json일 때만 씁니다.
예제의 value_json은 JSON 원문 문자열입니다. 실제 메시지가 아니라 설명용 가상 예제를 적습니다.
encoding은 unknown·json·string·binary·avro·protobuf·other입니다.

사용 설명#

사용 설명은 Topic을 발행·소비하는 애플리케이션과 Consumer Group을 기록합니다. service_id로 Service를 지정하면 Service 상세에서 역으로 조회됩니다.

Topic 전체를 수정하지 않고 사용 설명 하나만 추가·교체·삭제할 수 있습니다. Topic 상세의 etag를 사용합니다.

stly kafka-topics get <topic-id>
stly kafka-usages put <usage-id> --topic <topic-id> --input usage.json --if-match '"Topic 상세의 ETag"'
stly kafka-usages delete <usage-id> --topic <topic-id> --if-match '"Topic 상세의 ETag"'

usage.json은 direction·application_name·description·consumer_group과 선택 service_id를 받습니다. 새 사용 설명은 새 ID를 정해 <usage-id>로 씁니다.

{"direction": "consumer", "application_name": "billing-service", "description": "결제 완료 주문으로 청구서를 만듭니다.", "consumer_group": "billing-order-events"}

stly services kafka-usages <service-id> --fields topic_name,cluster_name,direction

삭제#

Topic이 남아 있는 Cluster는 삭제할 수 없습니다(HTTP 409 CLUSTER_IN_USE). Topic을 먼저 삭제합니다.