에어갭 Kubernetes에 배포

​

소개

• 보안 정부 시설
• 네트워크 격리가 엄격한 금융 기관
• 규정 준수 요구 사항이 있는 의료 기관
• 산업 제어 시스템(ICS) 환경
• 기밀 네트워크를 운영하는 연구 시설

​

사전 요구 사항

​

버전 요구 사항

​

SSL/TLS 요구 사항

​

하드웨어 요구 사항

​

MySQL 데이터베이스

• AWS RDS Aurora MySQL
• Google Cloud SQL for MySQL
• Azure Database for MySQL

​

Redis

• Amazon ElastiCache
• Google Cloud Memorystore
• Azure Cache for Redis
• 클라우드 또는 온프레미스 인프라에서 자체 호스팅하는 Redis

​

오브젝트 스토리지

• Amazon S3: 확장성, 데이터 가용성, 보안, 성능을 제공하는 오브젝트 스토리지 서비스입니다.
• Google Cloud Storage: 대규모 비정형 데이터를 저장하기 위한 관리형 서비스입니다.
• Azure Blob Storage: 대규모 비정형 데이터를 위한 클라우드 기반 오브젝트 스토리지입니다.
• CoreWeave AI Object Storage: AI 워크로드에 최적화된 S3 호환 오브젝트 스토리지입니다.
• MinIO Enterprise (AIStor), NetApp StorageGRID 등의 엔터프라이즈 S3 호환 저장소 또는 기타 엔터프라이즈 솔루션

​

에어갭 환경 전용 요구 사항

• 내부 컨테이너 레지스트리: 필요한 W&B 이미지가 모두 포함된 비공개 컨테이너 레지스트리(Harbor, JFrog Artifactory, Nexus 등)에 대한 액세스
• 내부 Helm 저장소: W&B Helm 차트가 포함된 비공개 Helm 차트 저장소에 대한 액세스
• 이미지 전송 수단: 인터넷에 연결된 시스템에서 에어갭 레지스트리로 컨테이너 이미지를 전송하는 방법
• 라이선스 파일: 유효한 W&B 엔터프라이즈 라이선스. 라이선스를 획득하는 방법(예: 인터넷에 연결된 머신에서 획득)은 요구 사항 페이지의 라이선스 섹션을 참조하거나 W&B 계정 팀에 문의하세요.

​

에어갭 환경 준비

​

1단계: 내부 컨테이너 레지스트리 설정

​

핵심 W&B 컴포넌트 컨테이너

• docker.io/wandb/controller: W&B Kubernetes Operator
• docker.io/wandb/local: W&B 애플리케이션 서버
• docker.io/wandb/console: W&B 관리 콘솔
• docker.io/wandb/megabinary: W&B 마이크로서비스(API, executor, glue, parquet)

​

의존성 컨테이너

• docker.io/bitnamilegacy/redis: 테스트 및 개발 환경에서 로컬 Redis를 배포할 때 필요합니다. 프로덕션 환경의 Redis 요구 사항은 사전 요구 사항의 Redis 섹션을 참조하세요.
• docker.io/otel/opentelemetry-collector-contrib: 메트릭과 로그를 수집하는 OpenTelemetry 에이전트입니다.
• quay.io/prometheus/prometheus: 메트릭 수집에 사용하는 Prometheus입니다.
• quay.io/prometheus-operator/prometheus-config-reloader: Prometheus의 의존성입니다.

​

전체 이미지 목록 조회

1. 인터넷에 연결된 시스템에서 W&B Helm 차트 저장소의 W&B Helm 차트를 다운로드하세요.
   # helm-charts 저장소 복제
   git clone https://github.com/wandb/helm-charts.git
   cd helm-charts
   
