에어갭(Air-gapped) 인스턴스를 위한 Kubernetes operator

도입

이 가이드는 인터넷 연결이 제한된(air-gapped) 고객 관리형 환경에서 W&B 플랫폼을 배포하는 단계별 지침을 제공합니다. 내부 저장소 또는 레지스트리를 사용하여 Helm 차트와 컨테이너 이미지를 호스팅하세요. Kubernetes 클러스터에 대한 적절한 엑세스 권한이 있는 셸 콘솔에서 모든 코맨드를 실행합니다. Kubernetes 애플리케이션을 배포하는 데 사용하는 모든 지속적 인도(continuous delivery) 툴에서도 유사한 코맨드를 활용할 수 있습니다.

1단계: 필수 조건

시작하기 전에 환경이 다음 요구 사항을 충족하는지 확인하세요.

버전 요구 사항

Software	Minimum version
Kubernetes	v1.32 or newer (Supported Kubernetes versions)
Helm	v3.x
MySQL	v8.0.x is required, v8.0.32 or newer; v8.0.44 or newer is recommended. Aurora MySQL 3.x releases, must be v3.05.2 or newer
Redis	v7.x

SSL/TLS 요구 사항

W&B requires a valid signed SSL/TLS certificate for secure communication between clients and the server. SSL/TLS termination must occur on the ingress/load balancer. The W&B Server application does not terminate SSL or TLS connections. Important: W&B does not support self-signed certificates and custom CAs. Using self-signed certificates will cause challenges for users and is not supported. If possible, using a service like Let’s Encrypt is a great way to provide trusted certificates to your load balancer. Services like Caddy and Cloudflare manage SSL for you. If your security policies require SSL communication within your trusted networks, consider using a tool like Istio and side car containers.

하드웨어 요구 사항

CPU Architecture: W&B runs on Intel (x86) CPU architecture only. ARM is not supported. Sizing: For CPU, memory, and disk sizing recommendations for Kubernetes nodes and MySQL, see the Sizing section in the reference architecture. Requirements vary based on whether you’re running Models, Weave, or both.

MySQL 데이터베이스

W&B requires an external MySQL database. For production, W&B strongly recommends using managed database services:

Managed database services provide automated backups, monitoring, high availability, patching, and reduce operational overhead. See the reference architecture for complete MySQL requirements, including sizing recommendations and configuration parameters. For database creation SQL, see the bare-metal guide. For questions about your deployment’s database configuration, contact support or your AISE.

Redis

W&B depends on a single-node Redis 7.x deployment used by W&B’s components for job queuing and data caching. For convenience during testing and development of proofs of concept, W&B Self-Managed includes a local Redis deployment that is not appropriate for production deployments. For production deployments, W&B can connect to a Redis instance in the following environments:

AWS Elasticache
Google Cloud Memory Store
Azure Cache for Redis
Redis deployment hosted in your cloud or on-premise infrastructure

오브젝트 스토리지

W&B requires object storage with pre-signed URL and CORS support. For production deployments, W&B recommends using managed object storage services:

Amazon S3: Object storage service offering industry-leading scalability, data availability, security, and performance.
Google Cloud Storage: Managed service for storing unstructured data at scale.
Azure Blob Storage: Cloud-based object storage solution for storing massive amounts of unstructured data.
CoreWeave AI Object Storage: High-performance, S3-compatible object storage service optimized for AI workloads.

For self-hosted object storage options, see the bare-metal guide object storage section for detailed setup instructions including CORS configuration and enterprise alternatives.

MinIO Open Source is in maintenance mode with no active development or pre-compiled binaries. For production deployments, W&B recommends using managed object storage services or enterprise-grade S3-compatible solutions.

See the reference architecture object storage section for complete requirements.

추가 요구 사항

필요한 W&B 이미지가 있는 내부 컨테이너 레지스트리에 대한 엑세스
W&B Helm 차트를 위한 내부 Helm 저장소에 대한 엑세스

