Kafka Connect 관리

Kafka Connect 관리 (Administration)

이 페이지는 Kafka Connect 클러스터를 REST API로 관리하는 방법과, 커넥터·태스크의 상태, 리밸런스 동작을 이해하는 데 도움이 되는 내용이에요. 운영 중인 Connect 클러스터를 다룬다면 꼭 알아두면 좋아요.

출처: 문서

본문

Kafka Connect의 REST 계층은 클러스터 관리를 가능하게 하는 일련의 API를 제공합니다. 여기에는 커넥터의 구성과 태스크의 상태를 조회하는 API와, 현재 동작을 변경하는 API(예: 구성 변경, 태스크 재시작)가 포함됩니다.

커넥터가 처음 클러스터에 제출되면 새 커넥터의 태스크로 구성된 부하를 분산하기 위해 Connect 워커 사이에서 리밸런스가 트리거됩니다. 이와 동일한 리밸런싱 절차는 커넥터가 필요로 하는 태스크 수를 늘리거나 줄일 때, 커넥터의 구성이 변경될 때, 또는 Connect 클러스터의 의도적 업그레이드나 장애로 인해 워커가 그룹에 추가되거나 제거될 때도 사용됩니다.

2.3.0 이전 버전에서는 Connect 워커가 각 워커가 대략 동일한 양의 작업을 갖도록 보장하는 간단한 방식으로 클러스터의 전체 커넥터와 태스크 집합을 리밸런스했습니다. 이 동작은 connect.protocol=eager로 설정하면 여전히 활성화할 수 있습니다.

2.3.0부터 Kafka Connect는 기본적으로 증분 협력 리밸런싱(incremental cooperative rebalancing)을 수행하는 프로토콜을 사용합니다. 이 프로토콜은 커넥터와 태스크를 Connect 워커 전반에 점진적으로 균형 잡으며, 새로 생기거나, 제거되거나, 한 워커에서 다른 워커로 이동해야 하는 태스크에만 영향을 줍니다. 다른 태스크는 이전 프로토콜에서처럼 리밸런스 중에 중지·재시작되지 않습니다.

Connect 워커가 의도적으로든 장애로든 그룹을 떠나면, Connect는 리밸런스를 트리거하기 전에 scheduled.rebalance.max.delay.ms를 기다립니다. 이 지연은 기본적으로 5분(300000ms)이며, 떠난 워커의 부하를 즉시 재분배하지 않고 워커의 장애나 업그레이드를 견디도록 해줍니다. 워커가 구성된 지연 시간 안에 돌아오면 이전에 할당받았던 태스크를 그대로 다시 받습니다. 하지만 이는 scheduled.rebalance.max.delay.ms에 지정된 시간이 경과할 때까지 태스크가 할당되지 않은 채 남는다는 뜻입니다. 워커가 그 시간 제한 안에 돌아오지 않으면 Connect는 그 태스크들을 Connect 클러스터의 남은 워커들 사이에 재할당합니다.

새 Connect 프로토콜은 Connect 클러스터를 구성하는 모든 워커가 connect.protocol=compatible로 구성될 때 활성화되며, 이 속성이 없을 때의 기본값이기도 합니다. 따라서 모든 워커가 2.3.0으로 업그레이드되면 새 Connect 프로토콜로의 업그레이드가 자동으로 이루어집니다. Connect 클러스터의 롤링 업그레이드는 마지막 워커가 2.3.0 버전으로 합류할 때 증분 협력 리밸런싱을 활성화합니다.

REST API를 사용해 커넥터와 태스크의 현재 상태(각각이 할당된 워커의 ID 포함)를 볼 수 있습니다. 예를 들어 GET /connectors/file-source/status 요청은 file-source라는 이름의 커넥터 상태를 보여줍니다.

{
    "name": "file-source",
    "connector": {
        "state": "RUNNING",
        "worker_id": "192.168.1.208:8083"
    },
    "tasks": [
        {
            "id": 0,
            "state": "RUNNING",
            "worker_id": "192.168.1.209:8083"
        }
    ]
}

커넥터와 그 태스크는 상태 업데이트를 status.storage.topic으로 구성되는 공유 토픽에 게시하며, 클러스터의 모든 워커가 이 토픽을 모니터링합니다. 워커가 이 토픽을 비동기로 소비하므로 상태 API를 통해 상태 변경이 보이기까지 일반적으로 (짧은) 지연이 있습니다. 커넥터 또는 그 태스크가 가질 수 있는 상태는 다음과 같습니다.

