AMAZON EKS / FEATURE ANALYSIS

EKS 컨트롤 플레인 파라미터가 열렸다 - Advanced Control Plane Configuration 분석

EKS가 전담 관리하던 kube-scheduler, kube-controller-manager, kube-apiserver의 파라미터 4종이 2026-08-12부터 고객 설정 대상이 되었습니다. 각 파라미터가 무엇을 바꾸는지, 어떤 함정이 있는지, 어떤 상황에서 조정할 가치가 있는지 분석합니다.

작성 기준일은 2026-08-13입니다.

적용 대상은 Kubernetes 1.31 이상의 신규 및 기존 EKS 클러스터입니다.

지원 리전은 모든 AWS 상용 리전과 GovCloud, 중국 리전입니다.

주 출처는 EKS 공식 문서(control-plane-configuration)와 What's New 공지(2026-08-12)입니다.

추가 요금은 없으며, 유일한 예외는 Provisioned Control Plane(티어 시간당 과금)이 필요한 horizontalPodAutoscalerSyncPeriod입니다.

요약

01무엇이 열렸나

이 섹션은 해석 없이 사실만 정리합니다. 무엇을, 어디까지, 어떤 방식으로 설정할 수 있는지입니다.

Amazon EKS는 2026-08-12에 Advanced Kubernetes control plane configuration 기능을 출시했습니다. EKS가 관리하는 컨트롤 플레인(클러스터의 결정을 내리는 관리 계층 - API 서버, 스케줄러, 컨트롤러 매니저)의 파라미터 4종을 고객이 직접 설정할 수 있습니다.

아래 표에서 볼 것은 세 가지입니다. 어느 컴포넌트의 어떤 파라미터인지, 허용 범위가 얼마나 좁은지, 그리고 horizontalPodAutoscalerSyncPeriod 하나만 Provisioned Control Plane (컨트롤 플레인 용량을 사전 할당하는 모드, 이하 PCP)을 요구한다는 점입니다.

표 1. 설정 가능한 컨트롤 플레인 파라미터 4종
컴포넌트 파라미터 허용 범위 기본값 PCP 필요
kube-scheduler nodeResourcesFit.scoringStrategy LeastAllocated, MostAllocated LeastAllocated (cpu:1, memory:1) 아니요
kube-controller-manager horizontalPodAutoscalerSyncPeriod 10s ~ 15s 15s 예
kube-apiserver eventTtl 10m ~ 60m 60m 아니요
kube-apiserver serviceNodePortRange minPort/maxPort 각 10260 ~ 32767 30000 ~ 32767 아니요

설정 방식은 신규 API가 아니라 기존 API의 확장입니다. CreateCluster와 UpdateClusterConfig 오퍼레이션에 컴포넌트별 파라미터가 추가되었고, 콘솔, AWS CLI, SDK, CloudFormation에서 같은 방식으로 쓸 수 있습니다.

통제 장치 세 가지가 함께 붙어 있습니다. 각 파라미터는 EKS가 검증한 범위(validated range) 안의 값만 받고, 모든 변경은 CloudTrail에 기록되며, 설정은 항상 클러스터 전역입니다. 네임스페이스나 워크로드 단위로 스코프를 좁히는 방법은 없습니다.

지원 대상은 Kubernetes 1.31 이상의 신규 및 기존 클러스터이고, 모든 AWS 상용 리전과 GovCloud, 중국 리전에서 쓸 수 있습니다. 추가 요금은 없습니다. 단 표의 마지막 열이 보여주듯 HPA sync period 하나만 PCP(티어 시간당 과금)를 요구합니다.

참고 - 설정하기 전까지는 아무것도 바뀌지 않습니다

이 기능의 출시 자체는 기존 클러스터의 동작을 바꾸지 않습니다. 파라미터를 명시적으로 설정하기 전까지 모든 클러스터는 기본값으로 동작합니다. 즉 "업그레이드했더니 스케줄링이 달라졌다" 같은 경로는 이 기능에는 없습니다.

02왜 의미가 있나

파라미터 4개는 숫자로 보면 작은 개방입니다. 그런데 관리형 Kubernetes에서 고객과 서비스 제공자를 나누던 통제 경계가 컨트롤 플레인 안쪽으로 움직였다는 점에서 의미가 있습니다.

2.1 지금까지 컨트롤 플레인 플래그는 EKS의 영역이었습니다

