Google Cloud 리소스는 Google Cloud내에서 만들거나 사용하는 모든 구성요소입니다. 이러한 리소스는 플랫폼에서 실행되는 애플리케이션과 시스템의 빌딩 블록을 형성합니다.
Managed Service for Apache Kafka의 리소스에는 다음이 포함됩니다.
클러스터
주제
소비자 그룹
ACL
스키마 레지스트리
컨텍스트 (스키마 레지스트리 내)
주제 (스키마 레지스트리 또는 컨텍스트 내)
버전 (주제 아래의 스키마 버전)
스키마 (ID로 식별되며 단일 또는 여러 주제 및 버전과 연결됨)
일반 Google Cloud 리소스 이름 지정에 대한 자세한 내용은 리소스 이름을 참고하세요. Managed Service for Apache Kafka의 스키마 레지스트리 API는 기존 오픈소스 API와의 호환성을 위해 설계되었으므로 일부 명명 규칙이 일반적인 API 표준과 다를 수 있습니다.
리소스 이름 지정 형식
다음은 다양한 리소스의 형식입니다.
클러스터:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}주제:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}소비자 그룹:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}ACL:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}스키마 레지스트리:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}컨텍스트:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}제목:
- 기본 컨텍스트 내:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID} - 특정 컨텍스트 내:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}
- 기본 컨텍스트 내:
스키마 (ID로 식별됨):
- 기본 컨텍스트 내:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID} - 특정 컨텍스트 내:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}
- 기본 컨텍스트 내:
버전 (주제 아래의 버전 번호로 식별됨):
- 기본 컨텍스트 내:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID} - 특정 컨텍스트 내:
projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
- 기본 컨텍스트 내:
다음 섹션에서는 각 구성요소를 자세히 설명합니다.
프로젝트 ID
값은 Google Cloud 콘솔에서 사용할 수 있는 프로젝트 ID 또는 프로젝트 번호여야 합니다. 예를 들어 my-cool-project는 프로젝트 ID이고 123456789123는 프로젝트 번호입니다.
위치
값은 지원되는 Apache Kafka용 관리형 서비스 위치 중 하나여야 합니다. 사용 가능한 위치 목록은 Apache Kafka용 관리형 서비스 위치를 참고하세요.
ID
ID은 리소스 경로의 마지막 세그먼트입니다. {CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID}, {SCHEMA_REGISTRY_ID}, {CONTEXT_ID}, {SUBJECT_ID}과 같은 변수는 다음 가이드라인을 준수해야 합니다.
goog문자열로 시작하지 않도록 합니다.문자로 시작합니다.
길이 제약 조건:
클러스터 ID: 3~255자여야 합니다.
주제, 소비자 그룹 ID: Apache Kafka에서 허용하는 길이입니다. Apache Kafka 주제 이름은 249자로 제한됩니다.
스키마 레지스트리 ID: 최대 255자(영문 기준)를 포함합니다.
컨텍스트 ID: 최대 255자(영문 기준)를 포함합니다.
주체 ID: 최대 255 UTF-8 바이트를 포함합니다.
글자 제약 조건:
클러스터 ID: 정규식
^[a-z]([-a-z0-9]*[a-z0-9])?와 일치해야 합니다. 즉, 소문자, 숫자, 하이픈을 사용할 수 있습니다. 문자로 시작해야 하고 하이픈으로 끝나면 안 됩니다.주제, 소비자 그룹 ID: Kafka에서 유효성 검사를 실행합니다. 허용되는 문자는 `[a-zA-Z0-9.-], 여기에는 ASCII 영숫자, 마침표 (.), 밑줄 (), 대시 (-)가 포함됩니다.
스키마 레지스트리 ID: 문자 (대문자 또는 소문자), 숫자, 밑줄
_컨텍스트 ID: 문자(대문자 또는 소문자), 숫자, 다음 특수 문자(대시
-, 마침표., 밑줄_, 물결표~, 퍼센트%, 더하기 기호+)주제 ID: 문자(대문자 또는 소문자), 숫자, 다음 특수 문자(대시
-, 마침표., 밑줄_, 물결표~, 퍼센트%, 더하기 기호+)
ACL ID
acl_id는 ACL 항목이 적용되는 리소스 패턴을 정의합니다. ACL의 모든 ACL 항목은 ACL ID에 인코딩된 리소스 패턴에 적용됩니다.
acl_id는 다음 중 하나와 같이 구성되어야 합니다.
클러스터의 ACL:
cluster
클러스터 내 단일 리소스의 ACL:
topic/{RESOURCE_NAME}consumerGroup/{RESOURCE_NAME}transactionalId/{RESOURCE_NAME}
접두사와 일치하는 모든 리소스의 ACL:
topicPrefixed/{RESOURCE_NAME}consumerGroupPrefixed/{RESOURCE_NAME}transactionalIdPrefixed/{RESOURCE_NAME}
특정 유형의 모든 리소스에 대한 ACL (와일드 카드):
allTopics(topic/*을 나타냄)allConsumerGroups(consumerGroup/*을 나타냄)allTransactionalIds(transactionalId/*을 나타냄)
{RESOURCE_NAME}: 특정 리소스의 이름입니다.
예:
- 특정 주제
my-topic에 대한 권한을 부여하려면 다음 단계를 따르세요.topic/my-topic test-로 시작하는 모든 주제에 권한을 부여하려면 다음을 실행합니다.topicPrefixed/test-- 클러스터 자체에 권한을 부여하려면 다음을 실행하세요.
cluster - 그룹에 권한을 부여하려면 다음 단계를 따르세요.
allConsumerGroups - 특정 거래 ID
tx-id에 권한을 부여하려면 다음을 실행하세요.transactionalId/tx-id
특수문자
URL로 인코딩하지 않고 리소스 ID에 이전 섹션에 나열된 특수문자를 사용할 수 있습니다. 하지만 다른 특수문자를 URL에 사용하는 경우 올바르게 암호화되거나 디코딩되었는지 확인해야 합니다.
예를 들어 ó이 특정 리소스 ID 유형에 허용되는 문자가 아닌 경우 mi-tópico은 잘못된 ID입니다. 하지만 기본 라틴 문자만 허용되는 경우 mi-topico는 유효합니다. 이 형식은 REST를 호출할 때 중요합니다.
Kafka 클라이언트 라이브러리에서 주제를 참조하는 경우 전체 리소스 경로가 사용되지 않습니다. 주제 이름만 사용됩니다. 마찬가지로 직렬화기 또는 역직렬화기와 같은 Kafka 클라이언트 통합을 사용하여 스키마와 상호작용할 때는 일반적으로 전체 리소스 경로가 아닌 주제 이름을 사용합니다.
주제 이름 지정 전략
스키마 레지스트리, 특히 직렬화기 및 역직렬화기와 같은 Kafka 클라이언트 통합을 사용할 때는 주제 이름이 중요합니다. 주제 이름 지정 전략은 스키마가 스키마 레지스트리에서 등록되고 검색되는 방식을 결정합니다. 다양한 전략을 통해 스키마 진화에 대한 유연성과 제어 수준을 다양하게 설정할 수 있습니다.
Kafka 클라이언트 구성에서 key.subject.name.strategy 또는 value.subject.name.strategy 속성을 설정하여 주제 이름 지정 전략을 구성할 수 있습니다.
TopicNameStrategy
이는 오픈소스 Kafka 클라이언트 라이브러리의 기본 전략입니다.
주제 이름은 Kafka 주제 이름에서 직접 파생되며 메시지 키의 경우 key, 메시지 값의 경우 value이 추가됩니다. auto.register.schema이 true로 설정된 경우 프로듀서 클라이언트는 topicName라는 주제에 topicName-value 또는 topicName-key를 사용합니다.
예를 들면 다음과 같습니다.
- 주제 이름:
orders - 메시지 값의 제목:
orders-value - 메시지 키 제목:
orders-key
다음은 TopicNameStrategy 사용의 이점 목록입니다.
간단한 전략이므로 다양한 사용 사례에 적합합니다.
스키마는 주제에 직접 연결되므로 단일 주제 내에서 레코드 유형을 독립적으로 발전시킬 수 있습니다.
다음은 TopicNameStrategy 사용의 단점 목록입니다.
- 각 주제는 값 스키마를 기반으로 하는 하나의 메시지 유형만 효과적으로 처리할 수 있습니다. 주제 이름이 주제 이름으로 고정되어 있기 때문입니다. 동일한 주제에 여러 유형의 레코드를 전송해야 하는 경우 이 전략은 작동하지 않습니다.
RecordNameStrategy
이 전략은 Avro 또는 Protobuf 레코드의 정규화된 클래스 이름을 주제 이름으로 사용합니다.
예를 들면 다음과 같습니다.
- Avro 스키마 이름:
com.example.data.Customer - Protobuf 메시지 이름:
com.example.data.Order customer스키마의 제목:com.example.data.Customerorder스키마의 제목:com.example.data.Order
다음은 RecordNameStrategy 사용의 이점 목록입니다.
주제 이름이 주제에 연결되어 있지 않으므로 동일한 Kafka 주제에 다양한 유형의 레코드를 전송할 수 있습니다. 각 레코드 유형에 고유한 정규화된 이름과 등록된 해당 스키마가 있는 한 가능합니다.
com.example.common.Address과 같은 특정 레코드 유형의 스키마는 여러 주제에서 사용할 수 있으며, 그 진화는 단일 주제에서 중앙에서 관리됩니다.
다음은 RecordNameStrategy 사용의 단점 목록입니다.
- 특정 레코드 유형을 사용하는 모든 주제에 동일한 주제와 버전을 사용해야 합니다. 다른 주제에 동일한 레코드 유형의 다른 버전이 필요한 경우 제한적일 수 있습니다.
TopicRecordNameStrategy
이 전략은 TopicNameStrategy과 RecordNameStrategy의 측면을 모두 결합합니다.
주제 이름은 Kafka 주제 이름과 레코드의 정규화된 클래스 이름의 조합이며 TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME 형식으로 지정됩니다.
예를 들면 다음과 같습니다.
주제:
user-events정규화된 이름:
com.example.events.PageView이 조합의 주제 이름:
user-events-com.example.events.PageView다른 주제:
product-interactions정규화된 이름:
com.example.events.PageView이 조합의 주제 이름:
product-interactions-com.example.events.PageView
다음은 TopicRecordNameStrategy 사용의 이점 목록입니다.
RecordNameStrategy과 마찬가지로 동일한 주제에 다양한 유형의 레코드를 보낼 수 있습니다.RecordNameStrategy와 달리 이 전략을 사용하면 각 주제 내에서 특정 레코드 유형의 스키마를 독립적으로 발전시킬 수 있습니다. 즉,my-topic-com.example.project.MyRecord은another-topic-com.example.project.MyRecord과 다르게 발전할 수 있습니다.
다음은 TopicRecordNameStrategy 사용의 단점 목록입니다.
- 주제 이름과 정규화된 레코드 이름의 조합으로 인해 주제 이름이 상당히 길어질 수 있습니다.