ClickHouse 컨트롤 플레인과 BYOC VPC 간 연결
ClickHouse Cloud 컨트롤 플레인은 BYOC 배포를 운영하고 지원하기 위해 여러 유형의 연결을 유지합니다:클라우드 제공업체 API와 Kubernetes API
서로 다른 두 제어 경로는 혼동하기 쉽습니다. 두 경로는 트래픽 출발지, 인증 방식, Tailscale 적용 가능 여부가 다릅니다.
요약하면 Kubernetes API 및 문제 해결 트래픽만 Tailscale을 사용할 수 있습니다. 위에서 설명한 관리 호출은 항상 ClickHouse Cloud 네트워크에서 시작해 제공업체 엔드포인트에서 종료됩니다. 애초에 사용자 네트워크에 진입하지 않으므로 Tailscale을 통해 라우팅할 수 없습니다.
클라우드 제공업체 API는 반대 방향에서, 즉 사용자 cluster 내부에서 실행되는 컨트롤러(load balancer 컨트롤러, CSI 드라이버, 자동 스케일러, DNS 컨트롤러, cert-manager)에 의해서도 호출됩니다. 이러한 호출은 cluster 내부 아이덴티티를 사용하며 사용자의 자체 이그레스 경로를 통해 나가므로, 감사 추적에는 관리 호출과 다른 아이덴티티 및 다른 소스 주소로 나타납니다. 아웃바운드 연결을 참조하십시오.
네트워크 출발지 기반 권한 경계
조직에서 네트워크 출발지를 기준으로 IAM role 수임 또는 Cloud API 호출을 제한하는 경우(예:aws:SourceIp 또는 aws:SourceVpc를 사용하는 AWS SCP 또는 역할 신뢰 조건), 이러한 조건으로 인해 ClickHouse의 자동화가 차단됩니다. 해당 호출은 사용자 네트워크가 아니라 ClickHouse Cloud 네트워크에서 정상적으로 발생하기 때문입니다. 이러한 조건에서 ClickHouse가 생성한 역할을 제외하거나, 출발지를 기준으로 허용 목록을 적용해야 한다면 현재 egress IP 범위를 ClickHouse에 문의하십시오.
다음 섹션에서는 문제 해결 및 선택적 관리 액세스에 Tailscale 프라이빗 네트워크를 사용하는 방법을 설명합니다.
Tailscale 프라이빗 네트워크
개요
- 관리 작업: ClickHouse 관리 서비스가 BYOC 인프라와 연동하여 수행하는 작업
- 문제 해결 접근: ClickHouse 엔지니어가 진단을 위해 Kubernetes API 서버와 ClickHouse 시스템 테이블에 접근
- 메트릭 접근: ClickHouse의 중앙 집중식 모니터링 대시보드가 BYOC VPC 내에 배포된 Prometheus 스택의 메트릭에 접근하여, ClickHouse 엔지니어가 해당 환경의 관측성을 확보할 수 있도록 합니다.
BYOC에서 Tailscale이 작동하는 방식
Tailscale을 통해 액세스해야 하는 각 서비스 또는 엔드포인트에 대해 ClickHouse BYOC는 다음을 배포합니다:-
Tailnet 주소 등록: 각 엔드포인트는 고유한 tailnet 주소를 등록합니다(예: Kubernetes API 서버의 경우
k8s.xxxx.us-east-1.aws.byoc.clickhouse-prd.com) -
Tailscale 에이전트 컨테이너: Kubernetes 클러스터에서 Tailscale 에이전트 컨테이너가 실행되며, 다음을 담당합니다:
- Tailscale coordination server에 연결
- 서비스를 등록해 검색할 수 있도록 함
- Nginx 파드와 네트워크 설정을 조정
-
Nginx 파드: 다음을 수행하는 Nginx 파드:
- Tailscale에서 들어오는 TLS 트래픽을 종료 처리
- Kubernetes 클러스터 내의 적절한 IP로 트래픽을 라우팅
네트워크 연결 프로세스
Tailscale 연결은 다음 단계로 이루어집니다:-
초기 연결:
- 양쪽 끝의 Tailscale 에이전트(ClickHouse 엔지니어의 환경과 BYOC Kubernetes 클러스터)가 Tailscale coordination server에 연결합니다
- Kubernetes 클러스터 에이전트가 Kubernetes 서비스를 등록해 검색 가능하도록 합니다
- ClickHouse 엔지니어가 해당 서비스를 볼 수 있도록 하려면 내부 에스컬레이션이 필요합니다
-
연결 모드:
- 직접 모드: 에이전트가 NAT 트래버설 터널을 통해 직접 연결을 설정하려고 시도합니다
- 릴레이 모드: 직접 모드가 실패하면 통신은 Tailscale DERP(Distributed Encrypted Relay Protocol) 서버를 통한 릴레이 모드로 전환됩니다
-
암호화:
- 모든 통신은 종단 간 암호화됩니다
- 각 Tailscale 에이전트는 자체 공개 키-개인 키 쌍(PKI와 유사함)을 생성합니다
- 직접 모드와 릴레이 모드 중 어느 것을 사용하든 트래픽은 암호화된 상태로 유지됩니다
보안 기능
- Kubernetes 클러스터의 Tailscale 에이전트가 Tailscale coordination/relay server로 아웃바운드 연결을 시작합니다
- 인바운드 연결은 필요하지 않습니다 — security group 규칙에서 Tailscale 에이전트에 대한 인바운드 트래픽을 허용할 필요가 없습니다
- 따라서 공격 표면이 줄어들고 네트워크 보안 구성이 단순해집니다
- 엔지니어가 Tailscale을 통해 고객 엔드포인트로 라우팅되기 전에 내부 승인 워크플로를 통해 액세스를 요청해야 합니다
- 액세스는 일정 시간 동안만 유효하며 자동으로 만료됩니다
- 모든 액세스는 감사되며 로그에 기록됩니다
관리 서비스 액세스
기본적으로 ClickHouse 관리 서비스는 API 서버의 퍼블릭 엔드포인트를 통해 BYOC Kubernetes 클러스터에 액세스하며, 이를 제어하는 방식은 클라우드마다 다릅니다. AWS에서는 ClickHouse의 NAT gateway 주소만 포함된 IP 허용 목록으로, GCP와 Azure에서는 클라우드 IAM으로 제어합니다. 클라우드별 세부 사항은 Kubernetes API 서버 노출을 참조하십시오. 선택적 Private Endpoint 구성:- Kubernetes API 서버가 Private Endpoint만 사용하도록 구성할 수 있습니다
- 이 경우 관리 서비스는 Tailscale을 통해 API 서버에 액세스하거나(사용자의 문제 해결 접근과 유사), AWS에서는 VPC Lattice를 통해 액세스합니다(Kubernetes API Private Connection 참조)
- 기본적으로 퍼블릭 엔드포인트는 긴급 investigation 및 지원이 필요한 경우를 대비한 백업 메커니즘으로 유지되며, 프라이빗 액세스가 확인되면 ClickHouse와 협의하여 완전히 비활성화할 수 있습니다
네트워크 트래픽 흐름
Tailscale 연결 흐름:- Kubernetes 클러스터의 Tailscale 에이전트 → Tailscale coordination server(아웃바운드)
- 엔지니어의 머신에 있는 Tailscale 에이전트 → Tailscale coordination server(아웃바운드)
- 에이전트 간에 직접 연결 또는 릴레이 연결이 설정됩니다
- 설정된 터널을 통해 암호화된 트래픽이 흐릅니다
- Kubernetes 클러스터의 Nginx 파드가 TLS 종료를 수행하고 내부 서비스로 라우팅합니다
- Tailscale 연결은 관리 및 문제 해결 목적으로만 사용됩니다
- 쿼리 트래픽과 고객 데이터는 Tailscale을 통해 전송되지 않습니다
- 모든 고객 데이터는 사용자 자신의 클라우드 계정 내에 유지됩니다
네트워크 경계
이 섹션에서는 BYOC 배포를 방화벽 관점에서 살펴봅니다. 즉, 양방향 어느 쪽으로든 BYOC 네트워크의 경계를 넘나드는 모든 연결을 다룹니다. AWS, GCP, Azure에 모두 적용되며, 클라우드마다 동작이 다를 때는 해당 클라우드를 명시합니다. 문서 전반에서 사용되는 용어는 다음과 같습니다.- Inbound: BYOC 네트워크로 들어오는 트래픽 — AWS의 VPC, GCP의 VPC 네트워크, Azure의 VNet.
- Outbound: BYOC 네트워크에서 시작되어 외부 대상으로 전송되는 트래픽.
- Public: 공용 인터넷에서 연결할 수 있는 endpoint.
- Private: 프라이빗 경로를 통해서만 연결할 수 있는 endpoint — VPC/VNet peering, AWS PrivateLink, GCP Private Service Connect, Azure Private Link 또는 Tailscale.
프로바이더별 대응 항목
이 페이지의 나머지 부분에서는 클라우드 중립적인 명칭을 사용합니다. 다음 표는 이러한 명칭을 각 프로바이더의 항목에 매핑한 것입니다:
공용 인터넷으로 나가는 이그레스 트래픽은 모든 클라우드에서 소수의 고정된 NAT 주소를 통해 BYOC 네트워크를 빠져나가므로, 자체 이그레스 제어 정책에 해당 주소를 고정해 둘 수 있습니다. 배포 환경에 적용되는 현재 값은 ClickHouse 팀에 문의하십시오. AWS와 GCP에서는 프로바이더 자체 스토리지 API로 향하는 트래픽만 예외입니다. 이 트래픽은 위 표의 프라이빗 경로를 사용하며 NAT gateway를 거치지 않습니다.
인바운드 연결
이러한 로드 밸런서에서 두 개의 포트가 보이기도 하지만 클라이언트용은 아닙니다. TCP 15021은 인그레스 게이트웨이를 대상으로 한 공급자 자체의 상태 확인에 사용되며 쿼리 트래픽은 전달하지 않고, MySQL 인터페이스(포트 3306)는 현재 BYOC에서 노출되지 않습니다 — FAQ를 참조하십시오.
인그레스 게이트웨이의 certificate는 cert-manager가 퍼블릭 ACME certificate authority(Let’s Encrypt)에서 DNS-01 검증을 통해 발급하며, 사용자의 클러스터 내부에 Kubernetes secret으로 저장됩니다. 인그레스 게이트웨이와 ClickHouse 파드 사이의 트래픽은 BYOC 네트워크 내부에 머무릅니다 — 네트워크 내부 트래픽을 참조하십시오.
두 로드 밸런서 중 어느 쪽이 기본으로 활성화되는지는 네트워킹 모델에 따라 달라집니다. ClickHouse 관리형 VPC에서는 각 서비스에 IP 액세스 목록으로 보호되는 퍼블릭 로드 밸런서가 제공되며, 프라이빗 로드 밸런서를 함께 활성화할 수 있습니다. 고객 관리형 VPC에서는 기본값이 정반대입니다. 프라이빗 로드 밸런서만 활성화되며, 별도로 추가하지 않는 한 서비스에는 퍼블릭 인그레스 노출면이 존재하지 않습니다. BYOC 서비스에 연결을 참조하십시오.
퍼블릭 경로를 활성화한 곳에서는 IP 필터 구성을 강력히 권장하며, 프라이빗 경로를 추가한 뒤(Private Networking Setup 참조) 퍼블릭 액세스를 완전히 비활성화할 수도 있습니다. IP 필터링은 인그레스 프록시 계층에서 적용되므로, 스캔 시 로드 밸런서 포트가 열려 있는 것처럼 보이더라도 목록에 없는 소스의 연결은 거부됩니다.
위에 나열된 리스너 외에 SSH, 배스천 호스트, 상시 관리자 자격 증명은 존재하지 않습니다. 쿼리 트래픽은 어느 방향으로도 ClickHouse 소유 인프라를 경유하지 않으며, 클라이언트는 사용자 네트워크 내부의 인그레스에 직접 연결합니다.배포별로 추가 프로토콜 포트를 활성화할 수 있습니다. certificate 인증 기반 네이티브 액세스와 Arrow Flight가 현재의 예시입니다. 따라서 이 표를 근거로 방화벽 규칙을 작성하기 전에 담당 ClickHouse 팀과 함께 해당 배포의 정확한 포트 구성을 확인하십시오.
Kubernetes API 서버 노출
ClickHouse 관리 서비스가 Kubernetes API 서버에 접근하는 방식과 그 액세스를 제한하는 요소는 클라우드별로 다릅니다:- AWS (EKS): 퍼블릭 엔드포인트는 클러스터의 퍼블릭 액세스 CIDR 목록을 통해 ClickHouse의 egress CIDR 범위로만 제한됩니다. Tailscale 또는 VPC Lattice를 사용해 프라이빗 전용 액세스로 전환할 수 있습니다 — Kubernetes API Private Connection을 참조하십시오.
- GCP (GKE): 노드는 항상 프라이빗입니다. 컨트롤 플레인은 DNS 기반 엔드포인트(
*.gke.goog)를 통해 접근하며, IP 허용 목록가 아니라 가장된(impersonated) service account에 부여된container.clusters.connectIAM permission으로 인증됩니다. 요청은 사용자의 VPC 네트워크 내부가 아니라 Google 프런트엔드에서 종료되지만, 여전히 클러스터 컨트롤 플레인으로 들어가는 액세스 경로이므로 인바운드 액세스로 간주하여 검토하십시오. 별도의 IP 기반 퍼블릭 엔드포인트는 비활성화할 수 있으며, 이 경우 DNS 기반 엔드포인트가 컨트롤 플레인으로 향하는 유일한 경로가 됩니다 — Kubernetes API Private Connection을 참조하십시오. - Azure (AKS): Kubernetes API 서버는 퍼블릭 FQDN을 통해 접근하며 Microsoft Entra ID와 Azure RBAC로 인증됩니다. Kubernetes API 서버 승인 IP 범위는 기본적으로 적용되지 않으므로, 정책상 필요한 경우 ClickHouse에 문의하십시오. 또는 퍼블릭 FQDN을 비활성화하고 Azure Private Link를 통해 접근하는 프라이빗 클러스터로 생성할 수도 있습니다 — Kubernetes API Private Connection을 참조하십시오.
프라이빗 경로로 옮길 수 있는 것은 Kubernetes API 및 문제 해결 트래픽뿐입니다. 클라우드 제공업체 API로 향하는 관리 호출은 ClickHouse Cloud 네트워크에서 시작되므로 해당 경로로 라우팅할 수 없습니다 — 클라우드 제공업체 API와 Kubernetes API 비교를 참조하십시오. 여기서는 사용자 클러스터 내부의 컨트롤러가 수행하는 제공업체 API calls도 함께 설명합니다.
문제 해결 접근
Inbound, Private ClickHouse Cloud 엔지니어는 모든 클라우드에서 문제 해결을 위해 오직 Tailscale을 통해서만 배포 환경에 접근하며, 공용 인터넷으로는 절대 접근하지 않습니다. 액세스는 적시(just-in-time) 방식의 인증서 기반으로 이루어집니다. 엔지니어가 내부 승인 workflow를 통해 액세스를 요청하면 플랫폼이 엔지니어별 단기 credential을 발급하며, 이 credential은 자동으로 만료됩니다. 공유되는 관리자 아이덴티티나 상시 액세스는 존재하지 않습니다. 엔지니어가 읽을 수 있는 테이블을 비롯한 전체 정책은 ClickHouse data access를 참조하십시오.Outbound connections
Billing scraper
Outbound, Private billing scraper는 ClickHouse에서 사용량 데이터를 수집하여 ClickHouse Cloud가 소유한 버킷으로 전송합니다. AWS에서는 S3, GCP에서는 Cloud Storage, Azure에서는 Blob Storage가 사용됩니다. 이 구성 요소는 ClickHouse 서버 컨테이너와 함께 사이드카로 실행되며, ClickHouse 시스템 테이블에서 CPU 및 메모리 메트릭을 주기적으로 스크레이프합니다. 레코드는 불투명한 서비스 식별자와 파드 이름을 키로 사용합니다. 동일 리전 요청은 Provider equivalents에 나열된 provider의 storage API로 프라이빗 경로를 통해 전달되므로, AWS와 GCP에서는 이 트래픽이 공용 인터넷을 거치지 않습니다.알림
Outbound, Public AlertManager는 ClickHouse 클러스터가 비정상 상태일 때 ClickHouse Cloud로 알림을 전송하도록 구성되어 있습니다. BYOC 알림 payload는 의도적으로 알림 이름과 서비스 식별자만 포함하도록 축소되어 있습니다. 전체 모니터링 데이터셋은 어떤 클라우드에서든 사용자 소유 계정 내에 그대로 유지됩니다. 다음 두 가지는 경계가 서로 다르므로 반드시 구분해야 합니다.- 지속적으로 내보내는 데이터. Billing scraper에서 설명한 축소된 사용량 및 health 텔레메트리와 이러한 알림 payload가 ClickHouse 소유 시스템에 기록되는 유일한 관측성 데이터입니다. ClickHouse Cloud로의 Prometheus remote-write는 BYOC 빌드에서 비활성화되어 있습니다.
- 원위치에서 조회. ClickHouse의 모니터링 대시보드는, 그리고 승인된 에스컬레이션이 있을 경우 ClickHouse 엔지니어는 Tailscale을 통해 클러스터 내부의 Prometheus 스택과 사용자의 로그를 쿼리합니다 — Tailscale Private Network를 참조하십시오. 쿼리 결과는 화면에 표시하기 위해 ClickHouse 측 도구까지 전달될 수밖에 없지만, 그곳에 저장되지는 않으며 원본 데이터는 사용자 계정을 벗어나지 않습니다.
서비스 상태
Outbound, Public State Exporter는 ClickHouse 서비스 및 Backup 상태 정보(백업 내용이 아니라 운영 상태 이벤트)를 ClickHouse Cloud가 소유한 큐로 전송합니다. 이때 AWS에서는 SQS, GCP에서는 Pub/Sub, Azure에서는 Service Bus를 사용합니다. 덕분에 ClickHouse Cloud 콘솔에서 사용자 계정에서 실행 중인 서비스의 상태를 확인할 수 있습니다.네트워크 내부 트래픽
클러스터 내부 구성 요소 간 트래픽(ClickHouse와 ClickHouse Keeper 간, 연산자, 인그레스에서 ClickHouse 파드로, 모니터링 스크레이프)은 BYOC 네트워크를 벗어나지 않습니다. 각 클라우드 제공업체는 자사 인스턴스 간 트래픽을 네트워크 계층에서 암호화합니다. AWS, GCP, Azure 문서를 참고하십시오. 이그레스는 기본적으로 보안 그룹, 방화벽 규칙, 네트워크 보안 그룹 계층에서 제한되지 않으며, 실제로 연결되는 대상은 아웃바운드 연결에 명시된 대상입니다. 이를 대신해 서비스별 이그레스 방화벽을 선택적으로 적용하여 대상 허용 목록을 강제할 수 있으니, 필요한 경우 ClickHouse 팀에 문의하십시오.경계 감사
전체 data plane이 사용자 계정에서 실행되므로, 이 페이지에서 설명하는 흐름은 사용자가 보유한 도구로 관찰할 수 있습니다. 일부 소스는 기본적으로 활성화되어 있으며, 나머지는 직접 활성화해야 합니다:- 클라우드 감사 추적(CloudTrail, Cloud Audit Logs 또는 Azure Activity 로그): ClickHouse 자동화가 수행하는 모든 role assumption, 서비스 계정 가장, 서비스 주체 로그인과 이를 통해 이루어진 모든 클라우드 API 호출.
- 플로우 로그(VPC Flow Logs, VPC flow logs 또는 NSG flow logs): 앞서 설명한 연결 중 사용자 네트워크를 통과하는 것들 — 클라이언트 인그레스, 모든 아웃바운드 흐름, Tailscale 채널. 이러한 로그를 보관하려면 직접 활성화하십시오. 단, Kubernetes API 서버에 대한 management 액세스는 예외입니다. 퍼블릭 엔드포인트를 사용하는 동안에는 해당 트래픽이 사용자 네트워크 내부가 아니라 provider의 관리형 컨트롤 플레인 endpoint에서 종료되므로 플로우 로그에 나타나지 않습니다. 대신 Kubernetes audit logs와 클라우드 감사 추적에서 확인하십시오. 플로우 로그에는 API server를 Private Endpoint로 전환한 이후에야 나타납니다.
- Kubernetes audit logs: AWS에서는 audit log를 포함한 EKS 컨트롤 플레인 로그가 사용자 계정의 CloudWatch 로그 그룹으로 전달됩니다. GCP와 Azure에서는 Support에 문의하여 해당 cluster의 컨트롤 플레인 감사 로깅을 확인하거나 활성화하십시오.
- 데이터 및 백업 버킷, 그리고 장기 모니터링 보존 버킷(활성화한 경우)에 대한 객체 스토리지 액세스 로그.
- 사용자의
system.query_log: ClickHouse 자동화 또는 엔지니어가 실행한 모든 statement가 해당 아이덴티티와 함께 기록됩니다.