KubeRay 정리 - Kubernetes 위에서 분산 학습/추론을 돌리는 Ray Operator

OpenShift 4.20 등에서 AI 워크로드 기본 지원이 강화되면서 함께 자주 언급되는 KubeRay(Ray on Kubernetes)의 개념, 핵심 CRD, 적용 시 이점, 설치 방법, 실제 예시를 정리합니다.

KubeRay란

Ray는 파이썬 기반 분산 컴퓨팅 프레임워크로, 분산 학습·하이퍼파라미터 튜닝·배치/온라인 추론 등 대규모 병렬 워크로드를 손쉽게 여러 노드에 흩뿌려 실행할 수 있게 해줍니다. KubeRay는 이 Ray 클러스터를 쿠버네티스 네이티브 방식(CRD + Operator)으로 생성·관리·오토스케일링해주는 오픈소스 오퍼레이터입니다. MIG로 GPU를 잘게 쪼갰다면, 그 위에서 실제 분산 학습/추론 작업을 돌리는 계층이 바로 이 KubeRay라고 보면 됩니다.

핵심 CRD 3종

CRD	역할
RayCluster	Ray 클러스터의 생성/삭제, 오토스케일링, 장애 복구까지 생명주기 전체를 관리
RayJob	RayCluster를 자동으로 만들고 클러스터가 준비되면 작업을 제출. 작업이 끝나면 클러스터를 자동 삭제하도록 설정 가능
RayService	RayCluster + Ray Serve 배포로 구성되며, 무중단(zero-downtime) 업그레이드와 고가용성을 제공하는 서빙 전용 리소스

KubeRay를 적용했을 때의 이점

Ray 클러스터를 VM이나 베어메탈에 직접 구성하는 방식과 비교하면, KubeRay를 쓸 때 얻는 이점은 크게 다음과 같습니다.

이점	설명
쿠버네티스 네이티브 라이프사이클 관리	RayCluster/RayJob/RayService가 CRD이므로 kubectl, ArgoCD/Flux 등 GitOps 도구로 나머지 워크로드와 동일하게 관리 가능. 별도 프로비저닝 스크립트나 클러스터 관리 툴이 불필요
비용 절감형 오토스케일링	워커 그룹의 minReplicas/maxReplicas가 K8s 노드 오토스케일러(Karpenter, cluster-autoscaler 등)와 맞물려 동작. 유휴 시 워커 파드는 물론 실제 GPU 노드까지 반납되어 비용이 줄어듦
멀티테넌시 기본 제공	여러 팀의 Ray 클러스터를 네임스페이스로 나눠 같은 클러스터에 올릴 수 있고, 기존 RBAC/ResourceQuota/NetworkPolicy가 그대로 적용됨
RayService의 무중단 배포	서빙 모델을 새 버전으로 교체할 때 블루/그린 방식으로 트래픽을 전환해 요청 유실 없이 업그레이드 가능
RayJob의 완전 자동화된 배치 작업	학습 작업을 위해 클러스터를 자동 생성 → 제출 → 완료 후 자동 삭제까지 가능해 일회성 작업에 인프라를 계속 띄워둘 필요가 없음
기존 K8s 생태계 재사용	Prometheus/Grafana, Kueue/Volcano, GPU 디바이스 플러그인(MIG 포함)이 다른 워크로드와 동일한 방식으로 연동됨. OpenShift/순정 K8s 어디서든 같은 매니페스트가 동작해 특정 벤더에 종속되지 않음

한 줄로 요약하면, Ray 자체의 분산 컴퓨팅 능력은 그대로 가져가면서 클러스터 운영·확장·배포·관측은 이미 익숙한 쿠버네티스 방식으로 처리할 수 있다는 것이 핵심입니다.

아키텍처 - Head 노드 vs Worker 노드

Ray 클러스터는 Head 파드 1개와 다수의 Worker 파드로 구성됩니다. Head는 클러스터 전체를 조율하고 대시보드(기본 포트 8265)를 제공하며, Worker는 Head가 분배한 실제 분산 작업을 수행합니다. RayCluster 리소스는 headGroupSpec과 workerGroupSpecs로 이 둘을 각각 정의합니다.

설치

helm repo add kuberay https://ray-project.github.io/kuberay-helm/
helm repo update
helm install kuberay-operator kuberay/kuberay-operator --version 1.7.0

최소 RayCluster 예시

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  name: raycluster-sample
spec:
  headGroupSpec:
    rayStartParams: {}
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.58.0
          resources:
            requests:
              cpu: "2"
              memory: "4Gi"
            limits:
              cpu: "2"
              memory: "4Gi"
  workerGroupSpecs:
  - groupName: worker-group
    replicas: 2
    minReplicas: 1
    maxReplicas: 5
    rayStartParams: {}
    template:
      spec:
        containers:
        - name: ray-worker
          image: rayproject/ray:2.58.0
          resources:
            requests:
              cpu: "2"
              memory: "4Gi"
              nvidia.com/gpu: "1"
            limits:
              cpu: "2"
              memory: "4Gi"
              nvidia.com/gpu: "1"

Job 제출

Head 파드에 직접 들어가지 않고, 대시보드 포트를 포워딩한 뒤 Ray Job Submission SDK로 제출하는 방식이 권장됩니다.

kubectl port-forward service/raycluster-sample-head-svc 8265:8265 &

ray job submit --address http://localhost:8265 \
  -- python -c "import ray; ray.init(); print(ray.cluster_resources())"

주요 활용 사례

• Llama, DeepSeek, Mistral 등 오픈웨이트 LLM의 분산 파인튜닝
• 대규모 하이퍼파라미터 튜닝 (Ray Tune)
• 배치 추론 및 RayService를 통한 온라인 모델 서빙

참고사항

• 참고: KubeRay는 OpenShift와 순정 Kubernetes에서 동일하게 동작하며, OpenShift 전용 기능이 아니라 CNCF 생태계의 범용 오퍼레이터입니다.
• 참고: worker 파드의 리소스 요청에 nvidia.com/gpu를 넣으면, MIG로 분할한 nvidia.com/mig-2g.10gb 같은 리소스명도 동일하게 요청할 수 있어 GPU 파티셔닝과 자연스럽게 조합됩니다.
• 참고: Prometheus/Grafana 같은 관측 도구, Kueue/Volcano 같은 큐잉 시스템과도 통합되므로 멀티테넌트 클러스터에서 리소스 경합을 관리하기 좋습니다.
• 주의: minReplicas/maxReplicas로 오토스케일링을 켜두면 유휴 GPU 워커가 자동으로 스케일다운되지만, 이 과정에서 실행 중이던 태스크가 재스케줄링될 수 있으므로 장시간 학습 작업에는 체크포인트 전략을 함께 고려해야 합니다.
• 참고 문서: Ray on Kubernetes (Ray 공식 문서)
• 참고 문서: ray-project/kuberay (GitHub)