[GPU] KubeRay Operator란? 🚀

 

 

 

KubeRay Operator란? 🚀

Kubernetes에서 Ray 클러스터를 쉽게 운영하는 방법

AI/ML 인프라를 운영하다 보면 여러 대의 서버, 특히 GPU 서버를 묶어서 분산 학습이나 분산 추론을 수행해야 하는 경우가 많습니다. 이때 많이 사용되는 프레임워크 중 하나가 바로 Ray입니다.

그런데 Ray를 Kubernetes 환경에서 직접 운영하려면 Head Node, Worker Node, Service, Job, Autoscaling, 장애 복구 등을 직접 구성해야 합니다. 이 작업은 생각보다 복잡합니다.

이 문제를 해결하기 위해 나온 것이 바로 KubeRay Operator입니다. 🚀

---

1. KubeRay Operator란? 🤔

KubeRay Operator는 Kubernetes 환경에서 Ray 클러스터를 자동으로 생성하고 관리해주는 Operator입니다.

쉽게 말하면 다음과 같습니다.

KubeRay Operator = Kubernetes 위에서 Ray 클러스터를 쉽게 만들고 운영하게 해주는 관리자 프로그램

KubeRay Operator를 사용하면 사용자는 복잡한 Kubernetes 리소스를 하나하나 만들 필요 없이 RayCluster, RayJob, RayService 같은 리소스만 정의하면 됩니다.

그러면 KubeRay Operator가 이를 감지해서 Ray Head Pod, Worker Pod, Service 등을 자동으로 생성하고 관리합니다.

---

2. 먼저 Ray가 뭐야? 🧠

Ray는 Python 기반의 분산 컴퓨팅 프레임워크입니다.

여러 대의 서버나 여러 개의 GPU를 묶어서 하나의 큰 컴퓨팅 환경처럼 사용할 수 있게 도와줍니다.

Ray는 주로 다음과 같은 작업에 사용됩니다.

용도설명

분산 학습	여러 GPU를 사용해 AI 모델 학습
분산 추론	여러 서버에서 모델 추론 처리
LLM 서빙	대규모 언어모델 추론 서비스
강화학습	RLlib 기반 학습
하이퍼파라미터 튜닝	Ray Tune 사용
데이터 처리	Ray Data 기반 대규모 데이터 처리
모델 서빙	Ray Serve 기반 API 서비스

즉, Ray는 AI/ML 작업을 여러 서버와 GPU에 나눠서 처리할 수 있게 해주는 분산 처리 프레임워크입니다.

---

3. KubeRay Operator가 필요한 이유 ⚙️

Ray 클러스터는 보통 다음과 같은 구조를 가집니다.

Ray Head Node
 ├─ Ray Worker Node 1
 ├─ Ray Worker Node 2
 ├─ Ray Worker Node 3
 └─ Ray Worker Node N

여기서 Head Node는 클러스터의 중심 역할을 하고, Worker Node는 실제 연산을 수행합니다.

Kubernetes에서 이 구조를 직접 만들려면 다음 작업이 필요합니다.

- Head Pod 생성
- Worker Pod 생성
- Service 생성
- Dashboard 포트 구성
- Worker 수 조정
- 장애 발생 시 재시작 처리
- Job 제출 방식 구성
- 모델 서빙 구성

운영자가 이걸 모두 직접 관리하면 번거롭고 실수도 생기기 쉽습니다.

KubeRay Operator는 이 과정을 자동화합니다.

사용자 RayCluster YAML 작성
        ↓
Kubernetes에 적용
        ↓
KubeRay Operator가 감지
        ↓
Ray Head / Worker / Service 자동 생성
        ↓
Ray 클러스터 실행

---

4. KubeRay의 핵심 리소스 📦

KubeRay는 Kubernetes의 CRD(Custom Resource Definition) 를 사용합니다.

CRD는 쉽게 말해 Kubernetes에 새로운 리소스 타입을 추가하는 기능입니다.

KubeRay에서 주로 사용하는 리소스는 다음과 같습니다.

