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 요구 사항에 따라 security context,
runAsUser/fsGroup 값 및 기타 보안 설정을 조정하십시오.
- 리소스 사이징: 표시된 리소스 할당은 시작점일 뿐입니다. 예상 트레이스 볼륨과 성능 요구사항에 따른 적절한 사이징을 위해 W&B Solutions Architect 팀과 상의하십시오.
- 인프라 세부 사항: 환경에 맞도록 storage class, node selector 및 기타 인프라별 설정을 업데이트하십시오.
이 가이드의 설정은 처방적인 해법이 아니라 템플릿으로 간주해야 합니다.
Self-managed Weave 인스턴스에는 다음 리소스가 필요합니다:
- Kubernetes Cluster: 버전 1.29 이상
- Kubernetes Nodes: 다중 노드 클러스터(고가용성을 위해 최소 3개 노드 권장)
- Storage Class: 퍼시스턴트 볼륨용으로 정상 동작하는 StorageClass (예:
gp3, standard, nfs-csi)
- S3 Bucket: 적절한 액세스 권한이 사전에 설정된 S3 또는 S3 호환 버킷
- W&B Platform: 이미 설치되어 실행 중이어야 함 (참고: W&B Self-Managed Deployment Guide)
- W&B License: W&B Support에서 발급한 Weave 활성화 라이선스
이 사전 준비 사항 목록만을 근거로 리소스 규모를 결정하지 마세요. 필요한 리소스는 트레이스 볼륨과 사용 패턴에 따라 크게 달라질 수 있습니다. 클러스터 규모 산정을 위한 구체적인 지침은 Resource Requirements 섹션을 참조하세요.
- 클러스터에 대한 액세스가 설정된
kubectl
helm v3.0+- AWS 자격 증명(S3 사용 시) 또는 S3 호환 스토리지에 대한 액세스
Kubernetes 클러스터에는 다음과 같은 네트워크 구성이 필요합니다:
clickhouse 네임스페이스의 Pod는 wandb 네임스페이스의 Pod와 통신할 수 있어야 합니다.- ClickHouse 노드는 포트 8123, 9000, 9009, 2181에서 서로 통신할 수 있어야 합니다.
1단계: Altinity ClickHouse Operator 배포
helm repo add altinity https://helm.altinity.com
helm repo update
ch-operator.yaml라는 이름의 파일을 만듭니다:
operator:
image:
repository: altinity/clickhouse-operator
tag: "0.25.4"
# 보안 컨텍스트 - 클러스터 요구 사항에 맞게 조정하세요
containerSecurityContext:
runAsGroup: 0
runAsNonRoot: true
runAsUser: 10001 # OpenShift/Kubernetes 보안 정책에 따라 업데이트하세요
allowPrivilegeEscalation: false
capabilities:
drop:
- ALL
privileged: false
readOnlyRootFilesystem: false
metrics:
enabled: false
# 이름 재정의 - 필요한 경우 사용자 지정하세요
nameOverride: "wandb"
containerSecurityContext 값은 대부분의 Kubernetes 배포판에서 작동합니다. OpenShift의 경우, 프로젝트에 할당된 UID 범위에 맞도록 runAsUser 및 fsGroup 값을 조정해야 할 수 있습니다.
helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
--version 0.25.4 \
--namespace clickhouse \
--create-namespace \
-f ch-operator.yaml
# operator pod가 실행 중인지 확인
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
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:
# Pod 보안 컨텍스트 - 환경에 맞게 조정하세요
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.3.5.42"
# 리소스 요청 - 예시 값이며, 워크로드에 따라 조정하세요
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:
storageClassName: gp3를 클러스터에서 사용 가능한 StorageClass와 일치하도록 수정하십시오.
- Security Context: 조직의 보안 정책을 준수하도록
runAsUser, fsGroup 값을 조정하십시오.
- Anti-Affinity: 클러스터 토폴로지와 HA 요구 사항에 따라
affinity 섹션을 수정하거나 제거하십시오.
- Resources: CPU/메모리 값은 예시 값이므로, 적절한 사이징을 위해 W&B Solutions Architects와 상의하십시오.
- Naming:
metadata.name 또는 configuration.clusters[0].name을 변경하는 경우, Step 4의 ch-server.yaml에서 Keeper 호스트 이름을 이에 맞게 반드시 업데이트해야 합니다.
3.2 ClickHouse Keeper 배포하기
kubectl apply -f ch-keeper.yaml
### Step 2: Configure S3 Storage
#### 3.3 Verify Keeper deployment
```bash
# 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 서비스가 표시되어야 함
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:
# Pod 보안 컨텍스트 - 환경에 맞게 커스터마이즈하세요
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.3.5.42
# 리소스 할당 예시 - 워크로드에 따라 조정하세요
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) 설정
# 중요: 이 호스트명은 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
# 비밀번호 팁:
# sha256sum <<< weave123 OR echo -n weave123 | sha256sum OR printf "weave123" | sha256sum
# 사용자 설정에서 <password_sha256_hex>...</password_sha256_hex> 형태로 반환됩니다
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)보다 작아야 합니다.
- Security Context:
runAsUser, fsGroup 및 기타 보안 설정을 조직의 정책에 맞게 조정하세요.
- Resource Allocation: CPU/메모리 값은 예시일 뿐이므로, 예상 트레이스 양에 따른 적절한 사이징을 위해 W&B Solutions Architect와 상의하세요.
- Anti-Affinity Rules: 클러스터 토폴로지와 고가용성 요구 사항에 따라 수정하거나 제거하세요.
- Keeper Hostnames: Keeper 노드 호스트 이름은 반드시 3단계에서 사용한 Keeper 배포 네이밍과 일치해야 합니다(아래의 “Keeper 네이밍 이해하기” 참조).
- Cluster Naming: 클러스터 이름
weavecluster는 변경할 수 있지만, 5단계의 WF_CLICKHOUSE_REPLICATED_CLUSTER 값과 일치해야 합니다.
- Credentials:
- 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 노드 호스트 이름은 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'"
- Host:
clickhouse-wandb.clickhouse.svc.cluster.local
- Port:
8123
- User:
weave (ch-server.yaml에서 설정한 값)
- Password:
weave123 (ch-server.yaml에서 설정한 값)
- Database:
weave (자동으로 생성됨)
- Cluster Name:
weavecluster (ch-server.yaml에서 설정한 값)
호스트 이름은 다음 패턴을 따릅니다: clickhouse-{installation-name}.{namespace}.svc.cluster.local
Weave 설정을 추가하도록 W&B Platform 커스텀 리소스(CR)를 편집합니다:
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"
# Pod 보안 컨텍스트 - 환경에 맞게 커스터마이즈
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 - replica 3개를 사용할 때 필수WF_CLICKHOUSE_REPLICATED: "true" - 복제 구성을 위해 필수WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" - ch-server.yaml의 클러스터 이름과 일치해야 함
위에 표시된 security context, 리소스 할당 및 기타 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 서비스는 처음 시작될 때 필요한 데이터베이스 스키마를 자동으로 생성합니다.
# 시작 중 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"
- 오른쪽 상단 메뉴 → Organization Dashboard로 이동합니다.
- Weave access가 활성화되어 있는지 확인합니다.
Weave가 정상적으로 작동하는지 확인하기 위해 간단한 Python 테스트 코드를 작성합니다:
import weave
# Weave 초기화 (실제 W&B 호스트로 교체하세요)
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"
- 안티 어피니티(anti-affinity)에는 서로 다른 노드 3개가 필요하지만, 클러스터에 노드가 3개 미만임
- 노드의 CPU/메모리가 부족하여 파드 요청을 충족하지 못함
- 노드 테인트(node taint)로 인해 파드 스케줄링이 되지 않음
해결 방법:
- 노드가 3개 미만인 경우 안티 어피니티 규칙을 제거하거나 조정
- 더 유연한 안티 어피니티를 위해
requiredDuringSchedulingIgnoredDuringExecution 대신 preferredDuringSchedulingIgnoredDuringExecution 사용
- 노드 리소스가 제한적인 경우 리소스 요청 값(resource requests)을 줄임
- 클러스터에 노드를 추가
문제: CrashLoopBackOff 상태의 Keeper 파드
해결 방법: 로그를 확인하고 설정을 검증하세요:
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 팀과 상의하여 특정 사용 사례에 맞는 적절한 규모를 결정하십시오. 리소스를 과소 할당하면 성능 문제가 발생할 수 있고, 과도하게 할당하면 인프라 비용이 낭비됩니다. | Component | Replicas | CPU 요청 / 한도 | 메모리 요청 / 한도 | Storage |
|---|
| ClickHouse Keeper | 3 | 0.5 / 1 | 256Mi / 2Gi | 10Gi each |
| ClickHouse Server | 3 | 1 / 4 | 1Gi / 16Gi | 50Gi each |
| Weave Trace | 1 | 1 / 4 | 4Gi / 8Gi | - |
| Total | 7 pods | ~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 each |
| ClickHouse Server | 3 | 1 / 16 | 8Gi / 64Gi | 200Gi each |
| Weave Trace | 2-3 | 1 / 4 | 4Gi / 8Gi | - |
| Total | 8-9 pods | ~6-9 / 52-64 CPU | ~27-33Gi / 204-216Gi | 660Gi |
-
수직 스케일링(Vertical Scaling): 파드당 리소스를 늘리는 방식입니다 (더 간단한 접근 방식)
resources:
requests:
memory: 8Gi
cpu: 1
limits:
memory: 64Gi
cpu: 16
-
수평 스케일링(Horizontal Scaling): 더 많은 레플리카를 추가하는 방식입니다 (신중한 계획이 필요함)
- 레플리카를 늘리면 데이터를 리밸런싱해야 합니다
- 샤드 관리를 위해 ClickHouse 문서를 참고하십시오
- 프로덕션 환경에서 수평 스케일링을 구현하기 전에 W&B Solutions Architect에게 문의하십시오
다른 ClickHouse 버전을 사용하려면 ch-keeper.yaml과 ch-server.yaml 두 파일 모두에서 이미지 태그를 업데이트하세요:
image: clickhouse/clickhouse-keeper:25.3.5.42 # Keeper 버전
image: clickhouse/clickhouse-server:25.3.5.42 # 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 \
--version 0.25.4 \
--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:
support@wandb.com
- Solutions Architects: 초대규모 배포, 맞춤 용량 산정, 배포 계획 수립 관련 문의
- 지원 요청 시 포함할 정보:
- weave-trace, ClickHouse 파드, operator 로그
- W&B 버전, ClickHouse 버전, Kubernetes 버전
- 클러스터 정보 및 트레이스 볼륨
Q: 3개 대신 ClickHouse replica를 1개만 사용할 수 있나요?
A: 사용할 수는 있지만, 프로덕션 환경에서는 권장하지 않습니다. ch-server.yaml에서 replicasCount: 1로 수정하고, wandb-cr.yaml에서 clickhouse.replicated: false로 설정하세요.
Q: ClickHouse 대신 다른 데이터베이스를 사용할 수 있나요?
A: 불가능합니다. Weave Trace는 고성능 컬럼 지향 스토리지 기능 때문에 ClickHouse를 필요로 합니다.
Q: S3 스토리지는 얼마나 필요하나요?
A: S3 스토리지 요구량은 trace 볼륨, 보존 기간, 데이터 압축 여부에 따라 달라집니다. 배포 후 실제 사용량을 모니터링하고 그에 맞게 조정하세요. ClickHouse의 컬럼 형식은 trace 데이터에 대해 매우 우수한 압축률을 제공합니다.
Q: ClickHouse에서 database 이름을 별도로 설정해야 하나요?
A: 아닙니다. weave 데이터베이스는 초기 시작 시 weave-trace 서비스에 의해 자동으로 생성됩니다.
Q: 제 클러스터 이름이 weavecluster가 아니면 어떻게 하나요?
A: 클러스터 이름과 일치하도록 WF_CLICKHOUSE_REPLICATED_CLUSTER 환경 변수를 설정해야 합니다. 그렇지 않으면 데이터베이스 마이그레이션이 실패합니다.
Q: 예시에서 보여준 security context를 그대로 사용해야 하나요?
A: 아닙니다. 이 가이드에 제공된 security context(runAsUser, fsGroup 등)는 참고용 예시입니다. 특히 특정 UID/GID 범위 요구사항이 있는 OpenShift 클러스터의 경우, 조직의 보안 정책을 준수하도록 반드시 조정해야 합니다.
Q: ClickHouse 클러스터 사이징이 적절한지 어떻게 알 수 있나요?
A: 예상 trace 볼륨과 사용 패턴을 포함해 W&B Solutions Architect 팀에 문의하세요. 팀에서 구체적인 사이징 권장 사항을 제공합니다. 배포의 리소스 사용량을 모니터링하고 필요에 따라 조정하세요.
Q: 예시에서 사용된 네이밍 규칙을 커스터마이즈할 수 있나요?
A: 가능합니다. 하지만 모든 컴포넌트에서 일관성을 유지해야 합니다:
- ClickHouse Keeper 이름 → ch-server.yaml의
zookeeper.nodes 섹션에 있는 Keeper 노드 호스트 이름과 일치해야 합니다.
- ClickHouse 클러스터 이름(
weavecluster) → wandb-cr.yaml의 WF_CLICKHOUSE_REPLICATED_CLUSTER와 일치해야 합니다.
- ClickHouse 설치 이름 → weave-trace가 사용하는 서비스 호스트 이름에 영향을 줍니다.
네이밍 패턴과 실제 이름을 확인하는 방법에 대한 자세한 내용은 Step 4의 “Understanding Keeper Naming” 섹션을 참조하세요.
Q: 제 클러스터에서 다른 anti-affinity 요구사항을 사용하는 경우는 어떻게 하나요?
A: 제시된 anti-affinity 규칙은 고가용성을 위한 권장 설정입니다. 클러스터 크기, 토폴로지, 가용성 요구사항에 따라 조정하거나 제거해도 됩니다. 소규모 클러스터나 개발 환경에서는 anti-affinity 규칙이 필요하지 않을 수 있습니다. 
플랫폼
W&B Models
W&B Weave
W&B Inference
W&B 트레이닝
릴리스 노트