Wave Autoscale CRD

이 kind들은 CRD Mode에서 Wave Autoscale(Autopilot)을 설정합니다. 이 kind들이 구동하는 기능 개념은 Core Configuration과 Autopilot Scheduler를 참고하세요.

WaveAutopilotPolicy

WaveAutopilotPolicy는 워크로드 하나에 대해 Autopilot을 설정합니다. 레플리카 범위, 스케일링 전략, load 메트릭, 임계값, 동작 모드를 지정할 수 있습니다. 각 설정에 대한 설명은 Core Configuration을 참고하세요.

적용 범위: namespaced. 대상 워크로드와 동일한 namespace에 있어야 합니다.

apiVersion: wavek8s.com/v1alpha1
kind: WaveAutopilotPolicy
metadata:
  name: checkout-api-policy
  namespace: payment
spec:
  targetRef:
    kind: Deployment
    name: checkout-api
  # active = Autopilot applies scaling decisions; simulation = monitor only (default when omitted)
  mode: active
  strategy: performance          # performance | cost
  applicationType: cpuIntensive  # cpuIntensive | memoryIntensive
  minReplicas: 2
  maxReplicas: 20
  load: requests                 # requests | networkIn | customPromql
  thresholds:
    cpu: 70.0
    memory: 80.0
    requests: 500.0
    networkIn: 1048576.0
  cpuUtilizationBasis: request   # request (기본값) | limit
  fallbackOnly: false            # true = ML을 건너뛰고 임계값 경로만 사용
  fallbackCpuUtilization: 65.0   # fallback HPA target when ML data is unavailable
  fallbackMemoryUtilization: 75.0
  stabilizationWindowSeconds: 300  # mutually exclusive with cooldownSeconds
  ignoreInitialMetricsSec: 60
  gradualScaleInEnabled: true
  forecastHorizon: 1             # 0 = forecasting off (default)
  latency: 250                   # target latency budget in ms

Spec 필드

참고 사항

• targetRef.kind는 Deployment, Rollout(Argo Rollouts), DeploymentConfig(OpenShift) 중 하나여야 합니다. 스키마상으로는 다른 값도 허용되지만, reconcile 시점에 ValidationFailed가 발생합니다.
• mode을 생략하면 기본값은 simulation입니다. 이 경우 Wave는 관찰하고 권고안을 만들지만 실제로 적용하지는 않습니다. Autopilot이 워크로드를 스케일링하도록 하려면 mode: active를 명시적으로 설정하세요. YAML에 "off"를 쓸 때는 반드시 따옴표로 감싸야 합니다. 따옴표 없는 off는 YAML 1.1 파서(kubectl 포함)에서 boolean false로 해석되어 string enum 검증에 실패합니다.
• cooldownSeconds와 stabilizationWindowSeconds는 상호 배타적입니다(콘솔의 "Scaling Adjustment Type"에 해당). 둘 다 설정하면 CRD CEL 규칙에 의해 kubectl apply 시점에 거부됩니다. 둘 다 생략하면 Wave가 60초짜리 stabilization window를 적용하므로 스케일링이 즉시 이뤄지지 않습니다. 콘솔의 "None" 옵션과 동일하게 맞추려면 stabilizationWindowSeconds: 0으로 설정하세요.
• loadPromql은 deprecated 상태이며 하위 호환성을 위해서만 유지됩니다. load: customPromql일 때는 필수이고, 그 외의 load 값에서는 생략합니다.
• 선택 필드를 생략하면 콘솔과 동일한 기본값이 적용됩니다: 폴백 CPU/메모리 사용률 50, ignore-initial-metrics 10초, gradual scale-in 꺼짐, CPU 사용률 기준 request, fallback-only 꺼짐. cooldownSeconds와 stabilizationWindowSeconds를 둘 다 생략하면 Wave는 60초짜리 stabilization window를 적용합니다.
• cpuUtilizationBasis: limit 은 CPU 사용률을 컨테이너의 request가 아니라 limit 기준으로 잽니다. request를 일부러 작게 잡아 Pod를 조밀하게 배치하면서도 스케일링은 limit 기준으로 하고 싶을 때 쓰세요. CPU limit이 없는 컨테이너는 자동으로 request 기준으로 돌아가고, request와 limit이 둘 다 없는 컨테이너는 기존과 동일하게 스케일링되지 않습니다. 워크로드의 기준을 request와 limit 사이에서 바꾸면 학습된 모델이 무효화됩니다. 다른 기준으로 학습된 모델을 재사용하지 않고 새 기준으로 다시 학습하므로, 잠깐의 워밍업 구간이 생깁니다.
• fallbackOnly: true 로 두면 Autopilot이 결정론적으로 동작합니다. ML 예측을 요청하지 않고 모든 스케일링 판단이 임계값 기반 폴백 계산에서 나오며, 스케일링 이벤트는 Fallback apply type으로 기록됩니다. 모델 없이 빠른 반응 경로만 쓰고 싶을 때, 또는 워크로드가 아직 학습 데이터를 모으는 중일 때 유용합니다.
• fallbackCpuUtilization에는 더 이상 100 상한이 없습니다(Wave 3.4.5+). request나 limit 기준을 넘겨 Pod를 운용하다가 스케일 아웃하는 것도 정상적인 설정이므로 100을 초과하는 값을 받습니다. 숫자가 아닌 값은 여전히 거부됩니다.

WaveAutopilotPreset

WaveAutopilotPreset은 재사용 가능한 Autopilot 설정을 정의하며, WaveAutopilotSchedule이 이름으로 참조합니다. WaveAutopilotPolicy와 동일한 튜닝 옵션을 제공하지만, 예약된 시간 동안 여러 워크로드에 걸쳐 적용됩니다. 스케줄링 모델은 Autopilot Scheduler를 참고하세요.