직접 설치한 Kubernetes에서는 kube-scheduler나 kube-apiserver의 플래그를 운영자가 정합니다. EKS 같은 관리형 서비스에서는 그 결정권이 서비스 쪽에 있었습니다. EKS가 컨트롤 플레인의 가용성을 책임지는 대신 컴포넌트 설정도 EKS가 정하는 구조였습니다.

이 경계가 실제로 아팠던 지점이 스케줄러 점수 전략입니다. 노드를 채워서 쓰는 MostAllocated 방식으로 컴퓨트 비용을 줄이고 싶어도 관리형 컨트롤 플레인의 스케줄러 설정에는 손댈 방법이 없었습니다. 이번 기능은 그 요구를 관리형 서비스의 API 안으로 가져왔습니다.

2.2 완전 개방이 아니라 검증된 범위 안의 개방입니다

설계를 보면 EKS가 무엇을 지키려 했는지 드러납니다. 개방된 것은 컴포넌트 플래그 전체가 아니라 파라미터 4종이고, 각 파라미터의 폭도 좁습니다. HPA sync period는 10s에서 15s 사이 5초 폭이고, eventTtl은 기본값 60m에서 줄이는 방향만 열려 있으며, serviceNodePortRange의 상한은 32767로 고정되어 있습니다.

스케줄러 전략도 같은 패턴입니다. 업스트림 Kubernetes의 scoringStrategy 가운데 RequestedToCapacityRatio는 지원하지 않고, LeastAllocated와 MostAllocated 두 가지만 받습니다. 검증된 범위 안에서만 값을 받는 이 구조는 컨트롤 플레인의 안정성 책임을 EKS가 계속 지겠다는 설계로 읽힙니다. 이 문장은 공식 문서의 표현이 아니라 허용 범위의 모양에서 끌어낸 해석입니다.

2.3 버전별 기본값은 DescribeClusterVersions가 기준입니다

표 1의 기본값과 허용 범위는 발행 시점의 Kubernetes 버전(EKS 1.31 이상) 기준이고, 이후 버전에서 바뀔 수 있습니다. AWS 문서가 지정한 버전별 source of truth는 DescribeClusterVersions API입니다. 버전마다 defaultValue와 constraints를 반환하므로, IaC나 자동화에 기본값을 하드코딩하지 말고 이 API를 조회하는 편이 안전합니다.

03파라미터별 심층 분석

파라미터 4종을 하나씩 봅니다. 각 파라미터마다 무엇을 바꾸는지, 언제 조정할 가치가 있는지, 어떤 함정이 있는지 순서로 정리합니다.

3.1 kube-scheduler - nodeResourcesFit scoringStrategy

스케줄러는 두 단계로 동작합니다. filter 단계에서 pod를 실행할 수 있는 노드를 골라내고, score 단계에서 후보 노드에 점수를 매겨 최고점 노드에 배치합니다. 자원 확인과 점수화는 nodeResourcesFit 플러그인이 담당하는데, 이번에 열린 것은 그중 score 단계의 전략입니다. filter 단계는 바뀌지 않습니다.