네트워킹 및 로드 밸런서 설정을 포함한 전체 인프라 요구 사항은 참조 아키텍처를 참조하세요.

W&B는 에어갭(air-gapped) OpenShift Kubernetes 클러스터에 배포할 수 있습니다. 자세한 내용은 참조 아키텍처를 참조하고, 에어갭 OpenShift 배포에 맞게 조정할 수 있는 특정 설정 지침은 Operator 가이드의 OpenShift 섹션을 검토하세요.

2단계: 내부 컨테이너 레지스트리 준비

성공적인 에어갭 배포를 위해 다음 컨테이너 이미지가 내부 컨테이너 레지스트리에 준비되어 있어야 합니다. 사용자는 W&B Operator의 요구 사항을 추적하고 컨테이너 레지스트리를 최신 이미지로 정기적으로 유지 관리할 책임이 있습니다. 필요한 컨테이너 이미지 및 버전의 최신 목록은 Helm 차트를 참조하거나 지원팀 또는 담당 AISE에게 문의하세요.

핵심 W&B 구성 요소 컨테이너

종속성

docker.io/bitnamilegacy/redis: 테스트 및 개발 중 로컬 Redis 배포에 필요합니다. 로컬 Redis 배포를 사용하려면 이 이미지가 컨테이너 레지스트리에 있는지 확인하세요. 프로덕션 Redis 요구 사항은 필수 조건의 Redis 섹션을 참조하세요.
docker.io/otel/opentelemetry-collector-contrib: W&B는 Kubernetes 레이어의 리소스에서 메트릭과 로그를 수집하여 W&B에 표시하기 위해 OpenTelemetry 에이전트에 의존합니다.
quay.io/prometheus/prometheus: W&B는 다양한 구성 요소에서 메트릭을 캡처하여 W&B에 표시하기 위해 Prometheus에 의존합니다.
quay.io/prometheus-operator/prometheus-config-reloader: Prometheus의 필수 종속성입니다.

필요한 이미지 가져오기

Helm 차트 값에서 필요한 이미지 및 버전의 전체 목록을 추출하려면 다음을 수행하세요.

W&B Helm 차트 저장소에서 W&B Operator 및 플랫폼 Helm 차트를 다운로드합니다.

values.yaml 파일을 검사하여 모든 컨테이너 이미지와 버전을 확인합니다.

# Helm 차트에서 이미지 참조 추출
helm show values wandb/operator \
  | awk -F': *' '/^[[:space:]]*repository:/{print $2}' \
  | grep -E '^wandb/' \
  | sort -u

목록은 다음과 유사할 수 있습니다. 이미지 버전은 다를 수 있습니다.

wandb/anaconda2
wandb/console
wandb/frontend-nginx
wandb/local
wandb/megabinary
wandb/weave-python
wandb/weave-trace

3단계: 내부 Helm 차트 저장소 준비

컨테이너 이미지와 함께 다음 Helm 차트도 내부 Helm 차트 저장소에 준비되어 있어야 합니다. 다음 위치에서 다운로드하세요.

operator 차트는 Controller Manager라고도 불리는 W&B Operator를 배포하는 데 사용됩니다. platform 차트는 사용자 정의 리소스 정의(CRD)에 설정된 값을 사용하여 W&B 플랫폼을 배포하는 데 사용됩니다.

4단계: Helm 저장소 설정

이제 내부 저장소에서 W&B Helm 차트를 가져오도록 Helm 저장소를 설정합니다. 다음 코맨드를 실행하여 Helm 저장소를 추가하고 업데이트합니다.

helm repo add local-repo https://charts.yourdomain.com
helm repo update

5단계: Kubernetes Operator 설치

