자체 관리형 W&B Weave 인스턴스 설정

자체 인프라에서 Weave 배포 및 관리

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 데이터 영속성을 위한 객체 저장소

자세한 레퍼런스 아키텍처는 W&B Self-Managed Reference Architecture를 참조하세요.

​

중요한 설정 참고 사항

이 가이드의 설정 예시는 레퍼런스용일 뿐입니다. 각 조직의 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을 통해 서로 통신할 수 있어야 합니다

​

자체 관리형 Weave 인스턴스 배포하기

​

Step 1: Altinity ClickHouse Operator 배포

Altinity ClickHouse Operator는 Kubernetes에서 ClickHouse 설치를 관리하는 역할을 합니다.

​

1.1 Altinity Helm 저장소 추가하기

helm repo add altinity https://helm.altinity.com
helm repo update

​

1.2 Operator 설정 생성

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을 조정해야 할 수 있습니다.

​

1.3 Operator 설치하기

helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  --create-namespace \
  -f ch-operator.yaml

​

1.4 Operator 설치 확인

# 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

​

Step 2: S3 저장소 준비

ClickHouse는 데이터를 영구 저장하려면 S3 또는 S3 호환 저장소가 필요합니다.

​

2.1 S3 버킷 생성

AWS 계정 또는 S3 호환 저장소 제공업체에 S3 버킷을 생성합니다:

# AWS 예시
aws s3 mb s3://my-wandb-clickhouse-bucket --region eu-central-1

​

2.2 S3 자격 증명 설정

S3 액세스 자격 증명을 제공하는 방법은 두 가지가 있습니다:

옵션 A: AWS IAM 역할 사용(IRSA - AWS 환경에서 권장)

Kubernetes 노드에 S3에 액세스할 수 있는 IAM 역할이 있으면 ClickHouse는 EC2 인스턴스 메타데이터를 사용할 수 있습니다:

# ch-server.yaml에서 설정:
<use_environment_credentials>true</use_environment_credentials>

필수 IAM 정책 (노드 IAM 역할에 연결):

{
  "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

그런 다음 ClickHouse에서 해당 시크릿을 사용하도록 설정합니다(아래의 ch-server.yaml 설정 참조).

​

Step 3: ClickHouse Keeper 배포

ClickHouse Keeper는 데이터 복제와 분산 DDL 쿼리 실행을 위한 코디네이션 시스템을 제공합니다.

​

3.1 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)을 반드시 업데이트해야 합니다

​

3.2 ClickHouse Keeper 배포

kubectl apply -f ch-keeper.yaml

​

3.3 Keeper 배포 확인

# 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 클러스터 배포

이제 Weave 트레이스 데이터를 저장할 ClickHouse 서버 클러스터를 배포하세요.

​

4.1 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>

필수 설정 업데이트:

1. StorageClass: storageClassName: gp3를 클러스터의 StorageClass에 맞게 업데이트하세요
2. S3 Endpoint: YOUR-BUCKET-NAME 및 YOUR-REGION을 실제 값으로 바꾸세요
3. Cache Size: <max_size>40Gi</max_size>는 영구 볼륨 크기(50Gi)보다 반드시 작아야 합니다
4. 보안 컨텍스트: runAsUser, fsGroup 및 기타 보안 설정을 조직 정책에 맞게 조정하세요
5. Resource Allocation: CPU/메모리 값은 예시일 뿐이므로, 예상 트레이스 볼륨에 맞는 적절한 크기 산정을 위해 W&B Solutions Architect와 상의하세요
6. Anti-Affinity Rules: 클러스터 토폴로지와 고가용성 요구 사항에 따라 사용자 지정하거나 제거하세요
7. Keeper Hostnames: Keeper 노드 호스트명은 Step 3의 Keeper deployment 이름과 반드시 일치해야 합니다(아래의 “Keeper Naming 이해하기” 참조)
8. Cluster Naming: 클러스터 이름 weavecluster는 변경할 수 있지만, Step 5의 WF_CLICKHOUSE_REPLICATED_CLUSTER 값과 일치해야 합니다
9. 자격 증명:
   • IRSA의 경우: <use_environment_credentials>true</use_environment_credentials>를 유지하거나 환경 변수에 매핑된 시크릿 키를 사용하세요.

​

4.2 S3 설정 업데이트

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>

MinIO 예시:

<endpoint>https://minio.example.com:9000/my-bucket/s3_disk/{replica}</endpoint>
<region>us-east-1</region>

{replica}를 제거하지 마세요. 이렇게 해야 각 ClickHouse 복제본이 버킷의 자체 폴더에 기록합니다.

​

4.3 자격 증명 구성(옵션 B만 해당)

step 2의 **옵션 B(Access Keys)**를 사용하는 경우, 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

**Option A (IRSA)**를 사용하는 경우 env 섹션 전체를 제거하세요.

​

4.4 Keeper 이름 규칙 이해하기

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

