Amazon EKS Hybrid Nodes 게이트웨이 구성 참조

Amazon EKS Hybrid Nodes 게이트웨이 구성 참조 (Amazon EKS Hybrid Nodes gateway configuration reference)

이 페이지는 Amazon EKS Hybrid Nodes 게이트웨이의 모든 구성 가능한 매개변수를 문서화해요. 설치 지침은 EKS Hybrid Nodes 게이트웨이 시작하기를, 게이트웨이 개요는 Amazon EKS Hybrid Nodes 게이트웨이를 참고하세요.

출처: 문서

본문

Helm 차트 값 (Helm chart values)

다음 표는 eks-hybrid-nodes-gateway Helm 차트의 모든 값을 나열해요. helm install 또는 helm upgrade 중 --set 플래그나 커스텀 values.yaml 파일로 이 값을 설정할 수 있어요.

값	유형	기본값	필수	설명
`image.repository`	string	`public.ecr.aws/eks/eks-hybrid-nodes-gateway`	아니요	게이트웨이 이미지의 컨테이너 이미지 저장소. 기본값은 공용 Amazon ECR 레지스트리.
`image.tag`	string	차트 `appVersion`	아니요	이미지 태그. 기본값은 `Chart.yaml`에 정의된 `appVersion`.
`image.pullPolicy`	string	`IfNotPresent`	아니요	이미지 가져오기 정책. 유효한 값: `Always`, `IfNotPresent`, `Never`.
`replicas`	integer	`2`	아니요	게이트웨이 Pod 복제본 수. 프로덕션 환경의 고가용성을 위해 2개 복제본을 권장.
`nodeLabel`	string	`hybrid-gateway-node`	아니요	게이트웨이 노드를 선택하는 데 사용하는 노드 레이블 키. 노드는 이 레이블이 `"true"`로 설정되어 있어야 해요.
`vpcCIDR`	string	`""`	예	Cilium VTEP 구성에 사용되는 VPC CIDR 블록. 예: `10.0.0.0/16`.
`podCIDRs`	string	`""`	예	하이브리드 노드의 Cilium이 사용하는 Pod CIDR 목록(쉼표 구분). 예: `10.85.0.0/16,10.86.0.0/16`.
`routeTableIDs`	string	`""`	예	하이브리드 Pod 경로를 프로그래밍할 VPC 라우팅 테이블 ID 목록(쉼표 구분). 예: `rtb-0123456789abcdef0,rtb-0123456789abcdef1`.
`autoMode.enabled`	boolean	`true`	아니요	EKS Auto Mode 통합 활성화. `true`이면 차트가 `eks.amazonaws.com/compute-type: auto` 노드 선택기를 추가하고 무중단 롤링 업데이트 전략을 사용해요. 관리형 노드 그룹이나 자체 관리형 노드에는 `false`로 설정하세요.

예시 설치 명령

EKS Auto Mode(기본값):

helm install eks-hybrid-nodes-gateway oci://public.ecr.aws/eks/eks-hybrid-nodes-gateway \
  --version 1.0.0 \
  --namespace eks-hybrid-nodes-gateway \
  --create-namespace \
  --set vpcCIDR=VPC_CIDR \
  --set podCIDRs=POD_CIDRS \
  --set routeTableIDs=ROUTE_TABLE_IDS

관리형 노드 그룹 또는 자체 관리형 노드:

helm install eks-hybrid-nodes-gateway oci://public.ecr.aws/eks/eks-hybrid-nodes-gateway \
  --version 1.0.0 \
  --namespace eks-hybrid-nodes-gateway \
  --create-namespace \
  --set autoMode.enabled=false \
  --set vpcCIDR=VPC_CIDR \
  --set podCIDRs=POD_CIDRS \
  --set routeTableIDs=ROUTE_TABLE_IDS

Auto Mode vs. 관리형 노드 그룹 구성

autoMode.enabled Helm 값은 Deployment 템플릿에서 두 가지 동작을 제어해요.