2. values.yaml 파일을 살펴보고 모든 컨테이너 이미지와 해당 버전을 파악하세요.
   # operator 차트에서 이미지 레퍼런스 추출
   helm show values charts/operator | grep -E "repository:|tag:" | grep -v "^#"
   
   # platform 차트에서 이미지 레퍼런스 추출
   helm show values charts/operator-wandb | grep -E "repository:|tag:" | grep -v "^#"
   
   또는 다음 명령으로 버전 태그를 제외한 저장소 이름만 추출할 수도 있습니다.
   helm show values charts/operator-wandb \
     | awk -F': *' '/^[[:space:]]*repository:/{print $2}' \
     | grep -v "^#" \
     | sort -u
   
   출력되는 저장소 목록은 다음과 비슷합니다.
   wandb/controller
   wandb/local
   wandb/console
   wandb/megabinary
   wandb/weave-python
   wandb/weave-trace
   otel/opentelemetry-collector-contrib
   prometheus/prometheus
   prometheus-operator/prometheus-config-reloader
   bitnamilegacy/redis
   
   각 이미지의 구체적인 버전 태그를 확인하려면 앞의 첫 번째 명령(grep -E "repository:|tag:")을 사용하세요. 이 명령은 저장소 이름과 해당 버전 태그를 함께 보여 줍니다.

​

에어갭 레지스트리로 이미지 전송

1. 인터넷에 연결된 시스템에서 필요한 이미지를 모두 pull하고 저장하세요.
   다음 예시의 버전 번호를 이전 단계에서 Helm 차트를 검사해 확인한 실제 버전으로 바꾸세요. 여기에 표시된 버전은 예시일 뿐이며, 시간이 지나면 최신 버전과 달라집니다.
   셸 변수를 사용하면 버전을 일관되게 관리할 수 있습니다.
   # 버전 변수 설정 (Helm chart 버전에 맞게 업데이트하세요)
   CONTROLLER_VERSION="1.13.3"
   APP_VERSION="0.59.2"
   CONSOLE_VERSION="2.12.2"
   
   # 이미지 pull
   docker pull wandb/controller:${CONTROLLER_VERSION}
   docker pull wandb/local:${APP_VERSION}
   docker pull wandb/console:${CONSOLE_VERSION}
   docker pull wandb/megabinary:${APP_VERSION}
   # ... 필요한 나머지 이미지도 모두 해당 버전으로 pull
   
   # 이미지를 .tar 파일로 저장
   docker save wandb/controller:${CONTROLLER_VERSION} -o wandb-controller-${CONTROLLER_VERSION}.tar
   docker save wandb/local:${APP_VERSION} -o wandb-local-${APP_VERSION}.tar
   docker save wandb/console:${CONSOLE_VERSION} -o wandb-console-${CONSOLE_VERSION}.tar
   docker save wandb/megabinary:${APP_VERSION} -o wandb-megabinary-${APP_VERSION}.tar
   # ... 나머지 이미지도 모두 저장
   
2. USB 드라이브나 보안 파일 전송 등 승인된 방법으로 .tar 파일을 에어갭 환경에 옮기세요.
3. 에어갭 환경에서 이미지를 로드한 후 내부 레지스트리로 push하세요.
   # 위에서 사용한 것과 동일한 버전 변수 설정
   CONTROLLER_VERSION="1.13.3"
   APP_VERSION="0.59.2"
   CONSOLE_VERSION="2.12.2"
   INTERNAL_REGISTRY="registry.yourdomain.com"
   
   # 이미지 로드
   docker load -i wandb-controller-${CONTROLLER_VERSION}.tar
   docker load -i wandb-local-${APP_VERSION}.tar
   docker load -i wandb-console-${CONSOLE_VERSION}.tar
   docker load -i wandb-megabinary-${APP_VERSION}.tar
   # ... 나머지 이미지도 모두 로드
   
   # 내부 레지스트리용 태그 지정
   docker tag wandb/controller:${CONTROLLER_VERSION} ${INTERNAL_REGISTRY}/wandb/controller:${CONTROLLER_VERSION}
   docker tag wandb/local:${APP_VERSION} ${INTERNAL_REGISTRY}/wandb/local:${APP_VERSION}
   docker tag wandb/console:${CONSOLE_VERSION} ${INTERNAL_REGISTRY}/wandb/console:${CONSOLE_VERSION}
   docker tag wandb/megabinary:${APP_VERSION} ${INTERNAL_REGISTRY}/wandb/megabinary:${APP_VERSION}
   # ... 나머지 이미지에도 모두 태그 지정
   
   # 내부 레지스트리로 push
   docker push ${INTERNAL_REGISTRY}/wandb/controller:${CONTROLLER_VERSION}
   docker push ${INTERNAL_REGISTRY}/wandb/local:${APP_VERSION}
   docker push ${INTERNAL_REGISTRY}/wandb/console:${CONSOLE_VERSION}
   docker push ${INTERNAL_REGISTRY}/wandb/megabinary:${APP_VERSION}
   # ... 나머지 이미지도 모두 push
   