Keeper 설치 이름을 사용자 지정한 경우(예: 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

Keeper 클러스터 이름을 사용자 지정했다면(예: 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 호스트명을 확인하려면:

# 실제 이름을 확인하기 위해 Keeper 서비스 목록 조회
kubectl get svc -n clickhouse | grep keeper

# 명명 패턴을 확인하기 위해 Keeper 파드 목록 조회
kubectl get pods -n clickhouse -l app=clickhouse-keeper

ch-server.yaml의 Keeper 호스트 이름은 Keeper 배포에서 실제로 생성된 서비스 이름과 정확히 일치해야 하며, 그렇지 않으면 ClickHouse 서버가 조정 서비스에 연결하지 못합니다.

​

4.5 ClickHouse 클러스터 배포

kubectl apply -f ch-server.yaml

​

4.6 ClickHouse 배포 확인

# 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'"

​

Step 5: W&B Platform에서 Weave 활성화

이제 Weave 트레이스에 ClickHouse 클러스터를 사용하도록 W&B Platform을 설정합니다.

​

5.1 ClickHouse 연결 정보 확인

다음 정보가 필요합니다:

• 호스트: 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 업데이트

Weave 설정을 추가하려면 W&B Platform 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"
      # 파드 보안 컨텍스트 - 환경에 맞게 사용자 지정
      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 팀과 상의하세요.

​

5.3 업데이트된 설정 적용하기

kubectl apply -f wandb-cr.yaml

​

5.4 Weave Trace 배포 확인

# 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 연결 성공 메시지 확인

​

Step 6: Weave 데이터베이스 초기화

weave-trace 서비스는 처음 시작될 때 필요한 데이터베이스 스키마를 자동으로 생성합니다.

​

6.1 데이터베이스 마이그레이션 모니터링

# 시작 중 weave-trace 로그 확인
kubectl logs -n wandb <weave-trace-pod-name> -f

# 데이터베이스 초기화 성공을 나타내는 마이그레이션 메시지 확인

​

6.2 데이터베이스가 생성되었는지 확인

# 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"

​

Step 7: Weave 활성화 여부 확인

​

7.1 W&B Console에 접속

웹 브라우저에서 W&B 인스턴스 URL로 이동합니다.

​

7.2 Weave 라이선스 상태 확인

W&B Console에서 다음을 수행합니다:

1. Top Right Menu → Organization Dashboard로 이동합니다.
2. Weave access가 활성화되었는지 확인합니다.

​

7.3 Weave 기능 테스트

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)

이 작업을 실행한 후, 조직의 트레이스 페이지에서 W&B UI의 트레이스를 확인하세요.

​

문제 해결

​

ClickHouse Keeper 문제

문제: Keeper 파드가 Pending 상태에서 멈춰 있음

해결 방법: 가능한 여러 원인을 확인하세요:

1. PVC 및 StorageClass 문제:

kubectl get pvc -n clickhouse
kubectl describe pvc -n clickhouse

StorageClass가 올바르게 설정되어 있고 사용 가능한 용량이 충분한지 확인하세요.

2. 안티 어피니티 및 노드 가용성:

# 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 Server 문제

문제: 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

연결에 실패하면 ch-server.yaml의 Keeper 호스트명이 실제 Keeper 배포 환경과 일치하지 않을 가능성이 높습니다. 이름 지정 패턴은 Step 4의 “Keeper 이름 지정 이해하기”를 참조하세요.

​

Weave 트레이스 문제

문제: 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가 활성화된 것으로 표시되지 않음

해결 방법: 설정을 확인합니다.

1. 라이선스에 Weave가 포함되어 있는지 확인합니다.

   kubectl get secret license-key -n wandb -o jsonpath='{.data.value}' | base64 -d | jq
   

2. wandb-cr.yaml에서 weave-trace.enabled: true 및 clickhouse.replicated: true가 설정되어 있는지 확인합니다.

3. 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

적합한 환경: 대규모 프로덕션 환경

초대규모 배포의 경우, 특정 트레이스 양과 성능 요구 사항을 기반으로 한 맞춤형 크기 권장 사항을 받으려면 W&B Solutions Architect 팀에 문의하세요.

​

고급 설정

이 섹션에서는 Self-Managed Weave 배포를 위한 맞춤 설정 옵션을 다룹니다. 여기에는 수직 확장 또는 수평 확장을 통해 ClickHouse 용량을 확장하는 방법, keeper와 server 설정 모두에서 이미지 태그를 수정해 ClickHouse 버전을 업데이트하는 방법, 그리고 ClickHouse 상태를 모니터링하는 방법이 포함됩니다.

인스턴스에 고급 변경을 적용할 때는 성능 및 안정성 요구 사항에 맞도록 W&B Solutions Architect 팀과 상담할 것을 권장합니다.

​

ClickHouse 스케일링

ClickHouse 용량을 늘리려면 다음과 같은 방법을 사용할 수 있습니다.

1. 수직 스케일링: 파드당 리소스를 늘립니다(더 간단한 방법)

   resources:
     requests:
       memory: 8Gi
       cpu: 1
     limits:
       memory: 64Gi
       cpu: 16
   

   권장 사항: 실제 리소스 사용량을 모니터링하고 그에 맞춰 스케일링하세요. 매우 높은 볼륨의 배포에서는 W&B Solutions Architect 팀에 문의하세요.

2. 수평 스케일링: 레플리카를 추가합니다(신중한 계획이 필요함)

   • 레플리카를 늘리려면 데이터를 재분산해야 합니다
   • 샤드 관리에 대해서는 ClickHouse 문서를 참조하세요
   • 프로덕션에서 수평 스케일링을 구현하기 전에 W&B Solutions Architect에 문의하세요

​

다른 ClickHouse 버전 사용하기

다른 ClickHouse 버전을 사용하려면 ch-keeper.yaml과 ch-server.yaml의 이미지 태그를 모두 업데이트하세요:

image: clickhouse/clickhouse-keeper:25.10   # Keeper 버전
image: clickhouse/clickhouse-server:25.10   # Server 버전

호환성을 위해 Keeper와 서버 버전은 동일해야 하거나, Keeper 버전이 서버 버전보다 크거나 같아야 합니다.

​

ClickHouse 모니터링

모니터링을 위해 ClickHouse 시스템 테이블에 액세스하세요:

# 디스크 사용량 확인
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 데이터는 S3에 저장되며, S3 버전 관리와 버킷 복제 특성 덕분에 기본적인 백업 기능이 제공됩니다. 배포 환경에 맞는 백업 전략은 W&B Solutions Architect 팀에 문의하고 ClickHouse backup documentation을 참고하세요.

​

보안 고려사항

1. 자격 증명: ClickHouse 비밀번호는 일반 텍스트가 아닌 Kubernetes 시크릿에 저장하세요
2. 네트워크 정책: ClickHouse에 대한 접근을 제한할 수 있도록 NetworkPolicies 구현을 고려하세요
3. RBAC: 서비스 계정에는 필요한 최소 권한만 부여되었는지 확인하세요
4. S3 버킷: 저장 데이터 암호화를 활성화하고 버킷 접근은 필요한 IAM 역할로만 제한하세요
5. TLS (선택): 프로덕션 환경에서는 ClickHouse 클라이언트 연결에 TLS를 활성화하세요

​

업그레이드하기

​

ClickHouse Operator 업그레이드

helm upgrade ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  -f ch-operator.yaml

​

ClickHouse Server 업그레이드

ch-server.yaml에서 이미지 버전을 업데이트한 다음 적용하세요:

# ch-server.yaml 편집, 이미지 태그 변경
kubectl apply -f ch-server.yaml

# 파드 모니터링
kubectl get pods -n clickhouse

​

Weave Trace 업그레이드

wandb-cr.yaml의 이미지 태그를 업데이트한 후 적용하세요:

kubectl apply -f wandb-cr.yaml

# weave-trace 파드 재시작 모니터링
kubectl get pods -n wandb | grep weave-trace

​

추가 자료

• Altinity ClickHouse Operator 문서
• ClickHouse 문서
• W&B Weave 문서
• ClickHouse S3 저장소 설정

​

지원팀

프로덕션 배포 또는 문제 발생 시:

• W&B 지원팀: [e-mail]
• Solutions Architects: 초대규모 배포, 맞춤형 sizing, 배포 계획이 필요한 경우
• 지원 요청 시 포함할 내용:
  • weave-trace, ClickHouse 파드, Operator의 로그
  • W&B 버전, ClickHouse 버전, Kubernetes 버전
  • 클러스터 정보 및 트레이스 볼륨

​

FAQ

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: 예. 하지만 모든 컴포넌트에서 일관성을 유지해야 합니다.

1. ClickHouse Keeper 이름 → ch-server.yaml의 zookeeper.nodes section에 있는 Keeper 노드 호스트 이름과 일치해야 합니다.
2. ClickHouse 클러스터 이름 (weavecluster) → wandb-cr.yaml의 WF_CLICKHOUSE_REPLICATED_CLUSTER와 일치해야 합니다.
3. ClickHouse 설치 이름 → weave-trace에서 사용하는 서비스 호스트 이름에 영향을 줍니다.

이름 지정 패턴과 실제 이름을 확인하는 방법에 대한 자세한 내용은 Step 4의 “Understanding Keeper Naming” section을 참조하세요.

Q: 클러스터에서 다른 안티 어피니티 requirements를 사용하는 경우에는 어떻게 하나요?

A: 여기에 나온 안티 어피니티 규칙은 고가용성을 위한 권장 사항입니다. 클러스터 크기, 토폴로지, 가용성 requirements에 따라 조정하거나 제거하세요. 작은 클러스터나 개발 환경에서는 안티 어피니티 규칙이 필요하지 않을 수 있습니다.