UNASSIGNED: 커넥터/태스크가 아직 워커에 할당되지 않음.
RUNNING: 커넥터/태스크가 실행 중.
PAUSED: 커넥터/태스크가 관리적으로 일시 중지됨.
STOPPED: 커넥터가 정지됨. 이 상태는 태스크에는 적용되지 않습니다. 정지된 커넥터의 태스크는 종료되며 상태 API에 보이지 않기 때문입니다.
FAILED: 커넥터/태스크가 (보통 예외를 발생시켜) 실패함. 예외는 상태 출력에 보고됩니다.
RESTARTING: 커넥터/태스크가 적극적으로 재시작 중이거나 곧 재시작될 예정.

대부분의 경우 커넥터와 태스크 상태는 일치하지만, 변경이 발생하는 동안이나 태스크가 실패한 경우 짧은 기간 동안 달라질 수 있습니다. 예를 들어 커넥터가 처음 시작될 때 커넥터와 태스크가 모두 RUNNING 상태로 전환되기까지 눈에 띄는 지연이 있을 수 있습니다. Connect는 실패한 태스크를 자동으로 재시작하지 않으므로 태스크가 실패하면 상태도 어긋나게 됩니다. 커넥터/태스크를 수동으로 재시작하려면 위에 나열된 restart API를 사용할 수 있습니다. 리밸런스가 진행되는 동안 태스크를 재시작하려 하면 Connect가 409(Conflict) 상태 코드를 반환한다는 점에 유의하세요. 리밸런스가 완료된 후 재시도할 수 있지만, 리밸런스가 본질적으로 클러스터의 모든 커넥터와 태스크를 재시작하므로 재시도가 필요하지 않을 수도 있습니다.

2.5.0부터 Kafka Connect는 status.storage.topic을 사용해 각 커넥터가 사용 중인 토픽과 관련된 정보도 저장합니다. Connect 워커는 이러한 커넥터별 토픽 상태 업데이트를 사용해 REST 엔드포인트 GET /connectors/{name}/topics에 대한 요청에 응답하며, 커넥터가 사용 중인 토픽 이름 집합을 반환합니다. REST 엔드포인트 PUT /connectors/{name}/topics/reset에 대한 요청은 커넥터의 활성 토픽 집합을 리셋하고, 커넥터의 최신 토픽 사용 패턴을 기반으로 새 집합이 채워지도록 합니다. 커넥터 삭제 시 커넥터의 활성 토픽 집합도 삭제됩니다. 토픽 추적은 기본적으로 활성화되어 있으며 topic.tracking.enable=false로 설정하면 비활성화할 수 있습니다. 런타임 중 커넥터의 활성 토픽 리셋 요청을 허용하지 않으려면 워커 속성 topic.tracking.allow.reset=false로 설정하세요.

커넥터의 메시지 처리를 잠시 중지하는 것이 유용할 때가 있습니다. 예를 들어 원격 시스템이 유지보수 중이라면 소스 커넥터가 예외 로그를 채우는 대신 새 데이터 폴링을 중지하는 것이 좋습니다. 이런 사용 사례를 위해 Connect는 pause/resume API를 제공합니다. 소스 커넥터가 일시 중지되는 동안 Connect는 추가 레코드를 폴링하는 것을 중지합니다. 싱크 커넥터가 일시 중지되는 동안 Connect는 새 메시지를 푸시하는 것을 중지합니다. 일시 중지 상태는 영속적이므로, 클러스터를 재시작해도 태스크가 재개(resume)될 때까지 커넥터가 메시지 처리를 다시 시작하지 않습니다. 커넥터의 모든 태스크가 일시 중지될 당시 처리 중이던 작업을 마치는 데 시간이 걸릴 수 있으므로, 모든 태스크가 PAUSED 상태로 전환되기까지 지연이 있을 수 있다는 점에 유의하세요. 또한 실패한 태스크는 재시작될 때까지 PAUSED 상태로 전환되지 않습니다.

3.5.0에서 Connect는 커넥터의 태스크를 완전히 종료하고 태스크가 점유한 리소스를 해제하는 stop API를 도입했습니다. 이는 태스크를 유휴 상태로 두고 점유 리소스를 할당된 채로 남겨두는(재개 시 커넥터가 빠르게 데이터 처리를 시작할 수 있게 하는) 일시 중지와는 다릅니다. 커넥터를 정지하는 것은 일시 중지보다 리소스 사용 측면에서 더 효율적이지만, 재개 시 데이터 처리를 시작하는 데 더 오래 걸릴 수 있습니다. 커넥터의 오프셋은 정지 상태일 때만 오프셋 관리 엔드포인트를 통해 수정할 수 있다는 점에 유의하세요.

더 알아보기 (Learn more)

커넥터·태스크 상태와 리밸런스 동작은 Connect 운영의 핵심이에요.
pause/resume과 stop API를 구분하면 리소스 관리를 더 효율적으로 할 수 있어요.
일반 운영 안내는 사용자 가이드를 참고하세요.