​

2단계: 내부 Helm 차트 저장소 설정

• W&B Operator 차트
• W&B Platform 차트

1. 인터넷에 연결된 시스템에서 차트를 다운로드하세요.
   # W&B Helm 저장소 추가
   helm repo add wandb https://wandb.github.io/helm-charts
   helm repo update
   
   # 차트 다운로드
   helm pull wandb/operator --version 1.13.3
   helm pull wandb/operator-wandb --version 0.18.0
   
2. .tgz 차트 파일을 에어갭 환경으로 전송한 다음, 사내 저장소 절차에 따라 내부 Helm 저장소에 업로드하세요. operator 차트는 W&B Kubernetes Operator(Controller Manager)를 배포합니다. operator-wandb 차트는 Custom Resource(CR)에 설정된 값으로 W&B Platform을 배포합니다.

​

3단계: Helm 저장소 액세스 설정

1. 에어갭 환경에서 내부 저장소를 사용하도록 Helm을 설정하세요.
   helm repo add local-repo https://charts.yourdomain.com
   helm repo update
   
2. 차트를 사용할 수 있는지 확인하세요.
   helm search repo local-repo/operator
   helm search repo local-repo/operator-wandb
   

​

에어갭 환경에 W&B 배포하기

​

4단계: Kubernetes Operator 설치

1. 다음 내용으로 values.yaml 파일을 생성하세요.
   image:
     repository: registry.yourdomain.com/wandb/controller
     tag: 1.13.3
   
   airgapped: true
   
   repository와 tag 값을 1단계에서 내부 레지스트리로 전송한 실제 버전으로 바꾸세요. 여기에 표시된 버전(1.13.3)은 예시이며, 시간이 지나면 최신 버전과 달라질 수 있습니다.
2. operator와 CRD(Custom Resource Definition)를 설치하세요.
   helm upgrade --install operator local-repo/operator \
     --namespace wandb \
     --create-namespace \
     --values values.yaml
   
3. operator가 실행 중인지 확인하세요.
   kubectl get pods -n wandb
   
   operator 파드가 Running 상태로 표시되어야 합니다.

​

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

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

​

6단계: W&B Custom Resource 설정

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

spec:
  chart:
    url: https://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:9000
        path: wandb
        provider: s3
        region: us-east-1
      
      mysql:
        database: wandb
        host: mysql.yourdomain.com
        password: [YOUR-MYSQL-PASSWORD]
        port: 3306
        user: wandb
      
      redis:
        host: redis.yourdomain.com
        port: 6379
        password: [YOUR-REDIS-PASSWORD]
      
      api:
        enabled: true
      
      glue:
        enabled: true
      
      executor:
        enabled: true
      
      extraEnv:
        ENABLE_REGISTRY_UI: 'true'

    # 모든 컴포넌트 이미지가 내부 레지스트리를 사용하도록 설정
    app:
      image:
        repository: registry.yourdomain.com/wandb/local
        tag: 0.59.2

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

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

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

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

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

    weave:
      image:
        repository: registry.yourdomain.com/wandb/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

• settingsMigrationJob
• weave-trace
• filestream
• flat-runs-table

​

7단계: W&B Platform 배포

1. W&B Custom Resource를 적용하여 플랫폼을 배포하세요.
   kubectl apply -f wandb.yaml
   
2. 배포 진행 상황을 모니터링하세요.
   # 파드 생성 과정 확인
   kubectl get pods -n wandb --watch
   
   # 배포 상태 확인
   kubectl get weightsandbiases -n wandb
   
   # operator 로그 확인
   kubectl logs -n wandb deployment/wandb-operator-controller-manager
   
   operator가 필요한 컴포넌트를 모두 생성하는 동안 배포에 몇 분 정도 걸릴 수 있습니다.

​

OpenShift 설정

​

OpenShift 보안 컨텍스트 제약 조건

​

옵션 1: restricted SCC 사용(권장)

spec:
  values:
    # 모든 파드의 보안 컨텍스트 설정
    app:
      podSecurityContext:
        fsGroup: 1000
        runAsUser: 1000
        runAsNonRoot: true
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault

    console:
      podSecurityContext:
        fsGroup: 1000
        runAsUser: 1000
        runAsNonRoot: true
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault

    # 나머지 컴포넌트에도 동일하게 적용: api, executor, glue, parquet, weave

