Lambda에서 Kafka 이벤트 소스와 함께 스키마 레지스트리 사용
스키마 레지스트리는 데이터 스트림 스키마를 정의하고 관리하는 데 도움이 됩니다. 스키마는 데이터 레코드의 구조와 포맷을 정의합니다. Kafka 이벤트 소스 매핑의 컨텍스트에서 Kafka 메시지가 Lambda 함수에 도달하기 전에 사전 정의된 스키마와 비교하여 Kafka 메시지의 구조와 형식을 검증하도록 스키마 레지스트리를 구성할 수 있습니다. 이렇게 하면 애플리케이션에 데이터 거버넌스 계층이 추가되고 데이터 형식을 효율적으로 관리하고, 스키마 규정 준수를 보장하고, 이벤트 필터링을 통해 비용을 최적화할 수 있습니다.
이 기능은 모든 프로그래밍 언어와 호환되지만 다음과 같은 중요한 사항을 고려해야 합니다.
Powertools for Lambda는 Java, Python 및 TypeScript에 대한 특정 지원을 제공하여 기존 Kafka 개발 패턴과의 일관성을 유지하고 사용자 지정 역직렬화 코드 없이 비즈니스 객체에 직접 액세스할 수 있도록 합니다.
이 기능은 프로비저닝된 모드를 사용하는 이벤트 소스 매핑에만 사용 가능합니다. 스키마 레지스트리는 온디맨드 모드에서 이벤트 소스 매핑을 지원하지 않습니다. 프로비저닝된 모드를 사용하고 있고 스키마 레지스트리가 구성된 경우 스키마 레지스트리 구성을 제거해야 온디맨드 모드로 변경할 수 있습니다. 자세한 내용은 프로비저닝된 모드 섹션을 참조하세요.
이벤트 소스 매핑(ESM)당 하나의 스키마 레지스트리만 구성할 수 있습니다. Kafka 이벤트 소스와 함께 스키마 레지스트리를 사용하면 프로비저닝된 모드의 요금 차원인 Lambda EPU(Event Poller Unit) 사용량이 증가할 수 있습니다.
주제
스키마 레지스트리 옵션
Lambda는 다음과 같은 스키마 레지스트리 옵션을 지원합니다.
스키마 레지스트리는 다음 데이터 형식의 메시지 검증을 지원합니다.
-
Apache Avro
-
프로토콜 버퍼(Protobuf)
-
JSON 스키마(JSON-SE)
스키마 레지스트리를 사용하려면 먼저 이벤트 소스 매핑이 프로비저닝된 모드인지 확인합니다. 스키마 레지스트리를 사용하면 Lambda가 페이로드에 스키마에 대한 메타데이터를 추가합니다. 자세한 내용은 페이로드 형식 및 역직렬화 동작을 참조하세요.
Lambda가 Kafka 메시지에 대한 스키마 검증을 수행하는 방법
스키마 레지스트리를 구성하면 Lambda가 각 Kafka 메시지에 대해 다음 단계를 수행합니다.
-
Lambda가 클러스터에서 Kafka 레코드를 폴링합니다.
-
Lambda가 스키마 레지스트리의 특정 스키마에 대해 레코드에서 선택된 메시지 속성을 검증합니다.
-
메시지와 연관된 스키마를 레지스트리에서 찾을 수 없는 경우 Lambda가
SCHEMA_NOT_FOUND
라는 이유 코드와 함께 메시지를 DLQ로 전송합니다.
-
-
Lambda가 스키마 레지스트리 구성에 따라 메시지를 역직렬화하여 메시지를 검증합니다. 이벤트 필터링이 구성된 경우 Lambda가 구성된 필터 기준을 기반으로 필터링을 수행합니다.
-
역직렬화에 실패하는 경우 Lambda가
DESERIALIZATION_ERROR
라는 이유 코드와 함께 메시지를 DLQ로 전송합니다. DLQ가 구성되지 않은 경우 Lambda가 메시지를 삭제합니다.
-
-
메시지가 스키마 레지스트리에 의해 검증되고 필터 기준에 의해 필터링되지 않는 경우 Lambda가 메시지와 함께 함수를 간접적으로 호출합니다.
이 기능은 스키마 레지스트리와 통합된 Kafka 클라이언트를 사용하여 이미 생성된 메시지를 검증하기 위한 것입니다. 스키마 레지스트리로 작업하여 올바른 형식의 메시지를 생성하도록 Kafka 생산자를 구성하는 것이 좋습니다.
Kafka 스키마 레지스트리 구성
다음 콘솔 단계에서는 이벤트 소스 매핑에 Kafka 스키마 레지스트리 구성을 추가합니다.
이벤트 소스 매핑에 Kafka 스키마 레지스트리 구성을 추가하려면 다음을 수행하세요(콘솔).
-
Lambda 콘솔의 함수 페이지
를 엽니다. -
구성을 선택합니다.
-
트리거를 선택합니다.
-
스키마 레지스트리를 구성하려는 Kafka 이벤트 소스 매핑을 선택한 다음 편집을 선택합니다.
-
이벤트 폴러 구성에서 스키마 레지스트리 구성을 선택합니다. 이 옵션을 보려면 이벤트 소스 매핑이 프로비저닝된 모드에 있어야 합니다.
-
스키마 레지스트리 URI에 AWS Glue 스키마 레지스트리의 ARN 또는 Confluent 클라우드 스키마 레지스트리나 자체 관리형 Confluent 스키마 레지스트리의 HTTPS URL을 입력합니다.
-
다음은 Lambda가 스키마 레지스트리에 액세스하는 방법을 지정하는 구성 단계입니다. 자세한 내용은 스키마 레지스트리의 인증 방법 섹션을 참조하세요.
-
액세스 구성 유형에서 Lambda가 스키마 레지스트리에 액세스하는 데 사용하는 인증 유형을 선택합니다.
-
액세스 구성 URI에 스키마 레지스트리로 인증할 Secrets Manager 시크릿의 ARN을 입력합니다(해당하는 경우). 함수의 실행 역할에 올바른 권한이 있는지 확인합니다.
-
-
스키마 레지스트리가 Private Certificate Authority(CA) 또는 Lambda 트러스트 스토어에 없는 인증 기관(CA)에 의해 서명된 경우에만 암호화 필드가 적용됩니다. 해당하는 경우 TLS 암호화를 위해 스키마 레지스트리에서 사용하는 Private CA Certificate가 포함된 시크릿 키를 제공합니다.
-
이벤트 레코드 형식에서 스키마 검증 후 Lambda가 함수에 레코드를 전달하는 방법을 선택합니다. 자세한 내용은 페이로드 형식 예제를 참조하세요.
-
JSON을 선택하는 경우 Lambda가 아래 스키마 검증 속성에서 선택한 속성을 표준 JSON 형식으로 전달합니다. 선택하지 않은 속성의 경우 Lambda가 해당 속성을 그대로 전달합니다.
-
소스를 선택하는 경우 Lambda가 아래 스키마 검증 속성에서 선택한 속성을 원본 소스 형식으로 전달합니다.
-
-
스키마 검증 속성에서 Lambda가 스키마 레지스트리를 사용하여 검증하고 역직렬화할 메시지 속성을 선택합니다. KEY 또는 VALUE 중 하나 이상을 선택해야 합니다. 이벤트 레코드 형식으로 JSON을 선택한 경우 Lambda가 선택한 메시지 속성을 함수로 전송하기 전에 역직렬화합니다. 자세한 내용은 페이로드 형식 및 역직렬화 동작을 참조하세요.
-
저장을 선택합니다.
Lambda API를 사용하여 스키마 레지스트리 구성으로 이벤트 소스 매핑을 생성하거나 업데이트할 수도 있습니다. 다음 예제에서는 AWS Lambda API 참조의 UpdateEventSourceMapping 및 CreateEventSourceMapping API 작업에 해당하는 AWS CLI를 사용하여 AWS Glue 또는 Confluent 스키마 레지스트리를 구성하는 방법을 보여줍니다.
중요
AWS CLI 또는 update-event-source-mapping
API를 사용하여 스키마 레지스트리 구성 필드를 업데이트하는 경우 스키마 레지스트리 구성의 모든 필드를 업데이트해야 합니다.
Avro 및 Protobuf 필터링
스키마 레지스트리와 함께 Avro 또는 Protobuf 형식을 사용하면 Lambda 함수에 이벤트 필터링을 적용할 수 있습니다. 필터 패턴은 스키마 검증 후 데이터의 역직렬화된 클래식 JSON 표현에 적용됩니다. 예를 들어 가격을 포함한 제품 세부 정보를 정의하는 Avro 스키마를 사용하면 가격 값을 기준으로 메시지를 필터링할 수 있습니다.
참고
역직렬화될 때 Avro는 표준 JSON으로 변환되므로 Avro 객체로 직접 다시 변환할 수 없습니다. Avro 객체로 변환해야 하는 경우 SOURCE 형식을 대신 사용합니다.
Protobuf의 역직렬화 시 결과 JSON의 필드 이름은 Protobuf가 일반적으로 수행하는 것처럼 낙타 대문자로 변환되지 않고 스키마에 정의된 필드 이름과 일치합니다. 필터링 패턴을 생성할 때 이 점에 유의하세요.
aws lambda create-event-source-mapping \ --function-name myAvroFunction \ --topics myAvroTopic \ --starting-position TRIM_HORIZON \ --kafka-bootstrap-servers '["broker1:9092", "broker2:9092"]' \ --schema-registry-config '{ "SchemaRegistryURI": "arn:aws:glue:us-east-1:123456789012:registry/myAvroRegistry", "EventRecordFormat": "JSON", "SchemaValidationConfigs": [ { "Attribute": "VALUE" } ] }' \ --filter-criteria '{ "Filters": [ { "Pattern": "{ \"value\" : { \"field_1\" : [\"value1\"], \"field_2\" : [\"value2\"] } }" } ] }'
이 예제에서 필터 패턴은 value
객체를 분석하여 field_1
의 메시지를 "value1"
과 일치시키고 field_2
의 메시지를 "value2"
와 일치시킵니다. Lambda가 Avro 형식에서 JSON으로 메시지를 변환한 후 역직렬화된 데이터에 대해 필터 기준이 평가됩니다.
이벤트 필터링에 대한 자세한 내용은 Lambda 이벤트 필터링을 참조하세요.
페이로드 형식 및 역직렬화 동작
스키마 레지스트리를 사용할 때 Lambda는 일반 이벤트 페이로드와 비슷한 형식으로 최종 페이로드를 함수에 전달하며, 여기에는 몇 가지 추가 필드가 포함됩니다. 추가 필드는 SchemaValidationConfigs
파라미터에 따라 달라집니다. 검증을 위해 선택하는 각 속성(키 또는 값)에 대해 Lambda는 페이로드에 해당 스키마 메타데이터를 추가합니다.
참고
스키마 메타데이터 필드를 사용하려면 aws-lambda-java-events
예를 들어 value
필드를 검증하면 Lambda는 페이로드에 valueSchemaMetadata
라는 필드를 추가합니다. 마찬가지로 key
필드에 대해 Lambda는 keySchemaMetadata
라는 필드를 추가합니다. 이 메타데이터에는 데이터 형식과 검증에 사용된 스키마 ID에 대한 정보가 포함되어 있습니다.
"valueSchemaMetadata": { "dataFormat": "AVRO", "schemaId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }
EventRecordFormat
파라미터는 JSON
또는 SOURCE
로 설정할 수 있으며, 이에 따라 Lambda가 스키마 검증된 데이터를 함수에 전달하기 전에 처리하는 방법이 결정됩니다. 각 옵션은 다양한 처리 기능을 제공합니다.
-
JSON
- Lambda는 검증된 속성을 표준 JSON 형식으로 역직렬화하여 JSON을 기본적으로 지원하는 언어에서 직접 사용할 수 있도록 데이터를 준비합니다. 이 형식은 원본 바이너리 형식을 보존하거나 생성된 클래스로 작업할 필요가 없는 경우에 가장 적합합니다. -
SOURCE
- Lambda는 데이터의 원본 바이너리 형식을 Base64로 인코딩된 문자열로 유지하여 Avro 또는 Protobuf 객체로 직접 변환할 수 있도록 합니다. 이 형식은 강력한 형식의 언어로 작업하거나 Avro 또는 Protobuf 스키마의 전체 기능을 유지해야 할 때 필수적입니다.
이러한 형식 특성과 언어별 고려 사항을 바탕으로 다음 형식이 권장됩니다.
Language | Avro | Protobuf | JSON |
---|---|---|---|
Java | SOURCE | SOURCE | SOURCE |
Python | JSON | JSON | JSON |
NodeJS | JSON | JSON | JSON |
.NET | SOURCE | SOURCE | SOURCE |
기타 | JSON | JSON | JSON |
다음 섹션에서는 이러한 형식을 자세히 설명하고 각 형식에 대한 예제 페이로드를 제공합니다.
JSON 형식
EventRecordFormat
으로 JSON
을 선택하면 Lambda는 SchemaValidationConfigs
필드에서 선택한 메시지 속성(key
및/또는 value
속성)을 검증하고 역직렬화합니다. Lambda는 선택된 속성을 함수에서 표준 JSON 표현의 base64로 인코딩된 문자열로 전달합니다.
참고
역직렬화될 때 Avro는 표준 JSON으로 변환되므로 Avro 객체로 직접 다시 변환할 수 없습니다. Avro 객체로 변환해야 하는 경우 SOURCE 형식을 대신 사용합니다.
Protobuf의 역직렬화 시 결과 JSON의 필드 이름은 Protobuf가 일반적으로 수행하는 것처럼 낙타 대문자로 변환되지 않고 스키마에 정의된 필드 이름과 일치합니다. 필터링 패턴을 생성할 때 이 점에 유의하세요.
다음은 EventRecordFormat
으로 JSON
을 선택하고, key
및 value
속성을 모두 SchemaValidationConfigs
로 선택하는 경우의 예제 페이로드입니다.
{ "eventSource":"aws:kafka", "eventSourceArn":"arn:aws:kafka:us-east-1:123456789012:cluster/vpc-2priv-2pub/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111-1", "bootstrapServers":"b-2.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092,b-1.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092", "records":{ "mytopic-0":[ { "topic":"mytopic", "partition":0, "offset":15, "timestamp":1545084650987, "timestampType":"CREATE_TIME", "key":"abcDEFghiJKLmnoPQRstuVWXyz1234==", //Base64 encoded string of JSON "keySchemaMetadata": { "dataFormat": "AVRO", "schemaId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }, "value":"abcDEFghiJKLmnoPQRstuVWXyz1234", //Base64 encoded string of JSON "valueSchemaMetadata": { "dataFormat": "AVRO", "schemaId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }, "headers":[ { "headerKey":[ 104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101 ] } ] } ] } }
이 예시에서는 다음이 적용됩니다.
-
key
와value
모두 JSON 표현을 역직렬화한 후 base64로 인코딩된 문자열입니다. -
Lambda에는
keySchemaMetadata
와valueSchemaMetadata
의 두 속성에 대한 스키마 메타데이터가 포함됩니다. -
함수는
key
및value
문자열을 디코딩하여 역직렬화된 JSON 데이터에 액세스할 수 있습니다.
JSON 형식은 Python이나 Node.js와 같이 강력한 형식이 아닌 언어에 권장됩니다. 이러한 언어는 JSON을 객체로 변환하는 기능을 기본적으로 지원합니다.
소스 형식
EventRecordFormat
으로 SOURCE
를 선택하면 Lambda는 스키마 레지스트리에 대해 레코드를 검증하지만 역직렬화 없이 원본 바이너리 데이터를 함수에 전달합니다. 이 바이너리 데이터는 원본 바이트 데이터의 Base64로 인코딩된 문자열로 전달되며, 생산자가 추가한 메타데이터는 제거됩니다. 따라서 함수 코드 내에서 원시 바이너리 데이터를 Avro 및 Protobuf 객체로 직접 변환할 수 있습니다. Powertools for AWS Lambda를 사용하는 것이 좋습니다. 이 도구는 원시 바이너리 데이터를 역직렬화하여 Avro 및 Protobuf 객체를 직접 제공합니다.
예를 들어 key
및 value
속성을 모두 검증하도록 Lambda를 구성하지만 SOURCE
형식을 사용하는 경우 함수는 다음과 같은 페이로드를 수신합니다.
{ "eventSource": "aws:kafka", "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/vpc-2priv-2pub/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111-1", "bootstrapServers": "b-2.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092,b-1.demo-cluster-1.a1bcde.c1.kafka.us-east-1.amazonaws.com:9092", "records": { "mytopic-0": [ { "topic": "mytopic", "partition": 0, "offset": 15, "timestamp": 1545084650987, "timestampType": "CREATE_TIME", "key": "abcDEFghiJKLmnoPQRstuVWXyz1234==", // Base64 encoded string of Original byte data, producer-appended metadata removed "keySchemaMetadata": { "dataFormat": "AVRO", "schemaId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }, "value": "abcDEFghiJKLmnoPQRstuVWXyz1234==", // Base64 encoded string of Original byte data, producer-appended metadata removed "valueSchemaMetadata": { "dataFormat": "AVRO", "schemaId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111" }, "headers": [ { "headerKey": [ 104, 101, 97, 100, 101, 114, 86, 97, 108, 117, 101 ] } ] } ] } }
이 예시에서는 다음이 적용됩니다.
-
key
와value
모두 원본 바이너리 데이터를 Base64로 인코딩 문자열로 포함합니다. -
함수는 적절한 라이브러리를 사용하여 역직렬화를 처리해야 합니다.
Avro에서 생성한 객체나 Protobuf에서 생성한 객체를 사용하는 경우, 특히 Java 함수와 함께 사용하는 경우 EventRecordFormat
에 대해 SOURCE
를 선택하는 것이 좋습니다. 이는 Java가 강력한 형식이고 Avro 및 Protobuf 형식에 특정 역직렬화기가 필요하기 때문입니다. 함수 코드에서 선호하는 Avro 또는 Protobuf 라이브러리를 사용하여 데이터를 역직렬화할 수 있습니다.
Lambda 함수에서 역직렬화된 데이터 작업
AWS Lambda는 사용하는 형식에 따라 함수 코드에서 Kafka 레코드를 역직렬화하는 데 도움이 됩니다. 이 유틸리티는 데이터 변환을 처리하고 바로 사용할 수 있는 객체를 제공함으로써 Kafka 레코드 작업을 간소화합니다.
함수에서 Powertools for AWS Lambda를 사용하려면 Lambda 함수를 빌드할 때 Powertools for AWS Lambda를 계층으로 추가하거나 종속성으로 포함해야 합니다. 설정 방법과 자세한 내용은 선호하는 언어에 대한 Powertools for AWS Lambda 설명서를 참조하세요.
참고
스키마 레지스트리 통합 작업 시 SOURCE
또는 JSON
형식을 선택할 수 있습니다. 각 옵션은 아래와 같이 다양한 직렬화 형식을 지원합니다.
형식 | 지원 |
---|---|
SOURCE |
Avro 및 Protobuf(Lambda 스키마 레지스트리 통합 사용) |
JSON |
JSON 데이터 |
SOURCE
또는 JSON
형식을 사용할 때 Powertools for AWS를 사용하여 함수 코드의 데이터를 역직렬화할 수 있습니다. 다음은 다양한 데이터 형식을 처리하는 방법의 예입니다.
스키마 레지스트리의 인증 방법
스키마 레지스트리를 사용하려면 Lambda가 스키마 레지스트리에 안전하게 액세스할 수 있어야 합니다. AWS Glue 스키마 레지스트리로 작업하는 경우 Lambda는 IAM 인증을 사용합니다. 즉, AWS Glue 레지스트리에 액세스하려면 함수의 실행 역할에 다음 권한이 있어야 합니다.
-
AWS Glue 웹 API 참조의 GetRegistry
-
AWS Glue 웹 API 참조의 GetSchemaVersion
필요한 IAM 정책의 예:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "glue:GetRegistry", "glue:GetSchemaVersion" ], "Resource": [ "*" ] } ] }
참고
AWS Glue 스키마 레지스트리의 경우 AWS Glue 레지스트리에 AccessConfigs
를 제공하면 Lambda가 검증 예외를 반환합니다.
Confluent 스키마 레지스트리로 작업하는 경우 KafkaSchemaRegistryAccessConfig 객체의 Type
파라미터에 대해 지원되는 세 가지 인증 방법 중 하나를 선택할 수 있습니다.
-
BASIC_AUTH - Lambda가 사용자 이름과 암호 또는 API 키 및 API 시크릿 인증을 사용하여 레지스트리에 액세스합니다. 이 옵션을 선택하는 경우 URI 필드에 자격 증명이 포함된 Secrets Manager ARN을 제공합니다.
-
CLIENT_CERTIFICATE_TLS_AUTH - Lambda가 클라이언트 인증서와 상호 TLS 인증을 사용합니다. 이 옵션을 사용하려면 Lambda가 인증서와 프라이빗 키 모두에 액세스할 수 있어야 합니다. URI 필드에 이러한 자격 증명이 포함된 Secrets Manager ARN을 제공합니다.
-
NO_AUTH - 퍼블릭 CA 인증서는 Lambda 신뢰 저장소에 있는 인증 기관(CA)에서 서명해야 합니다. 프라이빗 CA/자체 서명 인증서의 경우 서버 루트 CA 인증서를 구성합니다. 이 옵션을 사용하려면
AccessConfigs
파라미터를 생략합니다.
또한 Lambda가 스키마 레지스트리의 TLS 인증서를 확인하기 위해 Private CA Certificate에 액세스해야 하는 경우 Type
으로 SERVER_ROOT_CA_CERT
를 선택하고 URI 필드에 인증서에 대한 Secrets Manager ARN을 입력합니다.
참고
콘솔에서 SERVER_ROOT_CA_CERT
옵션을 구성하려면 암호화 필드에 인증서가 포함된 시크릿 ARN을 입력합니다.
스키마 레지스트리의 인증 구성은 Kafka 클러스터에 대해 구성한 인증과 별개입니다. 유사한 인증 방법을 사용하더라도 둘 다 별도로 구성해야 합니다.
스키마 레지스트리 문제에 대한 오류 처리 및 문제 해결
Amazon MSK 이벤트 소스와 함께 스키마 레지스트리를 사용하는 경우 다양한 오류가 발생할 수 있습니다. 이 섹션에서는 일반적인 문제와 해결 방법에 대한 지침을 제공합니다.
구성 오류
이러한 오류는 스키마 레지스트리 구성을 설정할 때 발생합니다.
- 프로비저닝된 모드 필요
-
오류 메시지:
SchemaRegistryConfig is only available for Provisioned Mode. To configure Schema Registry, please enable Provisioned Mode by specifying MinimumPollers in ProvisionedPollerConfig.
해결 방법:
ProvisionedPollerConfig
에서MinimumPollers
파라미터를 구성하여 이벤트 소스 매핑에 대해 프로비저닝된 모드를 활성화합니다. - 잘못된 스키마 레지스트리 URL
-
오류 메시지:
Malformed SchemaRegistryURI provided. Please provide a valid URI or ARN. For example, https://schema-registry.example.com:8081 or arn:aws:glue:us-east-1:123456789012:registry/ExampleRegistry.
해결 방법: Confluent 스키마 레지스트리에 유효한 HTTPS URL이나 AWS Glue 스키마 레지스트리에 유효한 ARN을 제공합니다.
- 잘못되었거나 누락된 이벤트 레코드 형식
-
오류 메시지:
EventRecordFormat is a required field for SchemaRegistryConfig. Please provide one of supported format types: SOURCE, JSON.
해결 방법: 스키마 레지스트리 구성에서 EventRecordFormat으로 SOURCE나 JSON을 지정합니다.
- 중복 검증 속성
-
오류 메시지:
Duplicate KEY/VALUE Attribute in SchemaValidationConfigs. SchemaValidationConfigs must contain at most one KEY/VALUE Attribute.
해결 방법: SchemaValidationConfigs에서 중복된 KEY 또는 VALUE 속성을 제거합니다. 각 속성 유형은 한 번만 나타날 수 있습니다.
- 누락된 검증 구성
-
오류 메시지:
SchemaValidationConfigs is a required field for SchemaRegistryConfig.
해결 방법: 하나 이상의 검증 속성(KEY 또는 VALUE)을 지정하여 구성에 SchemaValidationConfigs를 추가합니다.
액세스 및 권한 오류
이러한 오류는 Lambda가 권한 또는 인증 문제로 인해 스키마 레지스트리에 액세스할 수 없을 때 발생합니다.
- AWS Glue 스키마 레지스트리 액세스 거부됨
-
오류 메시지:
Cannot access Glue Schema with provided role. Please ensure the provided role can perform the GetRegistry and GetSchemaVersion Actions on your schema.
해결 방법: 함수의 실행 역할에 필요한 권한(
glue:GetRegistry
및glue:GetSchemaVersion
)을 추가합니다. - Confluent 스키마 레지스트리 액세스 거부됨
-
오류 메시지:
Cannot access Confluent Schema with the provided access configuration.
해결 방법: Secrets Manager에 저장된 인증 자격 증명이 올바르고 스키마 레지스트리에 액세스하는 데 필요한 권한이 있는지 확인합니다.
- 교차 계정 AWS Glue 스키마 레지스트리
-
오류 메시지:
Cross-account Glue Schema Registry ARN not supported.
해결 방법: Lambda 함수와 동일한 AWS 계정에 있는 AWS Glue 스키마 레지스트리를 사용합니다.
- 교차 리전 AWS Glue 스키마 레지스트리
-
오류 메시지:
Cross-region Glue Schema Registry ARN not supported.
해결 방법: Lambda 함수와 동일한 리전에 있는 AWS Glue 스키마 레지스트리를 사용합니다.
- 시크릿 액세스 문제
-
오류 메시지:
Lambda received InvalidRequestException from Secrets Manager.
해결 방법: 함수의 실행 역할에 시크릿에 액세스할 수 있는 권한이 있고 다른 계정에서 액세스하는 경우 시크릿이 기본 AWS KMS 키로 암호화되지 않았는지 확인합니다.
연결 오류
이러한 오류는 Lambda가 스키마 레지스트리에 대한 연결을 설정할 수 없을 때 발생합니다.
- VPC 연결 문제
-
오류 메시지:
Cannot connect to your Schema Registry. Your Kafka cluster's VPC must be able to connect to the schema registry. You can provide access by configuring AWS PrivateLink or a NAT Gateway or VPC Peering between Kafka Cluster VPC and the schema registry VPC.
해결 방법: AWS PrivateLink, NAT 게이트웨이 또는 VPC 피어링을 사용하여 스키마 레지스트리에 대한 연결을 허용하도록 VPC 네트워킹을 구성합니다.
- TLS 핸드셰이크 실패
-
오류 메시지:
Unable to establish TLS handshake with the schema registry. Please provide correct CA-certificate or client certificate using Secrets Manager to access your schema registry.
해결 방법: Secrets Manager에서 CA 인증서와 클라이언트 인증서(mTLS용)가 올바르고 적절하게 구성되었는지 확인합니다.
- Throttling
-
오류 메시지:
Receiving throttling errors when accessing the schema registry. Please increase API TPS limits for your schema registry.
해결 방법: 스키마 레지스트리의 API 속도 제한을 늘리거나 애플리케이션의 요청 속도를 줄입니다.
- 자체 관리형 스키마 레지스트리 오류
-
오류 메시지:
Lambda received an internal server an unexpected error from the provided self-managed schema registry.
해결 방법: 자체 관리형 스키마 레지스트리 서버의 상태와 구성을 확인합니다.