Kafka 이벤트 소스 매핑 오류 문제 해결

Kafka 이벤트 소스 매핑 오류 문제 해결 (Troubleshooting Kafka event source mapping errors)

다음 주제는 Lambda와 함께 Amazon MSK 또는 자체 관리형 Apache Kafka를 사용할 때 발생할 수 있는 오류와 문제에 대한 문제 해결 조언을 제공합니다. 더 많은 문제 해결 도움말은 AWS Knowledge Center를 방문하세요.

출처: AWS Lambda 개발자 안내서

본문

인증 및 권한 부여 오류

Kafka 클러스터에서 데이터를 소비하는 데 필요한 권한 중 하나라도 누락되면 Lambda는 이벤트 소스 매핑의 LastProcessingResult 아래에 다음 오류 메시지 중 하나를 표시합니다.

오류 메시지:

Cluster failed to authorize Lambda
SASL authentication failed
Server failed to authenticate Lambda
Lambda failed to authenticate server
Provided certificate or private key is invalid

Cluster failed to authorize Lambda

SASL/SCRAM 또는 mTLS의 경우 이 오류는 제공된 사용자에게 다음 필수 Kafka 액세스 제어 목록(ACL) 권한이 모두 없는 것을 나타냅니다:

DescribeConfigs Cluster
Describe Group
Read Group
Describe Topic
Read Topic

필수 kafka-cluster 권한으로 Kafka ACL을 만들 때 토픽과 그룹을 리소스로 지정하세요. 토픽 이름은 이벤트 소스 매핑의 토픽과 일치해야 합니다. 그룹 이름은 이벤트 소스 매핑의 UUID와 일치해야 합니다.

필수 권한을 실행 역할에 추가한 후 변경 사항이 적용되는 데 몇 분이 걸릴 수 있습니다.

다음은 이 문제에 대해 Logging Config를 활성화한 후의 ESM 시스템 수준 로그 예시입니다:

{
    "eventType": "ESM_PROCESSING_EVENT",
    "timestamp": 1734567890123,
    "resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE11111-1",
    "eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111/0",
    "logLevel": "WARN",
    "error": {
        "errorMessage": "Not authorized to access topics: [my-topic]",
        "errorCode": "org.apache.kafka.common.errors.TopicAuthorizationException"
    }
}

SASL authentication failed

SASL/SCRAM 또는 SASL/PLAIN의 경우 이 오류는 제공된 로그인 자격 증명이 유효하지 않은 것을 나타냅니다.

IAM 액세스 제어의 경우 실행 역할에 클러스터에 대한 kafka-cluster:Connect 권한이 없습니다. 이 권한을 역할에 추가하고 클러스터의 Amazon 리소스 이름(ARN)을 리소스로 지정하세요.

이 오류가 간헐적으로 발생하는 것을 볼 수 있습니다. TCP 연결 수가 서비스 할당량을 초과하면 클러스터는 연결을 거부합니다. Lambda는 연결이 성공할 때까지 백오프하고 재시도합니다. Lambda가 클러스터에 연결하고 레코드를 폴링한 후 마지막 처리 결과는 OK로 변경됩니다.

다음은 IAM 인증을 사용할 때 이 문제에 대해 Logging Config를 활성화한 후의 ESM 시스템 수준 로그 예시입니다:

{
    "eventType": "ESM_PROCESSING_EVENT",
    "timestamp": 1734567890456,
    "resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
    "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE22222-1",
    "eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222/0",
    "logLevel": "WARN",
    "error": {
        "errorMessage": "[a1b2c3d4-5678-90ab-cdef-EXAMPLE22222]: Access denied",
        "errorCode": "org.apache.kafka.common.errors.SaslAuthenticationException"
    }
}

Server failed to authenticate Lambda

이 오류는 Kafka 브로커가 Lambda를 인증하지 못한 것을 나타냅니다. 이는 다음 중 어떤 이유로든 발생할 수 있습니다:

mTLS 인증에 대한 클라이언트 인증서를 제공하지 않았습니다.
클라이언트 인증서를 제공했지만 Kafka 브로커가 mTLS 인증을 사용하도록 구성되지 않았습니다.
클라이언트 인증서가 Kafka 브로커에 의해 신뢰되지 않습니다.

Lambda failed to authenticate server

이 오류는 Lambda가 Kafka 브로커를 인증하지 못한 것을 나타냅니다. 이는 다음 중 어떤 이유로든 발생할 수 있습니다:

자체 관리형 Apache Kafka의 경우: Kafka 브로커가 자체 서명 인증서나 개인 CA를 사용하지만 서버 루트 CA 인증서를 제공하지 않았습니다.
자체 관리형 Apache Kafka의 경우: 서버 루트 CA 인증서가 브로커의 인증서에 서명한 루트 CA와 일치하지 않습니다.
브로커의 인증서가 DNS 이름이나 IP 주소를 주체 대체 이름(subject alternative name)으로 포함하지 않아 호스트 이름 검증이 실패했습니다.

Provided certificate or private key is invalid

이 오류는 Kafka 컨슈머가 제공된 인증서나 개인 키를 사용할 수 없는 것을 나타냅니다. 인증서와 키가 PEM 형식이고 개인 키 암호화가 PBES1 알고리즘을 사용하는지 확인하세요.

다음은 이 문제에 대해 Logging Config를 활성화한 후의 ESM 시스템 수준 로그 예시입니다:

{
    "eventType": "ESM_PROCESSING_EVENT",
    "timestamp": 1734567891234,
    "resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE44444",
    "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE44444-1",
    "eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE44444/0",
    "logLevel": "WARN",
    "error": {
        "errorMessage": "Invalid PEM keystore configs",
        "errorCode": "org.apache.kafka.common.errors.InvalidConfigurationException"
    }
}