​

옵션 2: 맞춤형 SCC 생성(필요한 경우)

apiVersion: security.openshift.io/v1
kind: SecurityContextConstraints
metadata:
  name: wandb-scc
allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
allowPrivilegeEscalation: false
allowPrivilegedContainer: false
allowedCapabilities: []
defaultAddCapabilities: []
fsGroup:
  type: MustRunAs
  ranges:
    - min: 1000
      max: 65535
readOnlyRootFilesystem: false
requiredDropCapabilities:
  - ALL
runAsUser:
  type: MustRunAsRange
  uidRangeMin: 1000
  uidRangeMax: 65535
seLinuxContext:
  type: MustRunAs
supplementalGroups:
  type: RunAsAny
volumes:
  - configMap
  - downwardAPI
  - emptyDir
  - persistentVolumeClaim
  - projected
  - secret

1. SCC를 적용하세요.
   oc apply -f wandb-scc.yaml
   
2. W&B 서비스 계정에 SCC를 바인딩하세요.
   oc adm policy add-scc-to-user wandb-scc -z wandb-app -n wandb
   oc adm policy add-scc-to-user wandb-scc -z wandb-console -n wandb
   

​

OpenShift Route

spec:
  values:
    ingress:
      enabled: false
    
    route:
      enabled: true
      host: wandb.apps.openshift.yourdomain.com
      tls:
        enabled: true
        termination: edge
        insecureEdgeTerminationPolicy: Redirect

​

OpenShift 이미지 풀 설정

1. 이미지 풀 시크릿을 생성하세요.
   kubectl create secret docker-registry wandb-registry-secret \
     --docker-server=registry.yourdomain.com \
     --docker-username=[USERNAME] \
     --docker-password=[PASSWORD] \
     --namespace=wandb
   
2. Custom Resource에서 이 시크릿을 참조하세요.
   spec:
     values:
       imagePullSecrets:
         - name: wandb-registry-secret
   

​

OpenShift 전체 예제

apiVersion: apps.wandb.com/v1
kind: WeightsAndBiases
metadata:
  name: wandb
  namespace: wandb

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

  values:
    global:
      host: https://wandb.apps.openshift.yourdomain.com
      license: [YOUR-LICENSE]
      
      bucket:
        accessKey: [YOUR-ACCESS-KEY]
        secretKey: [YOUR-SECRET-KEY]
        name: s3.yourdomain.com:9000
        path: wandb
        provider: s3
        region: us-east-1
      
      mysql:
        database: wandb
        host: mysql.yourdomain.com
        password: [YOUR-MYSQL-PASSWORD]
        port: 3306
        user: wandb
      
      redis:
        host: redis.yourdomain.com
        port: 6379
        password: [YOUR-REDIS-PASSWORD]

    # OpenShift 전용: Ingress 대신 Routes 사용
    ingress:
      enabled: false
    
    route:
      enabled: true
      host: wandb.apps.openshift.yourdomain.com
      tls:
        enabled: true
        termination: edge

    # 내부 레지스트리용 이미지 풀 시크릿
    imagePullSecrets:
      - name: wandb-registry-secret

    # OpenShift restricted SCC용 보안 컨텍스트
    app:
      image:
        repository: registry.yourdomain.com/wandb/local
        tag: 0.59.2
      podSecurityContext:
        fsGroup: 1000
        runAsUser: 1000
        runAsNonRoot: true
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault

    console:
      image:
        repository: registry.yourdomain.com/wandb/console
        tag: 2.12.2
      podSecurityContext:
        fsGroup: 1000
        runAsUser: 1000
        runAsNonRoot: true
      securityContext:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        runAsNonRoot: true
        seccompProfile:
          type: RuntimeDefault

    # api, executor, glue, parquet, weave에도 동일한 보안 컨텍스트 적용
    # (간결성을 위해 생략)

​

설치 확인

1. W&B CLI 설치:
   pip install wandb
   
2. W&B에 로그인:
   wandb login --host=https://YOUR_DNS_DOMAIN
   
   예시:
   wandb login --host=https://wandb.company-name.com
   
3. 설치 확인:
   wandb verify
   

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

​