Controller Manager라고도 하는 W&B Kubernetes Operator는 W&B 플랫폼 구성 요소를 관리하는 역할을 합니다. 에어갭 환경에 설치하려면 내부 컨테이너 레지스트리를 사용하도록 설정해야 합니다. 이를 위해 기본 이미지 설정을 내부 컨테이너 레지스트리를 사용하도록 재정의하고, 예상되는 배포 유형을 나타내기 위해 airgapped: true 키를 설정해야 합니다. 아래와 같이 values.yaml 파일을 업데이트하세요.

image:
  repository: registry.yourdomain.com/library/controller
  tag: 1.13.3
airgapped: true

태그를 내부 레지스트리에서 사용 가능한 버전으로 교체하세요. Operator 및 CRD를 설치합니다.

helm upgrade --install operator local-repo/operator -n wandb --create-namespace -f values.yaml

지원되는 값에 대한 자세한 내용은 Kubernetes operator GitHub 저장소를 참조하세요.

6단계: MySQL 데이터베이스 설정

W&B 사용자 정의 리소스를 설정하기 전에 외부 MySQL 데이터베이스를 설정해야 합니다. 프로덕션 배포의 경우 W&B는 관리형 데이터베이스 서비스를 사용할 것을 강력히 권장합니다. 직접 MySQL 인스턴스를 운영하는 경우 데이터베이스와 사용자를 생성하세요. Create a database and a user with the following SQL commands. Replace SOME_PASSWORD with a secure password of your choice:

CREATE USER 'wandb_local'@'%' IDENTIFIED BY 'SOME_PASSWORD';
CREATE DATABASE wandb_local CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
GRANT ALL ON wandb_local.* TO 'wandb_local'@'%' WITH GRANT OPTION;

MySQL 설정 파라미터는 참조 아키텍처 MySQL 설정 섹션을 참조하세요.

7단계: W&B Custom Resource 설정

W&B Kubernetes Operator를 설치한 후, 내부 Helm 저장소와 컨테이너 레지스트리를 가리키도록 Custom Resource(CR)를 설정해야 합니다. 이 설정은 Kubernetes Operator가 W&B 플랫폼의 필요한 구성 요소를 배포할 때 내부 레지스트리와 저장소를 사용하도록 보장합니다. 이 예시 CR을 wandb.yaml이라는 새 파일에 복사합니다.

apiVersion: apps.wandb.com/v1
kind: WeightsAndBiases
metadata:
  labels:
    app.kubernetes.io/instance: wandb
    app.kubernetes.io/name: weightsandbiases
  name: wandb
  namespace: default

spec:
  chart:
    url: http://charts.yourdomain.com
    name: operator-wandb
    version: 0.18.0

  values:
    global:
      host: https://wandb.yourdomain.com
      license: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      bucket:
        accessKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        secretKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        name: s3.yourdomain.com:port #예: s3.yourdomain.com:9000
        path: bucket_name
        provider: s3
        region: us-east-1
      mysql:
        database: wandb
        host: mysql.home.lab
        password: password
        port: 3306
        user: wandb
      redis:
        host: redis.yourdomain.com
        port: 6379
        password: password
      api:
        enabled: true
      glue:
        enabled: true
      executor:
        enabled: true
      extraEnv:
        ENABLE_REGISTRY_UI: 'true'

    app:
      image:
        repository: registry.yourdomain.com/local
        tag: 0.59.2

    console:
      image:
        repository: registry.yourdomain.com/console
        tag: 2.12.2

    api:
      image:
        repository: registry.yourdomain.com/megabinary
        tag: 0.59.2

    executor:
      image:
        repository: registry.yourdomain.com/megabinary
        tag: 0.59.2

    glue:
      image:
        repository: registry.yourdomain.com/megabinary
        tag: 0.59.2

    parquet:
      image:
        repository: registry.yourdomain.com/megabinary
        tag: 0.59.2

    weave:
      image:
        repository: registry.yourdomain.com/weave-python
        tag: 0.59.2

    otel:
      image:
        repository: registry.yourdomain.com/otel/opentelemetry-collector-contrib
        tag: 0.97.0

    prometheus:
      server:
        image:
          repository: registry.yourdomain.com/prometheus/prometheus
          tag: v2.47.0
      configmapReload:
        prometheus:
          image:
            repository: registry.yourdomain.com/prometheus-operator/prometheus-config-reloader
            tag: v0.67.0

    ingress:
      annotations:
        nginx.ingress.kubernetes.io/proxy-body-size: 0
      class: nginx

    

