고급 Kubernetes 제어 플레인 파라미터 구성하기
고급 Kubernetes 제어 플레인 파라미터 구성하기
AWS CLI와 AWS Management Console로 고급 Kubernetes 제어 플레인 파라미터를 설정하고 보는 방법을 안내해요. 각 파라미터의 설명과 클러스터에 미치는 효과는 Advanced Kubernetes control plane configuration을 참고해 주세요.
출처: 문서
본문
사전 조건 (Prerequisites)
시작하기 전에 다음 준비가 되어 있어야 해요:
- Kubernetes 버전 1.31 이상을 실행하는 Amazon EKS 클러스터 — 고급 Kubernetes 제어 플레인 구성은 Kubernetes 버전 1.31 이상을 실행하는 신규 및 기존 클러스터에서 지원돼요. 이 토픽의 모든 파라미터가 이 최소 버전을 공유해요.
- AWS CLI — Amazon EKS를 포함한 AWS 서비스 작업을 위한 명령줄 도구입니다. 자세한 내용은 AWS CLI 사용자 안내서의 Installing을 참고해 주세요. AWS CLI 설치 후 구성도 권장합니다. 자세한 내용은 AWS CLI 사용자 안내서의 Quick configuration with aws configure 참고.
- 필요한 IAM 권한 — 사용 중인 IAM 주체는 Amazon EKS 클러스터를 describe하고 update할 권한이 있어야 해요. 현재 주체를 확인하려면 다음 명령을 실행하세요:
aws sts get-caller-identity
참고: 이 토픽의 단계는 Bash 셸에서 완료할 것을 권장합니다. Bash 셸이 아니라면 줄 연속 문자와 변수 설정·사용 방식 같은 일부 스크립트 명령을 셸에 맞게 조정해야 해요. 셸의 따옴표와 이스케이프 규칙도 다를 수 있어요. 자세한 내용은 AWS CLI 사용자 안내서의 Using quotation marks with strings in the AWS CLI 참고.
이 토픽의 명령을 실행하기 전에 선호하는 클러스터 이름과 리전을 설정해 주세요:
export CLUSTER=my-eks-cluster
export AWS_REGION=us-west-2
지원 값 (Supported values)
Amazon EKS는 각 파라미터를 다음 범위에 대해 검증하고 범위 밖의 요청은 거부해요.
| 컴포넌트 파라미터 | 지원 값 | 기본값 |
|---|---|---|
kubeSchedulerConfig.nodeResourcesFit.scoringStrategy.type |
LeastAllocated, MostAllocated |
LeastAllocated |
kubeSchedulerConfig.nodeResourcesFit.scoringStrategy.resources[].weight |
1 ~ 100 |
cpu: 1, memory: 1 |
kubeControllerManagerConfig.horizontalPodAutoscalerControllerConfig.horizontalPodAutoscalerSyncPeriod |
10s ~ 15s |
15s |
kubeControllerManagerConfig.podGcControllerConfig.terminatedPodGcThreshold |
10000 ~ 12500 |
12500 |
kubeApiServerConfig.eventTtl |
10m ~ 60m |
60m |
kubeApiServerConfig.serviceNodePortRange.minPort |
10260 ~ 32767 |
30000 |
kubeApiServerConfig.serviceNodePortRange.maxPort |
10260 ~ 32767 |
32767 |
이 값은 게시 시점의 Kubernetes 버전에 적용되며 이후 버전에서 변경될 수 있어요. 특정 버전의 현재 값을 검색하려면 다음 섹션을 참고해 주세요.
Kubernetes 버전의 기본값과 지원 값 찾기 (Find the defaults and supported values for a Kubernetes version)
DescribeClusterVersions 작업은 각 Kubernetes 버전에 대해 모든 제어 플레인 파라미터의 기본값과 지원 값을 보고해요. 특히 클러스터 구성을 자동화하거나 여러 Kubernetes 버전의 클러스터를 관리한다면 하드코딩 대신 이 작업에서 값을 읽어 주세요.
aws eks describe-cluster-versions --cluster-versions 1.35
응답에는 제어 플레인 컴포넌트별로 구성된 controlPlaneComponentConfig 객체가 포함돼요. 각 파라미터는 defaultValue와 constraints 객체를 보고해요:
{
"clusterVersions": [
{
"clusterVersion": "1.35",
"clusterType": "eks",
"defaultVersion": false,
"releaseDate": "2026-01-23T00:00:00+00:00",
"endOfStandardSupportDate": "2027-03-23T00:00:00+00:00",
"endOfExtendedSupportDate": "2028-03-23T00:00:00+00:00",
"status": "STANDARD_SUPPORT",
"controlPlaneScalingTiers": [
{
"tierName": "tier-xl",
"apiRequestConcurrency": 2000,
"podSchedulingRatePerSecond": 167,
"clusterDatabaseSizeGb": 16
},
{
"tierName": "tier-2xl",
"apiRequestConcurrency": 4000,
"podSchedulingRatePerSecond": 283,
"clusterDatabaseSizeGb": 16
},
{
"tierName": "tier-4xl",
"apiRequestConcurrency": 8000,
"podSchedulingRatePerSecond": 400,
"clusterDatabaseSizeGb": 16
},
{
"tierName": "tier-8xl",
"apiRequestConcurrency": 16000,
"podSchedulingRatePerSecond": 400,
"clusterDatabaseSizeGb": 16
}
],
"controlPlaneComponentConfig": {
"kubeApiServerConfig": {
"eventTtl": {
"defaultValue": "60m",
"constraints": {
"min": "10m",
"max": "60m"
}
},
"serviceNodePortRange": {
"defaultValue": {
"minPort": 30000,
"maxPort": 32767
},
"constraints": {
"minPort": {"min": 10260, "max": 32767},
"maxPort": {"min": 10260, "max": 32767}
}
}
},
"kubeSchedulerConfig": {
"nodeResourcesFit": {
"scoringStrategy": {
"defaultValue": {
"type": "LeastAllocated",
"resources": [
{"name": "cpu", "weight": 1},
{"name": "memory", "weight": 1}
]
},
"constraints": {
"scoringStrategy": {
"allowedValues": ["LeastAllocated", "MostAllocated"]
},
"resources": {
"name": {
"allowedValues": [
"cpu",
"memory",
"nvidia.com/gpu",
"aws.amazon.com/neuron",
"aws.amazon.com/neuroncore"
]
},
"weight": {"min": 1, "max": 100}
}
}
}
}
},
"kubeControllerManagerConfig": {
"horizontalPodAutoscalerControllerConfig": {
"horizontalPodAutoscalerSyncPeriod": {
"defaultValue": "15s",
"constraints": {
"min": "10s",
"max": "15s"
}
}
},
"podGcControllerConfig": {
"terminatedPodGcThreshold": {
"defaultValue": 12500,
"constraints": {
"min": 10000,
"max": 12500
}
}
}
}
}
}
]
}
위 응답은 버전 지원 날짜, Provisioned Control Plane 스케일링 티어, 제어 플레인 구성 필드를 보여줘요. 자세한 내용은 Amazon EKS API 참조의 DescribeClusterVersions를 참고해 주세요.
구성 필드만 반환하려면 --query 옵션을 사용해 주세요:
aws eks describe-cluster-versions --cluster-versions 1.35 \
--query 'clusterVersions[0].controlPlaneComponentConfig'
제어 플레인 구성 - AWS CLI (Control plane configuration — AWS CLI)
각 제어 플레인 컴포넌트에는 자체 파라미터인 --kube-scheduler-config, --kube-controller-manager-config, --kube-api-server-config가 있어요. 사용자 지정하려는 컴포넌트만 지정하면 돼요. 각 파라미터는 인라인 JSON을 받아요.
제어 플레인 파라미터로 클러스터 만들기 (Create a cluster with control plane parameters)
다음 명령은 새 Kubernetes 이벤트를 기본 60분 대신 10분 동안 보존하는 클러스터를 만들어요. 지정하지 않은 파라미터는 기본값을 사용해요.
aws eks create-cluster \
--name "$CLUSTER" \
--kubernetes-version 1.35 \
--role-arn arn:aws:iam::111122223333:role/eks-service-role \
--resources-vpc-config subnetIds=subnet-abc123,subnet-def456,securityGroupIds=sg-xyz789 \
--kube-api-server-config '{
"eventTtl": "10m"
}'
응답:
{
"cluster": {
"name": "my-eks-cluster",
"arn": "arn:aws:eks:us-west-2:111122223333:cluster/my-eks-cluster",
"createdAt": 1709640000.0,
"version": "1.35",
"roleArn": "arn:aws:iam::111122223333:role/eks-service-role",
"status": "CREATING",
"kubeSchedulerConfig": {
"nodeResourcesFit": {
"scoringStrategy": {
"type": "LeastAllocated"
}
}
},
"kubeControllerManagerConfig": {
"horizontalPodAutoscalerControllerConfig": {
"horizontalPodAutoscalerSyncPeriod": "15s"
}
},
"kubeApiServerConfig": {
"eventTtl": "10m",
"serviceNodePortRange": {
"minPort": 30000,
"maxPort": 32767
}
}
}
}
클러스터의 제어 플레인 구성 보기 (View the control plane configuration for a cluster)
aws eks describe-cluster --name "$CLUSTER"
응답에는 kubeSchedulerConfig, kubeControllerManagerConfig, kubeApiServerConfig가 최상위 필드로 포함돼요. 이 필드는 항상 존재하며, 사용자 지정하지 않은 파라미터와 기본값을 포함해 제어 플레인에서 실행 중인 전체 구성을 보여줘요.
단일 컴포넌트의 구성을 반환하려면 --query 옵션을 사용해 주세요:
aws eks describe-cluster --name "$CLUSTER" \
--query 'cluster.kubeSchedulerConfig'
응답:
{
"nodeResourcesFit": {
"scoringStrategy": {
"type": "LeastAllocated"
}
}
}
스케줄러 스코어링 전략 구성하기 (Configure the scheduler scoring strategy)
기본적으로 스케줄러는 파드를 노드에 분산하는 LeastAllocated 전략을 사용해요. 다음 명령은 이미 높은 리소스 할당을 가진 노드를 선호하고 파드를 더 적은 노드에 패킹하는 MostAllocated로 변경해요.
aws eks update-cluster-config \
--name "$CLUSTER" \
--kube-scheduler-config '{
"nodeResourcesFit": {
"scoringStrategy": {
"type": "MostAllocated"
}
}
}'
응답:
{
"update": {
"id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"status": "InProgress",
"type": "ControlPlaneComponentConfigUpdate",
"params": [
{
"type": "kubeSchedulerConfig",
"value": "{\"nodeResourcesFit\":{\"scoringStrategy\":{\"type\":\"MostAllocated\"}}}"
}
],
"createdAt": 1709643600.0,
"errors": []
}
}
특정 리소스가 클러스터의 제약인 경우 유용한, 점수화 계산에서 개별 리소스에 가중치를 두는 resources 배열을 지정할 수도 있어요. 자세한 내용은 Advanced Kubernetes control plane configuration 참고.
다른 제어 플레인 파라미터도 각자의 컴포넌트 플래그(eventTtl과 serviceNodePortRange는 --kube-api-server-config, Horizontal Pod Autoscaler 동기화 주기는 --kube-controller-manager-config)로 같은 패턴을 따라요. 각 파라미터가 무엇을 하고 변경 전 고려 사항은 Advanced Kubernetes control plane configuration 참고.
한 번에 여러 컴포넌트 업데이트하기 (Update more than one component at a time)
단일 호출에서 여러 컴포넌트 파라미터를 지정할 수 있어요:
aws eks update-cluster-config \
--name "$CLUSTER" \
--kube-scheduler-config '{"nodeResourcesFit":{"scoringStrategy":{"type":"MostAllocated"}}}' \
--kube-api-server-config '{"eventTtl":"30m"}'
업데이트는 기존 구성과 병합돼요. 지정한 필드만 변경되고 생략한 필드는 현재 값을 유지해요. 위 명령은 컨트롤러 매니저 구성을 변경하지 않아요.
제어 플레인 구성 업데이트 모니터링하기 (Monitor a control plane configuration update)
update-cluster-config가 반환될 때 구성 변경이 적용된 상태가 아니에요. Amazon EKS는 제어 플레인의 롤링 업데이트를 통해 새 구성을 적용하며, 이는 몇 분이 걸립니다. 변경이 완료될 때까지 차단하려면:
aws eks wait cluster-active --name "$CLUSTER"
이 명령은 클러스터가 ACTIVE 상태에 도달하면 반환되며, 일반적으로 몇 분 안에 반환돼요.
클러스터의 업데이트를 나열하려면:
aws eks list-updates --name "$CLUSTER"
응답:
{
"updateIds": [
"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"
]
}
특정 업데이트의 상태를 보려면:
aws eks describe-update --name "$CLUSTER" \
--update-id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
업데이트가 완료되면 상태가 InProgress에서 Successful로 바뀌고, 오류가 발생하면 Failed로 바뀌어요. errors 필드가 실패 이유를 나타내요.
제어 플레인 구성 - AWS Management Console (Control plane configuration — AWS Management Console)
클러스터를 만들 때 고급 Kubernetes 제어 플레인 파라미터를 구성하려면:
- Amazon EKS 콘솔을 엽니다.
- Create cluster를 선택합니다.
- Configuration options에서 Custom configuration을 선택합니다.
- Control plane configuration까지 아래로 스크롤합니다.
- Enable control plane configuration을 선택합니다.
- 구성할 파라미터를 설정합니다. 변경하지 않은 파라미터는 기본값을 사용해요.
- 필요에 따라 다른 클러스터 구성 옵션을 선택합니다. 마지막 단계에서 Create cluster를 선택합니다. 클러스터 생성 완료는 몇 분이 걸릴 수 있어요.
기존 클러스터에서 고급 Kubernetes 제어 플레인 파라미터를 구성하려면:
- Amazon EKS 콘솔을 엽니다.
- 업데이트할 클러스터를 선택합니다.
- Overview 탭을 선택한 다음 Control plane configuration까지 아래로 스크롤합니다.
- Manage를 선택한 다음 Enable control plane configuration을 선택해 변경할 파라미터를 설정합니다. 그런 다음 Save changes를 선택합니다.