W&B Weave를 자체 호스팅하면 환경과 설정을 더 세밀하게 제어할 수 있습니다. 이를 통해 더 격리된 환경을 구축하고 추가적인 보안 규정 준수 요구사항도 충족할 수 있습니다. 이 문서에서는 Altinity ClickHouse Operator를 사용해 자체 관리형 환경에서 W&B Weave를 실행하는 데 필요한 모든 컴포넌트를 배포하는 방법을 안내합니다.
자체 관리형 Weave 배포는 백엔드 관리를 위해 ClickHouseDB를 사용합니다. 이 배포에서는 다음을 사용합니다.
- Altinity ClickHouse Operator: Kubernetes용 엔터프라이즈급 ClickHouse 관리
- ClickHouse Keeper: 분산 코디네이션 서비스(ZooKeeper 대체)
- ClickHouse Cluster: 트레이스 저장을 위한 고가용성 데이터베이스 클러스터
- S3-Compatible Storage: ClickHouse 데이터 영속성을 위한 객체 저장소
이 가이드의 설정 예시는 레퍼런스용일 뿐입니다. 각 조직의 Kubernetes 환경은 서로 다르므로 self-hosted 인스턴스에서는 다음 항목을 조정해야 할 가능성이 높습니다.
- 보안 및 규정 준수: 조직의 보안 정책과 Kubernetes/OpenShift 요구 사항에 맞게 보안 컨텍스트,
runAsUser/fsGroup 값 및 기타 보안 설정을 조정합니다.
- 리소스 크기 산정: 여기에 표시된 리소스 할당은 시작점일 뿐입니다. 예상 트레이스 볼륨과 성능 요구 사항에 맞는 적절한 크기 산정을 위해 W&B Solutions Architect 팀에 문의하세요.
- 인프라별 세부 사항: 저장소 클래스, 노드 셀렉터 및 기타 인프라별 설정을 환경에 맞게 업데이트합니다.
이 가이드의 설정은 정해진 해법이 아니라 템플릿으로 취급해야 합니다.
자체 관리형 Weave 인스턴스에는 다음 리소스가 필요합니다:
- Kubernetes Cluster: 버전 1.29+
- Kubernetes Nodes: 멀티노드 클러스터(고가용성을 위해 최소 3개 노드 권장)
- Storage Class: 영구 볼륨용으로 정상 작동하는 StorageClass(예:
gp3, standard, nfs-csi)
- S3 Bucket: 적절한 액세스 권한이 설정된, 미리 구성된 S3 또는 S3 호환 버킷
- W&B Platform: 이미 설치되어 실행 중이어야 함(W&B 자체 관리형 Deployment Guide 참조)
- W&B License: W&B 지원팀에서 제공하는 Weave 활성화 라이선스
이 사전 요구 사항 목록만을 기준으로 크기 산정을 결정하지 마세요. 필요한 리소스는 트레이스 볼륨과 사용 패턴에 따라 크게 달라집니다. 구체적인 클러스터 크기 산정 지침은 자세한 Resource Requirements 섹션을 참조하세요.
- 클러스터에 접근할 수 있도록 구성된
kubectl
helm v3.0+- AWS 자격 증명(S3를 사용하는 경우) 또는 S3 호환 저장소에 대한 접근 권한
Kubernetes 클러스터에는 다음과 같은 네트워크 설정이 필요합니다:
clickhouse 네임스페이스의 파드는 wandb 네임스페이스의 파드와 통신할 수 있어야 합니다- ClickHouse 노드는 포트 8123, 9000, 9009, 2181을 통해 서로 통신할 수 있어야 합니다
Step 1: Altinity ClickHouse Operator 배포
1.1 Altinity Helm 저장소 추가하기
helm repo add altinity https://helm.altinity.com
helm repo update
ch-operator.yaml이라는 이름의 파일을 생성합니다:
operator:
image:
repository: altinity/clickhouse-operator
# Security context - 클러스터 요구 사항에 맞게 조정하세요
containerSecurityContext:
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # OpenShift/Kubernetes 보안 정책에 따라 업데이트하세요
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
metrics:
enabled: false
# Name override - 필요한 경우 사용자 지정하세요
nameOverride: "wandb"
containerSecurityContext 값은 대부분의 Kubernetes 배포판에서 잘 동작합니다. OpenShift의 경우 프로젝트에 할당된 UID 범위에 맞게 runAsUser와 fsGroup을 조정해야 할 수 있습니다.
helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
--namespace clickhouse \
--create-namespace \
-f ch-operator.yaml
# Operator 파드가 실행 중인지 확인
kubectl get pods -n clickhouse
# 예상 출력:
# NAME READY STATUS RESTARTS AGE
# ch-operator-wandb-xxxxx 1/1 Running 0 30s
# Operator 이미지 버전 확인
kubectl get pods -n clickhouse -o jsonpath="{.items[*].spec.containers[*].image}" | \
tr ' ' '\n' | grep -v 'metrics-exporter' | sort -u
# 예상 출력:
# altinity/clickhouse-operator:0.25.4
# AWS 예시
aws s3 mb s3://my-wandb-clickhouse-bucket --region eu-central-1
옵션 A: AWS IAM 역할 사용(IRSA - AWS 환경에서 권장)
Kubernetes 노드에 S3에 액세스할 수 있는 IAM 역할이 있으면 ClickHouse는 EC2 인스턴스 메타데이터를 사용할 수 있습니다:
# ch-server.yaml에서 설정:
<use_environment_credentials>true</use_environment_credentials>
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:DeleteObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::my-wandb-clickhouse-bucket",
"arn:aws:s3:::my-wandb-clickhouse-bucket/*"
]
}
]
}
옵션 B: 액세스 키 사용
정적 자격 증명을 사용하려면 Kubernetes 시크릿을 생성합니다:
kubectl create secret generic aws-creds \
--namespace clickhouse \
--from-literal aws_access_key=YOUR_ACCESS_KEY \
--from-literal aws_secret_key=YOUR_SECRET_KEY
ch-server.yaml 설정 참조).
Step 3: ClickHouse Keeper 배포
ch-keeper.yaml 파일을 만듭니다:
apiVersion: "clickhouse-keeper.altinity.com/v1"
kind: "ClickHouseKeeperInstallation"
metadata:
name: wandb
namespace: clickhouse
annotations: {}
spec:
defaults:
templates:
podTemplate: default
dataVolumeClaimTemplate: default
templates:
podTemplates:
- name: keeper
metadata:
labels:
app: clickhouse-keeper
spec:
# 파드 보안 컨텍스트 - 환경에 맞게 조정하세요
securityContext:
fsGroup: 10001 # 클러스터의 보안 요구 사항에 맞게 업데이트하세요
fsGroupChangePolicy: Always
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # OpenShift의 경우 프로젝트에 할당된 UID 범위를 사용하세요
seccompProfile:
type: RuntimeDefault
# 노드 전반에 keeper를 분산하기 위한 안티-어피니티 (HA 권장)
# 클러스터 크기 및 가용성 요구 사항에 따라 사용자 지정하거나 제거하세요
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: "app"
operator: In
values:
- clickhouse-keeper
topologyKey: "kubernetes.io/hostname"
containers:
- name: clickhouse-keeper
imagePullPolicy: IfNotPresent
image: "clickhouse/clickhouse-keeper:25.10"
# 리소스 요청 - 예시 값이므로 워크로드에 맞게 조정하세요
resources:
requests:
memory: "256Mi"
cpu: "0.5"
limits:
memory: "2Gi"
cpu: "1"
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
volumeClaimTemplates:
- name: data
metadata:
labels:
app: clickhouse-keeper
spec:
storageClassName: gp3 # 사용 중인 StorageClass로 변경하세요
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi
configuration:
clusters:
- name: keeper # Keeper 클러스터 이름 - 서비스 DNS 명명에 사용됨
layout:
replicasCount: 3
templates:
podTemplate: keeper
dataVolumeClaimTemplate: data
settings:
logger/level: "information"
logger/console: "true"
listen_host: "0.0.0.0"
keeper_server/four_letter_word_white_list: "*"
keeper_server/coordination_settings/raft_logs_level: "information"
keeper_server/enable_ipv6: "false"
keeper_server/coordination_settings/async_replication: "true"
- StorageClass: 클러스터에서 사용 가능한 StorageClass에 맞게
storageClassName: gp3를 업데이트하세요
- Security Context: 조직의 보안 정책을 준수하도록
runAsUser, fsGroup 값을 조정하세요
- Anti-Affinity: 클러스터 토폴로지와 HA 요구 사항에 따라
affinity 섹션을 사용자 지정하거나 제거하세요
- Resources: CPU/메모리 값은 예시일 뿐입니다 - 적절한 크기 산정을 위해 W&B Solutions Architects와 상의하세요
- Naming:
metadata.name 또는 configuration.clusters[0].name을 변경하는 경우, 이에 맞게 ch-server.yaml의 Keeper 호스트명(Step 4)을 반드시 업데이트해야 합니다
kubectl apply -f ch-keeper.yaml
# Keeper 파드 확인
kubectl get pods -n clickhouse -l app=clickhouse-keeper
# 예상 출력:
# NAME READY STATUS RESTARTS AGE
# chk-wandb-keeper-0-0-0 1/1 Running 0 2m
# chk-wandb-keeper-0-1-0 1/1 Running 0 2m
# chk-wandb-keeper-0-2-0 1/1 Running 0 2m
# Keeper 서비스 확인
kubectl get svc -n clickhouse | grep keeper
# 포트 2181에서 keeper 서비스가 표시될 것으로 예상
Step 4: ClickHouse 클러스터 배포
ch-server.yaml이라는 이름의 파일을 만듭니다:
apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
name: wandb
namespace: clickhouse
annotations: {}
spec:
defaults:
templates:
podTemplate: default
dataVolumeClaimTemplate: default
templates:
podTemplates:
- name: clickhouse
metadata:
labels:
app: clickhouse-server
spec:
# 파드 보안 컨텍스트 - 사용자 환경에 맞게 사용자 지정하세요
securityContext:
fsGroup: 10001 # 보안 정책에 따라 조정하세요
fsGroupChangePolicy: Always
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # OpenShift의 경우 할당된 UID 범위를 사용하세요
seccompProfile:
type: RuntimeDefault
# 안티-어피니티 규칙 - 서버가 서로 다른 노드에서 실행되도록 보장합니다 (선택 사항이지만 권장)
# 클러스터 크기 및 요구 사항에 따라 조정하거나 제거하세요
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: "app"
operator: In
values:
- clickhouse-server
topologyKey: "kubernetes.io/hostname"
containers:
- name: clickhouse
image: clickhouse/clickhouse-server:25.10
# 리소스 할당 예시 - 워크로드에 따라 조정하세요
resources:
requests:
memory: 1Gi
cpu: 1
limits:
memory: 16Gi
cpu: 4
# AWS 자격 증명 (IRSA 사용 시 이 섹션을 제거하세요)
env:
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_access_key
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_secret_key
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
volumeClaimTemplates:
- name: data
metadata:
labels:
app: clickhouse-server
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 50Gi
storageClassName: gp3 # 사용 중인 StorageClass로 변경하세요
configuration:
# Keeper (ZooKeeper) 설정
# 중요: 이 호스트명은 Step 3의 Keeper 배포와 반드시 일치해야 합니다
zookeeper:
nodes:
- host: chk-wandb-keeper-0-0.clickhouse.svc.cluster.local
port: 2181
- host: chk-wandb-keeper-0-1.clickhouse.svc.cluster.local
port: 2181
- host: chk-wandb-keeper-0-2.clickhouse.svc.cluster.local
port: 2181
# 선택 사항: 필요한 경우 주석을 해제하여 타임아웃을 조정하세요
# session_timeout_ms: 30000
# operation_timeout_ms: 10000
# Users 설정: https://clickhouse.com/docs/operations/configuration-files#user-settings
# 프로덕션 환경에서는 평문 대신 SHA-256 해시 비밀번호를 사용하세요:
# printf "your-password" | sha256sum
# 그런 다음 weave/password 대신 weave/password_sha256_hex: <hash>를 사용하세요
users:
weave/password: weave123 # 배포 전에 강력한 비밀번호로 교체하세요
weave/access_management: 1
weave/profile: default
weave/networks/ip:
- "0.0.0.0/0"
- "::"
# 서버 설정
settings:
disable_internal_dns_cache: 1
# 클러스터 설정
clusters:
- name: weavecluster # 클러스터 이름 - 사용자 지정 가능하지만 wandb-cr.yaml과 일치해야 합니다
layout:
shardsCount: 1
replicasCount: 3 # 복제본 수 - HA 요구 사항에 따라 조정하세요
templates:
podTemplate: clickhouse
dataVolumeClaimTemplate: data
# 설정 파일
files:
config.d/network_configuration.xml: |
<clickhouse>
<listen_host>0.0.0.0</listen_host>
<listen_host>::</listen_host>
</clickhouse>
config.d/logger.xml: |
<clickhouse>
<logger>
<level>information</level>
</logger>
</clickhouse>
config.d/storage_configuration.xml: |
<clickhouse>
<storage_configuration>
<disks>
<s3_disk>
<type>s3</type>
<!-- S3 버킷 엔드포인트와 리전으로 업데이트하세요 -->
<endpoint>https://YOUR-BUCKET-NAME.s3.YOUR-REGION.amazonaws.com/s3_disk/{replica}</endpoint>
<metadata_path>/var/lib/clickhouse/disks/s3_disk/</metadata_path>
<use_environment_credentials>true</use_environment_credentials>
<region>YOUR-REGION</region>
</s3_disk>
<s3_disk_cache>
<type>cache</type>
<disk>s3_disk</disk>
<path>/var/lib/clickhouse/s3_disk_cache/cache/</path>
<!-- 캐시 크기는 반드시 영구 볼륨보다 작아야 합니다 -->
<max_size>40Gi</max_size>
<cache_on_write_operations>true</cache_on_write_operations>
</s3_disk_cache>
</disks>
<policies>
<s3_main>
<volumes>
<main>
<disk>s3_disk_cache</disk>
</main>
</volumes>
</s3_main>
</policies>
</storage_configuration>
<merge_tree>
<storage_policy>s3_main</storage_policy>
</merge_tree>
</clickhouse>
- StorageClass:
storageClassName: gp3를 클러스터의 StorageClass에 맞게 업데이트하세요
- S3 Endpoint:
YOUR-BUCKET-NAME 및 YOUR-REGION을 실제 값으로 바꾸세요
- Cache Size:
<max_size>40Gi</max_size>는 영구 볼륨 크기(50Gi)보다 반드시 작아야 합니다
- 보안 컨텍스트:
runAsUser, fsGroup 및 기타 보안 설정을 조직 정책에 맞게 조정하세요
- Resource Allocation: CPU/메모리 값은 예시일 뿐이므로, 예상 트레이스 볼륨에 맞는 적절한 크기 산정을 위해 W&B Solutions Architect와 상의하세요
- Anti-Affinity Rules: 클러스터 토폴로지와 고가용성 요구 사항에 따라 사용자 지정하거나 제거하세요
- Keeper Hostnames: Keeper 노드 호스트명은 Step 3의 Keeper deployment 이름과 반드시 일치해야 합니다(아래의 “Keeper Naming 이해하기” 참조)
- Cluster Naming: 클러스터 이름
weavecluster는 변경할 수 있지만, Step 5의 WF_CLICKHOUSE_REPLICATED_CLUSTER 값과 일치해야 합니다
- 자격 증명:
- IRSA의 경우:
<use_environment_credentials>true</use_environment_credentials>를 유지하거나 환경 변수에 매핑된 시크릿 키를 사용하세요.
ch-server.yaml에서 storage_configuration.xml 섹션을 수정합니다:
AWS S3 예시:
<endpoint>https://my-wandb-clickhouse.s3.eu-central-1.amazonaws.com/s3_disk/{replica}</endpoint>
<region>eu-central-1</region>
<endpoint>https://minio.example.com:9000/my-bucket/s3_disk/{replica}</endpoint>
<region>us-east-1</region>
{replica}를 제거하지 마세요. 이렇게 해야 각 ClickHouse 복제본이 버킷의 자체 폴더에 기록합니다.
ch-server.yaml의 env 섹션이 시크릿을 참조하는지 확인하세요:
env:
- name: AWS_ACCESS_KEY_ID
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_access_key
- name: AWS_SECRET_ACCESS_KEY
valueFrom:
secretKeyRef:
name: aws-creds
key: aws_secret_key
env 섹션 전체를 제거하세요.
zookeeper.nodes 섹션의 Keeper 노드 호스트 이름은 Step 3에서 배포한 Keeper를 기준으로 특정 패턴을 따릅니다.
호스트 이름 패턴: chk-{installation-name}-{cluster-name}-{cluster-index}-{replica-index}.{namespace}.svc.cluster.local
각 항목의 의미는 다음과 같습니다:
chk = ClickHouseKeeperInstallation 접두사 (고정){installation-name} = ch-keeper.yaml의 metadata.name (예: wandb){cluster-name} = ch-keeper.yaml의 configuration.clusters[0].name (예: keeper){cluster-index} = 클러스터 인덱스, 단일 클러스터인 경우 일반적으로 0{replica-index} = 복제본 번호: 복제본이 3개이면 0, 1, 2{namespace} = Kubernetes 네임스페이스 (예: clickhouse)
기본 이름 예시:
chk-wandb-keeper-0-0.clickhouse.svc.cluster.local
chk-wandb-keeper-0-1.clickhouse.svc.cluster.local
chk-wandb-keeper-0-2.clickhouse.svc.cluster.local
metadata.name: myweave):
chk-myweave-keeper-0-0.clickhouse.svc.cluster.local
chk-myweave-keeper-0-1.clickhouse.svc.cluster.local
chk-myweave-keeper-0-2.clickhouse.svc.cluster.local
clusters[0].name: coordination):
chk-wandb-coordination-0-0.clickhouse.svc.cluster.local
chk-wandb-coordination-0-1.clickhouse.svc.cluster.local
chk-wandb-coordination-0-2.clickhouse.svc.cluster.local
# 실제 이름을 확인하기 위해 Keeper 서비스 목록 조회
kubectl get svc -n clickhouse | grep keeper
# 명명 패턴을 확인하기 위해 Keeper 파드 목록 조회
kubectl get pods -n clickhouse -l app=clickhouse-keeper
ch-server.yaml의 Keeper 호스트 이름은 Keeper 배포에서 실제로 생성된 서비스 이름과 정확히 일치해야 하며, 그렇지 않으면 ClickHouse 서버가 조정 서비스에 연결하지 못합니다.
kubectl apply -f ch-server.yaml
# ClickHouse 파드 확인
kubectl get pods -n clickhouse -l app=clickhouse-server
# 예상 출력:
# NAME READY STATUS RESTARTS AGE
# chi-wandb-weavecluster-0-0-0 1/1 Running 0 3m
# chi-wandb-weavecluster-0-1-0 1/1 Running 0 3m
# chi-wandb-weavecluster-0-2-0 1/1 Running 0 3m
# ClickHouse 연결 테스트
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query "SELECT version()"
# 클러스터 상태 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SELECT cluster, host_name, port FROM system.clusters WHERE cluster='weavecluster'"
- 호스트:
clickhouse-wandb.clickhouse.svc.cluster.local
- 포트:
8123
- 사용자:
weave (ch-server.yaml에 설정된 값)
- 비밀번호:
weave123 (ch-server.yaml에 설정된 값)
- 데이터베이스:
weave (자동으로 생성됨)
- 클러스터 이름:
weavecluster (ch-server.yaml에 설정된 값)
호스트 이름은 다음 패턴을 따릅니다: clickhouse-{installation-name}.{namespace}.svc.cluster.local
5.2 W&B Custom Resource 업데이트
apiVersion: apps.wandb.com/v1
kind: WeightsAndBiases
metadata:
name: wandb
namespace: wandb
spec:
values:
global:
# ... 기존 설정 ...
# ClickHouse 설정 추가
clickhouse:
install: false # 별도로 배포함
host: clickhouse-wandb.clickhouse.svc.cluster.local
port: 8123
user: weave
password: weave123
database: weave
replicated: true # 다중 복제본 설정 시 필수
# Weave Trace 활성화
weave-trace:
enabled: true
# Weave Trace 설정
weave-trace:
install: true
extraEnv:
WF_CLICKHOUSE_REPLICATED: "true"
WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster"
image:
repository: wandb/weave-trace
tag: 0.74.1
replicaCount: 1
size: "default"
sizing:
default:
autoscaling:
horizontal:
enabled: false
# 리소스 할당 예시 - 워크로드에 맞게 조정
resources:
limits:
cpu: 4
memory: "8Gi"
requests:
cpu: 1
memory: "4Gi"
# 파드 보안 컨텍스트 - 환경에 맞게 사용자 지정
podSecurityContext:
fsGroup: 10001 # 보안 요구 사항에 맞게 조정
fsGroupChangePolicy: Always
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # OpenShift의 경우 할당된 UID 범위 사용
seccompProfile:
type: RuntimeDefault
# 컨테이너 보안 컨텍스트
securityContext:
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
clickhouse.replicated: true - 레플리카 3개를 사용할 때 필수WF_CLICKHOUSE_REPLICATED: "true" - 복제 구성을 사용할 때 필수WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" - ch-server.yaml의 클러스터 이름과 반드시 일치해야 함
위에 표시된 보안 컨텍스트, 리소스 할당 및 기타 Kubernetes 관련 설정은 참고용 예시입니다. 조직의 요구 사항에 맞게 사용자 지정하고, 적절한 리소스 규모 산정을 위해 W&B Solutions Architect 팀과 상의하세요.
kubectl apply -f wandb-cr.yaml
# weave-trace 파드 상태 확인
kubectl get pods -n wandb | grep weave-trace
# 예상 출력:
# wandb-weave-trace-bc-xxxxx 1/1 Running 0 2m
# ClickHouse 연결 관련 weave-trace 로그 확인
kubectl logs -n wandb <weave-trace-pod-name> --tail=50
# ClickHouse 연결 성공 메시지 확인
# 시작 중 weave-trace 로그 확인
kubectl logs -n wandb <weave-trace-pod-name> -f
# 데이터베이스 초기화 성공을 나타내는 마이그레이션 메시지 확인
# ClickHouse에 연결하고 데이터베이스 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SHOW DATABASES"
# 'weave' 데이터베이스가 목록에 표시되어야 함
# weave 데이터베이스의 테이블 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SHOW TABLES FROM weave"
- Top Right Menu → Organization Dashboard로 이동합니다.
- Weave access가 활성화되었는지 확인합니다.
Weave가 제대로 작동하는지 확인하려면 단순한 Python 테스트를 만드세요:
import os
import weave
# Self-Managed W&B 인스턴스를 Weave에 연결합니다
os.environ["WANDB_BASE_URL"] = "https://your-wandb-host" # W&B URL로 변경하세요
weave.init('test-project')
# 간단한 트레이스 함수를 생성합니다
@weave.op()
def hello_weave(name: str) -> str:
return f"Hello, {name}!"
# 함수를 호출합니다
result = hello_weave("World")
print(result)
Pending 상태에서 멈춰 있음
해결 방법: 가능한 여러 원인을 확인하세요:
- PVC 및 StorageClass 문제:
kubectl get pvc -n clickhouse
kubectl describe pvc -n clickhouse
- 안티 어피니티 및 노드 가용성:
# anti-affinity 규칙이 스케줄링을 방해하는지 확인
kubectl describe pod -n clickhouse <pod-name> | grep -A 10 "Events:"
# 사용 가능한 노드와 리소스 확인
kubectl get nodes
kubectl describe nodes | grep -A 5 "Allocated resources"
- 안티 어피니티를 사용하려면 서로 다른 3개의 노드가 필요하지만, 클러스터의 노드 수가 그보다 적습니다
- 노드에 파드의 요청을 충족할 만큼 충분한 CPU/메모리가 없습니다
- 노드 테인트 때문에 파드 스케줄링이 되지 않습니다
해결 방법:
- 노드가 3개 미만이면 안티 어피니티 규칙을 제거하거나 조정합니다
- 안티 어피니티를 더 완화하려면
requiredDuringSchedulingIgnoredDuringExecution 대신 preferredDuringSchedulingIgnoredDuringExecution를 사용합니다
- 노드 리소스가 부족하면 리소스 요청을 줄입니다
- 클러스터에 노드를 더 추가합니다
문제: Keeper 파드가 CrashLoopBackOff 상태입니다
해결 방법: 로그를 확인하고 설정을 확인합니다:
kubectl logs -n clickhouse <keeper-pod-name>
- 잘못된 보안 컨텍스트(
runAsUser, fsGroup 확인)
- 볼륨 권한 문제
- 포트 충돌
ch-keeper.yaml의 설정 오류
문제: ClickHouse가 S3에 연결할 수 없습니다
해결 방법: S3 자격 증명과 권한을 확인하세요:
# 시크릿 존재 여부 확인 (액세스 키 사용 시)
kubectl get secret aws-creds -n clickhouse
# S3 오류 관련 ClickHouse 로그 확인
kubectl logs -n clickhouse <clickhouse-pod-name> | grep -i s3
# 저장소 설정에서 S3 엔드포인트 확인
kubectl get chi wandb -n clickhouse -o yaml | grep -A 10 storage_configuration
문제: ClickHouse가 Keeper에 연결할 수 없습니다
해결 방법: Keeper 엔드포인트와 이름 설정을 확인합니다:
# Keeper 서비스 및 실제 이름 확인
kubectl get svc -n clickhouse | grep keeper
# Keeper 파드에서 명명 패턴 확인
kubectl get pods -n clickhouse -l app=clickhouse-keeper
# ch-server.yaml의 zookeeper.nodes 설정과 비교
# 호스트명은 반드시 실제 서비스 이름과 일치해야 함
# 연결 오류에 대한 ClickHouse 로그 확인
kubectl logs -n clickhouse chi-wandb-weavecluster-0-0-0 | grep -i keeper
weave-trace 파드가 시작되지 않음
해결 방법: ClickHouse 연결 상태를 확인하세요:
# weave-trace 파드 이름 조회
kubectl get pods -n wandb | grep weave-trace
# weave-trace 로그 확인
kubectl logs -n wandb <weave-trace-pod-name>
# 일반적인 오류: "connection refused" 또는 "authentication failed"
# wandb-cr.yaml의 ClickHouse 자격 증명이 ch-server.yaml과 일치하는지 확인
문제: Console에서 Weave가 활성화된 것으로 표시되지 않음
해결 방법: 설정을 확인합니다.
-
라이선스에 Weave가 포함되어 있는지 확인합니다.
kubectl get secret license-key -n wandb -o jsonpath='{.data.value}' | base64 -d | jq
-
wandb-cr.yaml에서
weave-trace.enabled: true 및 clickhouse.replicated: true가 설정되어 있는지 확인합니다.
-
W&B Operator 로그를 확인합니다.
kubectl logs -n wandb deployment/wandb-controller-manager
문제: 데이터베이스 마이그레이션 실패
해결 방법: 클러스터 이름이 일치하는지 확인합니다.
WF_CLICKHOUSE_REPLICATED_CLUSTER 환경 변수는 ch-server.yaml의 클러스터 이름과 반드시 일치해야 합니다:
# ch-server.yaml에서:
clusters:
- name: weavecluster # <-- 이 이름
# wandb-cr.yaml에서 일치해야 함:
weave-trace:
extraEnv:
WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" # <-- 이 값
아래 리소스 할당은 예시용 시작점일 뿐입니다. 실제 요구 사항은 다음 요소에 따라 크게 달라집니다.
- 트레이스 수집량(초당 트레이스 수)
- 쿼리 패턴 및 동시성
- 데이터 보존 기간
- 동시 사용자 수
특정 사용 사례에 맞는 적절한 규모를 확인하려면 반드시 W&B Solutions Architect 팀과 상의하세요. 리소스를 부족하게 프로비저닝하면 성능 문제가 발생할 수 있고, 과도하게 프로비저닝하면 인프라 비용만 낭비됩니다. | 구성 요소 | 레플리카 수 | CPU 요청 / 제한 | 메모리 요청 / 제한 | 저장소 |
|---|
| ClickHouse Keeper | 3 | 0.5 / 1 | 256Mi / 2Gi | 각 10Gi |
| ClickHouse Server | 3 | 1 / 4 | 1Gi / 16Gi | 각 50Gi |
| Weave Trace | 1 | 1 / 4 | 4Gi / 8Gi | - |
| 총계 | 7 파드 | ~4.5 / 15 CPU | ~7.8Gi / 58Gi | 180Gi |
| Component | Replicas | CPU Request / Limit | Memory Request / Limit | Storage |
|---|
| ClickHouse Keeper | 3 | 1 / 2 | 1Gi / 4Gi | 각 20Gi |
| ClickHouse Server | 3 | 1 / 16 | 8Gi / 64Gi | 각 200Gi |
| Weave Trace | 2-3 | 1 / 4 | 4Gi / 8Gi | - |
| 합계 | 8-9 파드 | ~6-9 / 52-64 CPU | ~27-33Gi / 204-216Gi | 660Gi |
-
수직 스케일링: 파드당 리소스를 늘립니다(더 간단한 방법)
resources:
requests:
memory: 8Gi
cpu: 1
limits:
memory: 64Gi
cpu: 16
-
수평 스케일링: 레플리카를 추가합니다(신중한 계획이 필요함)
- 레플리카를 늘리려면 데이터를 재분산해야 합니다
- 샤드 관리에 대해서는 ClickHouse 문서를 참조하세요
- 프로덕션에서 수평 스케일링을 구현하기 전에 W&B Solutions Architect에 문의하세요
다른 ClickHouse 버전을 사용하려면 ch-keeper.yaml과 ch-server.yaml의 이미지 태그를 모두 업데이트하세요:
image: clickhouse/clickhouse-keeper:25.10 # Keeper 버전
image: clickhouse/clickhouse-server:25.10 # Server 버전
# 디스크 사용량 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SELECT name, path, formatReadableSize(free_space) as free, formatReadableSize(total_space) as total FROM system.disks"
# 복제 상태 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
clickhouse-client --user weave --password weave123 --query \
"SELECT database, table, is_leader, total_replicas, active_replicas FROM system.replicas WHERE database='weave'"
# ClickHouse 서버 상태 확인
kubectl get pods -n clickhouse -l app=clickhouse-server
- 자격 증명: ClickHouse 비밀번호는 일반 텍스트가 아닌 Kubernetes 시크릿에 저장하세요
- 네트워크 정책: ClickHouse에 대한 접근을 제한할 수 있도록 NetworkPolicies 구현을 고려하세요
- RBAC: 서비스 계정에는 필요한 최소 권한만 부여되었는지 확인하세요
- S3 버킷: 저장 데이터 암호화를 활성화하고 버킷 접근은 필요한 IAM 역할로만 제한하세요
- TLS (선택): 프로덕션 환경에서는 ClickHouse 클라이언트 연결에 TLS를 활성화하세요
ClickHouse Operator 업그레이드
helm upgrade ch-operator altinity/altinity-clickhouse-operator \
--namespace clickhouse \
-f ch-operator.yaml
ch-server.yaml에서 이미지 버전을 업데이트한 다음 적용하세요:
# ch-server.yaml 편집, 이미지 태그 변경
kubectl apply -f ch-server.yaml
# 파드 모니터링
kubectl get pods -n clickhouse
wandb-cr.yaml의 이미지 태그를 업데이트한 후 적용하세요:
kubectl apply -f wandb-cr.yaml
# weave-trace 파드 재시작 모니터링
kubectl get pods -n wandb | grep weave-trace
- W&B 지원팀:
support@wandb.com
- Solutions Architects: 초대규모 배포, 맞춤형 sizing, 배포 계획이 필요한 경우
- 지원 요청 시 포함할 내용:
- weave-trace, ClickHouse 파드, Operator의 로그
- W&B 버전, ClickHouse 버전, Kubernetes 버전
- 클러스터 정보 및 트레이스 볼륨
Q: ClickHouse 레플리카를 3개 대신 1개만 사용해도 되나요?
A: 예. 하지만 프로덕션 환경에는 권장되지 않습니다. ch-server.yaml에서 replicasCount: 1로 업데이트하고, wandb-cr.yaml에서 clickhouse.replicated: false로 설정하세요.
Q: ClickHouse 대신 다른 데이터베이스를 사용할 수 있나요?
A: 아니요. Weave Trace는 고성능 컬럼형 저장 기능을 위해 ClickHouse가 필요합니다.
Q: S3 저장소는 얼마나 필요하나요?
A: 필요한 S3 저장소 용량은 트레이스 볼륨, 보존 기간, 데이터 압축에 따라 달라집니다. deployment 후 실제 사용량을 모니터링하고 그에 맞게 조정하세요. ClickHouse의 컬럼형 포맷은 트레이스 데이터에 매우 뛰어난 압축 효율을 제공합니다.
Q: ClickHouse에서 database 이름을 설정해야 하나요?
A: 아니요. weave 데이터베이스는 초기 시작 시 weave-trace 서비스가 자동으로 생성합니다.
Q: 클러스터 이름이 weavecluster가 아니면 어떻게 하나요?
A: WF_CLICKHOUSE_REPLICATED_CLUSTER 환경 변수를 클러스터 이름과 일치하도록 설정해야 합니다. 그렇지 않으면 데이터베이스 마이그레이션이 실패합니다.
Q: 예시에 나온 보안 컨텍스트를 그대로 사용해야 하나요?
A: 아니요. 이 가이드에 나온 보안 컨텍스트(runAsUser, fsGroup 등)는 레퍼런스 예시입니다. 조직의 보안 정책을 준수하도록 반드시 조정해야 하며, 특히 OpenShift 클러스터는 특정 UID/GID 범위 requirements가 있으므로 주의해야 합니다.
Q: ClickHouse 클러스터 크기를 올바르게 산정했는지 어떻게 알 수 있나요?
A: 예상 트레이스 볼륨과 사용 패턴을 W&B Solutions Architect 팀에 문의하세요. 그러면 구체적인 사이징 권장 사항을 제공합니다. deployment의 리소스 사용량을 모니터링하고 필요에 따라 조정하세요.
Q: 예제에서 사용된 naming convention을 사용자 지정할 수 있나요?
A: 예. 하지만 모든 컴포넌트에서 일관성을 유지해야 합니다.
- ClickHouse Keeper 이름 → ch-server.yaml의
zookeeper.nodes section에 있는 Keeper 노드 호스트 이름과 일치해야 합니다.
- ClickHouse 클러스터 이름 (
weavecluster) → wandb-cr.yaml의 WF_CLICKHOUSE_REPLICATED_CLUSTER와 일치해야 합니다.
- ClickHouse 설치 이름 → weave-trace에서 사용하는 서비스 호스트 이름에 영향을 줍니다.
이름 지정 패턴과 실제 이름을 확인하는 방법에 대한 자세한 내용은 Step 4의 “Understanding Keeper Naming” section을 참조하세요.
Q: 클러스터에서 다른 안티 어피니티 requirements를 사용하는 경우에는 어떻게 하나요?
A: 여기에 나온 안티 어피니티 규칙은 고가용성을 위한 권장 사항입니다. 클러스터 크기, 토폴로지, 가용성 requirements에 따라 조정하거나 제거하세요. 작은 클러스터나 개발 환경에서는 안티 어피니티 규칙이 필요하지 않을 수 있습니다. 