리소스	역할
RayCluster	Ray 클러스터 생성 및 관리
RayJob	Ray 작업 실행
RayService	Ray Serve 기반 모델 서빙
RayCronJob	주기적인 Ray 작업 실행

---

5. RayCluster란? 🏗️

RayCluster는 Ray 클러스터 자체를 정의하는 리소스입니다.

예를 들어 다음과 같은 내용을 정의할 수 있습니다.

- Ray 버전
- Head Pod 설정
- Worker Pod 개수
- CPU / Memory / GPU 자원
- Autoscaling 설정
- Pod image
- Dashboard 설정

예시 YAML은 다음과 같습니다.

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  name: raycluster-sample
spec:
  rayVersion: "2.9.0"
  headGroupSpec:
    rayStartParams:
      dashboard-host: "0.0.0.0"
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.9.0
          resources:
            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.9.0
          resources:
            limits:
              cpu: "4"
              memory: "8Gi"

이 YAML을 Kubernetes에 적용하면 KubeRay Operator가 Ray Head Pod와 Worker Pod를 생성합니다.

---

6. RayJob이란? 🧾

RayJob은 Ray 클러스터에서 특정 작업을 실행하기 위한 리소스입니다.

예를 들어 Python 학습 스크립트를 Ray 클러스터에서 실행하고 싶을 때 사용할 수 있습니다.

RayJob은 다음과 같은 흐름으로 동작합니다.

RayJob 생성
   ↓
KubeRay Operator가 RayCluster 생성
   ↓
Ray 클러스터 준비 완료
   ↓
Job 제출
   ↓
작업 실행
   ↓
필요 시 클러스터 삭제

운영 관점에서는 일회성 학습 작업, 배치 작업, 분산 처리 작업에 적합합니다.

---

7. RayService란? 🌐

RayService는 Ray Serve를 사용해서 모델 서빙을 운영할 때 사용하는 리소스입니다.

예를 들어 LLM, 이미지 모델, 추천 모델 등을 API 형태로 서비스하고 싶을 때 사용할 수 있습니다.

RayService는 다음과 같은 목적에 적합합니다.

- 모델 추론 API 운영
- Ray Serve 배포
- 무중단 업그레이드
- 장기 실행 서비스
- 고가용성 모델 서빙

즉, RayJob이 일회성 작업에 가깝다면, RayService는 계속 실행되는 서비스형 워크로드에 가깝습니다.

---

8. KubeRay Operator는 소프트웨어야? 💿

네. KubeRay Operator는 소프트웨어입니다.

정확히 말하면 Kubernetes 안에서 실행되는 컨트롤러 프로그램입니다.

설치하면 보통 다음과 같은 Pod가 생성됩니다.

kubectl get pods -n kuberay-system

예상 형태는 다음과 비슷합니다.

NAME                                READY   STATUS    RESTARTS   AGE
kuberay-operator-xxxxxxxxxx-xxxxx   1/1     Running   0          1m

이 Operator Pod가 Kubernetes API를 계속 감시하면서 RayCluster, RayJob, RayService 리소스를 관리합니다.

---

9. KubeRay는 오픈소스야? 🔓

네. KubeRay는 오픈소스입니다.

GitHub에서 공개되어 있으며, 누구나 코드를 확인하고 사용할 수 있습니다.

KubeRay는 Ray 프로젝트와 함께 Kubernetes 환경에서 Ray 애플리케이션을 운영하기 위한 공식적인 도구로 사용됩니다.

운영자 입장에서 장점은 다음과 같습니다.

- 소스코드 확인 가능
- Helm Chart 제공
- Kubernetes 표준 방식으로 설치 가능
- CRD 기반 운영 가능
- RayCluster / RayJob / RayService 지원
- GPU 기반 AI/ML 워크로드에 적합

---

 

KubeRay Operator 설치 방법 🛠️

1. 사전 준비 사항

KubeRay Operator를 설치하려면 기본적으로 다음이 필요합니다.

