ClickHouse Cloud Secure S3 Sink

ClickHouse 분류

ClickHouse Cloud

Type

Lab

작성자

Ken

ClickHouse Cloud에서 실시간 데이터를 안전하게 S3로 내보내는 아키텍처와 구현 방법을 다룹니다. IAM Role 기반 인증부터 실제 테스트 결과, 그리고 이벤트 기반 파이프라인 확장 가능성에 대해서 작성하였습니다.

공식 문서는 아래 링크에서 확인하실 수 있습니다. 단, 해당 문서는 s3에 안전하게 “접근”하는 방법만 다루기 때문에, 이번 글에서 다루는 “쓰기”작업을 위해서는 s3:PutObject ,s3:DeleteObject , s3:AbortMultipartUpload 이 추가로 필요합니다.

Accessing S3 data securely | ClickHouse Docs

This article demonstrates how ClickHouse Cloud customers can leverage role-based access to authenticate with Amazon Simple Storage Service(S3) and access their data securely.

clickhouse.com

Accessing S3 data securely | ClickHouse Docs

Secure S3란?
동작 원리
ClickHouse Cloud와 S3 간 Secure S3의 필요성
보안 관점에서의 이점
운영 관점에서의 이점
규정 준수
설정 방법
Step 1: ClickHouse Cloud 서비스의 IAM Role ARN 확인
Step 2: CloudFormation을 통한 IAM Role 생성
Step 3-1: AWS Console에서 직접 IAM Role 생성
Step 3-2: Terraform을 통한 자동화 구성
실제 수행 테스트
테스트 환경
S3 Table Engine을 활용한 Sink 구성
포맷별 성능 비교
데이터 정합성 검증
용도별 권장 설정
Queue 서비스와 연계 가능성
S3 Event Notification 아키텍처
사용 사례별 연계 방안
실용적인 활용 시나리오
마무리

Secure S3란?

Secure S3는 ClickHouse Cloud 서비스가 고객의 AWS S3 버킷에 접근할 때 IAM Role 기반의 크로스 계정 인증을 사용하는 방식입니다. 기존의 Access Key/Secret Key 방식과 달리, AWS STS(Security Token Service)의 AssumeRole 메커니즘을 활용하여 임시 자격 증명을 발급받습니다.

동작 원리

ClickHouse Cloud 서비스는 Anthropic이 관리하는 AWS 계정 내에서 실행됩니다. 고객의 S3 버킷에 접근하려면 ClickHouse 서비스가 고객 AWS 계정 내의 IAM Role을 "Assume"하는 방식으로 동작합니다.

이 방식의 핵심은 고객이 자신의 IAM Policy 한 곳에서 모든 S3 접근 권한을 관리할 수 있다는 점입니다. 개별 버킷 정책을 수정할 필요 없이 IAM Role의 정책만 업데이트하면 됩니다.

ClickHouse Cloud와 S3 간 Secure S3의 필요성

보안 관점에서의 이점

기존 Access Key 방식은 몇 가지 보안 취약점을 가집니다. Access Key는 장기 자격 증명으로, 한번 유출되면 키를 교체할 때까지 위험에 노출됩니다. 또한 키 관리의 복잡성이 증가하고, 여러 서비스에서 동일한 키를 공유하게 되면 추적이 어려워집니다.

IAM Role 기반 인증은 이러한 문제를 해결합니다. 임시 자격 증명은 기본적으로 1시간 후 만료되며, 자동으로 갱신됩니다. CloudTrail을 통해 어떤 서비스가 언제 접근했는지 명확하게 추적할 수 있습니다. 또한 role_session_name을 shared secret처럼 활용하여 추가적인 보안 계층을 구현할 수 있습니다.

운영 관점에서의 이점

운영 측면에서도 IAM Role 방식이 유리합니다. 키 로테이션 작업이 불필요하고, 권한 변경 시 IAM Policy만 수정하면 됩니다. AWS Organizations의 SCP(Service Control Policies)와 연계하여 조직 전체의 접근 정책을 일관되게 적용할 수 있습니다.

규정 준수

금융, 의료 등 규제 산업에서는 자격 증명 관리에 대한 엄격한 요구사항이 있습니다. IAM Role 기반 인증은 SOC 2, HIPAA, PCI-DSS 등의 컴플라이언스 요구사항을 충족하는 데 도움이 됩니다.

설정 방법

Step 1: ClickHouse Cloud 서비스의 IAM Role ARN 확인

ClickHouse Cloud Console에서 다음 단계를 따릅니다.

대상 서비스를 선택합니다
Settings 탭으로 이동합니다
Network security information 섹션에서 Service role ID (IAM) 값을 복사합니다

이 ARN은 arn:aws:iam::123456789012:role/CH-S3-service-name-Role 형태입니다.

Step 2: CloudFormation을 통한 IAM Role 생성

AWS에서 제공하는 CloudFormation 템플릿을 사용하면 필요한 리소스를 자동으로 생성할 수 있습니다. ClickHouse 공식 문서에서 제공하는 템플릿 URL을 통해 스택을 생성합니다.

us-west-2.console.aws.amazon.com

주요 파라미터는 다음과 같습니다.

파라미터	설명
RoleName	생성할 IAM Role 이름 (예: ClickHouseAccessRole-001)
ClickHouse Instance Roles	ClickHouse 서비스 IAM Role ARN (쉼표로 구분)
Bucket Names	접근을 허용할 S3 버킷 이름 (ARN이 아닌 이름만)
Bucket Access	Read 또는 Read/Write
Role Session Name	추가 보안을 위한 세션 이름 (선택)

Step 3-1: AWS Console에서 직접 IAM Role 생성

Terraform 없이 AWS Console에서 직접 설정하는 방법입니다.

1. IAM Role 생성

AWS Console → IAM → Roles → Create role로 이동합니다. "Custom trust policy"를 선택하고 아래 Trust Policy를 입력합니다.

json

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowClickHouseAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:role/CH-S3-your-service-Role"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Principal.AWS 값을 ClickHouse Cloud Console에서 복사한 Service role ID (IAM)로 교체합니다.

2. Permission Policy 생성

Role 생성 후 Permissions 탭에서 "Add permissions" → "Create inline policy"를 선택하고 JSON 탭에서 아래 내용을 입력합니다.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "BucketLevelPermissions",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketLocation",
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    },
    {
      "Sid": "ObjectLevelReadPermissions",
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:GetObjectVersion",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    },
    {
      "Sid": "ObjectLevelWritePermissions",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    }
  ]
}

YOUR_BUCKET_NAME을 실제 S3 버킷 이름으로 교체합니다. 여러 버킷에 접근해야 하면 Resource를 배열로 지정하거나 Statement를 추가합니다.

3. Role ARN 복사

생성된 Role의 ARN (예: arn:aws:iam::111111111111:role/ClickHouseAccessRole)을 복사해서 ClickHouse 쿼리의 extra_credentials에서 사용합니다.

Step 3-2: Terraform을 통한 자동화 구성

프로덕션 환경에서는 Infrastructure as Code로 관리하는 것이 권장됩니다. 아래는 Terraform 구성 예시입니다.

# variables.tf
variable "clickhouse_service_role_arn" {
  description = "ClickHouse Cloud 서비스의 IAM Role ARN"
  type        = string
}

variable "s3_bucket_name" {
  description = "접근을 허용할 S3 버킷 이름"
  type        = string
}

# iam.tf
resource "aws_iam_role" "clickhouse_access" {
  name = "ClickHouseAccessRole"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect = "Allow"
        Principal = {
          AWS = var.clickhouse_service_role_arn
        }
        Action = "sts:AssumeRole"
      }
    ]
  })
}

resource "aws_iam_role_policy" "s3_access" {
  name = "S3AccessPolicy"
  role = aws_iam_role.clickhouse_access.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid    = "BucketLevelPermissions"
        Effect = "Allow"
        Action = [
          "s3:GetBucketLocation",
          "s3:ListBucket"
        ]
        Resource = "arn:aws:s3:::${var.s3_bucket_name}"
      },
      {
        Sid    = "ObjectLevelReadPermissions"
        Effect = "Allow"
        Action = [
          "s3:GetObject",
          "s3:GetObjectVersion",
          "s3:ListMultipartUploadParts"
        ]
        Resource = "arn:aws:s3:::${var.s3_bucket_name}/*"
      },
      {
        Sid    = "ObjectLevelWritePermissions"
        Effect = "Allow"
        Action = [
          "s3:PutObject",
          "s3:DeleteObject",
          "s3:AbortMultipartUpload"
        ]
        Resource = "arn:aws:s3:::${var.s3_bucket_name}/*"
      }
    ]
  })
}

# s3.tf
resource "aws_s3_bucket" "data_lake" {
  bucket = var.s3_bucket_name
}

resource "aws_s3_bucket_versioning" "data_lake" {
  bucket = aws_s3_bucket.data_lake.id
  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "data_lake" {
  bucket = aws_s3_bucket.data_lake.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

# outputs.tf
output "clickhouse_access_role_arn" {
  description = "ClickHouse에서 사용할 IAM Role ARN"
  value       = aws_iam_role.clickhouse_access.arn
}

output "s3_bucket_url" {
  description = "S3 버킷 URL"
  value       = "s3://${aws_s3_bucket.data_lake.id}/"
}

실제 수행 테스트

테스트 환경

실제 테스트를 통해 Secure S3 연동의 성능과 안정성을 검증했습니다.

항목	설정값
ClickHouse Cloud 리전	ap-northeast-2 (Seoul)
S3 버킷 리전	ap-northeast-2
테이블 엔진	SharedMergeTree
데이터 소스	ClickPipes (Kafka)
테스트 레코드 수	137,240건
테스트 기간	약 3분 (13:50:00 ~ 13:53:13 UTC)

S3 Table Engine을 활용한 Sink 구성

ClickHouse에서 S3로 데이터를 내보내는 방법은 S3 Table Engine을 활용합니다.

-- S3 테이블 생성 (CSV 포맷)
CREATE TABLE s3_sink_csv
ENGINE = S3(
  'https://s3.ap-northeast-2.amazonaws.com/my-bucket/exports/csv/',
  'CSVWithNames',
  extra_credentials(
    role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole'
  )
)
AS SELECT * FROM source_table WHERE 1=0;

-- S3 테이블 생성 (Parquet 포맷)
CREATE TABLE s3_sink_parquet
ENGINE = S3(
  'https://s3.ap-northeast-2.amazonaws.com/my-bucket/exports/parquet/',
  'Parquet',
  extra_credentials(
    role_arn = 'arn:aws:iam::111111111111:role/ClickHouseAccessRole'
  )
)
AS SELECT * FROM source_table WHERE 1=0;

Materialized View를 통해 실시간으로 데이터를 S3로 스트리밍할 수 있습니다.

-- 실시간 S3 Sink를 위한 Materialized View
CREATE MATERIALIZED VIEW mv_s3_export
TO s3_sink_parquet
AS SELECT
  toDateTime(timestamp) as event_time,
  user_id,
  event_type,
  properties
FROM source_kafka_table;

중요한 설정으로 s3_create_new_file_on_insert를 활성화해야 각 INSERT마다 새로운 파일이 생성됩니다.

s3_create_new_file_on_insert = 0 (기본값)이면, S3는 객체 스토리지이 때문에 파일에 append를 하지 못하고 새로 덮어써쓰게 됩니다. 그래서 같은 경로로 INSERT를 여러 번 하면 마지막 INSERT 데이터만 남고, 이전 데이터는 전부 유실됩니다.

SET s3_create_new_file_on_insert = 1;

포맷별 성능 비교

CSV와 Parquet 두 포맷으로 동일한 데이터셋을 테스트한 결과입니다.

메트릭	CSVWithNames	Parquet	비고
쓰기 시간	~17초	~20초	CSV가 약 15% 빠름
읽기 시간 (COUNT)	189ms	141ms	Parquet가 25% 빠름
읽기 데이터 크기	11.75 MiB	1.05 MiB	Parquet 11배 효율적
메모리 사용량	23.2 MB	6.1 MB	Parquet 3.8배 효율적
처리량 (Write)	~8,073 rows/s	~6,862 rows/s	CSV 17.6% 높음

데이터 정합성 검증

분 단위로 레코드 수를 비교하여 데이터 무결성을 확인했습니다.

시간	원본 테이블	CSV (S3)	Parquet (S3)	상태
13:50:00	46,805	46,805	46,805	✓ 일치
13:51:00	46,329	46,329	46,329	✓ 일치
13:52:00	37,091	37,091	37,091	✓ 일치
13:53:00	7,015	7,015	7,015	✓ 일치
합계	137,240	137,240	137,240	100% 정합

용도별 권장 설정

테스트 결과를 바탕으로 용도별 권장 설정은 다음과 같습니다.

분석/백업 용도에는 Parquet 포맷을 권장합니다. 압축률이 우수하고 컬럼 기반 분석 쿼리에 최적화되어 있습니다. Athena, Spark 등 다른 분석 도구와의 호환성도 뛰어납니다.

실시간 스트리밍에는 CSV 포맷과 작은 배치 사이즈를 권장합니다. 쓰기 속도가 빠르고 파싱 오버헤드가 적어 레이턴시에 민감한 워크로드에 적합합니다.

Queue 서비스와 연계 가능성

S3에 데이터가 적재되면 AWS의 이벤트 기반 서비스들과 연계하여 다양한 파이프라인을 구축할 수 있습니다.

S3 Event Notification 아키텍처

S3는 객체 생성, 삭제 등의 이벤트 발생 시 다양한 대상으로 알림을 전송할 수 있습니다.

사용 사례별 연계 방안

SQS를 통한 순차 처리는 파일 처리 순서가 중요하거나, 처리 실패 시 재시도가 필요한 경우에 적합합니다. Dead Letter Queue를 통해 실패한 메시지를 별도로 관리할 수 있습니다.

# Lambda 함수 예시 - SQS 트리거
import json
import boto3

def lambda_handler(event, context):
    for record in event['Records']:
        body = json.loads(record['body'])
        s3_event = json.loads(body['Message']) if 'Message' in body else body

        for s3_record in s3_event.get('Records', []):
            bucket = s3_record['s3']['bucket']['name']
            key = s3_record['s3']['object']['key']

            # Parquet 파일 처리 로직
            process_parquet_file(bucket, key)

SNS를 통한 Fan-out 패턴은 동일한 이벤트를 여러 소비자에게 동시에 전달해야 할 때 유용합니다. 예를 들어 새 파일이 업로드되면 데이터 품질 검증, 메타데이터 추출, 알림 발송을 동시에 수행할 수 있습니다.

EventBridge를 통한 고급 라우팅은 이벤트 내용에 따라 다른 처리 로직을 적용해야 할 때 적합합니다. 파일 크기, 경로 패턴 등을 기반으로 세밀한 라우팅 규칙을 정의할 수 있습니다.

{
  "source": ["aws.s3"],
  "detail-type": ["Object Created"],
  "detail": {
    "bucket": {
      "name": ["my-clickhouse-export-bucket"]
    },
    "object": {
      "key": [{
        "prefix": "exports/parquet/"
      }]
    }
  }
}

실용적인 활용 시나리오

데이터 레이크 연동 시나리오에서는 ClickHouse에서 집계된 데이터를 S3에 Parquet로 적재하고, AWS Glue Crawler가 스키마를 자동 탐지합니다. 이후 Athena나 Redshift Spectrum에서 분석하는 파이프라인을 구성할 수 있습니다.

실시간 알림 시스템에서는 특정 조건의 데이터가 적재되면 SNS를 통해 Slack이나 이메일로 알림을 발송합니다. 이상 탐지, 임계치 초과 등의 이벤트를 즉시 전달할 수 있습니다.

백업 및 아카이빙에서는 일정 주기로 S3에 백업하고, S3 Lifecycle Policy를 통해 Glacier로 자동 이관합니다. 비용 효율적인 장기 보관이 가능합니다.

마무리

ClickHouse Cloud의 Secure S3 기능은 엔터프라이즈 환경에서 요구하는 보안 수준을 충족하면서도 실시간 데이터 파이프라인 구축에 필요한 성능을 제공합니다. IAM Role 기반 인증을 통해 키 관리 부담을 줄이고, Terraform을 활용한 IaC 구성으로 재현 가능한 인프라를 유지할 수 있습니다.

테스트 결과에서 확인했듯이 Parquet 포맷은 읽기 성능과 저장 효율성에서 우수하며, CSV는 쓰기 속도가 빨라 용도에 맞게 선택할 수 있습니다. S3 Event Notification과 AWS 메시징 서비스를 연계하면 ClickHouse를 중심으로 한 확장 가능한 데이터 아키텍처를 구축할 수 있습니다.

참고 자료

ClickHouse Docs - Accessing S3 data securely
AWS S3 Event Notifications
Terraform AWS Provider

테스트 코드

clickhouse-hols/terraform-chc-secures3-aws at main · litkhai/clickhouse-hols

ClickHouse Hands-on Labs . Contribute to litkhai/clickhouse-hols development by creating an account on GitHub.

github.com

clickhouse-hols/terraform-chc-secures3-aws at main · litkhai/clickhouse-hols