이 페이지 개선에 도움 주기

이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 GitHub에서 이 페이지 편집 링크를 선택합니다.

고급 Kubernetes 컨트롤 플레인 파라미터 구성

이 가이드에서는 AWS CLI 및 AWS Management Console을 사용하여 고급 Kubernetes 컨트롤 플레인 파라미터를 설정하고 보는 방법을 안내합니다. 각 파라미터와 클러스터에 미치는 영향에 대한 설명은 고급 Kubernetes 컨트롤 플레인 구성 섹션을 참조하세요.

사전 조건

이 자습서를 시작하기 전에 다음 사항을 갖췄는지 확인하세요.

이 주제에서 명령을 실행하기 전에 원하는 클러스터 이름과 리전을 설정합니다.

export CLUSTER=my-eks-cluster
export AWS_REGION=us-west-2

지원되는 값

Amazon EKS는 다음 범위에 대해 각 파라미터를 검증하고 범위를 벗어난 요청을 거부합니다.

이러한 값은 게시 시점에 사용 가능한 Kubernetes 버전에 적용되며 이후 버전에서 변경될 수 있습니다. 특정 버전의 최신 값을 검색하려면 다음 섹션을 참조하세요.

Kubernetes 버전의 기본값 및 지원되는 값 찾기

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
                            }
                        }
                    }
                }
            }
        }
    ]
}

이전 응답에서는 버전 지원 날짜, 프로비저닝된 컨트롤 플레인 규모 조정 티어 및 컨트롤 플레인 구성 필드를 보여줍니다. 자세한 내용은 Amazon EKS API 참조의 DescribeClusterVersions를 참조하세요.

구성 필드만 반환하려면 --query 옵션을 사용합니다.

aws eks describe-cluster-versions --cluster-versions 1.35 \
--query 'clusterVersions[0].controlPlaneComponentConfig'

컨트롤 플레인 구성 - AWS CLI

각 컨트롤 플레인 구성 요소에는 --kube-scheduler-config, --kube-controller-manager-config 및 --kube-api-server-config와 같은 고유한 파라미터가 있습니다. 사용자 지정하려는 구성 요소만 지정합니다. 각 파라미터는 인라인 JSON을 허용합니다.

컨트롤 플레인 파라미터를 사용하여 클러스터 생성

다음 명령은 기본 60분 대신 10분 동안 새 Kubernetes 이벤트를 유지하는 클러스터를 생성합니다. 사용자가 지정하지 않은 파라미터는 기본값을 사용합니다.

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
            }
        }
    }
}

클러스터의 컨트롤 플레인 구성 보기

aws eks describe-cluster --name "$CLUSTER"

응답에는 kubeSchedulerConfig, kubeControllerManagerConfig 및 kubeApiServerConfig가 최상위 필드로 포함됩니다. 이러한 필드는 항상 존재하며, 사용자 지정하지 않은 파라미터와 해당 기본값을 포함하여 컨트롤 플레인에서 실행되는 전체 구성을 보여줍니다.

단일 구성 요소에 대한 구성을 반환하려면 --query 옵션을 사용합니다.

aws eks describe-cluster --name "$CLUSTER" \
--query 'cluster.kubeSchedulerConfig'

응답:

{
    "nodeResourcesFit": {
        "scoringStrategy": {
            "type": "LeastAllocated"
        }
    }
}

스케줄러 점수 책정 전략 구성

기본적으로 스케줄러는 여러 노드 간에 포드를 분산하는 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 배열을 지정할 수도 있습니다. 특정 리소스가 클러스터의 제약 조건일 때 유용합니다. 자세한 내용은 고급 Kubernetes 컨트롤 플레인 구성 섹션을 참조하세요.

다른 컨트롤 플레인 파라미터는 동일한 패턴을 따르며, 각각 자체 구성 요소 플래그를 사용합니다. 즉, eventTtl 및 serviceNodePortRange의 경우 --kube-api-server-config, Horizontal Pod Autoscaler 동기화 기간의 경우 --kube-controller-manager-config입니다. 각 파라미터가 수행하는 작업과 변경하기 전 고려 사항은 고급 Kubernetes 컨트롤 플레인 구성 섹션을 참조하세요.

한 번에 두 개 이상의 구성 요소 업데이트

한 번의 직접 호출로 여러 구성 요소 파라미터를 지정할 수 있습니다.

aws eks update-cluster-config \
--name "$CLUSTER" \
--kube-scheduler-config '{"nodeResourcesFit":{"scoringStrategy":{"type":"MostAllocated"}}}' \
--kube-api-server-config '{"eventTtl":"30m"}'

업데이트는 기존 구성과 병합됩니다. 지정한 필드만 변경되고 생략한 필드는 현재 값을 유지합니다. 위의 명령은 컨트롤러 관리자 구성을 변경하지 않은 상태로 둡니다.

컨트롤 플레인 구성 업데이트 모니터링

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

클러스터를 생성할 때 고급 Kubernetes 컨트롤 플레인 파라미터를 구성하는 방법:

기존 클러스터에서 고급 Kubernetes 컨트롤 플레인 파라미터를 구성하는 방법: