Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Managed Service for Apache Kafka 데이터를 BigQuery에 쓰기

Managed Service for Apache Kafka 주제에서 BigQuery 테이블로 AVRO 또는 JSON 메시지를 로드해야 하는 경우 Dataflow 템플릿을 사용하여 로드할 수 있습니다. 이 문서에서는 Google Cloud 콘솔을 사용하여 이 템플릿을 기반으로 파이프라인을 설정하는 방법을 설명합니다. REST API 또는 Google Cloud CLI를 사용하여 이 파이프라인을 설정할 수도 있습니다.

Google Cloud 개 제품 사용됨

Kafka에서 BigQuery로 Dataflow 템플릿은 다음 청구 가능한 Google Cloud 제품을 사용합니다. 가격 계산기를 사용하여 예상 사용량을 기준으로 예상 비용을 산출합니다.

BigQuery: BigQuery는 Google Cloud의 서버리스 데이터 웨어하우스입니다. 이 솔루션에서 BigQuery는 Kafka 데이터의 대상 역할을 합니다. BigQuery Streaming Write API는 BigQuery에 데이터를 쓰는 데 사용됩니다. 그런 다음 BigQuery를 사용하여 SQL 쿼리로 이 데이터를 분석하고, BigQuery ML로 머신러닝 모델을 빌드하고, 비즈니스 인텔리전스 애플리케이션을 지원할 수 있습니다.
Dataflow: Dataflow는 완전 관리형 데이터 처리 서비스입니다. Kafka to BigQuery Dataflow는 Dataflow를 활용하여 Kafka 주제에서 데이터를 읽고, 필요한 변환을 실행하고, BigQuery에 쓰는 파이프라인을 만듭니다. Dataflow의 자동 확장 및 자체 복구 기능을 사용하면 파이프라인이 안정적이고 효율적으로 실행됩니다.
Cloud Storage: 핵심 데이터 흐름에 직접 관여하지는 않지만 Kafka 메시지에 Avro 바이너리 인코딩을 사용하는 경우 Avro 스키마 파일을 저장하는 데 Cloud Storage를 사용할 수 있습니다. 이렇게 하면 Dataflow 파이프라인이 데이터 구조를 올바르게 해석할 수 있습니다.

또한 이 솔루션은 Managed Service for Apache Kafka도 사용합니다.

Managed Service for Apache Kafka: Apache Kafka를 실행하는 데 도움이 되는 Google Cloud 서비스입니다. Managed Service for Apache Kafka를 사용하면 인프라를 관리하는 대신 이벤트 기반 시스템과 스트리밍 데이터 파이프라인을 빌드하는 데 집중할 수 있습니다. Managed Service for Apache Kafka 가격 책정에 관한 자세한 내용은 가격 책정 가이드를 참고하세요.

시작하기 전에

Kafka to BigQuery Dataflow 템플릿을 실행하기 전에 다음을 완료해야 합니다.

Managed Service for Apache Kafka 클러스터 및 주제를 만듭니다.

클러스터와 주제를 만드는 한 가지 방법은 Apache Kafka용 관리형 서비스 빠른 시작을 따르는 것입니다.

주제에 Avro 레코드가 포함된 경우 추가 리소스 요구사항은 Kafka 메시지 형식 구성을 참고하세요.

다음 Google Cloud API를 사용 설정합니다.

Dataflow
BigQuery
Cloud Storage

gcloud services enable dataflow.googleapis.com bigquery.googleapis.com \
storage.googleapis.com

BigQuery 데이터 세트와 테이블을 만듭니다. 테이블의 스키마가 Kafka 입력 주제의 스키마와 일치하는지 확인합니다.

동일한 주제 내에서 여러 스키마를 사용하고 여러 테이블에 쓰는 경우 파이프라인을 구성하기 전에 테이블을 만들지 않아도 됩니다.

BigQuery 데이터 세트 및 테이블을 만드는 방법에 대한 자세한 내용은 데이터 세트 만들기 및 스키마 정의를 사용하여 빈 테이블 만들기를 참고하세요.

Dataflow 작업자 서비스 계정에 관리형 Kafka 클라이언트 역할 부여

