Troubleshoot Data Connectivity Proxy

Troubleshoot Data Connectivity Proxy (데이터 연결 프록시 문제 해결)

DCP 에이전트나 커넥터 경로가 예상대로 동작하지 않을 때 아래 증상과 해결 방법을 사용해요.

출처: Snowflake Documentation

본문

에이전트 시작 실패: 토큰 거부됨

증상: 에이전트가 인증 오류와 함께 즉시 종료돼요.

원인: 자격 증명 파일에 Snowflake Access JWT 대신 불투명 토큰(PAT_로 시작)이 들어 있어요.

해결: SYSTEM$GENERATE_DATA_CONNECTIVITY_PROXY_BOOTSTRAP_TOKEN으로 토큰을 재생성하고, 그 출력(PAT가 아닌)을 자격 증명 파일에 작성해요.

TLS 핸드셰이크 실패: 인증서가 DCP 호스트 이름과 일치하지 않음

증상: dcp.<org>-<account>.<region>.<cloud>.snowflake.com의 DNS가 해석되고 포트 443 TCP는 성공하지만 TLS 핸드셰이크는 실패해요. 서버가 DCP 호스트 이름과 공통 이름이 일치하지 않는 인증서(종종 *.privatelink.snowflakecomputing.com)를 제시해요.

원인: 계정에 아직 중첩된 snowflake.com 호스트 이름에 대한 TLS 인증서가 없거나, 에이전트가 공용 DCP 컨트롤 플레인 대신 PrivateLink 엔드포인트에 도달하고 있어요.

해결:

  1. 에이전트가 SYSTEM$ALLOWLIST의 공용 DCP 호스트 이름을 사용하는지 확인해요. PrivateLink 호스트 이름이나 PrivateLink DNS 오버라이드가 아니어야 해요. PrivateLink 엔드포인트를 통해 DCP 에이전트를 연결하는 것은 지원되지 않아요.
  2. 계정 수준 인증서를 발급한 후 에이전트를 재시도하기 전에 최소 30분 기다려요:
SELECT SYSTEM$ISSUE_PER_ACCOUNT_CERTIFICATES();

자세한 내용은 SYSTEM$ISSUE_PER_ACCOUNT_CERTIFICATES 및 설정 주제의 참고를 참고해요.

에이전트가 disconnected 또는 down 상태 표시

증상: DESCRIBE DATA CONNECTIVITY PROXY가 AGENT_HEALTH = DOWN을 반환하거나, AGENT_STATUS가 DCP_AGENT_LIFECYCLE_CONNECTED가 아니에요.

단계:

  1. 에이전트 컨테이너가 실행 중인지 확인: docker ps | grep dcp-agent
  2. 에이전트 로그 확인: docker logs dcp-agent --tail 50
  3. 에이전트 호스트에서 <account>.snowflakecomputing.com으로 아웃바운드 포트 443이 열려 있는지 확인
  4. 에이전트 상태 확인 실행(상태 확인 참고)으로 어떤 단계가 실패하는지 격리
  5. DCP_CLIENT_EVENT_HISTORY에서 EVENT_TYPE = 'BOOTSTRAP' 또는 'CONTROL_PLANE' 행 중 STATUS = 'FAILURE'인 것을 확인. 인증이 실패하면 DESCRIBE의 LAST_AUTH_FAILURE_REASON 확인.

커넥터가 사설 소스에 도달할 수 없음

증상: 에이전트가 연결되어 있어도 커넥터 연결 시도가 실패해요.

단계:

  1. DESCRIBE DATA CONNECTIVITY PROXY가 EXTERNAL_ACCESS_INTEGRATIONS에 EAI를 나열하는지 확인. 비어 있으면 ALTER DATA CONNECTIVITY PROXY ... SET EXTERNAL_ACCESS_INTEGRATIONS로 EAI를 연결.
  2. 목적지 FQDN과 포트가 해당 EAI에서 MODE = DATA_CONNECTIVITY_PROXY_EGRESS인 HOST_PORT 네트워크 규칙으로 커버되는지 확인
  3. 같은 EAI가 Openflow 런타임에 연결되어 있는지 확인
  4. 목적지를 host:port로 DCP_CLIENT_ROUTE_CHECK 실행
  5. 에이전트 호스트가 목적지에 도달할 수 있는지 확인: docker exec dcp-agent nc -z <host> <port>
  6. 에이전트 호스트와 데이터 소스 사이의 방화벽 규칙 확인

교체 전에 bootstrap 토큰 만료

증상: DCP_CLIENT_EVENT_HISTORY가 EVENT_TYPE = 'CERT_ROTATION'에 STATUS = 'FAILURE'를 보여 줘요. 에이전트는 여전히 실행 중이지만 인증서를 갱신할 수 없어요. DESCRIBE도 CERT_ROTATION_STATUS가 실패로 표시해요.

해결: 에이전트는 현재 인증서로 계속 운영되지만 유효한 토큰이 제자리에 놓일 때까지 인증서를 교체할 수 없어요. 새 토큰을 생성해 자격 증명 파일에 작성해요(무중단으로 bootstrap 토큰 교체 참고). 에이전트는 다음 교체 시도에서 이를 읽으며, 재시작은 필요하지 않아요.

여러 에이전트: 일부 연결이 잘못된 에이전트에 도달

원인: DCP는 에이전트 간에 개별 연결을 부하 분산하지 않아요. 각 워크로드-목적지 매핑은 한 번에 정확히 하나의 에이전트가 소유해요. 연결은 컨트롤 플레인 라우팅 테이블을 통해 결정적으로 라우팅돼요.

해결: 이는 오설정이 아닌 예상된 동작이에요. 처리량 확장을 위해 개별 에이전트 호스트 크기를 적절히 조정해요. 특정 에이전트가 포화되면 EAI 스코핑을 검토해 목적지가 에이전트 간에 올바르게 분할되게 해요.

더 알아보기 (Learn more)