12장. Kafka Bridge


이 장에서는 Red Hat Enterprise Linux의 AMQ Streams Kafka Bridge에 대한 개요를 제공하고 AMQ Streams와 상호 작용하기 위해 REST API 사용을 시작하는 데 도움이 됩니다. 로컬 환경에서 Kafka 브리지를 시도하려면 이 장의 뒷부분에 있는 12.2절. “Kafka 브리지 빠른 시작” 를 참조하십시오.

추가 리소스

12.1. Kafka 브리지 개요

Kafka 브리지는 HTTP 기반 클라이언트가 Kafka 클러스터와 상호 작용할 수 있는 RESTful 인터페이스를 제공합니다. 클라이언트 애플리케이션에서 Kafka 프로토콜을 해석할 필요 없이 AMQ Streams에 대한 웹 API 연결의 이점을 제공합니다.

API에는 Kafka 클러스터의소비자 및 생산자와 상호 작용하기 위해 엔드포인트를 통해 노출되고 액세스할 수 있는 두 가지 주요 리소스( 소비자 및 주제)가 있습니다. 리소스는 Kafka 브리지에 직접 연결된 소비자 및 생산자가 아닌 Kafka 브리지와만 관련이 있습니다.

HTTP 요청

Kafka 브리지는 다음과 같은 방법으로 Kafka 클러스터에 대한 HTTP 요청을 지원합니다.

  • 메시지를 주제로 보냅니다.
  • 주제에서 메시지를 검색합니다.
  • 주제의 파티션 목록을 검색합니다.
  • 소비자를 생성하고 삭제합니다.
  • 해당 주제에서 메시지를 수신하기 시작할 수 있도록 소비자를 구독합니다.
  • 소비자가 구독한 주제 목록을 검색합니다.
  • 주제에서 소비자를 서브스크립션 해제합니다.
  • 소비자에게 파티션을 할당합니다.
  • 소비자 오프셋 목록을 커밋합니다.
  • 소비자가 첫 번째 또는 마지막 오프셋 위치 또는 지정된 오프셋 위치에서 메시지를 수신하기 시작할 수 있도록 파티션을 찾습니다.

이 메서드는 JSON 응답 및 HTTP 응답 코드 오류 처리를 제공합니다. 메시지는 JSON 또는 바이너리 형식으로 보낼 수 있습니다.

클라이언트는 네이티브 Kafka 프로토콜을 사용해야 하는 요구 사항 없이 메시지를 생성하고 사용할 수 있습니다.

AMQ Streams 설치와 유사하게 Kafka Bridge 파일을 Red Hat Enterprise Linux에 설치할 수 있습니다. 12.1.5절. “Kafka 브리지 아카이브 다운로드”을 참조하십시오.

KafkaBridge 리소스의 호스트 및 포트 구성에 대한 자세한 내용은 12.1.6절. “Kafka 브리지 속성 구성” 을 참조하십시오.

12.1.1. 인증 및 암호화

HTTP 클라이언트와 Kafka 브리지 간의 인증 및 암호화는 아직 지원되지 않습니다. 즉 클라이언트에서 Kafka 브리지로 전송된 요청은 다음과 같습니다.

  • 암호화되지 않으며 HTTPS 대신 HTTP를 사용해야 합니다.
  • 인증 없이 전송됨

Kafka 브리지와 Kafka 클러스터 간에 TLS 또는 SASL 기반 인증을 구성할 수 있습니다.

속성 파일을 통해 인증을 위해 Kafka 브리지를 구성합니다.

12.1.2. Kafka 브릿지 요청

데이터 형식 및 HTTP 헤더를 지정하여 유효한 요청이 Kafka 브리지에 제출되도록 합니다.

API 요청 및 응답 본문은 항상 JSON으로 인코딩됩니다.

12.1.2.1. 콘텐츠 유형 헤더

모든 요청에 대해 Content-Type 헤더를 제출해야 합니다. 유일한 예외는 POST 요청 본문이 비어 있을 때이며, Content-Type 헤더를 추가하면 요청이 실패합니다.

소비자 작업(/consumers 끝점) 및 생산자 작업(/topics 끝점)에는 다른 Content-Type 헤더가 필요합니다.

소비자 작업을 위한 content-Type 헤더

포함된 데이터 형식에 관계없이 요청 본문에 데이터가 포함된 경우 소비자 작업에 대한POST 요청은 다음 Content-Type 헤더를 제공해야 합니다.

Content-Type: application/vnd.kafka.v2+json

생산자 작업을 위한 content-Type 헤더

생산자 작업을 수행할 때 POST 요청은 생성된 메시지의 포함된 데이터 형식을 지정하는 Content-Type 헤더를 제공해야 합니다. 이는 json 또는 binary 일 수 있습니다.

Expand
표 12.1. 데이터 형식에 대한 content-Type 헤더
포함된 데이터 형식content-Type 헤더

JSON