Dataflow 작업을 Apache Kafka용 관리형 서비스에 연결하려면 Dataflow 작업자 서비스 계정에 특정 권한을 부여해야 합니다. 이 서비스 계정은 Dataflow 작업의 모든 작업자 VM에 사용되는 ID이며 이러한 VM에서 이루어진 모든 요청은 이 계정을 사용합니다.

Kafka 리소스에 대한 액세스를 허용하려면 Dataflow 작업자 서비스 계정에 roles/managedkafka.client 역할을 부여해야 합니다. 이 역할에는 연결을 설정하는 데 필요한 managedkafka.clusters.connect 권한이 포함되어 있습니다.

작업자 서비스 계정에 대한 자세한 내용은 Google Cloud의 파이프라인 보안 및 권한을 참고하세요.

Dataflow 서비스 계정에 관리형 Kafka 클라이언트 역할을 부여하려면 다음 단계를 따르세요.

콘솔

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
IAM으로 이동
프로젝트가 Managed Service for Apache Kafka 클라이언트가 액세스할 소비자 프로젝트로 설정되어 있는지 확인합니다.
액세스 권한 부여를 클릭합니다.
새 페이지의 주 구성원 추가에 사용 중인 Dataflow 작업자 서비스 계정의 이메일 주소를 입력합니다.
역할 할당에서 관리형 Kafka 클라이언트 역할을 선택합니다.
저장을 클릭합니다.

gcloud CLI

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화

Google Cloud 콘솔 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.
gcloud projects add-iam-policy-binding 명령어를 실행합니다.
```
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
  --role roles/managedkafka.client
```
다음을 바꿉니다.
- PROJECT_ID는 프로젝트 ID입니다.
- SERVICE_ACCOUNT_EMAIL은 Dataflow 작업자 서비스 계정의 이메일 주소입니다.

Kafka-BigQuery Dataflow 템플릿 실행

콘솔의 클러스터 세부정보 페이지에서 Kafka to BigQuery Dataflow 템플릿을 실행할 수 있습니다.

Google Cloud 콘솔에서 클러스터 페이지로 이동합니다.

클러스터로 이동
프로젝트에서 생성한 클러스터가 나열됩니다.
클러스터 세부정보 페이지를 보려면 클러스터 이름을 클릭합니다.
클러스터 세부정보 페이지의 Topics에서 주제의 BigQuery Export 아이콘을 클릭합니다.
템플릿 'Kafka-BigQuery'를 사용하여 Dataflow 작업 만들기 페이지가 열립니다.

다음 섹션에 포함된 정보에 따라 템플릿의 필드를 구성합니다.

작업 이름 입력

작업 이름 필드에 Dataflow 작업의 이름을 입력합니다.

이름은 프로젝트에서 현재 실행 중인 모든 작업 중에서 고유해야 합니다.

파이프라인의 리전 엔드포인트 선택

리전 엔드포인트 필드에서 리전 간 데이터 전송 요금을 최소화하도록 Kafka 클러스터 또는 BigQuery 데이터 세트의 위치로 리전 엔드포인트를 설정합니다.

Dataflow 작업자는 Kafka 클러스터의 리전과 독립적으로 실행할 수 있습니다. 하지만 Kafka 클러스터의 리전 외부에서 작업자를 실행하면 리전 간 이그레스 비용이 발생합니다.

클러스터의 위치를 확인하려면 Managed Service for Apache Kafka 클러스터 나열의 단계를 따르세요.

Dataflow 템플릿 선택

Dataflow 템플릿의 경우 기본값인 Kafka to BigQuery를 유지합니다.

소스 구성

소스의 경우 기본값인 Apache Kafka용 관리형 서비스를 유지합니다.
선택한 주제에 따라 Kafka 클러스터, Kafka 주제, Kafka 소스 인증 모드의 기본값이 이미 선택되어 있습니다. 이 값을 유지합니다.

Kafka 메시지 형식 구성

Dataflow 템플릿은 다음 세 가지 메시지 형식을 지원합니다.

Avro Confluent 와이어 형식: 각 Kafka 메시지에는 매직 바이트, 스키마 ID, Avro 바이너리 인코딩 레코드가 포함됩니다. 기본적으로 메시지 키는 BigQuery에 로드되지 않습니다.