네트워크 및 연결 오류

네트워크 구성 문제로 인해 Lambda가 Kafka 클러스터에 연결하지 못할 수 있습니다. 다음 주제는 일반적인 네트워크 관련 오류를 설명합니다.

오류 메시지:

Connection timeout due to security group configuration
Kafka broker endpoints cannot be resolved

Connection timeout due to security group configuration

Kafka 클러스터와 연결된 보안 그룹이 자체로부터의 인바운드 트래픽을 허용하지 않으면 Lambda가 클러스터에 연결할 수 없습니다. 보안 그룹의 인바운드 규칙이 Kafka 브로커 포트에서 보안 그룹 자체로부터의 트래픽을 허용하는지 확인하세요.

다음은 이 문제에 대해 Logging Config를 활성화한 후의 ESM 시스템 수준 로그 예시입니다:

{
    "eventType": "ESM_PROCESSING_EVENT",
    "timestamp": 1734567892345,
    "resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE55555",
    "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE55555-1",
    "eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE55555/0",
    "logLevel": "WARN",
    "error": {
        "errorMessage": "Timeout expired while fetching topic metadata",
        "errorCode": "org.apache.kafka.common.errors.TimeoutException"
    }
}

Kafka 컨슈머 INFO 로그를 확인해 연결과 네트워크 구성을 검증할 수도 있습니다. brokerEndpoints 필드는 Kafka 브로커 주소를, securityProtocol 및 saslMechanism(해당되는 경우)은 인증 방법을, networkConfig 필드는 이벤트 소스 매핑이 사용하는 IP 주소, 서브넷 CIDR 블록, 보안 그룹을 보여줍니다. 나열된 보안 그룹이 필요한 인바운드 트래픽을 허용하는지 확인하세요:

{
    "eventType": "POLLER_STATUS_EVENT",
    "timestamp": 1734567892456,
    "resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
    "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/a1b2c3d4-5678-90ab-cdef-11111EXAMPLE-1",
    "eventProcessorId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE/0",
    "logLevel": "INFO",
    "kafkaEventSourceConnection": {
        "brokerEndpoints": "boot-abcd1234.c2.kafka-serverless.us-east-1.amazonaws.com:9098",
        "consumerId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE-0",
        "topics": [
            "my-topic"
        ],
        "consumerGroupId": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
        "securityProtocol": "SASL_SSL",
        "saslMechanism": "AWS_MSK_IAM",
        "totalPartitionCount": 2,
        "assignedPartitionCount": 2,
        "partitionsAssignmentGeneration": 1,
        "assignedPartitions": [
            "my-topic-0",
            "my-topic-1"
        ],
        "networkConfig": {
            "ipAddresses": [
                "10.0.0.37"
            ],
            "subnetCidrBlock": "10.0.0.32/28",
            "securityGroups": [
                "sg-0123456789abcdef0"
            ]
        }
    }
}

Kafka broker endpoints cannot be resolved

이 오류는 Kafka 클러스터가 존재하지 않거나 삭제된 것을 나타냅니다. 이벤트 소스 매핑에 지정된 클러스터가 존재하고 활성 상태인지 확인하세요.

다음은 이 문제에 대해 Logging Config를 활성화한 후의 ESM 시스템 수준 로그 예시입니다:

{
    "eventType": "ESM_PROCESSING_EVENT",
    "timestamp": 1734567893456,
    "resourceArn": "arn:aws:lambda:us-east-1:123456789012:event-source-mapping:a1b2c3d4-5678-90ab-cdef-EXAMPLE66666",
    "eventSourceArn": "arn:aws:kafka:us-east-1:123456789012:cluster/my-kafka-cluster/12345678-abcd-1234-efgh-EXAMPLE66666-1",
    "eventProcessorId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE66666/0",
    "logLevel": "WARN",
    "error": {
        "errorMessage": "No resolvable bootstrap urls given in bootstrap.servers",
        "errorCode": "org.apache.kafka.common.config.ConfigException"
    }
}

이벤트 소스 매핑 오류

Apache Kafka 클러스터를 Lambda 함수의 이벤트 소스로 추가할 때 함수에 오류가 발생하면 Kafka 컨슈머는 레코드 처리를 중지합니다. 토픽 파티션의 컨슈머는 레코드를 구독하고, 읽고, 처리하는 주체입니다. 다른 Kafka 컨슈머는 같은 오류가 발생하지 않는 한 레코드 처리를 계속할 수 있습니다.

중지된 컨슈머의 원인을 확인하려면 EventSourceMapping 응답에서 StateTransitionReason 필드를 확인하세요. 다음 목록은 받을 수 있는 이벤트 소스 오류를 설명합니다:

ESM_CONFIG_NOT_VALID — 이벤트 소스 매핑 구성이 유효하지 않습니다.
EVENT_SOURCE_AUTHN_ERROR — Lambda가 이벤트 소스를 인증할 수 없습니다.
EVENT_SOURCE_AUTHZ_ERROR — Lambda에 이벤트 소스에 액세스하는 데 필요한 권한이 없습니다.
FUNCTION_CONFIG_NOT_VALID — 함수 구성이 유효하지 않습니다.

참고

Lambda 이벤트 레코드가 허용된 크기 제한 6MB를 초과하면 처리되지 않을 수 있습니다.

더 알아보기 (Learn more)

Amazon MSK 이벤트 소스 매핑
자체 관리형 Apache Kafka 이벤트 소스
Lambda 이벤트 소스 매핑 문제 해결