Content-Type: application/vnd.kafka.json.v2+json

바이너리

content-Type: application/vnd.kafka.binary.v2+json

포함된 데이터 형식은 다음 섹션에 설명된 대로 소비자별로 설정됩니다.

POST 요청에 빈 본문이 있는 경우 Content-Type 을 설정하지 않아야 합니다. 빈 본문을 사용하여 기본값이 있는 소비자를 생성할 수 있습니다.

12.1.2.2. 포함된 데이터 형식

포함된 데이터 형식은 HTTP를 통해 Kafka 브리지를 사용하여 생산자에서 소비자로 전송되는 Kafka 메시지의 형식입니다. 두 가지 임베디드 데이터 형식(JSON 또는 바이너리)이 지원됩니다.

/consumers/groupid 엔드포인트를 사용하여 소비자를 생성할 때 POST 요청 본문은 JSON 또는 바이너리의 포함된 데이터 형식을 지정해야 합니다. 이는 요청 본문의 format 필드에 지정됩니다. 예를 들면 다음과 같습니다.

{
  "name": "my-consumer",
  "format": "binary", 
1

...
}
1
바이너리 포함된 데이터 형식입니다.

소비자에 대한 포함된 데이터 형식을 지정하지 않으면 바이너리 형식이 설정됩니다.

소비자를 생성할 때 지정된 포함된 데이터 형식은 사용할 Kafka 메시지의 데이터 형식과 일치해야 합니다.

바이너리 포함 데이터 형식을 지정하도록 선택하는 경우 후속 생산자 요청은 요청 본문에 바이너리 데이터를 Base64로 인코딩된 문자열로 제공해야 합니다. 예를 들어 POST 요청을 /topics/topicname 엔드포인트에 수행하여 메시지를 보낼 때 값은 Base64로 인코딩되어야 합니다.

{
  "records": [
    {
      "key": "my-key",
      "value": "ZWR3YXJkdGhldGhyZWVsZWdnZWRjYXQ="
    },
  ]
}

생산자 요청은 포함된 데이터 형식에 해당하는 Content-Type 헤더(예: Content-Type: application/vnd.kafka.binary.v2+json )도 제공해야 합니다.

12.1.2.3. 메시지 형식

/topics 엔드포인트를 사용하여 메시지를 보낼 때 요청 본문에 메시지 페이로드를 records 매개변수에 입력합니다.

records 매개변수는 다음 선택적 필드를 포함할 수 있습니다.

  • 메시지
  • 메시지
  • 대상 파티션
  • 메시지 헤더

/topics에 대한 POST 요청의 예

curl -X POST \
  http://localhost:8080/topics/my-topic \
  -H 'content-type: application/vnd.kafka.json.v2+json' \
  -d '{
    "records": [
        {
            "key": "my-key",
            "value": "sales-lead-0001"
            "partition": 2
            "headers": [
              {
                "key": "key1",
                "value": "QXBhY2hlIEthZmthIGlzIHRoZSBib21iIQ==" 
1

              }
            ]
        },
    ]
}'

1
바이너리 형식의 헤더 값과 Base64로 인코딩됩니다.

12.1.2.4. 헤더 수락

소비자를 생성한 후 모든 후속 GET 요청은 다음 형식으로 Accept 헤더를 제공해야 합니다.

Accept: application/vnd.kafka.embedded-data-format.v2+json

embedded-data-formatjson 또는 바이너리 입니다.

예를 들어 JSON의 포함된 데이터 형식을 사용하여 구독된 소비자에 대한 레코드를 검색할 때 다음 Accept 헤더를 포함합니다.

Accept: application/vnd.kafka.json.v2+json

12.1.3. Kafka 브리지의 로거 구성

AMQ Streams Kafka 브릿지를 사용하면 관련 OpenAPI 사양에 정의된 각 작업에 대해 다른 로그 수준을 설정할 수 있습니다.

각 작업에는 브리지가 HTTP 클라이언트에서 요청을 수신하는 해당 API 끝점이 있습니다. 각 끝점에서 로그 수준을 변경하여 들어오고 나가는 HTTP 요청에 대한 보다 세밀한 로깅 정보를 생성할 수 있습니다.

로거는 log4j.properties 파일에 정의되어 있으며 정상 및 준비된 끝점에 대해 다음과 같은 기본 구성이 있습니다.

log4j.logger.http.openapi.operation.healthy=WARN, out
log4j.additivity.http.openapi.operation.healthy=false
log4j.logger.http.openapi.operation.ready=WARN, out
log4j.additivity.http.openapi.operation.ready=false

다른 모든 작업의 로그 수준은 기본적으로 INFO 로 설정됩니다. 로거는 다음과 같이 포맷됩니다.

log4j.logger.http.openapi.operation.<operation-id>