- Kubernetes Cluster
- kubectl
- Helm
- Ray workload를 실행할 Node
- GPU 사용 시 NVIDIA Device Plugin 또는 GPU Operator

GPU 환경에서 사용할 경우 Kubernetes에서 GPU 리소스가 보여야 합니다.

kubectl describe nodes | grep nvidia.com/gpu

또는 다음 명령어로 확인할 수 있습니다.

kubectl get nodes -o json | grep nvidia.com/gpu

GPU가 정상적으로 인식되면 Pod에서 다음과 같은 리소스를 요청할 수 있습니다.

resources:
  limits:
    nvidia.com/gpu: 1

---

2. Helm Repo 추가

KubeRay Operator는 Helm Chart로 설치하는 방식이 가장 간단합니다.

helm repo add kuberay https://ray-project.github.io/kuberay-helm/
helm repo update

---

3. KubeRay Operator 설치

별도 namespace를 만들어 설치하는 것을 권장합니다.

kubectl create namespace kuberay-system

그 다음 Helm으로 Operator를 설치합니다.

helm install kuberay-operator kuberay/kuberay-operator \
  --namespace kuberay-system

설치 후 Pod 상태를 확인합니다.

kubectl get pods -n kuberay-system

정상 상태라면 다음과 비슷하게 보입니다.

NAME                                READY   STATUS    RESTARTS   AGE
kuberay-operator-xxxxxxxxxx-xxxxx   1/1     Running   0          1m

---

4. CRD 설치 확인

KubeRay Operator를 설치하면 Ray 관련 CRD가 함께 설치됩니다.

확인 명령어는 다음과 같습니다.

kubectl get crd | grep ray

예상 결과는 다음과 비슷합니다.

rayclusters.ray.io
rayjobs.ray.io
rayservices.ray.io
raycronjobs.ray.io

CRD가 보인다면 Kubernetes가 Ray 관련 리소스를 이해할 수 있는 상태입니다.

---

 

KubeRay 사용법 🚀

1. RayCluster 생성

간단한 RayCluster YAML을 작성합니다.

파일명은 예를 들어 raycluster-sample.yaml로 만들 수 있습니다.

apiVersion: ray.io/v1
kind: RayCluster
metadata:
  name: raycluster-sample
spec:
  rayVersion: "2.9.0"

  headGroupSpec:
    rayStartParams:
      dashboard-host: "0.0.0.0"
    template:
      spec:
        containers:
        - name: ray-head
          image: rayproject/ray:2.9.0
          ports:
          - containerPort: 6379
            name: gcs-server
          - containerPort: 8265
            name: dashboard
          - containerPort: 10001
            name: client
          resources:
            limits:
              cpu: "2"
              memory: "4Gi"
            requests:
              cpu: "1"
              memory: "2Gi"

  workerGroupSpecs:
  - groupName: worker-group
    replicas: 2
    minReplicas: 1
    maxReplicas: 3
    rayStartParams: {}
    template:
      spec:
        containers:
        - name: ray-worker
          image: rayproject/ray:2.9.0
          resources:
            limits:
              cpu: "4"
              memory: "8Gi"
            requests:
              cpu: "2"
              memory: "4Gi"

적용합니다.

kubectl apply -f raycluster-sample.yaml

상태 확인은 다음 명령어를 사용합니다.

kubectl get raycluster
kubectl get pods

---

2. Ray Dashboard 접속

Ray Dashboard는 기본적으로 Head Pod의 8265 포트를 사용합니다.

포트포워딩을 실행합니다.

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

브라우저에서 접속합니다.

http://localhost:8265

Dashboard에서는 다음 정보를 확인할 수 있습니다.

- Ray 클러스터 상태
- Node 상태
- Worker 상태
- Job 상태
- Task 상태
- 리소스 사용량

---

3. GPU Worker 구성 예시

GPU 서버에서 Ray Worker를 실행하려면 Worker Pod에 GPU 리소스를 요청하면 됩니다.