flowchart LR P["Pod 생성 요청"] --> F["filter
실행 가능 노드 선별"] F --> S["score
nodeResourcesFit 점수화"] S --> B["최고점 노드에 배치"]
그림 1. 스케줄러의 2단계 동작. 이번에 개방된 scoringStrategy는 score 단계의 점수 계산만 바꾸고, filter 단계는 그대로 유지됩니다.

전략은 두 가지 중에서 고릅니다. 기본값 LeastAllocated는 할당이 적은 노드를 선호해 워크로드를 분산하고, MostAllocated는 할당이 많은 노드를 선호해 워크로드를 집적합니다. 집적하면 가볍게 쓰이는 노드에 새 워크로드가 가지 않으므로, consolidation을 지원하는 노드 풀이 그 노드를 제거해 컴퓨트 비용을 줄일 수 있습니다. 업스트림 Kubernetes의 RequestedToCapacityRatio 전략은 지원하지 않습니다.

scoringStrategy.resources에는 cpu, memory와 가속기 3종(nvidia.com/gpu, aws.amazon.com/neuron, aws.amazon.com/neuroncore)을 가중치 1~100으로 나열할 수 있습니다. 가중치는 상대값입니다. cpu 100, memory 1로 두어도 memory가 무시되는 것이 아니라 cpu가 100배 가중될 뿐이고, 모든 후보 노드의 CPU 가용량이 같다면 사실상 memory가 배치를 결정합니다.

주의 - 누락은 낮은 가중치가 아닙니다

resources 배열을 지정하면 나열한 리소스만 점수화하고, 뺀 리소스는 계산에서 완전히 제외됩니다. cpu 100만 쓰면 memory의 영향은 0이 됩니다. 영향을 줄이되 유지하고 싶다면 낮은 가중치로라도 나열해야 합니다.

가속기 가중치는 해당 리소스를 resources.requests로 선언한 pod에만 영향을 줍니다. 가속기 3종은 extended resource라서 device plugin이 kubelet에 광고해야 점수화 대상이 되고, 드라이버만으로 노출된 리소스는 nodeResourcesFit에 보이지 않습니다. DRA로 관리되는 리소스는 별도 플러그인이 스케줄링하므로 이 점수화와 무관합니다.

운영 관점의 주의점은 세 가지입니다.

  • 실행 중인 pod는 이동하지 않습니다. 전략은 향후 스케줄링에만 영향을 주고, 기존 pod를 재배치하려면 evict나 재시작이 필요합니다.
  • MostAllocated는 blast radius를 집중시킵니다. 노드나 AZ 장애 시 동시에 영향받는 pod가 늘어나고, churn이 높은 클러스터에서는 Pending pod가 증가할 수 있습니다.
  • 스케줄러와 노드 관리는 다른 계층입니다. 이 설정은 EKS Auto Mode나 Karpenter의 프로비저닝과 제거 방식을 바꾸지 않으므로, 결합했을 때의 동작을 직접 검증해야 합니다.

3.2 kube-controller-manager - HPA sync period

HPA 컨트롤러가 각 HorizontalPodAutoscaler 객체의 메트릭을 조회하고, 원하는 replica 수를 계산해 변경이 필요하면 업데이트하는 주기입니다. 허용 범위는 10s에서 15s, 기본값은 15s입니다. 단축하면 부하 증가 후 더 빨리 스케일합니다.

이 파라미터만 Provisioned Control Plane이 필수인 이유가 있습니다. 주기 단축은 모든 HPA 객체의 reconcile 빈도를 올려 API 서버 요청을 늘립니다(reconcile당 최소 1개 요청, replica 변경 시 2개 추가). PCP는 용량을 미리 할당하는 모드라 이 증가를 흡수할 수 있고, Standard 모드에서 설정하면 실패합니다. 또 15s에서 10s로 최대 단축하면 같은 큐를 처리할 시간이 줄어, 지원 가능한 HPA 객체 수가 약 1/3 감소합니다. 사전에 kubectl get hpa --all-namespaces로 객체 수를 확인하세요.

주의 - 초과해도 경보 없이 조용히 저하됩니다

EKS는 클러스터의 HPA 객체 수 대비 검증을 하지 않습니다. 지원 한도를 초과한 상태여도 설정 변경은 성공합니다. 초과하면 일부 객체가 제때 reconcile되지 않는데, 경보도 Kubernetes 이벤트도 없습니다. 증상은 "오토스케일이 기대보다 느려짐"으로, 주기를 줄인 의도와 정반대입니다. 이 증상이 관찰되면 15s로 복원하는 것이 권장됩니다.

Provisioned Control Plane이 이 부하를 흡수하는 근거는 티어별 사전 할당 용량입니다. 아래 표에서 티어별 API 동시성과 함께, HPA 객체를 병렬로 처리하는 워커 수인 HPA sync concurrency를 볼 수 있습니다. 업스트림 Kubernetes 기본값이 5인 것과 비교하면 PCP 티어는 10배에서 40배 높게 튜닝되어 있습니다.

표 2. Provisioned Control Plane 티어 스펙 (Kubernetes 1.34 이상, SLA는 전 티어 99.99%)
티어API 요청 동시성 (seats)pod 스케줄링 (개/초)HPA sync concurrency
XL2,00016750
2XL4,000283100
4XL8,000400200
8XL16,000400200

티어 수치는 Kubernetes 버전에 따라 다르므로(1.30에서 1.33은 API 동시성이 더 낮습니다), 정확한 값은 DescribeClusterVersions로 조회하는 것이 안전합니다.

3.3 kube-apiserver - eventTtl

Kubernetes 이벤트(pod 스케줄링, 이미지 pull, 헬스체크 실패, 스케일링 등)의 보존 기간입니다. 허용 범위는 10m에서 60m, 기본값은 60m입니다. 대규모 배치, AI, CI/CD, 잦은 CronJob 같은 고churn 워크로드는 이벤트를 수천 개씩 빠르게 누적시켜 etcd 공간을 잠식하고 list 오퍼레이션 비용을 키웁니다. 이럴 때 단축을 검토합니다.

단축이 맞는 조건은 세 가지입니다. 이벤트를 다량 생성하는 워크로드가 있고, etcd 스토리지가 한도를 향해 성장하는 것이 관찰되며, 이벤트를 외부 시스템으로 내구성 있게 수집해 kubectl get events 히스토리에 의존하지 않는 경우입니다.

참고 - 새 이벤트에만 적용됩니다

이벤트의 만료 시점은 생성 시점에 결정됩니다. 기존 이벤트는 기존 TTL대로 만료되므로 스토리지 감소는 점진적입니다. 삭제된 이벤트는 복구할 수 없고, etcd lease 갱신(리더 선출 중) 때문에 설정값보다 약간 오래 남을 수 있습니다. kubectl get events와 describe의 디버깅 윈도우가 줄고, 모니터링 도구가 수집하는 데이터도 감소합니다.

3.4 kube-apiserver - serviceNodePortRange

NodePort 서비스(기본 설정에서는 LoadBalancer 타입 포함)에 할당하는 포트 범위입니다. minPort와 maxPort 각각 10260에서 32767 사이로 설정할 수 있고, 기본값은 30000에서 32767입니다. minPort가 maxPort보다 크면 거부됩니다.

용도는 조직 네트워크와 방화벽 정책에 맞춘 정렬, 범위 확장을 통한 클러스터당 서비스 수 증가, 그리고 특히 마이그레이션입니다. 고정 포트를 기대하는 앱과 클라이언트가 기본 범위 밖 포트를 쓰면 기존에는 앱 수정이나 프록시 추가가 필요했는데, 범위를 앱이 쓰는 포트에 맞추면 재작성이나 추가 네트워크 컴포넌트 없이 이전할 수 있습니다.

경계값에는 근거가 있습니다. 하한 10260은 노드에서 도는 Kubernetes 시스템 컴포넌트의 포트 (kubelet 헬스 10248, kube-proxy 헬스체크 10256)를 회피합니다. 상한 32767은 통상 32768에서 시작하는 Linux ephemeral port 범위를 회피합니다. NodePort가 ephemeral 범위 안에 있으면 커널이 아웃바운드 연결에 같은 포트를 선택해 충돌할 수 있기 때문입니다.

범위를 바꿔도 기존 서비스는 할당받은 포트를 유지합니다. 범위를 축소해도 동작하고 kube-proxy 라우팅도 유지되며, EKS가 재할당하지 않습니다. 단 서비스를 재생성하면 범위 밖 포트는 다시 받을 수 없으므로, 배포 프로세스가 서비스를 재생성한다면 주의해야 합니다. 범위 밖 신규 할당과 명시적 nodePort 지정은 모두 API 서버 검증에서 거부됩니다. 변경 전에는 보안 그룹과 NACL이 새 범위의 트래픽을 허용하는지, 노드의 다른 소프트웨어와 포트 충돌이 없는지 확인하세요.

04운영 시 알아야 할 것

어느 파라미터를 조정하든 공통으로 적용되는 운영 규칙입니다. 공식 문서의 Considerations를 기준으로 정리했습니다.

4.1 리셋 오퍼레이션이 없습니다

설정을 초기화하는 별도 오퍼레이션은 없습니다. 업데이트에서 필드를 생략하면 현재 값이 유지될 뿐 클리어되지 않습니다. 기본값으로 되돌리려면 기본값을 명시적으로 설정해야 하고, 버전별 기본값은 DescribeClusterVersions로 조회합니다.

업데이트는 병합(merge) 방식입니다. 지정한 필드만 바뀌고, 이 규칙은 컴포넌트 사이에서도 한 컴포넌트 안에서도 동일합니다. 현재 실행 구성 전체는 describe-cluster가 반환합니다. 커스터마이즈하지 않은 파라미터를 포함해 kubeSchedulerConfig, kubeControllerManagerConfig, kubeApiServerConfig 최상위 필드가 항상 존재합니다.

4.2 변경은 롤링 업데이트로 적용됩니다

설정 변경은 즉시 적용되지 않습니다. 컨트롤 플레인 롤링 업데이트로 수 분에 걸쳐 적용되고, 업데이트 타입은 ControlPlaneComponentConfigUpdate입니다. 진행 상태는 describe-update로 추적하고 (InProgress에서 Successful 또는 Failed로 전이), 완료되면 클러스터가 ACTIVE로 복귀합니다.

코드 1. 설정 변경, 적용 대기, 버전별 값 조회
# 스케줄러 점수 전략을 MostAllocated로 변경
aws eks update-cluster-config --name "$CLUSTER" \
  --kube-scheduler-config '{"nodeResourcesFit":{"scoringStrategy":{"type":"MostAllocated"}}}'

# 롤링 업데이트 완료까지 대기
aws eks wait cluster-active --name "$CLUSTER"

# 버전별 기본값(defaultValue)과 허용 범위(constraints) 조회
aws eks describe-cluster-versions --cluster-versions 1.35 \
  --query 'clusterVersions[0].controlPlaneComponentConfig'

CLI에서는 컴포넌트별 플래그(--kube-scheduler-config, --kube-controller-manager-config, --kube-api-server-config)에 인라인 JSON을 넘기고, 한 번의 호출에 복수 컴포넌트를 함께 지정할 수 있습니다. 콘솔, eksctl, AWS CLI, EKS API, CloudFormation, CDK는 출시 시점부터 지원하고 ACK와 Terraform은 coming soon 상태입니다.

4.3 PCP에는 탈출 제약이 있습니다

HPA sync period가 기본값(15s) 이외로 설정된 동안에는 Provisioned에서 Standard로 복귀할 수 없습니다. 먼저 15s로 되돌린 후에 티어를 변경해야 합니다. 별도로 etcd 사용량이 8GB를 초과한 상태에서도 Standard 복귀가 불가하므로, PCP 진입 전에 되돌아올 경로까지 계획에 넣어야 합니다.

05상황별 적용 가이드

기본값이 곧 안전값입니다. 아래 표의 상황에 해당하고 목적이 명확할 때만 조정을 검토하세요.

표 3. 상황별 조정 대상과 확인 사항
상황 조정 함께 확인할 것
노드를 채워 써서 컴퓨트 비용을 줄이고 싶다 scoringStrategy를 MostAllocated로 consolidation 노드 풀과의 결합 동작 검증, 노드나 AZ 장애 시 blast radius 집중
부하 증가에 더 빨리 스케일하고 싶다 syncPeriod를 15s에서 10s로 PCP 필수(티어 시간당 과금), HPA 객체 수 사전 확인, 한도 초과 시 조용한 저하
이벤트가 etcd 공간을 잠식한다 (대규모 배치, CI/CD, 잦은 CronJob) eventTtl 단축 (10m~60m) 새 이벤트에만 적용되어 감소는 점진적, 디버깅 윈도우 축소, 외부 이벤트 수집 여부
마이그레이션에서 기본 범위 밖 고정 NodePort가 필요하다 serviceNodePortRange 조정 보안 그룹과 NACL의 새 범위 허용, 노드 소프트웨어와 포트 충돌, 서비스 재생성 시 범위 밖 포트 재할당 불가

어느 경우든 조정 전에 describe-cluster-versions로 해당 버전의 기본값과 허용 범위를 확인하고, 변경 후에는 describe-cluster로 실행 구성을 검증하는 절차를 IaC나 런북에 포함하는 것이 안전합니다.

인터랙티브 아키텍처 맵 전체 이미지 - EKS API를 통한 파라미터 설정과 컨트롤 플레인 3개 컴포넌트의 적용 경로
그림 2. 인터랙티브 아키텍처 맵 전체 보기. 이미지를 클릭하면 노드 탐색, 경로 추적, 다크/라이트 테마를 지원하는 인터랙티브 버전 ↗이 열립니다.

--참고 자료

핵심 출처

공식 문서

AMAZON EKS / FEATURE ANALYSIS

EKS Control Plane Parameters Are Now Open - An Analysis of Advanced Control Plane Configuration

Four parameters of kube-scheduler, kube-controller-manager, and kube-apiserver - previously managed exclusively by EKS - became customer-configurable on 2026-08-12. We analyze what each parameter changes, what pitfalls it carries, and in which situations it is worth tuning.

Written as of 2026-08-13.

This applies to new and existing EKS clusters running Kubernetes 1.31 or later.

Supported regions are all AWS commercial regions, GovCloud, and the China regions.

Primary sources are the EKS official documentation (control-plane-configuration) and the What's New announcement (2026-08-12).

There is no additional charge, and only horizontalPodAutoscalerSyncPeriod requires Provisioned Control Plane (billed hourly per tier).

TL;DR

01What Was Opened

This section states facts only, with no interpretation: what you can configure, how far, and by what mechanism.

Amazon EKS launched the Advanced Kubernetes control plane configuration capability on 2026-08-12. Customers can now directly configure four parameters of the EKS-managed control plane - the management layer that makes the cluster's decisions: the API server, the scheduler, and the controller manager.

There are three things to look for in the table below: which component each parameter belongs to, how narrow the allowed ranges are, and that only horizontalPodAutoscalerSyncPeriod requires Provisioned Control Plane (a mode that pre-allocates control plane capacity, PCP hereafter).

Table 1. The four configurable control plane parameters
Component Parameter Allowed range Default PCP required
kube-scheduler nodeResourcesFit.scoringStrategy LeastAllocated, MostAllocated LeastAllocated (cpu:1, memory:1) No
kube-controller-manager horizontalPodAutoscalerSyncPeriod 10s ~ 15s 15s Yes
kube-apiserver eventTtl 10m ~ 60m 60m No
kube-apiserver serviceNodePortRange minPort/maxPort each 10260 ~ 32767 30000 ~ 32767 No

The configuration mechanism is an extension of existing APIs, not a new one. Per-component parameters were added to the CreateCluster and UpdateClusterConfig operations, and they work the same way from the console, AWS CLI, SDKs, and CloudFormation.

Three guardrails come attached. Each parameter accepts only values within an EKS-validated range, every change is recorded in CloudTrail, and settings are always cluster-wide. There is no way to narrow the scope to a namespace or a workload.

Support covers new and existing clusters on Kubernetes 1.31 or later, in all AWS commercial regions plus GovCloud and the China regions. There is no additional charge - except, as the last column of the table shows, the HPA sync period alone requires PCP (billed hourly per tier).

Note - Nothing changes until you configure it

The launch itself does not change how existing clusters behave. Until you explicitly set a parameter, every cluster runs on the defaults. In other words, there is no "I upgraded and scheduling changed" path with this feature.

02Why It Matters

Four parameters is a small opening by the numbers. It matters, though, because the control boundary that separated customers from the service provider in managed Kubernetes has moved inward, into the control plane.

2.1 Until now, control plane flags were EKS territory

On self-installed Kubernetes, operators set the flags of kube-scheduler and kube-apiserver. On a managed service like EKS, that decision rested with the service side. EKS took responsibility for control plane availability, and in exchange, EKS also decided the component configuration.

The point where this boundary actually hurt was the scheduler scoring strategy. Even if you wanted to cut compute costs with the node-packing MostAllocated approach, there was no way to touch the scheduler configuration of the managed control plane. This feature brings that demand inside the managed service's API.

2.2 Not a full opening, but an opening within validated ranges

The design reveals what EKS set out to protect. What was opened is not the full set of component flags but four parameters, and each parameter's window is narrow. The HPA sync period is a 5-second window between 10s and 15s, eventTtl only opens downward from the 60m default, and the upper bound of serviceNodePortRange is fixed at 32767.

The scheduler strategy follows the same pattern. Among upstream Kubernetes scoringStrategy options, RequestedToCapacityRatio is not supported; only LeastAllocated and MostAllocated are accepted. This structure of accepting values only within validated ranges reads as a design in which EKS keeps owning responsibility for control plane stability. That sentence is our interpretation drawn from the shape of the allowed ranges, not wording from the official documentation.

2.3 DescribeClusterVersions is the source of truth for per-version defaults

The defaults and allowed ranges in Table 1 are as of the Kubernetes versions at publication time (EKS 1.31 and later) and may change in later versions. The per-version source of truth designated by the AWS documentation is the DescribeClusterVersions API. It returns defaultValue and constraints for each version, so rather than hardcoding defaults into IaC or automation, querying this API is the safer path.

03Parameter-by-Parameter Deep Dive

This section walks through the four parameters one by one. For each parameter, it covers what it changes, when tuning it is worth it, and what the pitfalls are, in that order.

3.1 kube-scheduler - nodeResourcesFit scoringStrategy

The scheduler works in two phases. The filter phase selects the nodes that can run the pod, and the score phase scores the candidate nodes and places the pod on the highest-scoring node. Resource checking and scoring are handled by the nodeResourcesFit plugin, and what was opened this time is the strategy of its score phase. The filter phase does not change.

flowchart LR P["Pod creation request"] --> F["filter
select runnable nodes"] F --> S["score
nodeResourcesFit scoring"] S --> B["place on highest-scoring node"]
Figure 1. The scheduler's two-phase operation. The newly opened scoringStrategy only changes the score computation of the score phase; the filter phase stays the same.

You choose between two strategies. The default LeastAllocated prefers nodes with less allocation and spreads workloads; MostAllocated prefers nodes with more allocation and packs workloads together. Packing keeps new workloads off lightly used nodes, so a node pool that supports consolidation can remove those nodes and reduce compute costs. The upstream Kubernetes RequestedToCapacityRatio strategy is not supported.

In scoringStrategy.resources you can list cpu, memory, and three accelerators (nvidia.com/gpu, aws.amazon.com/neuron, aws.amazon.com/neuroncore) with weights from 1 to 100. Weights are relative. Setting cpu 100 and memory 1 does not mean memory is ignored - cpu is simply weighted 100x - and if every candidate node has the same available CPU, memory effectively decides placement.

Caution - Omission is not a low weight

When you specify the resources array, only the listed resources are scored; resources you leave out are excluded from the computation entirely. With cpu 100 alone, memory's influence becomes 0. If you want to reduce a resource's influence while keeping it, list it with a low weight.

Accelerator weights only affect pods that declare the resource in resources.requests. The three accelerators are extended resources, so a device plugin must advertise them to the kubelet before they become scoring targets; resources exposed by a driver alone are invisible to nodeResourcesFit. Resources managed by DRA are scheduled by a separate plugin and are unrelated to this scoring.

There are three operational caveats.

  • Running pods do not move. The strategy affects future scheduling only; relocating existing pods requires evicting or restarting them.
  • MostAllocated concentrates the blast radius. A node or AZ failure affects more pods at once, and on high-churn clusters Pending pods can increase.
  • The scheduler and node management are different layers. This setting does not change how EKS Auto Mode or Karpenter provisions and removes nodes, so you must verify the combined behavior yourself.

3.2 kube-controller-manager - HPA sync period

This is the interval at which the HPA controller queries the metrics of each HorizontalPodAutoscaler object, computes the desired replica count, and updates it when a change is needed. The allowed range is 10s to 15s, and the default is 15s. Shortening it makes scaling react faster after load increases.

There is a reason this is the only parameter that requires Provisioned Control Plane. Shortening the period raises the reconcile frequency of every HPA object and increases API server requests (at least 1 request per reconcile, plus 2 more when replicas change). PCP is a mode that pre-allocates capacity, so it can absorb this increase; setting it in Standard mode fails. Also, shortening from 15s to the 10s minimum leaves less time to process the same queue, cutting the number of supportable HPA objects by roughly 1/3. Check the object count beforehand with kubectl get hpa --all-namespaces.

Caution - Exceeding the limit degrades silently, with no alarm

EKS does not validate against the cluster's HPA object count. The configuration change succeeds even when you are past the supported limit. Past it, some objects stop being reconciled on time - with no alarm and no Kubernetes event. The symptom is "autoscaling is slower than expected," the exact opposite of why you shortened the period. If you observe this symptom, restoring 15s is the recommendation.

What lets Provisioned Control Plane absorb this load is the capacity pre-allocated per tier. The table below shows each tier's API concurrency alongside HPA sync concurrency, the number of workers that reconcile HPA objects in parallel. Compared with the upstream Kubernetes default of 5, PCP tiers are tuned 10 to 40 times higher.

Table 2. Provisioned Control Plane tier specs (Kubernetes 1.34 and later; SLA is 99.99% on every tier)
TierAPI request concurrency (seats)Pod scheduling (pods/sec)HPA sync concurrency
XL2,00016750
2XL4,000283100
4XL8,000400200
8XL16,000400200

Tier values differ by Kubernetes version (1.30 through 1.33 have lower API concurrency), so retrieving the exact values with DescribeClusterVersions is the safe path.

3.3 kube-apiserver - eventTtl

This is the retention period for Kubernetes events (pod scheduling, image pulls, health check failures, scaling, and so on). The allowed range is 10m to 60m, and the default is 60m. High-churn workloads such as large-scale batch, AI, CI/CD, and frequent CronJobs accumulate events by the thousands, eating etcd space and inflating the cost of list operations. That is when shortening is worth considering.

Three conditions make shortening the right call: you have workloads that generate events in volume, you observe etcd storage growing toward its limit, and you collect events durably into an external system so you do not depend on kubectl get events history.

Note - Applies to new events only

An event's expiry is fixed at creation time. Existing events expire on their original TTL, so the storage reduction is gradual. Deleted events cannot be recovered, and events can linger slightly past the configured value because of etcd lease renewal (during leader election). The debugging window of kubectl get events and describe shrinks, and the data collected by monitoring tools decreases as well.

3.4 kube-apiserver - serviceNodePortRange

This is the port range allocated to NodePort services (which, in the default configuration, includes LoadBalancer-type services). minPort and maxPort can each be set between 10260 and 32767, and the default is 30000 to 32767. A minPort greater than maxPort is rejected.

The use cases are alignment with organizational network and firewall policy, more services per cluster through a wider range, and above all migrations. When apps and clients expecting fixed ports use ports outside the default range, the old answer was modifying the app or adding a proxy; matching the range to the ports the app uses lets you migrate without rewrites or extra network components.

The boundary values have a rationale. The lower bound 10260 avoids the ports of Kubernetes system components running on nodes (kubelet health 10248, kube-proxy health check 10256). The upper bound 32767 avoids the Linux ephemeral port range, which typically starts at 32768. If a NodePort sat inside the ephemeral range, the kernel could pick the same port for an outbound connection and collide.

Changing the range does not touch existing services - they keep their allocated ports. Shrinking the range still works and kube-proxy routing is preserved; EKS does not reallocate. But once a service is recreated, it can no longer receive a port outside the range, so beware if your deployment process recreates services. New allocations outside the range and explicit nodePort values are both rejected by API server validation. Before changing, confirm that security groups and NACLs allow traffic on the new range and that no other software on the nodes conflicts on those ports.

04What to Know for Operations

These are the operational rules that apply no matter which parameter you tune, organized around the Considerations in the official documentation.

4.1 There is no reset operation

There is no dedicated operation to reset the configuration. Omitting a field in an update keeps the current value - it does not clear it. To return to a default you must set the default explicitly, and per-version defaults are queried with DescribeClusterVersions.

Updates are merges. Only the fields you specify change, and this rule holds both across components and within a single component. The full running configuration is returned by describe-cluster: the top-level fields kubeSchedulerConfig, kubeControllerManagerConfig, and kubeApiServerConfig are always present, including parameters you never customized.

4.2 Changes apply via rolling update

Configuration changes do not apply instantly. They roll out through a control plane rolling update over several minutes, and the update type is ControlPlaneComponentConfigUpdate. Track progress with describe-update (transitioning from InProgress to Successful or Failed); on completion the cluster returns to ACTIVE.

Code 1. Change a setting, wait for rollout, query per-version values
# Switch the scheduler scoring strategy to MostAllocated
aws eks update-cluster-config --name "$CLUSTER" \
  --kube-scheduler-config '{"nodeResourcesFit":{"scoringStrategy":{"type":"MostAllocated"}}}'

# Wait for the rolling update to complete
aws eks wait cluster-active --name "$CLUSTER"

# Query per-version defaults (defaultValue) and allowed ranges (constraints)
aws eks describe-cluster-versions --cluster-versions 1.35 \
  --query 'clusterVersions[0].controlPlaneComponentConfig'

From the CLI you pass inline JSON to the per-component flags (--kube-scheduler-config, --kube-controller-manager-config, --kube-api-server-config), and multiple components can be specified together in a single call. The console, eksctl, the AWS CLI, the EKS API, CloudFormation, and CDK are supported from launch; ACK and Terraform are coming soon.

4.3 PCP has exit constraints

While the HPA sync period is set to anything other than the default (15s), you cannot return from Provisioned to Standard. Revert to 15s first, then change the tier. Separately, returning to Standard is also blocked while etcd usage exceeds 8GB, so plan the way back before entering PCP.

05Scenario-Based Application Guide

The defaults are the safe values. Consider tuning only when one of the scenarios in the table below applies and the goal is clear.

Table 3. What to tune per scenario and what to check alongside
Scenario Tune Check alongside
You want to pack nodes tighter and cut compute costs scoringStrategy to MostAllocated Verify combined behavior with consolidation node pools; blast radius concentrates on node or AZ failure
You want to scale faster when load rises syncPeriod from 15s to 10s PCP required (billed hourly per tier), check HPA object count beforehand, silent degradation past the limit
Events are eating etcd space (large-scale batch, CI/CD, frequent CronJobs) Shorten eventTtl (10m~60m) Applies to new events only so the reduction is gradual, shorter debugging window, external event collection in place
A migration needs fixed NodePorts outside the default range Adjust serviceNodePortRange Security groups and NACLs allow the new range, no port conflicts with node software, out-of-range ports cannot be reallocated when services are recreated

In every case, it is safest to bake into your IaC or runbooks a procedure that checks the version's defaults and allowed ranges with describe-cluster-versions before tuning, and verifies the running configuration with describe-cluster afterward.

Full interactive architecture map - how parameters set through the EKS API reach the three control plane components
Figure 2. Full view of the interactive architecture map. Click the image to open the interactive version ↗ with node exploration, path tracing, and dark/light themes.

--References

Primary sources

Official documentation