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 환경은 서로 다르기 때문에, 자체 호스팅 인스턴스를 구성할 때 다음 항목들을 조정해야 할 가능성이 큽니다:
- 보안 및 컴플라이언스: 조직의 보안 정책과 Kubernetes/OpenShift 요구사항에 맞게 security context,
runAsUser/fsGroup 값, 기타 보안 설정을 조정하십시오.
- 리소스 사이징: 제시된 리소스 할당은 시작점에 불과합니다. 예상 트레이스 양과 성능 요구사항에 맞는 적절한 사이징을 위해 W&B Solutions Architect 팀과 상의하십시오.
- 인프라 세부사항: 사용 중인 환경에 맞추어 storage class, node selector 및 기타 인프라 특화 설정을 업데이트하십시오.
이 가이드의 설정들은 정답 또는 규범적인 해법이 아닌 템플릿으로 간주해야 합니다.
자가 관리형 Weave 인스턴스를 위해서는 다음 리소스가 필요합니다:
- Kubernetes 클러스터: 버전 1.29 이상
- Kubernetes 노드: 멀티 노드 클러스터 (고가용성을 위해 최소 3개 노드 권장)
- Storage Class: 영구 볼륨용으로 정상 동작하는 StorageClass (예:
gp3, standard, nfs-csi)
- S3 버킷: 적절한 액세스 권한이 설정된, 사전에 구성된 S3 또는 S3 호환 버킷
- W&B 플랫폼: 이미 설치되어 실행 중이어야 함 (W&B Self-Managed Deployment Guide 참조)
- W&B 라이선스: 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"
# 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 \
--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: 클러스터에서 사용 가능한 StorageClass에 맞도록
storageClassName: gp3 값을 업데이트하십시오.
- Security Context: 조직의 보안 정책을 준수하도록
runAsUser, fsGroup 값을 조정하십시오.
- Anti-Affinity: 클러스터 토폴로지와 고가용성(HA) 요구 사항에 따라
affinity 섹션을 수정하거나 제거하십시오.
- Resources: CPU/메모리 값은 예시입니다. 적절한 사이징을 위해 W&B 솔루션 아키텍트와 상의하십시오.
- Naming:
metadata.name 또는 configuration.clusters[0].name을 변경하는 경우, ch-server.yaml(4단계)에서 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
# 사용자 구성: 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 솔루션 아키텍트와 상의하십시오.
- 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 replica가 버킷 내 자신의 폴더에 기록하도록 보장할 수 있습니다.
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 플랫폼 Custom Resource(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" - replicated 구성을 위해 필수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 로그 확인
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가 활성화되어 있는지 확인합니다.
간단한 Python 테스트를 만들어 Weave가 제대로 동작하는지 확인하세요:
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
StorageClass가 올바르게 구성되어 있고 충분한 사용 가능 용량이 있는지 확인하세요.
- 안티-어피니티 및 노드 가용성:
# 안티-어피니티 규칙으로 인해 스케줄링이 차단되는지 확인
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 pod가 시작되지 않음
해결 방법: 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 솔루션 아키텍트 팀과 상의하여 귀하의 구체적인 사용 사례에 맞는 적절한 규모를 결정하십시오. 리소스를 과소 할당하면 성능 문제가 발생할 수 있고, 과대 할당하면 인프라 비용이 낭비됩니다. | 구성 요소 | 레플리카 수 | 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 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 Secret에 저장하세요
- 네트워크 정책: ClickHouse 액세스를 제한하기 위해 Kubernetes NetworkPolicy 리소스 적용을 고려하세요
- RBAC: ServiceAccount에 최소 필요 권한만 부여했는지 확인하세요
- 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: ClickHouse 레플리카를 3개 대신 1개만 사용할 수 있나요?
A: 예, 가능하지만 프로덕션 환경에서는 권장하지 않습니다. ch-server.yaml에서 replicasCount: 1로 수정하고 wandb-cr.yaml에서 clickhouse.replicated: false로 설정하세요.
Q: ClickHouse 대신 다른 데이터베이스를 사용할 수 있나요?
A: 아니요, Weave Trace는 고성능 열 지향(columnar) 스토리지가 필요하므로 ClickHouse를 반드시 사용해야 합니다.
Q: S3 스토리지는 얼마나 필요하나요?
A: S3 스토리지 요구량은 트레이스 볼륨, 보존 기간, 데이터 압축 정도에 따라 달라집니다. 배포 후 실제 사용량을 모니터링하고 그에 맞게 조정하세요. ClickHouse의 열 지향 포맷은 트레이스 데이터에 대해 매우 뛰어난 압축 효율을 제공합니다.
Q: ClickHouse에서 database 이름을 별도로 설정해야 하나요?
A: 아닙니다. 초기 시작 시 weave-trace 서비스가 weave 데이터베이스를 자동으로 생성합니다.
Q: 제 클러스터 이름이 weavecluster가 아니라면 어떻게 하나요?
A: WF_CLICKHOUSE_REPLICATED_CLUSTER 환경 변수를 실제 클러스터 이름과 동일하게 설정해야 합니다. 그렇지 않으면 데이터베이스 마이그레이션이 실패합니다.
Q: 예시에서 보여주는 security context를 그대로 사용해야 하나요?
A: 아닙니다. 이 가이드에 제공된 security context(runAsUser, fsGroup 등)는 참고용 예시입니다. 특히 UID/GID 범위 요구 사항이 있는 OpenShift 클러스터에서는 조직의 보안 정책을 준수하도록 반드시 값을 조정해야 합니다.
Q: 제 ClickHouse 클러스터 사이징이 적절한지 어떻게 알 수 있나요?
A: 예상 트레이스 볼륨과 사용 패턴을 포함해 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 교육
릴리스 노트