워크로드 API

워크로드 API (Workload API)

Workload API 리소스는 다중 파드 애플리케이션의 스케줄링 요구 사항과 구조를 정의해요. Job 같은 워크로드 컨트롤러가 애플리케이션의 런타임 상태를 관리하는 반면, Workload는 파드 그룹이 어떻게 스케줄링되어야 하는지 지정해요. Job 컨트롤러는 런타임에 Workload의 PodGroupTemplates에서 PodGroup 객체를 생성하는 유일한 내장 컨트롤러예요.

출처: 문서

본문

Workload란 무엇인가?

Workload API 리소스는 scheduling.k8s.io/v1beta1 API 그룹의 일부이며, 이 API를 사용하려면 클러스터에 그 API 그룹과 GenericWorkload 기능 게이트가 둘 다 활성화되어 있어야 해요.

Workload는 정적이고 수명이 긴 정책 템플릿(policy template)이에요. 파드 그룹에 어떤 스케줄링 정책을 적용해야 하는지 정의하지만, 런타임 상태 자체는 추적하지 않아요. 런타임 스케줄링 상태는 컨트롤러가 Workload의 PodGroupTemplates에서 생성하는 PodGroup 객체가 유지해요.

API 구조 (API structure)

Workload는 두 필드로 구성돼요. PodGroupTemplates 목록과 선택적 컨트롤러 참조(controller reference)예요. Workload 사양 전체는 생성 후 변경할 수 없어요. 즉 기존 템플릿을 수정하거나, 새 템플릿을 추가하거나, podGroupTemplates에서 템플릿을 제거할 수 없어요.

PodGroupTemplates

spec.podGroupTemplates 목록은 워크로드의 서로 다른 컴포넌트를 정의해요. 예를 들어 머신러닝 작업에는 드라이버 템플릿과 워커 템플릿이 있을 수 있어요.

podGroupTemplates의 각 항목은 반드시 가져야 하는 것:

PodGroup의 spec.podGroupTemplateRef에서 템플릿을 참조하는 데 사용할 고유 이름
스케줄링 정책(basic 또는 gang)

각 항목은 우선순위와 중단 모드(disruption mode) 필드도 가질 수 있어요.

단일 Workload의 PodGroupTemplates 최대 개수는 8개예요.

apiVersion: scheduling.k8s.io/v1beta1
kind: Workload
metadata:
  name: training-job-workload
  namespace: some-ns
spec:
  controllerRef:
    apiGroup: batch
    kind: Job
    name: training-job
  podGroupTemplates:
  - name: workers
    schedulingPolicy:
      gang:
        # The gang is schedulable only if 4 pods can run at once
        minCount: 4
    priorityClassName: high-priority
    disruptionMode:
      all: {}

워크로드 컨트롤러가 이 템플릿 중 하나에서 PodGroup을 만들면 schedulingPolicy를 PodGroup의 자체 spec에 복사해요. Workload 변경은 기존 PodGroup이 아니라 새로 생성되는 PodGroup에만 영향을 미쳐요.

워크로드 제어 객체 참조

controllerRef 필드는 Workload를 Job이나 커스텀 CRD 같은 특정 상위 수준 객체에 연결해요. 관찰성(observability)과 도구에 유용해요. 이 데이터는 Workload를 스케줄링하거나 관리하는 데는 사용되지 않아요.

CompositePodGroupTemplates

CompositePodGroup 기능 게이트와 scheduling.k8s.io/v1alpha3 API 그룹이 활성화되면, CompositePodGroupTemplates를 사용해 Workload에서 다중 레벨의 계층적 스케줄링 요구 사항을 정의할 수 있어요. 이런 요구 사항에는 클러스터 인프라의 서로 다른 계층에 걸쳐 중첩된 토폴로지 제약 강제(다중 레벨 토폴로지 인식 스케줄링), 하위 그룹 간 전부-또는-전무 스케줄링(다중 레벨 gang 스케줄링), 그룹 수준 중단 정책 등이 포함될 수 있어요.

CompositePodGroupTemplates는 Workload API의 spec.compositePodGroupTemplates 필드로 정의할 수 있어요. 런타임에 워크로드 컨트롤러가 이 템플릿에서 CompositePodGroup과 PodGroup 객체를 생성해 계층 구조의 런타임 스케줄링 상태를 유지해요. PodGroup 객체는 잎(leaf)에서 파드 그룹을 관리하는 반면, CompositePodGroup 객체는 하위 그룹 간에 스케줄링 정책을 강제하는 비잎(non-leaf) 그룹을 나타내요.