W&B 플랫폼을 배포하기 위해 Kubernetes Operator는 CR의 값을 사용하여 내부 저장소의 operator-wandb Helm 차트를 설정합니다. 모든 태그와 버전을 내부 레지스트리에서 사용 가능한 버전으로 교체하세요. 위의 예시는 가장 일반적으로 사용되는 구성 요소를 보여줍니다. 배포 요구 사항에 따라 settingsMigrationJob, weave-trace, filestream 등과 같은 추가 구성 요소에 대한 이미지 레지스트리를 설정해야 할 수도 있습니다. 설정 가능한 구성 요소의 전체 목록은 W&B Helm 저장소 values 파일을 참조하세요.

8단계: W&B 플랫폼 배포

이제 Kubernetes Operator와 CR이 설정되었으므로, wandb.yaml 설정을 적용하여 W&B 플랫폼을 배포합니다.

kubectl apply -f wandb.yaml

9단계: 설치 확인

To verify the installation, W&B recommends using the W&B CLI. The verify command executes several tests that verify all components and configurations.

This step assumes that the first admin user account is created with the browser.

Follow these steps to verify the installation:

Install the W&B CLI:

pip install wandb

wandb login --host=https://YOUR_DNS_DOMAIN

For example:

wandb login --host=https://wandb.company-name.com

Verify the installation:

wandb verify

A successful installation and fully working W&B deployment shows the following output:

Default host selected:  https://wandb.company-name.com
Find detailed logs for this test at: /var/folders/pn/b3g3gnc11_sbsykqkm3tx5rh0000gp/T/tmpdtdjbxua/wandb
Checking if logged in...................................................✅
Checking signed URL upload..............................................✅
Checking ability to send large payloads through proxy...................✅
Checking requests to base url...........................................✅
Checking requests made over signed URLs.................................✅
Checking CORs configuration of the bucket...............................✅
Checking wandb package version is up to date............................✅
Checking logged metrics, saving and downloading a file..................✅
Checking artifact save and download workflows...........................✅

Contact W&B Support if you encounter errors.

FAQ

배포 프로세스 중에 자주 묻는 질문(FAQ) 및 문제 해결 팁을 참조하세요.

다른 ingress 클래스가 있습니다. 해당 클래스를 사용할 수 있나요?

예, values.yaml의 ingress 설정을 수정하여 ingress 클래스를 구성할 수 있습니다.

인증서 번들에 두 개 이상의 인증서가 있습니다. 작동할까요?

values.yaml의 customCACerts 섹션에서 인증서를 여러 엔트리로 분할해야 합니다.

Kubernetes Operator가 의도하지 않은 업데이트를 적용하지 못하도록 하려면 어떻게 해야 하나요? 가능합니까?

W&B 콘솔에서 자동 업데이트를 끌 수 있습니다. 지원되는 버전에 대한 질문은 W&B 팀에 문의하세요. W&B는 초기 출시일로부터 12개월 동안 주요 W&B 서버 릴리스를 지원합니다. Self-Managed 인스턴스를 사용하는 고객은 지원을 유지하기 위해 제때 업그레이드할 책임이 있습니다. 지원되지 않는 버전에 머물지 않도록 하세요. 릴리스 정책 및 프로세스를 참조하세요.

W&B는 Self-Managed 인스턴스를 사용하는 고객이 지원을 유지하고 최신 기능, 성능 개선 및 픽스를 받기 위해 최소 분기별로 한 번씩 최신 릴리스로 배포를 업데이트할 것을 강력히 권장합니다.