Avro (Confluent 와이어 형식) 형식의 경우 단일 스키마 또는 여러 스키마를 사용할 수 있습니다.
- 단일 스키마: 모든 메시지가 사전 정의된 단일 Avro 스키마를 준수합니다.
- 여러 스키마: 메시지에서 서로 다른 스키마를 사용할 수 있습니다. 이는 Avro (Confluent 와이어 형식)에만 지원됩니다.
Avro (바이너리 인코딩): 메시지에는 메타데이터 없이 레코드의 페이로드만 포함됩니다. Cloud Storage에 업로드된 Avro 스키마 파일 (.avsc)을 제공해야 합니다. 모든 메시지는 이 단일 스키마를 준수해야 합니다.
JSON: 레코드에 사전 정의된 스키마가 필요하지 않습니다. BigQuery 테이블 스키마를 준수하지 않는 레코드는 데드 레터 대기열 (구성된 경우)로 전송되거나 오류 메시지가 로깅됩니다. 지원되는 형식은 {"field": "value"} 형식입니다. [{"name": "field", "value": "value"}] 형식은 지원되지 않습니다.

Avro Confluent 와이어 형식

이 옵션을 Kafka 메시지 형식으로 선택하는 경우 다음 추가 설정을 구성합니다.

스키마 소스: 이 필드는 파이프라인에 스키마를 찾을 위치를 알려줍니다. 다음 옵션 중 하나를 선택합니다.

스키마 레지스트리: 스키마가 Confluent 스키마 레지스트리에 저장됩니다. 이는 스키마를 발전시키고 여러 버전을 관리하는 데 유용합니다. 스키마 레지스트리가 Apache Kafka용 관리형 서비스 클러스터 네트워크에서 액세스할 수 있고 Dataflow 작업자와 동일한 리전에 호스팅되어 있는지 확인합니다. 단일 스키마 시나리오와 다중 스키마 시나리오 모두에서 스키마 레지스트리를 사용할 수 있습니다. 다음 추가 설정을 구성합니다.
- 스키마 레지스트리 연결 URL: 스키마 레지스트리에 연결할 URL을 제공합니다.
- 인증 모드: 레지스트리에 인증이 필요한 경우 OAuth 또는 TLS를 선택합니다. 그렇지 않으면 없음을 선택합니다.
단일 스키마 파일: 모든 메시지가 파일에 정의된 단일 고정 스키마를 따르는 경우 이 옵션을 선택합니다.
- Avro 스키마 파일의 Cloud Storage 파일: 주제의 모든 메시지를 디코딩하는 데 사용되는 Avro 스키마 파일의 경로입니다.

Apache Kafka용 관리형 서비스는 스키마 레지스트리를 제공하지 않습니다. 이 템플릿은 Confluent-wire 형식과 호환되는 스키마 레지스트리에 인증 사용자 인증 정보를 전달하는 것만 지원합니다.

Avro 바이너리 인코딩

이 옵션을 Kafka 메시지 형식으로 선택하는 경우 다음 추가 설정을 구성합니다.

Avro 스키마 파일의 Cloud Storage 파일: 주제의 모든 메시지를 디코딩하는 데 사용되는 Avro 스키마 파일의 경로입니다.

JSON

이 옵션을 Kafka 메시지 형식으로 선택하면 다른 구성이 필요하지 않습니다.

Kafka 키를 BigQuery 테이블에 유지하도록 구성

Kafka 메시지 키를 BigQuery 테이블에 유지 옵션을 사용 설정하는 경우 대상 테이블에 BYTES 유형의 _key 필드도 추가해야 합니다. 키는 구조화된 데이터를 나타낼 수 있지만 템플릿은 이를 바이트 배열로 취급합니다.

오프셋 옵션 지정