workerGroupSpecs:
- groupName: gpu-worker
  replicas: 2
  minReplicas: 1
  maxReplicas: 4
  rayStartParams: {}
  template:
    spec:
      containers:
      - name: ray-worker
        image: rayproject/ray:2.9.0
        resources:
          limits:
            cpu: "8"
            memory: "32Gi"
            nvidia.com/gpu: 1
          requests:
            cpu: "4"
            memory: "16Gi"
            nvidia.com/gpu: 1

이 설정은 Worker Pod 하나당 GPU 1장을 사용한다는 의미입니다.

GPU 서버 2대에 Worker Pod가 배치되면 총 GPU 2장을 Ray 클러스터에서 사용할 수 있습니다.

---

4. RayJob 사용 예시

RayJob은 Ray 작업을 Kubernetes 리소스로 실행할 때 사용합니다.

예시 YAML은 다음과 같습니다.

apiVersion: ray.io/v1
kind: RayJob
metadata:
  name: rayjob-sample
spec:
  entrypoint: python /home/ray/samples/sample_code.py
  shutdownAfterJobFinishes: true

  rayClusterSpec:
    rayVersion: "2.9.0"

    headGroupSpec:
      rayStartParams:
        dashboard-host: "0.0.0.0"
      template:
        spec:
          containers:
          - name: ray-head
            image: rayproject/ray:2.9.0
            resources:
              limits:
                cpu: "2"
                memory: "4Gi"

    workerGroupSpecs:
    - groupName: worker-group
      replicas: 2
      rayStartParams: {}
      template:
        spec:
          containers:
          - name: ray-worker
            image: rayproject/ray:2.9.0
            resources:
              limits:
                cpu: "4"
                memory: "8Gi"

적용합니다.

kubectl apply -f rayjob-sample.yaml

상태 확인은 다음과 같습니다.

kubectl get rayjob
kubectl describe rayjob rayjob-sample
kubectl get pods

---

5. RayService 사용 예시

RayService는 Ray Serve 기반의 모델 서빙에 사용합니다.

주로 다음과 같은 상황에서 적합합니다.

- 모델 API 서버 운영
- LLM 추론 서비스 운영
- 무중단 배포 필요
- 장기 실행 서비스 필요

상태 확인 명령어는 다음과 같습니다.

kubectl get rayservice
kubectl describe rayservice <rayservice-name>

RayService를 사용하면 Ray Serve 애플리케이션을 Kubernetes 리소스처럼 관리할 수 있습니다.

---

 

운영자가 자주 쓰는 명령어 모음 🧰

Operator 상태 확인

kubectl get pods -n kuberay-system

CRD 확인

kubectl get crd | grep ray

RayCluster 확인

kubectl get raycluster
kubectl describe raycluster raycluster-sample

RayJob 확인

kubectl get rayjob
kubectl describe rayjob rayjob-sample

RayService 확인

kubectl get rayservice

Pod 확인

kubectl get pods -o wide

로그 확인

kubectl logs -n kuberay-system deploy/kuberay-operator

Head Pod 로그 확인 예시는 다음과 같습니다.

kubectl logs <ray-head-pod-name>

Worker Pod 로그 확인 예시는 다음과 같습니다.

kubectl logs <ray-worker-pod-name>

---

 

KubeRay Operator 삭제 방법 🧹

Operator를 삭제하려면 Helm으로 제거합니다.

helm uninstall kuberay-operator -n kuberay-system

namespace까지 삭제하려면 다음 명령어를 사용합니다.

kubectl delete namespace kuberay-system

RayCluster 리소스도 삭제하려면 다음과 같이 실행합니다.

kubectl delete raycluster raycluster-sample

모든 RayCluster를 삭제하려면 다음 명령어를 사용할 수 있습니다.

kubectl delete raycluster --all

---

 

KubeRay Operator의 장점 ✅

KubeRay Operator를 사용하면 다음과 같은 장점이 있습니다.