여기서 <operation-id >는 특정 작업의 식별자입니다. 다음은 OpenAPI 사양에서 정의한 작업 목록입니다.

  • createConsumer
  • deleteConsumer
  • 서브스크립션
  • 서브스크립션 취소
  • 폴링
  • 할당
  • 커밋
  • 전송
  • sendToPartition
  • seekToBeginning
  • seekToEnd
  • 검색
  • 상태
  • Ready
  • openAPI

12.1.4. Kafka 브리지 API 리소스

REST API 끝점 및 예제 요청 및 응답을 포함한 설명의 전체 목록은 Kafka Bridge API 참조를 참조하십시오.

12.1.5. Kafka 브리지 아카이브 다운로드

AMQ Streams Kafka Bridge의 압축 배포는 Red Hat 웹 사이트에서 다운로드할 수 있습니다.

12.1.6. Kafka 브리지 속성 구성

다음 절차에서는 AMQ Streams Kafka 브리지에서 사용하는 Kafka 및 HTTP 연결 속성을 구성하는 방법을 설명합니다.

Kafka 관련 속성에 적절한 접두사를 사용하여 Kafka 브리지를 다른 Kafka 클라이언트로 구성합니다.

  • Kafka. 서버 연결 및 보안과 같은 생산자 및 소비자에 적용되는 일반 구성의 경우
  • 소비자별 구성의 경우 Kafka.consumer.는 소비자에게만 전달됩니다.
  • 생산자별 구성의 경우 Kafka.producer.는 생산자에게만 전달됩니다.

Kafka 클러스터에 대한 HTTP 액세스를 활성화할 뿐만 아니라 HTTP 속성은 CORS(Cross-Origin Resource Sharing)를 통해 Kafka 브릿지에 대한 액세스 제어를 활성화하고 정의하는 기능을 제공합니다. CORS는 브라우저에서 두 개 이상의 원본에서 선택한 리소스에 액세스할 수 있는 HTTP 메커니즘입니다. CORS를 구성하려면 허용된 리소스 원본 및 HTTP 메서드 목록을 정의하여 액세스할 수 있습니다. 요청의 추가 HTTP 헤더 는 Kafka 클러스터에 액세스할 수 있는 원본을 설명합니다.

프로세스

  1. AMQ Streams Kafka Bridge 설치 아카이브와 함께 제공되는 application.properties 파일을 편집합니다.

    속성 파일을 사용하여 Kafka 및 HTTP 관련 속성을 지정하고 분산 추적을 활성화합니다.

    1. Kafka 소비자 및 생산자와 관련된 속성을 포함하여 표준 Kafka 관련 속성을 구성합니다.

      다음을 사용하십시오.

      • Kafka 클러스터에 대한 호스트/포트 연결을 정의하는 Kafka .bootstrap.servers
      • Kafka.producer.acks HTTP 클라이언트에 승인을 제공
      • Kafka.consumer.auto.offset.reset 에서 오프셋의 재설정을 관리하는 방법

        Kafka 속성 구성에 대한 자세한 내용은 Apache Kafka 웹 사이트를참조하십시오.

    2. Kafka 클러스터에 대한 HTTP 액세스를 활성화하도록 HTTP 관련 속성을 구성합니다.

      예를 들면 다음과 같습니다.

      http.enabled=true
      http.host=0.0.0.0
      http.port=8080 
      1
      
      http.cors.enabled=true 
      2
      
      http.cors.allowedOrigins=https://strimzi.io 
      3
      
      http.cors.allowedMethods=GET,POST,PUT,DELETE,OPTIONS,PATCH 
      4
      1
      포트 8080에서 수신 대기할 Kafka 브리지의 기본 HTTP 구성입니다.
      2
      CORS를 활성화하려면 true 로 설정합니다.
      3
      쉼표로 구분된 허용된 CORS 원본 목록입니다. URL 또는 Java 정규식을 사용할 수 있습니다.
      4
      CORS에 허용되는 HTTP 메서드의 쉼표로 구분된 목록입니다.
    3. 분산 추적을 활성화하거나 비활성화합니다.

      bridge.tracing=jaeger

      속성에서 코드 주석을 제거하여 분산 추적을 활성화합니다.

12.1.7. Kafka 브리지 설치

Red Hat Enterprise Linux에 AMQ Streams Kafka Bridge를 설치하려면 다음 절차를 따르십시오.

프로세스

  1. 아직 수행하지 않은 경우 AMQ Streams Kafka Bridge 설치 아카이브의 압축을 임의의 디렉터리에 풉니다.
  2. 구성 속성을 매개변수로 사용하여 Kafka Bridge 스크립트를 실행합니다.

    예를 들면 다음과 같습니다.

    ./bin/kafka_bridge_run.sh --config-file=_path_/configfile.properties
  3. 로그에 설치에 성공했는지 확인합니다.

    HTTP-Kafka Bridge started and listening on port 8080
    HTTP-Kafka Bridge bootstrap servers localhost:9092
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2026 Red Hat
맨 위로 이동