개별 작업자 또는 전체 파이프라인을 다시 시작해야 할 때 메시지 재처리를 방지하려면 Kafka에 오프셋 커밋 옵션을 선택하세요. 이렇게 하면 파이프라인이 중단된 지점부터 처리를 재개하여 중복 처리와 잠재적인 데이터 불일치를 방지할 수 있습니다.
소비자 그룹 ID 입력 필드에 이 파이프라인 그룹의 고유한 이름을 입력합니다. 대부분의 경우 파이프라인이 각 메시지를 한 번 읽고 다시 시작할 수 있기를 원합니다.
기본 Kafka 시작 오프셋 필드의 경우 Dataflow 파이프라인은 두 가지 시작 오프셋 옵션을 제공합니다. 다음 중 하나를 선택합니다.
- Earliest: Kafka 주제의 시작부터 메시지를 처리합니다.
- 최신: 사용 가능한 최신 오프셋부터 메시지를 처리합니다.

대상 위치 구성

이 옵션은 데이터 파이프라인이 BigQuery에 데이터를 쓰는 방식을 제어합니다.

테이블 이름 전략 필드는 데이터가 BigQuery 테이블로 구성되는 방식을 결정합니다. 다음 두 가지 중에서 선택할 수 있습니다.

단일 테이블 이름 (기본값): Kafka 주제의 모든 데이터가 단일 BigQuery 테이블로 이동합니다. 이는 가장 간단한 옵션이며 Kafka 데이터의 스키마가 동일한 경우 권장되는 옵션입니다.

BigQuery 출력 테이블에 Kafka 주제의 모든 데이터를 저장할 테이블 이름을 지정합니다.
동적 테이블 이름: Kafka 메시지의 스키마를 기반으로 여러 BigQuery 테이블을 만듭니다. Kafka 메시지의 스키마가 다른 경우 이 옵션을 사용하는 것이 좋습니다. 이 옵션은 파이프라인에서 메시지 구조를 처리하기 위해 Avro Confluent Wire 또는 스키마 레지스트리를 사용하는 경우에만 작동합니다.

Kafka 메시지의 각 고유 스키마는 BigQuery에 자체 테이블을 갖습니다. 표 이름은 스키마 이름을 기반으로 자동으로 생성됩니다.

동적 테이블 이름을 선택하는 경우 다음 추가 필드를 구성합니다.
- BigQuery 출력 프로젝트: BigQuery 데이터 세트가 있는 Google Cloud 프로젝트입니다.
- BigQuery 출력 데이터 세트: 테이블이 생성되는 프로젝트 내의 데이터 세트입니다.
- BigQuery 테이블 이름 지정 접두사 (선택사항): 더 나은 구성을 위해 자동으로 생성된 테이블 이름에 접두사를 추가합니다.

BigQuery Storage Write API 구성

BigQuery Storage Write API의 스트림 수의 경우 0 (기본값)으로 시작합니다. 이 옵션을 사용하면 파이프라인에서 최적의 스트림 수를 자동으로 결정할 수 있습니다.

이 설정은 BigQuery에 데이터를 쓰는 데 사용되는 병렬 스트림 수를 제어합니다. 숫자가 높을수록 특히 대량의 데이터의 경우 쓰기 속도가 향상될 수 있습니다. 최적의 수는 데이터와 BigQuery 설정에 따라 다릅니다.

트리거 빈도 구성

BigQuery Write API의 트리거 빈도(초) 옵션의 경우 5초(기본값)로 시작합니다. 이는 대부분의 사용 사례에 적합한 균형입니다.

이 설정은 BigQuery에 데이터를 쓰는 빈도를 결정합니다.

숫자가 낮을수록 쓰기 빈도가 높아집니다. 이렇게 하면 지연 시간이 줄어들지만 BigQuery 비용이 증가할 수 있습니다. 숫자가 높을수록 쓰기 빈도가 낮아집니다. 이 방법은 비용 효율성이 더 높지만 지연 시간이 증가할 수 있습니다.

데드 레터 큐 구성

손상, 호환되지 않는 데이터 유형 또는 대상 BigQuery 테이블과의 스키마 불일치로 인해 메시지를 처리할 수 없는 경우가 있습니다.

이러한 사례를 처리하려면 템플릿에서 데드 레터 큐를 사용 설정하고 테이블 이름을 제공하세요. 템플릿은 표준화된 스키마를 사용하여 표를 만듭니다. 오류가 있는 메시지는 별도의 BigQuery 테이블에 기록됩니다.

암호화 구성