장점	설명
Ray 클러스터 자동 생성	Head / Worker Pod를 자동 구성
Kubernetes 친화적	YAML 기반 선언형 관리
GPU 활용 가능	nvidia.com/gpu 리소스 요청 가능
Autoscaling 지원	Worker 수 자동 조정 가능
Job 실행 지원	RayJob으로 배치 작업 실행
모델 서빙 지원	RayService로 Ray Serve 운영
운영 자동화	장애 복구, 재시작, 상태 관리 가능
오픈소스	GitHub 기반 공개 프로젝트

---

 

GPUaaS 환경에서 KubeRay는 유용할까? 🎯

GPUaaS 환경에서는 KubeRay가 매우 유용할 수 있습니다.

예를 들어 사용자가 다음과 같이 요청한다고 가정해보겠습니다.

GPU 4장짜리 Ray 클러스터 하나 주세요.

운영자는 내부적으로 다음과 같은 RayCluster를 생성할 수 있습니다.

RayCluster
 ├─ Head Pod: CPU 중심
 └─ Worker Pod 4개: 각 GPU 1장 사용

또는 Worker Pod 하나에 GPU 여러 장을 할당할 수도 있습니다.

resources:
  limits:
    nvidia.com/gpu: 4

이런 방식으로 사용자별, 팀별, 프로젝트별 Ray 클러스터를 Kubernetes 위에서 제공할 수 있습니다.

---

 

KubeRay를 사용할 때 주의할 점 ⚠️

KubeRay가 편리하긴 하지만 운영 환경에서는 다음 사항을 반드시 확인해야 합니다.

1. GPU Plugin 구성

GPU를 사용하려면 Kubernetes Node에서 GPU 리소스가 정상적으로 보여야 합니다.

kubectl describe node <node-name> | grep nvidia.com/gpu

GPU 리소스가 보이지 않으면 NVIDIA Device Plugin 또는 GPU Operator 구성이 필요합니다.

---

2. 이미지 버전 관리

Ray 버전과 Docker image 버전을 맞추는 것이 중요합니다.

예를 들어 rayVersion은 2.9.0인데 image는 2.6.0이면 예상치 못한 문제가 생길 수 있습니다.

rayVersion: "2.9.0"
image: rayproject/ray:2.9.0

---

3. Namespace 분리

운영 환경에서는 사용자나 팀별로 namespace를 분리하는 것이 좋습니다.

team-a-ray
team-b-ray
team-c-ray

이렇게 구성하면 리소스 quota, RBAC, 네트워크 정책을 분리하기 쉽습니다.

---

4. 리소스 제한 설정

CPU, Memory, GPU 요청값을 명확히 지정해야 합니다.

resources:
  requests:
    cpu: "4"
    memory: "16Gi"
    nvidia.com/gpu: 1
  limits:
    cpu: "8"
    memory: "32Gi"
    nvidia.com/gpu: 1

리소스 제한이 없으면 특정 Ray 작업이 노드 리소스를 과도하게 사용할 수 있습니다.

---

5. 모니터링 구성

운영 환경에서는 다음 모니터링이 필요합니다.

- Ray Dashboard
- Kubernetes Pod 상태
- GPU 사용률
- GPU Memory 사용량
- Worker Pod 재시작 횟수
- RayJob 성공/실패 상태
- Node 장애 여부

GPU 환경이라면 DCGM Exporter, Prometheus, Grafana와 함께 구성하면 좋습니다.

---

 

한 줄 요약 📝

KubeRay Operator는 Kubernetes에서 Ray 클러스터를 쉽게 생성하고 운영하게 해주는 오픈소스 Operator입니다.

AI/ML, 분산 학습, LLM 추론, Ray Serve 기반 모델 서빙을 Kubernetes 위에서 운영하려는 환경이라면 KubeRay는 매우 유용한 선택지가 될 수 있습니다.

특히 GPUaaS나 Kubernetes 기반 AI 플랫폼을 운영하는 경우, KubeRay를 사용하면 사용자별 Ray 클러스터 제공, GPU 자원 할당, Job 실행, 모델 서빙까지 Kubernetes 방식으로 관리할 수 있습니다. 🚀