클라이언트는 오픈소스 Apache Kafka API를 사용하여 Apache Kafka용 관리형 서비스 클러스터에 연결할 수 있습니다. 모든 연결은 TLS를 사용하여 암호화해야 합니다. 일반 텍스트 통신은 지원되지 않습니다. 인증은 지원되는 두 가지 메커니즘(각각 다른 사용자 인증 정보 유형 사용) 중 하나를 통해 처리됩니다. SASL 또는 mTLS입니다.
이 문서에서는 SASL 메서드를 사용하여 인증하는 방법을 설명합니다. 클라이언트는 서비스 계정과 같은 승인된 Identity and Access Management 주 구성원의 사용자 인증 정보를 사용하여 인증합니다. Managed Service for Apache Kafka는 모든 연결의 서버 측 브로커 인증서를 관리합니다.
시작하기 전에
다음 내용에 대해 자세히 알아보세요.
서비스 계정에 관리형 Kafka 클라이언트 역할 부여
클러스터에 연결하는 데 사용할 서비스 계정에 클러스터가 포함된 프로젝트에 대한 roles/managedkafka.client IAM 역할을 부여해야 합니다.
관리형 Kafka 클라이언트 역할에는 모든 연결에 필요한 managedkafka.clusters.connect 권한이 포함됩니다.
서비스 계정에 관리형 Kafka 클라이언트 역할을 부여하려면 다음 단계를 따르세요.
콘솔
- Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
IAM으로 이동 - 프로젝트가 Apache Kafka용 관리 서비스 클라이언트가 액세스할 소비자 프로젝트로 설정되어 있는지 확인합니다.
- 액세스 권한 부여를 클릭합니다.
- 새 페이지의 주 구성원 추가에 사용 중인 서비스 계정의 이메일 주소를 입력합니다.
- 역할 할당에서 관리형 Kafka 클라이언트 역할을 선택합니다.
- 저장을 클릭합니다.
gcloud CLI
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
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은 서비스 계정의 이메일 주소입니다.
-
인증을 위해 Kafka 클라이언트 구성 Google Cloud
다음 메커니즘 중 하나를 사용하여 Kafka 클라이언트를 Google Cloud 에 인증할 수 있습니다.
OAUTHBEARER (권장): 이 메커니즘을 사용하려면 애플리케이션 기본 사용자 인증 정보 (ADC)를 사용해야 합니다. ADC는 애플리케이션 환경을 기준으로 사용자 인증 정보를 자동으로 검색하기 위해 인증 라이브러리에 사용되는 전략입니다. ADC가 사용자 인증 정보를 찾는 위치와 순서에 대한 자세한 내용은 애플리케이션 기본 사용자 인증 정보 작동 방식을 참고하세요.
SASL/PLAIN: 이 메커니즘을 사용하려면 서비스 계정 키 JSON 파일 또는 액세스 토큰에서 파생될 수 있는 사용자 이름과 비밀번호를 사용해야 합니다.
일반적으로 OAUTHBEARER이 권장되는 옵션입니다. 하지만 SASL/PLAIN이 테스트에 더 편리한 메커니즘일 수 있습니다.
OAuthBearer 인증
오픈소스 Kafka API를 인증하는 방법에 관한 자세한 내용은 GitHub의 문서를 참고하세요.
SASL/PLAIN 인증
Managed Service for Apache Kafka는 서비스 계정 키 JSON 파일 또는 액세스 토큰을 사용한 SASL/PLAIN 인증을 지원합니다.
서비스 계정 키 JSON 파일
이 방법은 모든 Kafka 클라이언트에 적용됩니다.
클라이언트에 사용하려는 서비스 계정에 대해 서비스 계정 키 JSON 파일을 다운로드합니다.
base64 인코딩을 사용해서 인증 문자열로 사용할 서비스 계정 파일을 인코딩합니다. 파일 이름이
my_service_account_key.json이라고 가정합니다.Linux 또는 macOS 시스템에서는 다음과 같이
base64명령어(기본적으로 설치되는 경우가 많음)를 사용합니다.base64 -w 0 < my_service_account_key.json > password.txt이 명령어는 다음 작업을 수행합니다.
base64 < my_service_account_key.json:my_service_account_key.json이라는 파일의 콘텐츠를 읽습니다.base64 인코딩을 사용하여 파일의 콘텐츠를 인코딩합니다. Base64 인코딩은 서비스 계정 파일의 JSON 데이터와 같은 바이너리 데이터를 ASCII 텍스트로 표현하는 방법입니다. 이는 텍스트용으로 설계된 채널을 통해 데이터를 전송하는 데 자주 사용됩니다.
> password.txt:base64명령의 출력(서비스 계정 파일의 base64 인코딩 버전)을password.txt라는 새 파일로 리디렉션합니다.
다음 매개변수를 사용하여 인증에 비밀번호 파일의 콘텐츠를 사용할 수 있습니다.
security.protocol=SASL_SSL sasl.mechanism=PLAIN sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \ username="SERVICE_ACCOUNT_EMAIL_ADDRESS" \ password="CONTENTS_OF_BASE64_ENCODED_PASSWORD_FILE";다음을 바꿉니다.
SERVICE_ACCOUNT_EMAIL_ADDRESS: 인증에 사용할 서비스 계정의 이메일 주소입니다.CONTENTS_OF_BASE64_ENCODED_PASSWORD_FILE: 이전 단계에서 획득한 base64 인코딩 비밀번호 파일의 콘텐츠입니다. 단일 행이어야 합니다.
클러스터에 대한 수신 연결을 인증할 때 Apache Kafka용 관리형 서비스는 다음을 확인합니다.
제공된 사용자 이름이 비밀번호에 사용된 키의 서비스 계정과 일치합니다.
제공된 서비스 계정 주 구성원에게 클러스터에 대한
managedkafka.clusters.connect권한 (roles/managedkafka.clientIAM 역할에 포함됨)이 있습니다.
액세스 토큰
인증에 사용할 주 구성원의 액세스 토큰을 가져옵니다. 예를 들어 현재 gcloud CLI 주 구성원의 액세스 토큰을 가져옵니다.
gcloud auth print-access-token다음 매개변수를 사용하여 인증에 액세스 토큰을 사용할 수 있습니다.
security.protocol=SASL_SSL sasl.mechanism=PLAIN sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \ username="PRINCIPAL_EMAIL_ADDRESS" \ password="ACCESS_TOKEN_VALUE";다음을 바꿉니다.
PRINCIPAL_EMAIL_ADDRESS: 액세스 토큰을 획득하는 데 사용한 주 구성원의 이메일 주소입니다.ACCESS_TOKEN_VALUE: 이전 단계에서 가져온 액세스 토큰 값입니다.
클러스터에 대한 수신 연결을 인증할 때 Apache Kafka용 관리형 서비스는 다음을 확인합니다.
액세스 토큰이 유효하며 만료되지 않았습니다.
제공된 사용자 이름이 액세스 토큰과 연결된 주 구성원 이메일과 일치합니다.
액세스 토큰의 주 구성원에게 클러스터에 대한
managedkafka.clusters.connect권한 (roles/managedkafka.clientIAM 역할에 포함됨)이 있습니다.
GKE용 워크로드 아이덴티티 제휴
Managed Service for Apache Kafka는 GKE용 워크로드 아이덴티티 제휴를 사용하여 오픈소스 Apache Kafka API에 대한 인증을 지원합니다. SASL/PLAIN 및 SASL/OAUTHBEARER 모두에 인증이 지원됩니다.
Apache Kafka용 관리형 서비스와 함께 GKE용 워크로드 아이덴티티 제휴를 사용하려면 다음 요구사항을 준수해야 합니다.
- GKE 버전
1.31.1-gke.1241000이상을 사용합니다. iam.gke.io/return-principal-id-as-email: "true"로 Kubernetes 서비스 계정에 주석을 추가합니다. 예를 들면 다음과 같습니다.apiVersion: v1 kind: ServiceAccount metadata: name: kafka-service-account annotations: iam.gke.io/return-principal-id-as-email: "true"로컬 인증 서버를 사용하는 경우 google-auth 패키지의
2.40.3이상 버전도 사용하는지 확인하세요.
GKE 주 구성원에게 managedkafka.clusters.connect 권한 (roles/managedkafka.client IAM 역할에 포함됨)이 있는지 확인합니다.
Managed Service for Apache Kafka는 Fleet 워크로드 아이덴티티를 사용한 오픈소스 Apache Kafka API에 대한 인증을 지원하지 않습니다. 또는 Kubernetes 서비스 계정을 IAM 서비스 계정에 연결할 수 있습니다.
인증 오류 문제 해결
Apache Kafka용 관리형 서비스 클라이언트가 Apache Kafka용 관리형 서비스에 인증할 수 없는 경우 다음과 유사한 오류 메시지가 표시됩니다.
Exception in thread "main" java.util.concurrent.ExecutionException:
org.apache.kafka.common.errors.SaslAuthenticationException:
Authentication failed: Invalid username or password
이 문제를 해결하려면 다음 원인을 확인하세요.
비밀번호의 형식이 잘못되어 base64로 디코딩할 때 유효한 서비스 계정 키 JSON blob 또는 유효한 액세스 토큰을 나타내지 않습니다.
인증 주체에 클러스터에 대한
managedkafka.clusters.connect권한이 없습니다.제공된 사용자 이름이 사용자 인증 정보의 주 구성원과 일치하지 않습니다.
클라이언트가 30분마다 자주 연결이 끊어지는 경우 클라이언트가 주기적인 재인증을 지원하지 않기 때문일 수 있습니다.
Managed Service for Apache Kafka 브로커는 클라이언트가 30분마다 다시 인증해야 하며 이는 connections.max.reauth.ms 브로커 속성에 의해 적용됩니다.
Kafka 클라이언트 라이브러리 버전이 2.2.0 이상이고 재인증을 지원하는지 확인합니다.