에어갭 환경 추가 확인

1. 이미지 풀: 모든 파드가 내부 레지스트리에서 이미지를 정상적으로 가져왔는지 확인하세요.
   kubectl get pods -n wandb -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\t"}{.status.containerStatuses[*].image}{"\n"}{end}'
   
   모든 이미지가 내부 레지스트리를 가리키고, 모든 파드가 Running 상태여야 합니다.
2. 외부 연결: W&B가 외부 연결을 시도하지 않는지 확인하세요. 에어갭 모드에서는 외부 연결을 시도하지 않아야 합니다.
   kubectl logs -n wandb deployment/wandb-app --tail=100 | grep -i "connection"
   
3. 라이선스 검증: W&B Console에 액세스하여 라이선스가 활성 상태인지 확인하세요.

​

문제 해결

​

이미지 풀 오류

• 내부 레지스트리에 이미지가 있는지 확인하세요.
• 이미지 풀 시크릿이 올바르게 설정되어 있는지 확인하세요.
• Kubernetes 노드에서 레지스트리로 네트워크 연결이 가능한지 확인하세요.
• 레지스트리 인증 자격 증명을 확인하세요.

kubectl run test-pull --image=registry.yourdomain.com/wandb/local:0.59.2 --namespace=wandb
kubectl logs test-pull -n wandb
kubectl delete pod test-pull -n wandb

​

OpenShift SCC 오류

# 사용 중인 SCC 확인
oc get pod [POD-NAME] -n wandb -o yaml | grep scc

# 서비스 계정 권한 확인
oc describe scc wandb-scc
oc get rolebinding -n wandb

​

Helm 차트를 찾을 수 없음

• Custom Resource에 지정된 차트 저장소 URL을 확인하세요.
• operator 파드가 내부 Helm 저장소에 연결할 수 있는지 확인하세요.
• 저장소에 차트가 있는지 확인하세요.
  helm search repo local-repo/operator-wandb
  

​

자주 묻는 질문

​

다른 ingress 클래스를 사용할 수 있나요?

spec:
  values:
    ingress:
      class: your-ingress-class

​

여러 인증서가 포함된 인증서 번들은 어떻게 처리하나요?

spec:
  values:
    customCACerts:
      cert1.crt: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----
      cert2.crt: |
        -----BEGIN CERTIFICATE-----
        ...
        -----END CERTIFICATE-----

​

자동 업데이트를 방지하려면 어떻게 해야 하나요?

• operator 설치 시 airgapped: true를 설정하세요(자동 업데이트 확인이 비활성화됩니다).
• Custom Resource의 spec.chart.version을 직접 수정하여 버전 업데이트를 관리하세요.
• 필요한 경우 W&B System Console에서 자동 업데이트를 비활성화할 수도 있습니다.

​

공개 저장소에 연결하지 않아도 배포가 작동하나요?

​

에어갭 환경에서 W&B를 업데이트하려면 어떻게 하나요?

1. 인터넷에 연결된 시스템에서 새 컨테이너 이미지를 pull하세요.
2. 이미지를 에어갭 레지스트리로 전송하세요.
3. 새 Helm 차트를 내부 저장소에 업로드하세요.
4. Custom Resource에서 spec.chart.version과 이미지 태그를 업데이트하세요.
5. 업데이트한 Custom Resource를 적용하세요. 그러면 operator가 W&B 컴포넌트를 롤링 업데이트합니다.

​

다음 단계

• 사용자 인증 설정: SSO 또는 기타 인증 방법을 설정하세요.
• 모니터링 설정: W&B 인스턴스와 인프라에 대한 모니터링을 설정하세요.
• 업데이트 계획 수립: Server 업그레이드 프로세스를 검토하고 업데이트 주기를 정하세요.
• 백업 설정: MySQL 데이터베이스 백업 절차를 마련하세요.
• 프로세스 문서화: 에어갭 환경에 맞는 업데이트 절차를 런북으로 작성하세요.

​

도움 받기

• 인프라 관련 안내는 레퍼런스 아키텍처를 참조하세요.
• 설정에 대한 자세한 내용은 Operator 가이드를 확인하세요.
• W&B 지원팀 또는 담당 W&B 지원 엔지니어에게 문의하세요.
• OpenShift 관련 문제는 Red Hat OpenShift 문서를 참조하세요.