동작	`autoMode.enabled=true` (기본값)	`autoMode.enabled=false`
노드 선택기	게이트웨이 노드 레이블에 더해 `eks.amazonaws.com/compute-type: auto`를 추가해요.	게이트웨이 노드 레이블(`hybrid-gateway-node: "true"`)만 사용해요.
롤링 업데이트 전략	`maxSurge: 1`, `maxUnavailable: 0` — 이전 Pod를 종료하기 전에 새 Pod를 시작해 업그레이드 중 무중단을 보장해요.	`maxSurge: 0`, `maxUnavailable: 1` — 노드 용량이 사전 프로비저닝되므로 새 Pod를 시작하기 전에 이전 Pod를 종료해요.

EKS Auto Mode를 사용할 때는 Helm 차트를 설치하기 전에 NodePool과 NodeClass를 만들어야 해요. NodePool은 올바른 레이블, taint, 소스/대상 확인 구성으로 EC2 인스턴스를 프로비저닝해요. 필요한 YAML은 EKS Hybrid Nodes 게이트웨이 시작하기를 참고하세요. 관리형 노드 그룹이나 자체 관리형 노드를 사용할 때는 차트를 설치하기 전에 노드를 직접 프로비저닝하고 레이블을 지정해야 해요.

모든 배포 대상에서 Deployment는 hostNetwork: true를 사용하며 NET_ADMIN 기능(capability)이 필요해요. Pod anti-affinity는 두 게이트웨이 Pod가 별도의 노드에서 실행되도록 보장해요.

리더 선출 튜닝 (Leader election tuning)

게이트웨이는 Kubernetes Lease 기반 리더 선출을 사용해 active-standby 모델을 유지해요. 기본 매개변수는 빠른 장애 조치(failover)에 맞게 튜닝되어 있어요.

매개변수	기본값	설명
`--leader-election-lease-duration`	`3s`	리더가 아닌 노드가 마지막으로 관찰한 리스 갱신 후 리스를 획득하려 시도하기 전에 대기하는 시간. 값이 낮을수록 리더 실패를 더 빨리 감지하지만 일시적인 네트워크 문제 중 가짜 장애 조치 위험이 커져요.
`--leader-election-renew-deadline`	`2s`	액티브 리더가 리더십을 포기하기 전에 리스를 갱신하려 시도하는 최대 시간. 리스 기간보다 작아야 해요.
`--leader-election-retry-period`	`1s`	후보자가 리스 획득 또는 갱신을 재시도하는 빈도.

기본값과 함께 액티브 게이트웨이에 장애가 발생했을 때 예상 장애 조치 시간은 약 3~5초예요. 여기에는 대기가 리스 만료를 감지하고, 리스를 획득하고, 리더 설정 시퀀스(VPC 라우팅 테이블 업데이트와 Cilium VTEP 구성)를 실행하는 시간이 포함돼요.

리더 선출 매개변수를 조정할 때:

게이트웨이 Pod와 Kubernetes API 서버 사이의 일시적인 네트워크 지연으로 잦은 리더 전환을 관찰한다면 리스 기간을 늘리세요.
더 빠른 장애 조치 감지가 필요하고 게이트웨이 노드와 API 서버 사이의 네트워크가 안정적이고 지연 시간이 낮다면 리스 기간을 줄이세요.
대형 클러스터에서 리더 선출로 인한 API 서버 부하를 줄이려면 재시도 주기를 늘리세요.

참고

--leader-election-renew-deadline은 항상 --leader-election-lease-duration보다 작아야 해요. 갱신 마감이 리스 기간을 초과하면 리더는 갱신하기 전에 리스를 잃을 수 있어요.

Amazon EKS Hybrid Nodes 게이트웨이
EKS Hybrid Nodes 게이트웨이 시작하기
Amazon EKS Hybrid Nodes 게이트웨이 운영
Amazon EKS Hybrid Nodes 게이트웨이 문제 해결

더 알아보기 (Learn more)

공식 문서

Amazon EKS Hybrid Nodes 게이트웨이 구성 참조