기본적으로 저장 데이터와 전송 중 데이터는 모두Google-owned and Google-managed encryption key에 의해 암호화됩니다. 고객 관리 암호화 키(CMEK)가 있는 경우 자체 키를 선택할 수 있습니다. CMEK를 구성하는 방법에 대한 자세한 내용은 메시지 암호화 구성을 참고하세요.

네트워킹 구성

Dataflow 템플릿에서 클러스터의 네트워크와 서브네트워크를 지정해야 합니다. 템플릿의 선택적 매개변수 섹션을 사용하면 Dataflow 작업자의 네트워크를 정의할 수 있습니다.

Kafka-BigQuery Dataflow 템플릿은 기본적으로 프로젝트의 기본 네트워크에 Dataflow 작업자를 프로비저닝합니다. Managed Service for Apache Kafka 클러스터가 Dataflow를 통해 BigQuery로 데이터를 전송하도록 하려면 Dataflow 작업자가 클러스터의 네트워크에 액세스할 수 있는지 확인하세요.

Kafka 클러스터가 프로젝트의 기본 네트워크에 있는 서브넷에 연결되어 있지 않은 경우 Kafka 클러스터에 프로젝트의 기본 네트워크를 사용하는 것이 좋습니다.

Dataflow 파이프라인으로 네트워킹을 설정하는 방법에 대한 자세한 내용은 다음을 참고하세요.

Dataflow 네트워킹을 구성하는 데 문제가 있는 경우 Dataflow 네트워킹 문제 해결 가이드를 참고하세요.

선택적 Dataflow 매개변수 구성

구성의 Dataflow 작업자에 대한 영향을 알고 있는 경우에만 선택적 매개변수를 구성하세요. 설정이 잘못되면 성능이나 비용에 영향을 줄 수 있습니다. 각 옵션에 대한 자세한 설명은 선택적 매개변수를 참고하세요.

모니터링

Kafka-BigQuery용 Dataflow 템플릿은 콘솔 내에서 로그, 측정항목, 오류를 탐색할 수 있는 모니터링 환경을 제공합니다. 이 모니터링 도구 모음은 Dataflow 사용자 인터페이스의 일부로 제공됩니다.

작업 측정항목 탭을 사용하면 맞춤 대시보드를 만들 수 있습니다. Kafka to BigQuery 템플릿의 경우 다음을 모니터링하는 작업 측정항목 대시보드를 설정하는 것이 좋습니다.

처리량: 특정 시점에서 처리되는 데이터의 양입니다. 이는 작업을 통한 데이터 흐름을 모니터링하고 잠재적인 성능 문제를 식별하는 데 유용합니다.

자세한 내용은 Dataflow 처리량 모니터링을 참고하세요.
데이터 최신 상태: 데이터 요소의 타임스탬프와 파이프라인에서 이벤트가 처리되는 시간 간의 차이(초)입니다. 이를 통해 성능 및 데이터 소스 병목 현상 또는 빈번한 재시도를 식별할 수 있습니다.

자세한 내용은 Dataflow 데이터 업데이트 빈도 모니터링을 참고하세요.
백로그: 처리 대기 중인 바이트 수입니다. 이 정보는 자동 확장 결정에 영향을 미칩니다.

Dataflow 모니터링에 대한 자세한 내용은 Dataflow 모니터링 문서를 참고하세요.

문제 해결

Dataflow 파이프라인에 성능 문제가 발생하면 Dataflow에서 포괄적인 문제 해결 및 진단 도구 세트를 제공합니다.

다음은 두 가지 일반적인 시나리오와 각 문제 해결 가이드입니다.

Dataflow 파이프라인 디버깅에 대한 일반적인 개요는 Dataflow 파이프라인 문제 해결 및 디버깅을 참고하세요.

알려진 제한사항

템플릿은 스키마 레지스트리에 대한 인증을 위해 사용자 인증 정보를 전달하는 것을 지원하지 않습니다.
Kafka에서 BigQuery로의 Dataflow 작업을 만들 때 Google Cloud 프로젝트가 Managed Service for Apache Kafka 클러스터가 포함된 동일한 프로젝트로 설정되어 있는지 확인합니다.

다음 단계

Apache Kafka to BigQuery 템플릿 매개변수