구조와 제약

spec.compositePodGroupTemplates 필드는 그룹-템플릿 계층 트리에서 비잎 템플릿을 정의해요. 각 항목은 CompositePodGroup용 템플릿을 나타내며 다음을 포함할 수 있어요.

하위 템플릿: 중첩된 CompositePodGroupTemplates(중간 비잎 그룹용) 또는 PodGroupTemplates(파드를 포함한 잎 그룹용)
스케줄링 정책: 이 복합 그룹 안의 하위 그룹이 어떻게 스케줄링되는지 지정. basic: 하위 그룹이 독립적으로 승인·스케줄링됨. gang: 하위 그룹 간 다중 레벨 전부-또는-전무 스케줄링 강제. 복합 그룹이 실현 가능하려면 동시에 스케줄링 가능해야 하는 하위 그룹의 최소 수를 지정하는 minGroupCount가 필요
스케줄링 제약: 다중 레벨 토폴로지 인식 스케줄링을 위한 선택적 토폴로지 제약
우선순위, 선점 정책, 중단 모드: 선택적 priorityClassName, disruptionMode(Single 또는 All), preemptionPolicy — 워크로드 인식 선점용

클러스터 안정성과 컨트롤 플레인 효율성을 보장하기 위해 그룹-템플릿 계층 구조는 다음 제한을 적용해요.

최대 중첩 깊이: 그룹-템플릿 계층 구조는 최대 깊이 4레벨 지원
목록 제한: 모든 compositePodGroupTemplates와 podGroupTemplates 목록은 최대 8개 항목으로 엄격히 제한

예시

다음 예시는 두 하위 PodGroup 템플릿(minGroupCount: 2) 간에 gang 스케줄링을 강제하는 CompositePodGroup 템플릿이 있는 계층적 Workload를 정의하며, 각각 자체 gang 스케줄링 정책을 지정해요.

apiVersion: scheduling.k8s.io/v1alpha3
kind: Workload
metadata:
  name: gang-of-gangs-workload
  namespace: default
spec:
  compositePodGroupTemplates:
  - name: root
    schedulingPolicy:
      gang:
        # Requires both child PodGroups to be schedulable together
        minGroupCount: 2
    podGroupTemplates:
    - name: workers-a
      schedulingPolicy:
        gang:
          # Requires 4 Pods in this group to be schedulable
          minCount: 4
    - name: workers-b
      schedulingPolicy:
        gang:
          # Requires 4 Pods in this group to be schedulable
          minCount: 4

Job과 함께하는 gang 스케줄링

WorkloadWithJob 기능 게이트가 활성화되면, Job 컨트롤러는 파드를 만들기 전에 Job의 .spec.scheduling 구성을 Workload와 PodGroup 객체로 컴파일해요. Job에 .spec.scheduling.schedulingPolicy.gang을 설정해 gang 스케줄링을 선택하는데, gang.minCount를 생략하면 Job의 .spec.parallelism으로 기본 설정되므로, 어떤 파드도 노드에 바인딩되기 전에 모든 파드가 함께 스케줄링 가능해야 해요.

.spec.scheduling을 생략하면 Job은 기본 정책으로 동작해 표준 파드-단위 스케줄링을 유지해요. 어느 쪽이든 Job 컨트롤러가 Workload와 PodGroup을 만들어 주므로 직접 만들 필요는 없어요. 다른 워크로드 컨트롤러(예: JobSet)는 자체 Workload와 PodGroup 객체를 독립적으로 관리할 수 있어요.

스케줄링 필드와 예시의 전체 목록은 Workload API와 통합을 참고해요.

다음 단계

PodGroup 스케줄링 정책 알아보기
PodGroup API 개요에서 Workload에서 PodGroup이 어떻게 생성되는지 보기
파드가 scheduling group 필드를 통해 PodGroup을 참조하는 방법 읽기
토폴로지 인식 워크로드 스케줄링 알아보기
gang 스케줄링 알고리즘 이해하기
Pod Group 중단과 우선순위
PodGroup 스케줄링 정책
토폴로지 인식 워크로드 스케줄링
스케줄링 빌딩 블록 API와 workloadbuilder 라이브러리

워크로드 API