> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Managed W&B Weave 인스턴스 설정

> 자체 인프라에 Weave를 배포하고 관리합니다

W\&B Weave를 자체 호스팅하면 환경과 설정을 더 세밀하게 제어할 수 있습니다. 또한 더 격리된 환경을 구성하고 추가적인 보안 규정 준수 요건을 충족하는 데 도움이 됩니다.

이 문서에서는 Altinity ClickHouse Operator를 사용하여 [W\&B Self-Managed](/ko/products/wandb/platform/hosting/hosting-options/self-managed) 배포에서 W\&B Weave를 실행하는 데 필요한 컴포넌트를 배포하는 방법을 안내합니다. 이 가이드를 완료하면 복제된 ClickHouse 데이터베이스와 S3 호환 오브젝트 저장소를 기반으로 자체 Kubernetes 클러스터에서 실행되는 프로덕션급 Weave 인스턴스를 구축할 수 있습니다. 이 가이드는 조직에서 W\&B를 배포하고 운영하는 Kubernetes 관리자와 플랫폼 엔지니어를 대상으로 합니다.

Self-Managed Weave 배포는 백엔드 관리에 [ClickHouseDB](https://clickhouse.com/)를 사용합니다. 이 배포는 다음으로 구성됩니다.

* **Altinity ClickHouse Operator**: Kubernetes용 엔터프라이즈급 ClickHouse 관리 도구입니다.
* **ClickHouse Keeper**: ZooKeeper를 대체하는 분산 코디네이션 서비스입니다.
* **ClickHouse 클러스터**: 트레이스를 저장하는 고가용성 데이터베이스 클러스터입니다.
* **S3 호환 저장소**: ClickHouse 데이터를 영구 저장하는 오브젝트 저장소입니다.

<Tip>
  자세한 레퍼런스 아키텍처는 [W\&B Self-Managed 레퍼런스 아키텍처](/ko/products/wandb/platform/hosting/self-managed/ref-arch#models-and-weave)를 참조하세요.
</Tip>

<h2 id="important-setup-notes">
  중요 설정 참고 사항
</h2>

이 가이드의 설정 예시는 참고용입니다. 조직마다 Kubernetes 환경이 다르므로 자체 호스팅 인스턴스에서는 다음 항목을 조정해야 할 가능성이 높습니다.

* **보안 및 규정 준수**: 조직의 보안 정책과 Kubernetes 또는 OpenShift 요구 사항에 따라 보안 컨텍스트, `runAsUser` 또는 `fsGroup` 값, 기타 보안 설정을 조정하세요.
* **리소스 사이징**: 여기에 제시된 리소스 할당은 출발점일 뿐입니다. 예상 트레이스 볼륨과 성능 요구 사항에 맞는 적절한 사이징은 W\&B Solutions Architect 팀과 상의하세요.
* **인프라별 세부 사항**: 스토리지 클래스, 노드 셀렉터 등 인프라별 설정을 사용 중인 환경에 맞게 업데이트하세요.

이 설정은 그대로 따라야 하는 정답이 아니라 템플릿으로 활용하세요.

<h2 id="architecture">
  아키텍처
</h2>

다음 다이어그램은 Self-Managed Weave 배포에서 W\&B Platform, ClickHouse 클러스터, ClickHouse Keeper 코디네이션 서비스, S3 저장소가 서로 어떻게 연계되어 구성되는지 보여줍니다.

```mermaid theme={"system"}
graph TD
    A["W&B Platform (wandb)<br/>weave-trace · app/API · console/parquet"] --> B["ClickHouse 클러스터"]
    B --> C["ch-server-0"]
    B --> D["ch-server-1"]
    B --> E["ch-server-2"]
    C --> F["ClickHouse Keeper 클러스터<br/>keeper-0 <br/>keeper-1 <br/>keeper-2"]
    D --> F
    E --> F
    C --> G["S3 저장소<br/>(AWS/MinIO)"]
    D --> G
    E --> G
```

<h2 id="prerequisites">
  사전 요구 사항
</h2>

시작하기 전에 환경이 다음 요구 사항을 충족하는지 확인하세요. Self-Managed Weave 인스턴스에는 다음 리소스가 필요합니다.

* **Kubernetes 클러스터**: 버전 1.29 이상.
* **Kubernetes 노드**: 다중 노드 클러스터(고가용성을 위해 최소 3개 노드 권장).
* **스토리지 클래스**: 영구 볼륨에 사용할 수 있는 정상 작동하는 StorageClass(예: `gp3`, `standard`, `nfs-csi`).
* **S3 버킷**: 적절한 액세스 권한이 미리 설정된 S3 또는 S3 호환 버킷.
* **W\&B Platform**: 이미 설치되어 실행 중이어야 합니다. [W\&B Self-Managed 배포 가이드](/ko/products/wandb/platform/hosting/hosting-options/self-managed)를 참조하세요.
* **W\&B 라이선스**: W\&B 지원팀에서 발급받은 Weave 활성화 라이선스.

<Warning>
  이 사전 요구 사항 목록만 보고 사이징을 결정하지 마세요. 필요한 리소스는 트레이스 볼륨과 사용 패턴에 따라 달라집니다. 자세한 내용은 [리소스 요구 사항](#resource-requirements)을 참조하세요.
</Warning>

<h3 id="required-tools">
  필수 도구
</h3>

인스턴스를 설정하려면 다음 도구가 필요합니다.

* 클러스터 액세스 권한이 설정된 `kubectl`
* `helm` 버전 3.0 이상
* AWS 자격 증명(S3를 사용하는 경우) 또는 S3 호환 저장소에 대한 액세스 권한

<h3 id="network-requirements">
  네트워크 요구 사항
</h3>

Kubernetes 클러스터에는 다음과 같은 네트워크 설정이 필요합니다.

* `clickhouse` namespace의 파드가 `wandb` namespace의 파드와 통신할 수 있어야 합니다.
* ClickHouse 노드 간에 `8123`, `9000`, `9009`, `2181` 포트로 통신할 수 있어야 합니다.

<h2 id="deploy-your-self-managed-weave-instance">
  Self-Managed Weave 인스턴스 배포하기
</h2>

다음 단계에서는 오퍼레이터 배포, 저장소 준비, ClickHouse Keeper 및 ClickHouse 클러스터 배포, W\&B Platform에서의 Weave 활성화 과정을 차례로 안내합니다. 각 단계는 이전 단계에서 생성한 리소스를 바탕으로 진행되므로 반드시 순서대로 완료하세요.

<h3 id="deploy-the-altinity-clickhouse-operator">
  Altinity ClickHouse 오퍼레이터 배포하기
</h3>

Altinity ClickHouse 오퍼레이터는 Kubernetes에서 ClickHouse 설치를 관리합니다. 오퍼레이터를 먼저 설치해 두면 이후 단계에서 ClickHouse Keeper와 ClickHouse 클러스터 리소스를 선언할 수 있으며, 선언된 리소스는 오퍼레이터가 알아서 조정(reconcile)합니다.

<h4 id="add-the-altinity-helm-repository">
  Altinity Helm 저장소 추가
</h4>

```bash theme={"system"}
helm repo add altinity https://helm.altinity.com
helm repo update
```

<h4 id="create-the-operator-configuration">
  오퍼레이터 설정 생성
</h4>

`ch-operator.yaml` 파일을 생성하세요. 이 파일은 오퍼레이터 배포에 필요한 보안 컨텍스트와 메타데이터를 정의합니다.

```yaml theme={"system"}
operator:
  image:
    repository: altinity/clickhouse-operator

  # 보안 컨텍스트 - 클러스터 요구 사항에 맞게 조정하세요
  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`을 조정해야 할 수 있습니다.

<h4 id="install-the-operator">
  오퍼레이터 설치
</h4>

```bash theme={"system"}
helm upgrade --install ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  --create-namespace \
  -f ch-operator.yaml
```

<h4 id="verify-the-operator-installation">
  오퍼레이터 설치 확인
</h4>

```bash theme={"system"}
# 오퍼레이터 파드가 실행 중인지 확인
kubectl get pods -n clickhouse

# 예상 출력:
# NAME                                 READY   STATUS    RESTARTS   AGE
# ch-operator-wandb-xxxxx              1/1     Running   0          30s

# 오퍼레이터 이미지 버전 확인
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
```

오퍼레이터가 실행 중이면 이제 ClickHouse 클러스터에 필요한 영구 저장소와 코디네이션 서비스를 프로비저닝할 수 있습니다.

<h3 id="prepare-s3-storage">
  S3 저장소 준비
</h3>

ClickHouse에서 데이터를 영구 저장하려면 S3 또는 S3 호환 저장소가 필요합니다. 이 단계에서는 버킷을 생성하고 ClickHouse가 버킷에 인증하는 방식을 설정합니다.

<h4 id="create-an-s3-bucket">
  S3 버킷 생성
</h4>

AWS 계정 또는 S3 호환 저장소 공급자에서 S3 버킷을 생성하세요. `[BUCKET-NAME]`은 버킷 이름으로, `[REGION]`은 AWS 리전으로 바꾸세요.

```bash theme={"system"}
# AWS 예시
aws s3 mb s3://[BUCKET-NAME] --region [REGION]
```

<h4 id="configure-s3-credentials">
  S3 자격 증명 설정
</h4>

ClickHouse가 버킷에서 데이터를 읽고 쓰려면 자격 증명이 필요합니다. S3 액세스 자격 증명을 제공하는 방법은 두 가지가 있습니다. AWS에서는 클러스터에 장기 시크릿을 저장할 필요가 없는 옵션 A(IRSA)를 사용할 것을 W\&B는 권장합니다.

<h5 id="option-a-use-aws-iam-roles-irsa-recommended-for-aws">
  옵션 A: AWS IAM 역할 사용(IRSA, AWS 환경에 권장)
</h5>

Kubernetes 노드에 S3 액세스 권한이 있는 IAM 역할이 부여되어 있다면 ClickHouse에서 EC2 인스턴스 메타데이터를 사용할 수 있습니다.

```yaml theme={"system"}
# ch-server.yaml에서 다음과 같이 설정하세요.
<use_environment_credentials>true</use_environment_credentials>
```

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

```json theme={"system"}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::[BUCKET-NAME]",
        "arn:aws:s3:::[BUCKET-NAME]/*"
      ]
    }
  ]
}
```

<h5 id="option-b-use-access-keys">
  옵션 B: 액세스 키 사용
</h5>

정적 자격 증명을 사용하려면 Kubernetes 시크릿을 생성하세요.

`[ACCESS-KEY]`는 AWS 액세스 키로, `[SECRET-KEY]`는 AWS 시크릿 키로 바꾸세요.

```bash theme={"system"}
kubectl create secret generic aws-creds \
  --namespace clickhouse \
  --from-literal aws_access_key=[ACCESS-KEY] \
  --from-literal aws_secret_key=[SECRET-KEY]
```

그런 다음 이 시크릿을 사용하도록 ClickHouse를 설정하세요(4단계의 ch-server.yaml 설정 참조).

<h3 id="deploy-clickhouse-keeper">
  ClickHouse Keeper 배포
</h3>

[ClickHouse Keeper](https://clickhouse.com/docs/guides/sre/keeper/clickhouse-keeper)는 데이터 복제와 분산 DDL 쿼리 실행에 필요한 코디네이션 시스템을 제공합니다. 4단계에서 배포하는 ClickHouse 서버는 시작할 때 Keeper에 연결하므로, ClickHouse 클러스터보다 Keeper를 먼저 배포해야 합니다.

<h4 id="create-the-keeper-configuration">
  Keeper 설정 생성
</h4>

`ch-keeper.yaml` 파일을 생성하세요. 이 매니페스트는 레플리카 3개로 구성된 Keeper 클러스터를 정의하며, 안티 어피니티, 영구 저장소, 그리고 Altinity 오퍼레이터가 Keeper 파드를 프로비저닝할 때 사용하는 설정을 포함합니다.

```yaml theme={"system"}
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`를 업데이트하세요.
* **보안 컨텍스트**: 조직의 보안 정책에 맞게 `runAsUser` 및 `fsGroup` 값을 조정하세요.
* **안티 어피니티**: 클러스터 토폴로지와 HA 요구 사항에 따라 `affinity` 섹션을 사용자 지정하거나 제거하세요.
* **리소스**: CPU 및 메모리 값은 예시입니다. 적절한 사이징은 W\&B Solutions Architect와 상의하세요.
* **이름 지정**: `metadata.name` 또는 `configuration.clusters[0].name`을 변경하는 경우, `ch-server.yaml`(4단계)의 Keeper 호스트 이름도 그에 맞게 업데이트해야 합니다.

<h4 id="deploy-clickhouse-keeper-resources">
  ClickHouse Keeper 리소스 배포
</h4>

```bash theme={"system"}
kubectl apply -f ch-keeper.yaml
```

<h4 id="verify-the-keeper-deployment">
  Keeper 배포 확인
</h4>

```bash theme={"system"}
# 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 Service 확인
kubectl get svc -n clickhouse | grep keeper

# 포트 2181을 사용하는 keeper Service가 조회되어야 합니다
```

이제 Keeper가 실행 중이므로 Keeper로 코디네이션을 수행하는 ClickHouse 클러스터를 배포할 수 있습니다.

<h3 id="deploy-the-clickhouse-cluster">
  ClickHouse 클러스터 배포
</h3>

이제 Weave 트레이스 데이터를 저장할 ClickHouse 서버 클러스터를 배포합니다. 이 클러스터는 3단계의 Keeper 서비스와 2단계의 S3 버킷에 모두 연결되므로, 이 가이드에서 작업량이 가장 많은 단계입니다.

<h4 id="create-the-clickhouse-server-configuration">
  ClickHouse 서버 설정 만들기
</h4>

`ch-server.yaml` 파일을 만드세요. 이 매니페스트에서는 ClickHouse 클러스터, Keeper 연결, Weave 사용자 계정, 트레이스 데이터에 사용할 S3 저장소 정책을 선언합니다.

```yaml theme={"system"}
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) 설정
    # 중요: 이 호스트 이름은 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
      # 선택: timeout을 조정해야 하는 경우 주석을 해제하세요
      # 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: [WEAVE-PASSWORD]  # 배포 전에 강력한 비밀번호로 바꾸세요
      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://[BUCKET-NAME].s3.[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>[REGION]</region>
                    </s3_disk>
                    <s3_disk_cache>
                        <type>cache</type>
                        <disk>s3_disk</disk>
                        <path>/var/lib/clickhouse/s3_disk_cache/cache/</path>
                        <!-- 캐시 크기는 반드시 Persistent Volume보다 작아야 합니다 -->
                        <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 엔드포인트**: `[BUCKET-NAME]`과 `[REGION]`을 실제 값으로 바꾸세요.
3. **캐시 크기**: `<max_size>40Gi</max_size>`는 영구 볼륨 크기(50Gi)보다 작아야 합니다.
4. **보안 컨텍스트**: `runAsUser`, `fsGroup` 및 기타 보안 설정을 조직의 정책에 맞게 조정하세요.
5. **리소스 할당**: CPU 및 메모리 값은 예시입니다. 예상 트레이스 볼륨에 맞는 적절한 사이징은 W\&B Solutions Architect와 상의하세요.
6. **안티 어피니티 규칙**: 클러스터 토폴로지와 고가용성 요구 사항에 따라 사용자 지정하거나 제거하세요.
7. **Keeper 호스트 이름**: Keeper 노드 호스트 이름은 3단계에서 정한 Keeper 배포 이름과 일치해야 합니다("Keeper 이름 지정" 참조).
8. **클러스터 이름 지정**: 클러스터 이름 `weavecluster`는 변경할 수 있지만, 5단계의 `WF_CLICKHOUSE_REPLICATED_CLUSTER` 값과 일치해야 합니다.
9. **자격 증명**:
   * IRSA를 사용하는 경우: `<use_environment_credentials>true</use_environment_credentials>`를 그대로 유지하거나, 환경 변수에 매핑된 시크릿 키에 액세스하세요.

<h4 id="update-the-s3-configuration">
  S3 설정 업데이트
</h4>

`ch-server.yaml`에서 `storage_configuration.xml` 섹션을 수정하세요.

AWS S3 예시:

```xml theme={"system"}
<endpoint>https://my-wandb-clickhouse.s3.eu-central-1.amazonaws.com/s3_disk/{replica}</endpoint>
<region>eu-central-1</region>
```

MinIO 예시:

```xml theme={"system"}
<endpoint>https://minio.example.com:9000/my-bucket/s3_disk/{replica}</endpoint>
<region>us-east-1</region>
```

<Warning>
  `{replica}`를 제거하지 마세요. 이 값이 있어야 각 ClickHouse 레플리카가 버킷 내의 고유한 폴더에 데이터를 기록합니다.
</Warning>

<h4 id="configure-credentials-option-b-only">
  자격 증명 설정(옵션 B만 해당)
</h4>

2단계에서 옵션 B(액세스 키)를 사용하는 경우, `ch-server.yaml`의 `env` 섹션에서 시크릿을 참조하고 있는지 확인하세요.

```yaml theme={"system"}
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
```

옵션 A(IRSA)를 사용하는 경우 `env` 섹션 전체를 삭제하세요.

<h4 id="keeper-naming">
  Keeper 명명 규칙
</h4>

Keeper 호스트 이름을 정확하게 지정하는 것이 매우 중요합니다. 3단계에서 생성한 서비스와 일치하지 않으면 ClickHouse가 시작되지 않습니다. `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 namespace입니다(예: `clickhouse`).

기본 이름을 사용한 예시:

```text theme={"system"}
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`):

```text theme={"system"}
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`):

```text theme={"system"}
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 호스트 이름을 확인하려면 다음을 수행하세요.

```bash theme={"system"}
# Keeper Service 목록을 조회하여 실제 이름 확인
kubectl get svc -n clickhouse | grep keeper

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

<Note>
  `ch-server.yaml`에 지정한 Keeper 호스트 이름은 Keeper 배포에서 생성된 실제 서비스 이름과 정확히 일치해야 합니다. 일치하지 않으면 ClickHouse 서버가 코디네이션 서비스에 연결할 수 없습니다.
</Note>

<h4 id="deploy-the-clickhouse-cluster-resources">
  ClickHouse 클러스터 리소스 배포
</h4>

```bash theme={"system"}
kubectl apply -f ch-server.yaml
```

<h4 id="verify-the-clickhouse-deployment">
  ClickHouse 배포 확인
</h4>

```bash theme={"system"}
# 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 [WEAVE-PASSWORD] --query "SELECT version()"

# 클러스터 상태 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --query \
  "SELECT cluster, host_name, port FROM system.clusters WHERE cluster='weavecluster'"
```

이제 Keeper와 S3를 기반으로 하는 ClickHouse 클러스터가 실행 중입니다. 나머지 단계에서는 W\&B Platform을 이 클러스터에 연결하고 Weave 트레이스가 엔드투엔드로 정상 전달되는지 확인합니다.

<h3 id="enable-weave-in-the-wb-platform">
  W\&B Platform에서 Weave 활성화하기
</h3>

이제 Weave 트레이스에 ClickHouse 클러스터를 사용하도록 W\&B Platform을 설정하세요. 이 단계에서는 외부에서 관리하는 ClickHouse의 위치를 W\&B 오퍼레이터에 알려 주고 `weave-trace` 서비스를 활성화합니다.

<h4 id="gather-clickhouse-connection-information">
  ClickHouse 연결 정보 확인
</h4>

다음 정보가 필요합니다.

* **호스트**: `clickhouse-wandb.clickhouse.svc.cluster.local`
* **포트**: `8123`
* **사용자**: `weave` (`ch-server.yaml`에 설정한 값)
* **비밀번호**: `ch-server.yaml`에 설정한 비밀번호
* **데이터베이스**: `weave` (자동으로 생성됨)
* **클러스터 이름**: `weavecluster` (`ch-server.yaml`에 설정한 값)

호스트 이름은 다음 형식을 따릅니다: `clickhouse-[INSTALLATION-NAME].[NAMESPACE].svc.cluster.local`

<h4 id="update-the-wb-custom-resource">
  W\&B 커스텀 리소스 업데이트
</h4>

W\&B Platform 커스텀 리소스(CR)를 편집하여 Weave 설정을 추가하세요.

```yaml theme={"system"}
apiVersion: apps.wandb.com/v1
kind: WeightsAndBiases
metadata:
  name: wandb
  namespace: wandb
spec:
  values:
    global:
      # ... 기존 설정 ...

      # ClickHouse 설정 추가
      clickhouse:
        install: false # 별도로 배포했으므로 false
        host: clickhouse-wandb.clickhouse.svc.cluster.local
        port: 8123
        user: weave
        password: [WEAVE-PASSWORD]
        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`에 지정된 클러스터 이름과 일치해야 합니다.

<Note>
  여기에 나온 보안 컨텍스트, 리소스 할당 및 기타 Kubernetes 관련 설정은 레퍼런스용 예시입니다. 조직의 요구 사항에 맞게 사용자 지정하고, 적절한 리소스 사이징은 W\&B Solutions Architect 팀과 상의하세요.
</Note>

<h4 id="apply-the-updated-configuration">
  업데이트된 설정 적용하기
</h4>

```bash theme={"system"}
kubectl apply -f wandb-cr.yaml
```

<h4 id="verify-the-weave-trace-deployment">
  Weave Trace 배포 확인
</h4>

```bash theme={"system"}
# weave-trace 파드 상태 확인
kubectl get pods -n wandb | grep weave-trace

# 예상 출력:
# wandb-weave-trace-bc-xxxxx   1/1     Running   0          2m

# weave-trace 로그에서 ClickHouse 연결 상태 확인
kubectl logs -n wandb [WEAVE-TRACE-POD-NAME] --tail=50

# ClickHouse 연결 성공 메시지가 있는지 확인하세요
```

<h3 id="initialize-the-weave-database">
  Weave 데이터베이스 초기화
</h3>

weave-trace 서비스는 처음 시작될 때 필요한 데이터베이스 스키마를 자동으로 생성합니다. 이 단계에서는 최종 사용자에게 Weave를 제공하기 전에 마이그레이션이 정상적으로 완료되었는지 확인합니다.

<h4 id="monitor-the-database-migration">
  데이터베이스 마이그레이션 모니터링
</h4>

```bash theme={"system"}
# 시작하는 동안 weave-trace 로그를 모니터링하세요
kubectl logs -n wandb [WEAVE-TRACE-POD-NAME] -f

# 데이터베이스가 성공적으로 초기화되었음을 알리는 마이그레이션 메시지를 확인하세요
```

<h4 id="verify-database-creation">
  데이터베이스 생성 확인
</h4>

```bash theme={"system"}
# ClickHouse에 연결하여 데이터베이스 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --query \
  "SHOW DATABASES"

# 목록에 'weave' 데이터베이스가 표시되어야 함

# weave 데이터베이스의 table 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --query \
  "SHOW TABLES FROM weave"
```

<h3 id="verify-that-weave-is-enabled">
  Weave 활성화 확인
</h3>

이 마지막 단계에서는 Weave에 라이선스가 적용되어 있는지, W\&B Console에서 접근할 수 있는지, 클라이언트 SDK에서 트레이스를 기록할 수 있는지 확인합니다.

<h4 id="access-the-wb-console">
  W\&B Console에 액세스하기
</h4>

웹 브라우저에서 W\&B 인스턴스 URL로 이동하세요.

<h4 id="check-the-weave-license-status">
  Weave 라이선스 상태 확인
</h4>

W\&B Console에서 다음 단계를 따르세요.

1. **Top Right Menu** > **Organization Dashboard**로 이동하세요.
2. **Weave access**가 활성화되어 있는지 확인하세요.

<h4 id="test-weave-functionality">
  Weave 기능 테스트
</h4>

Weave가 제대로 작동하는지 확인하는 Python 테스트를 작성하세요.

```python theme={"system"}
import os
import weave

# Weave가 자체 관리형 W&B 인스턴스를 사용하도록 설정
os.environ["WANDB_BASE_URL"] = "https://[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)
```

이 코드를 실행한 후 Weights & Biases UI에서 조직의 트레이스 페이지로 이동하여 트레이스를 확인하세요. 트레이스가 표시되면 Self-Managed Weave 배포가 정상적으로 작동하고 있는 것입니다.

<h2 id="troubleshooting">
  문제 해결
</h2>

다음 섹션에서는 자주 발생하는 배포 문제와 해결 방법을 증상이 처음 나타나는 컴포넌트별로 나누어 설명합니다.

<h3 id="clickhouse-keeper-issues">
  ClickHouse Keeper 문제
</h3>

**문제**: Keeper 파드가 `Pending` 상태에서 벗어나지 못함

**해결 방법**: 다음과 같이 여러 가지 원인이 있을 수 있으므로 각각 확인하세요.

1. **PVC 및 StorageClass 문제**:

```bash theme={"system"}
kubectl get pvc -n clickhouse
kubectl describe pvc -n clickhouse
```

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

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

```bash theme={"system"}
# 안티 어피니티 규칙 때문에 스케줄링이 안 되는지 확인
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` 상태임

**해결 방법**: 로그와 설정을 확인하세요.

```bash theme={"system"}
kubectl logs -n clickhouse [KEEPER-POD-NAME]
```

일반적인 문제:

* 올바르지 않은 보안 컨텍스트(`runAsUser` 및 `fsGroup`을 확인하세요).
* 볼륨 권한 문제.
* 포트 충돌.
* `ch-keeper.yaml`의 설정 오류.

<h3 id="clickhouse-server-issues">
  ClickHouse 서버 문제
</h3>

**문제**: ClickHouse가 S3에 연결할 수 없음

**해결 방법**: S3 자격 증명과 권한을 확인하세요:

```bash theme={"system"}
# 시크릿 존재 여부 확인 (액세스 키를 사용하는 경우)
kubectl get secret aws-creds -n clickhouse

# ClickHouse 로그에서 S3 오류 확인
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 엔드포인트와 이름 설정을 확인하세요.

```bash theme={"system"}
# 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 배포와 일치하지 않을 가능성이 높습니다. 명명 패턴은 4단계의 "Keeper naming"을 참조하세요.

<h3 id="weave-trace-issues">
  Weave Trace 문제
</h3>

**문제**: `weave-trace` 파드가 시작되지 않음

**해결 방법**: ClickHouse 연결 상태를 확인하세요.

```bash theme={"system"}
# 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가 포함되어 있는지 확인하세요.

   ```bash theme={"system"}
   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 로그를 확인하세요.
   ```bash theme={"system"}
   kubectl logs -n wandb deployment/wandb-controller-manager
   ```

***

**문제**: 데이터베이스 마이그레이션이 실패함

**해결 방법**: 클러스터 이름이 일치하는지 확인하세요.

`WF_CLICKHOUSE_REPLICATED_CLUSTER` 환경 변수의 값은 `ch-server.yaml`에 지정된 클러스터 이름과 일치해야 합니다.

```yaml theme={"system"}
# ch-server.yaml:
clusters:
  - name: weavecluster # <-- 이 이름

# wandb-cr.yaml의 값과 일치해야 함:
weave-trace:
  extraEnv:
    WF_CLICKHOUSE_REPLICATED_CLUSTER: "weavecluster" # <-- 이 값
```

<h2 id="resource-requirements">
  리소스 요구 사항
</h2>

이 섹션에서는 일반적인 두 가지 배포 프로필의 리소스 할당 예시를 제공합니다. 클러스터를 계획할 때 이 예시를 출발점으로 삼고, 실제 워크로드를 관찰하면서 수치를 조정하세요.

<Warning>
  이 섹션의 리소스 할당은 출발점으로 삼을 수 있는 예시입니다. 실제 요구 사항은 다음 요소에 따라 달라집니다.

  * 트레이스 임포트 볼륨(초당 트레이스 수)
  * 쿼리 패턴 및 동시성
  * 데이터 보존 기간
  * 동시 사용자 수

  사용 사례에 맞는 적절한 사이징을 확인하려면 반드시 W\&B Solutions Architect 팀과 상의하세요. 리소스를 부족하게 프로비저닝하면 성능 문제가 발생할 수 있으며, 과도하게 프로비저닝하면 인프라 비용이 낭비됩니다.
</Warning>

<h3 id="minimum-production-setup">
  최소 프로덕션 설정
</h3>

| 컴포넌트 | 레플리카 | 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** |

개발 환경, 테스트 환경 또는 트래픽이 적은 프로덕션 환경에 적합합니다.

<h3 id="recommended-production-setup">
  권장 프로덕션 설정
</h3>

트레이스 볼륨이 큰 프로덕션 워크로드에는 다음 구성을 권장합니다.

| 컴포넌트 | 레플리카 | CPU (요청, 제한) | 메모리 (요청, 제한) | 저장소 |
| - | - | - | - | - |
| 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 팀에 문의하세요.

<h2 id="advanced-configuration">
  고급 설정
</h2>

이 섹션에서는 Self-Managed Weave 배포를 위한 맞춤형 설정 옵션을 다룹니다. 수직 스케일링 또는 수평 스케일링을 통한 ClickHouse 용량 확장, keeper 및 server 설정에서 이미지 태그를 수정하여 ClickHouse 버전을 업데이트하는 방법, ClickHouse 상태 모니터링 방법을 설명합니다.

인스턴스에 고급 변경 사항을 적용할 때는 W\&B Solutions Architect 팀과 상의하여 해당 변경 사항이 성능 및 안정성 요구 사항에 부합하는지 확인하는 것이 좋습니다.

<h3 id="scale-clickhouse">
  ClickHouse 스케일링
</h3>

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

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

   ```yaml theme={"system"}
   resources:
     requests:
       memory: 8Gi
       cpu: 1
     limits:
       memory: 64Gi
       cpu: 16
   ```

   권장 사항: 실제 리소스 사용량을 모니터링하고 이에 맞춰 스케일링하세요. 데이터 처리량이 매우 많은 배포라면 W\&B Solutions Architect 팀에 문의하세요.

2. **수평 스케일링**: 레플리카를 추가합니다(신중한 계획 필요).
   * 레플리카를 늘리면 데이터 재분산이 필요합니다.
   * 샤드 관리 방법은 ClickHouse 문서를 참조하세요.
   * 프로덕션 환경에 수평 스케일링을 적용하기 전에 W\&B Solutions Architect에게 문의하세요.

<h3 id="use-a-different-clickhouse-version">
  다른 ClickHouse 버전 사용
</h3>

다른 ClickHouse 버전을 사용하려면 `ch-keeper.yaml`과 `ch-server.yaml` 두 파일 모두에서 이미지 태그를 변경하세요.

```yaml theme={"system"}
image: clickhouse/clickhouse-keeper:25.10   # Keeper 버전
image: clickhouse/clickhouse-server:25.10   # 서버 버전
```

호환성을 위해 Keeper 버전은 서버 버전과 일치하거나 서버 버전 이상이어야 합니다.

<Warning>
  ClickHouse Server를 업그레이드할 때는 ClickHouse Keeper도 호환되는 버전으로 함께 업그레이드하세요. W\&B Self-Managed 배포의 ClickHouse 버전을 변경하기 전에 [업그레이드 시 ClickHouse 호환성](/ko/products/wandb/platform/hosting/self-managed/operator#clickhouse-compatibility-for-upgrades) 및 [지원되는 W\&B Server 릴리스](/ko/release-notes/server-releases) 페이지를 확인하세요.
</Warning>

<h3 id="monitor-clickhouse">
  ClickHouse 모니터링
</h3>

ClickHouse 시스템 table에 액세스하여 모니터링하세요:

```bash theme={"system"}
# 디스크 사용량 확인
kubectl exec -n clickhouse chi-wandb-weavecluster-0-0-0 -- \
  clickhouse-client --user weave --password [WEAVE-PASSWORD] --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 [WEAVE-PASSWORD] --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
```

<h3 id="backup-and-recovery">
  백업 및 복구
</h3>

ClickHouse는 데이터를 S3에 저장하므로 S3 버전 관리 및 버킷 복제 기능을 통해 자체적으로 백업 기능을 갖추고 있습니다. 배포 환경에 맞는 백업 전략은 W\&B Solutions Architect 팀과 상의하고 [ClickHouse 백업 문서](https://clickhouse.com/docs/en/operations/backup)를 참고하세요.

<h2 id="security-considerations">
  보안 고려 사항
</h2>

프로덕션 배포에서는 이 가이드에 나온 기본 설정을 강화해야 합니다. 다음은 보안 팀과 함께 검토해야 할 가장 중요한 항목입니다.

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

<h2 id="upgrade">
  업그레이드
</h2>

다음 절차에서는 operator, ClickHouse 서버, Weave Trace 컴포넌트의 정기 업그레이드 방법을 설명합니다. 컴포넌트는 한 번에 하나씩 업그레이드하고, 다음 컴포넌트로 넘어가기 전에 배포가 정상 상태인지 확인하세요.

<Note>
  Weave를 사용하려면 지원되는 ClickHouse 버전이 필요합니다. ClickHouse 또는 W\&B Server를 업그레이드하기 전에 [업그레이드 시 ClickHouse 호환성](/ko/products/wandb/platform/hosting/self-managed/operator#clickhouse-compatibility-for-upgrades) 및 [지원되는 W\&B Server 릴리스](/ko/release-notes/server-releases)를 확인하세요. ClickHouse Server와 ClickHouse Keeper는 함께 업그레이드해야 합니다.
</Note>

<h3 id="upgrade-the-clickhouse-operator">
  ClickHouse Operator 업그레이드
</h3>

```bash theme={"system"}
helm upgrade ch-operator altinity/altinity-clickhouse-operator \
  --namespace clickhouse \
  -f ch-operator.yaml
```

<h3 id="upgrade-clickhouse-server">
  ClickHouse Server 업그레이드
</h3>

`ch-keeper.yaml`과 `ch-server.yaml` 두 파일의 이미지 버전을 모두 업데이트한 다음, 서버 매니페스트를 적용하세요.

```bash theme={"system"}
# ch-keeper.yaml과 ch-server.yaml을 편집하여 이미지 태그를 변경합니다
kubectl apply -f ch-keeper.yaml
kubectl apply -f ch-server.yaml

# 파드 상태를 모니터링합니다
kubectl get pods -n clickhouse
```

<h3 id="upgrade-weave-trace">
  Weave Trace 업그레이드
</h3>

`wandb-cr.yaml`에서 이미지 태그를 업데이트한 다음 변경 사항을 적용하세요.

```bash theme={"system"}
kubectl apply -f wandb-cr.yaml

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

<h2 id="additional-resources">
  추가 리소스
</h2>

* [ingest 샘플링 설정](/ko/products/wandb/weave/guides/platform/ingest-sampling): 수신되는 트레이스 중 일부만 보관하여, 트레이스 볼륨이 많을 때 저장소 비용과 LLM 점수화 비용을 관리합니다.
* [Altinity ClickHouse Operator 문서](https://docs.altinity.com/altinitykubernetesoperator/)
* [ClickHouse 문서](https://clickhouse.com/docs)
* [W\&B Weave 문서](/ko/products/wandb/weave)
* [ClickHouse S3 저장소 설정](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/mergetree#s3-virtual-hosted-style)

<h2 id="support">
  지원
</h2>

프로덕션 배포 관련 문의나 문제가 있는 경우:

* **CoreWeave Forge 지원팀**: `forge-support@coreweave.com`
* **솔루션 아키텍트**: 초대용량 배포, 맞춤형 사이징, 배포 계획 수립에 관해 문의하세요.
* **지원 요청 시 포함할 정보**:
  * `weave-trace`, ClickHouse 파드, 오퍼레이터의 로그
  * W\&B 버전, ClickHouse 버전, Kubernetes 버전
  * 클러스터 정보 및 트레이스 볼륨

<h2 id="faq">
  FAQ
</h2>

**Q: ClickHouse 레플리카를 3개 대신 1개만 사용할 수 있나요?**

A: 네, 가능하지만 프로덕션 환경에서는 권장하지 않습니다. `ch-server.yaml`에서 `replicasCount: 1`로 변경하고 `wandb-cr.yaml`에서 `clickhouse.replicated: false`로 설정하세요.

**Q: ClickHouse 대신 다른 데이터베이스를 사용할 수 있나요?**

A: 아니요. Weave Trace는 ClickHouse의 고성능 컬럼형 저장소 기능을 활용하므로 ClickHouse가 반드시 필요합니다.

**Q: S3 저장소는 얼마나 필요한가요?**

A: 필요한 S3 저장소 용량은 트레이스 볼륨, 보존 기간, 데이터 압축률에 따라 달라집니다. 배포 후 실제 사용량을 모니터링하면서 적절히 조정하세요. ClickHouse는 컬럼형 형식을 사용하므로 트레이스 데이터를 효율적으로 압축합니다.

**Q: ClickHouse에서 `database` 이름을 설정해야 하나요?**

A: 아니요. weave-trace 서비스가 최초 시작 시 `weave` 데이터베이스를 자동으로 생성합니다.

**Q: 클러스터 이름이 `weavecluster`가 아니면 어떻게 하나요?**

A: `WF_CLICKHOUSE_REPLICATED_CLUSTER` 환경 변수를 실제 클러스터 이름과 일치하도록 설정해야 합니다. 그렇지 않으면 데이터베이스 마이그레이션이 실패합니다.

**Q: 예시에 나온 보안 컨텍스트를 그대로 사용해야 하나요?**

A: 아니요. 이 가이드에서 제공하는 `runAsUser`, `fsGroup` 등의 보안 컨텍스트는 참고용 예시입니다. 조직의 보안 정책에 맞게 조정해야 하며, 특히 UID 및 GID 범위에 대한 별도 요구 사항이 있는 OpenShift 클러스터에서는 반드시 조정하세요.

**Q: ClickHouse 클러스터의 사이징이 적절한지 어떻게 알 수 있나요?**

A: 예상 트레이스 볼륨과 사용 패턴을 W\&B Solutions Architect 팀에 알려 주시면 사이징 권장 사항을 받을 수 있습니다. 배포 후에는 리소스 사용량을 모니터링하고 필요에 따라 조정하세요.

**Q: 예시에 사용된 명명 규칙을 사용자 지정할 수 있나요?**

A: 네, 가능하지만 모든 컴포넌트에서 일관성을 유지해야 합니다.

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

명명 패턴과 실제 이름을 확인하는 방법은 4단계의 "Keeper naming" 섹션을 참조하세요.

**Q: 클러스터의 안티 어피니티 요구 사항이 다르면 어떻게 하나요?**

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


## Related topics

- [Kubernetes Operator로 W&B 배포](/ko/products/wandb/platform/hosting/self-managed/operator.md)