환경이 공용 저장소에 연결되지 않은 경우에도 배포가 작동합니까?

설정에서 airgapped를 true로 설정하면 Kubernetes Operator는 내부 리소스만 사용하며 공용 저장소에 연결을 시도하지 않습니다.

Deployment Options

Configuring W&B

에어갭(Air-gapped) 인스턴스를 위한 Kubernetes operator

도입

1단계: 필수 조건

버전 요구 사항

SSL/TLS 요구 사항

하드웨어 요구 사항

MySQL 데이터베이스

Redis

오브젝트 스토리지

추가 요구 사항

2단계: 내부 컨테이너 레지스트리 준비

핵심 W&B 구성 요소 컨테이너

종속성

필요한 이미지 가져오기

3단계: 내부 Helm 차트 저장소 준비

4단계: Helm 저장소 설정

5단계: Kubernetes Operator 설치

6단계: MySQL 데이터베이스 설정

7단계: W&B Custom Resource 설정

8단계: W&B 플랫폼 배포

9단계: 설치 확인

FAQ

다른 ingress 클래스가 있습니다. 해당 클래스를 사용할 수 있나요?

인증서 번들에 두 개 이상의 인증서가 있습니다. 작동할까요?

Kubernetes Operator가 의도하지 않은 업데이트를 적용하지 못하도록 하려면 어떻게 해야 하나요? 가능합니까?

환경이 공용 저장소에 연결되지 않은 경우에도 배포가 작동합니까?

Deployment Options

Configuring W&B

​도입

​1단계: 필수 조건

​버전 요구 사항

​SSL/TLS 요구 사항

​하드웨어 요구 사항

​MySQL 데이터베이스

​Redis

​오브젝트 스토리지

​추가 요구 사항

​2단계: 내부 컨테이너 레지스트리 준비

​핵심 W&B 구성 요소 컨테이너

​종속성

​필요한 이미지 가져오기

​3단계: 내부 Helm 차트 저장소 준비

​4단계: Helm 저장소 설정

​5단계: Kubernetes Operator 설치

​6단계: MySQL 데이터베이스 설정

​7단계: W&B Custom Resource 설정

​8단계: W&B 플랫폼 배포

​9단계: 설치 확인

​FAQ

​다른 ingress 클래스가 있습니다. 해당 클래스를 사용할 수 있나요?

​인증서 번들에 두 개 이상의 인증서가 있습니다. 작동할까요?

​Kubernetes Operator가 의도하지 않은 업데이트를 적용하지 못하도록 하려면 어떻게 해야 하나요? 가능합니까?

​환경이 공용 저장소에 연결되지 않은 경우에도 배포가 작동합니까?

도입

1단계: 필수 조건

버전 요구 사항

SSL/TLS 요구 사항

하드웨어 요구 사항

MySQL 데이터베이스

Redis

오브젝트 스토리지

추가 요구 사항

2단계: 내부 컨테이너 레지스트리 준비

핵심 W&B 구성 요소 컨테이너

종속성

필요한 이미지 가져오기

3단계: 내부 Helm 차트 저장소 준비

4단계: Helm 저장소 설정

5단계: Kubernetes Operator 설치

6단계: MySQL 데이터베이스 설정

7단계: W&B Custom Resource 설정

8단계: W&B 플랫폼 배포

9단계: 설치 확인

FAQ

다른 ingress 클래스가 있습니다. 해당 클래스를 사용할 수 있나요?

인증서 번들에 두 개 이상의 인증서가 있습니다. 작동할까요?

Kubernetes Operator가 의도하지 않은 업데이트를 적용하지 못하도록 하려면 어떻게 해야 하나요? 가능합니까?

환경이 공용 저장소에 연결되지 않은 경우에도 배포가 작동합니까?