적용 범위: cluster-scoped. metadata.namespace가 필요하지 않습니다.

apiVersion: wavek8s.com/v1alpha1
kind: WaveAutopilotPreset
metadata:
  name: business-hours-perf
spec:
  applicationType: cpuIntensive
  strategy: performance
  minReplicas: 2
  maxReplicas: 20
  load: requests
  thresholds:
    cpu: 70.0
    memory: 80.0
    requests: 500.0
  cpuUtilizationBasis: request   # request (기본값) | limit
  fallbackOnly: false            # true = ML을 건너뛰고 임계값 경로만 사용
  fallbackCpuUtilization: 65.0
  fallbackMemoryUtilization: 75.0
  stabilizationWindowSeconds: 300  # mutually exclusive with cooldownSeconds
  ignoreInitialMetricsSec: 60
  gradualScaleInEnabled: true
  forecastHorizon: 1             # 0 = forecasting off, 1 = on
  latency: 250                   # target latency budget in ms

Spec 필드

참고 사항

• Cluster-scoped입니다. 프리셋 하나를 만들어 여러 namespace의 여러 스케줄에서 참조할 수 있습니다.
• 프리셋은 WaveAutopilotSchedule.spec.mappings[].preset에서 이름으로 참조됩니다. 여러 스케줄이 프리셋 하나를 공유할 수 있습니다.
• 생략된 필드가 콘솔 기본값으로 대체되는 WaveAutopilotPolicy와 달리, 프리셋은 모든 값을 명시해야 합니다. strategy, minReplicas, maxReplicas, applicationType은 모두 필수입니다.
• loadPromql은 프리셋에서 사용할 수 없습니다. WaveAutopilotPolicy에서도 deprecated 상태이며 하위 호환성을 위해서만 남아 있습니다.
• 아직 참조되고 있는 프리셋을 삭제하면, 프리셋이 같은 이름으로 다시 생성되거나 스케줄이 업데이트될 때까지 해당 스케줄은 .status.conditions에 RefNotFound를 보고합니다.

WaveAutopilotSchedule

WaveAutopilotSchedule은 정의된 시간 동안 하나 이상의 워크로드에 WaveAutopilotPreset을 적용합니다. 반복되는 시간대(cron 또는 주간 period)와 일회성 시간대를 모두 지원합니다. 전체 스케줄링 모델은 Autopilot Scheduler를 참고하세요.

적용 범위: cluster-scoped. metadata.namespace가 필요하지 않습니다.

# Cron variant — recurring window on a 7-field cron expression
apiVersion: wavek8s.com/v1alpha1
kind: WaveAutopilotSchedule
metadata:
  name: business-hours-schedule
spec:
  timing:
    kind: cron
    cronExpression: "0 0 9 * * 1-5 *"   # every weekday at 09:00
    cronDurationMin: 540             # window lasts 9 hours (540 minutes)
    cronAdvanceMin: 30               # optional: activate the preset 30 min early
  mappings:
    - preset: business-hours-perf   # name of a WaveAutopilotPreset
      targets:
        - namespace: payment
          name: checkout-api
        - namespace: payment
          name: payment-worker
  enabled: true
---
# Period variant — recurring window on named days of the week
apiVersion: wavek8s.com/v1alpha1
kind: WaveAutopilotSchedule
metadata:
  name: weekday-scale-up
spec:
  timing:
    kind: period
    daysOfWeek:
      - Mon
      - Tue
      - Wed
      - Thu
      - Fri
    startTime: "09:00"
    endTime: "18:00"
    timezone: Asia/Seoul
  mappings:
    - preset: business-hours-perf
      targets:
        - namespace: payment
          name: checkout-api
---
# Once variant — one-shot window for a specific date range
apiVersion: wavek8s.com/v1alpha1
kind: WaveAutopilotSchedule
metadata:
  name: promo-event-scale
spec:
  timing:
    kind: once
    startDt: "2026-11-25 00:00"
    endDt: "2026-11-25 23:59"
    timezone: Asia/Seoul
  mappings:
    - preset: business-hours-perf
      targets:
        - namespace: payment
          name: checkout-api
  enabled: true

Spec 필드

timing.kind: cron 필드

timing.kind: period 필드

timing.kind: once 필드

참고 사항

• Cluster-scoped입니다. 스케줄 하나가 mappings[].targets[].namespace를 통해 여러 namespace의 워크로드를 대상으로 삼을 수 있습니다.
• 워크로드는 namespace와 name으로 식별됩니다. 대상 워크로드가 아직 존재하지 않는 스케줄은 TargetNotFound를 보고하며, 워크로드가 나타나면 자동으로 정상화됩니다.
• 참조하는 프리셋이 아직 존재하지 않는 스케줄은 RefNotFound를 보고하며, 동일한 이름의 프리셋이 적용되면 자동으로 정상화됩니다.
• timing은 internally-tagged union 구조를 사용합니다. kind discriminator는 별도의 키 아래에 중첩되지 않고 다른 타이밍 필드들과 나란히 위치합니다. CRD 스키마는 timing 내부까지 검증하지 않으므로, 구조적 오류(잘못된 필드명, 필수 필드 누락)는 kubectl apply 시점에 거부되는 대신 Wave에서 ValidationFailed로 나타납니다.
• mappings의 기본값은 빈 목록입니다. mapping이 없는 스케줄은 유효하지만 아무 동작도 하지 않으므로, 항상 최소 하나의 mapping 항목을 포함하세요.
• enabled을 생략하면 기본값은 true입니다. 스케줄을 삭제하지 않고 일시 중지하려면 false로 설정하세요.