EKS Hybrid Nodes 게이트웨이 시작하기

EKS Hybrid Nodes 게이트웨이 시작하기 (Get started with EKS Hybrid Nodes gateway)

이 페이지는 Amazon EKS Hybrid Nodes 게이트웨이의 사전 요구 사항, 환경 준비, 설치, 확인, 제거를 안내해요. 게이트웨이와 그 아키텍처에 대한 소개는 Amazon EKS Hybrid Nodes 게이트웨이를 참고하세요.

출처: 문서

본문

사전 요구 사항 (Prerequisites)

Hybrid Nodes 게이트웨이를 설치하기 전에 환경이 다음 요구사항을 충족하는지 확인하세요.

  • Cilium CNI 및 VTEP 지원이 있는 EKS 클러스터 – EKS 클러스터는 하이브리드 노드의 CNI로 EKS 버전의 Cilium을 사용해야 하며, Cilium VTEP가 활성화되어 있어야 해요. 자세한 내용은 하이브리드 노드 게이트웨이용 CNI 구성하기를 참고하세요.
  • 클라우드 노드의 AWS VPC CNI – 게이트웨이 노드와 클러스터의 다른 클라우드 노드는 AWS VPC CNI를 사용해야 해요. 게이트웨이는 VPC와 VXLAN 터널 사이의 트래픽을 전달하기 위해 VPC 네이티브 라우팅에 의존해요.
  • 하이브리드 연결 – VPC와 온프레미스 환경 사이의 프라이빗 연결이 필요해요. AWS Direct Connect, AWS Site-to-Site VPN, 또는 자체 VPN 솔루션을 사용할 수 있어요. 자세한 내용은 하이브리드 노드용 네트워킹 준비하기를 참고하세요.
  • VXLAN 트래픽 허용 – 게이트웨이 EC2 인스턴스에 연결된 보안 그룹은 포트 8472의 인바운드 및 아웃바운드 UDP 트래픽을 허용해야 해요. 하이브리드 노드 쪽에서는 온프레미스 방화벽 규칙도 게이트웨이 노드 IP 주소와의 UDP 8472 포트 트래픽을 허용해야 해요.
  • 라우팅 테이블 관리를 위한 IAM 권한 – 게이트웨이는 VPC 라우팅 테이블을 관리하기 위해 다음 EC2 작업이 필요해요.
    • ec2:DescribeRouteTables
    • ec2:CreateRoute
    • ec2:ReplaceRoute
    • ec2:DescribeInstances
  • EKS Auto Mode(게이트웨이 노드에 Auto Mode를 사용하는 경우) – EKS Auto Mode로 게이트웨이 노드를 프로비저닝하려면 EKS 클러스터에서 Auto Mode가 활성화되어 있어야 해요. 자세한 내용은 EKS Auto Mode 활성화하기를 참고하세요.

게이트웨이 노드 준비

게이트웨이는 고가용성을 위해 최소 2개의 EC2 노드가 필요해요. 게이트웨이에는 두 가지 지원되는 노드 구성 옵션이 있어요.

  • EKS Auto Mode(권장) – 노드는 NodePool과 NodeClass를 사용해 자동으로 프로비저닝돼요. 소스/대상 확인(check), 레이블, taint가 모두 선언적으로 구성돼요.
  • 관리형 노드 그룹 – 관리형 노드 그룹 또는 자체 관리형 노드를 사용해 노드를 프로비저닝해요. 레이블은 관리형 노드 그룹 API로 구성할 수 있고, 소스/대상 확인은 사용자 데이터가 있는 커스텀 launch template으로 비활성화할 수 있어요.

EKS Auto Mode(권장)

EKS Auto Mode를 사용할 때는 Helm 차트를 설치하기 전에 NodePool과 NodeClass를 만들어야 해요. NodePool은 올바른 레이블, taint, 소스/대상 확인 구성으로 EC2 인스턴스를 프로비저닝해요. 노드를 수동으로 프로비저닝하거나 구성할 필요가 없어요.

자리 표시자 값을 바꿔 다음 리소스를 클러스터에 적용하세요.

  • YOUR_NODE_ROLE – EKS Auto Mode가 노드를 프로비저닝하는 데 사용하는 Node IAM Role의 이름. 클러스터에서 Auto Mode를 활성화할 때 구성한(또는 EKS가 만든) 역할이에요. 자세한 내용은 EKS Auto Mode용 Node IAM Role 생성을 참고하세요.
  • YOUR_CLUSTER_NAME – EKS 클러스터 이름.
  • SUBNET_ID_1, SUBNET_ID_2 – 게이트웨이 노드가 프로비저닝될 서로 다른 가용 영역의 서브넷 ID.
apiVersion: eks.amazonaws.com/v1
kind: NodeClass
metadata:
  name: hybrid-gateway
spec:
  advancedNetworking:
    sourceDestCheck: DisabledPrimaryENI
  role: YOUR_NODE_ROLE
  securityGroupSelectorTerms:
    - tags:
        aws:eks:cluster-name: YOUR_CLUSTER_NAME
  subnetSelectorTerms:
    - id: SUBNET_ID_1
    - id: SUBNET_ID_2
---
apiVersion: karpenter.sh/v1
kind: NodePool
metadata:
  name: hybrid-gateway
spec:
  template:
    metadata:
      labels:
        hybrid-gateway-node: "true"
    spec:
      expireAfter: 336h
      nodeClassRef:
        group: eks.amazonaws.com
        kind: NodeClass
        name: hybrid-gateway
      requirements:
        - key: karpenter.sh/capacity-type
          operator: In
          values:
            - on-demand
        - key: eks.amazonaws.com/instance-category
          operator: In
          values:
            - c
            - m
            - r
        - key: eks.amazonaws.com/instance-generation
          operator: Gt
          values:
            - "4"
        - key: kubernetes.io/arch
          operator: In
          values:
            - amd64
        - key: kubernetes.io/os
          operator: In
          values:
            - linux
      taints:
        - key: hybrid-gateway-node
          effect: NoSchedule
      terminationGracePeriod: 24h0m0s
  disruption:
    budgets:
      - nodes: 10%
    consolidateAfter: 30s
    consolidationPolicy: WhenEmptyOrUnderutilized

이 구성의 주요 필드:

  • advancedNetworking.sourceDestCheck: DisabledPrimaryENI – 노드의 기본 ENI에서 EC2 소스/대상 확인을 비활성화해 게이트웨이가 자기 자신에게 주소가 지정되지 않은 트래픽을 전달할 수 있게 해요.
  • taints – hybrid-gateway-node: NoSchedule taint는 일치하는 허용(toleration)이 있는 게이트웨이 Pod만 이 노드에 스케줄링되도록 보장해요.
  • labels – hybrid-gateway-node: "true" 레이블은 Helm 차트의 노드 선택기가 게이트웨이 Pod를 이 노드로 타겟팅하는 데 사용해요.
  • nodeClassRef – NodePool을 소스/대상 확인 구성이 있는 NodeClass에 연결해요.

관리형 노드 그룹

관리형 노드 그룹을 사용할 때는 필요한 레이블, taint, 그리고 시작 시 소스/대상 확인을 비활성화하는 커스텀 launch template으로 게이트웨이 전용 노드 그룹을 만들어요.

1단계: Launch template 생성

인스턴스 부팅 시 기본 ENI의 소스/대상 확인을 비활성화하는 사용자 데이터가 있는 launch template을 만들세요.

# Create the launch template with user data to disable source/dest check
USERDATA=$(cat ...

참고

사용자 데이터 스크립트가 성공하려면 노드의 IAM 역할에 ec2:ModifyNetworkInterfaceAttribute 권한이 있어야 해요. MIME multipart 형식은 사용자 데이터가 EKS 부트스트랩 스크립트와 함께 실행되도록 보장해요.

2단계: 관리형 노드 그룹 생성

1단계의 launch template과 함께 게이트웨이 레이블, taint가 있는 전용 관리형 노드 그룹을 만드세요.

aws eks create-nodegroup \
  --cluster-name YOUR_CLUSTER_NAME \
  --nodegroup-name YOUR_CLUSTER_NAME-gateway-nodes \
  --subnets SUBNET_ID_1 SUBNET_ID_2 \
  --node-role YOUR_NODE_ROLE_ARN \
  --instance-types INSTANCE_TYPE \
  --ami-type AL2023_x86_64_STANDARD \
  --scaling-config desiredSize=2,maxSize=2,minSize=2 \
  --labels hybrid-gateway-node=true \
  --taints "key=hybrid-gateway-node,effect=NO_SCHEDULE" \
  --launch-template "name=YOUR_CLUSTER_NAME-gateway-lt,version=1"

이렇게 하면 2노드 관리형 노드 그룹이 만들어지며, 여기서:

  • --labels는 hybrid-gateway-node=true를 설정해 Helm 차트의 노드 선택기가 이 노드를 타겟팅하게 해요.
  • --taints는 NoSchedule taint를 추가해 일치하는 허용(toleration)이 있는 게이트웨이 Pod만 이 노드에 스케줄링되도록 해요.
  • --launch-template은 부팅 시 소스/대상 확인을 비활성화하는 launch template을 연결해요.

고가용성을 위해 서로 다른 가용 영역의 서브넷을 사용하세요.

Helm으로 설치

EKS Auto Mode

다음 명령으로 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

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

관리형 노드 그룹이나 자체 관리형 노드의 경우 autoMode.enabled=false를 설정하세요.

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

필수 Helm 값

모든 설치에 필요한 값은 다음과 같아요.

값 설명
vpcCIDR EKS 클러스터 VPC의 CIDR 블록(예: 10.0.0.0/16). Cilium VTEP 구성에 사용되어 하이브리드 노드가 VPC로 향하는 트래픽을 게이트웨이를 통해 라우팅하게 해요.
podCIDRs 하이브리드 노드의 Cilium이 사용하는 Pod CIDR 목록(쉼표 구분, 예: 10.100.0.0/16,10.101.0.0/16). 게이트웨이는 이 CIDR에 대한 VPC 라우팅 테이블 항목과 VXLAN 경로를 만들어요.
routeTableIDs 프로그래밍할 VPC 라우팅 테이블 ID 목록(쉼표 구분, 예: rtb-0abc1234def567890,rtb-0fed9876cba543210). 게이트웨이는 이 테이블에 하이브리드 Pod CIDR을 활성 게이트웨이 인스턴스로 가리키는 경로를 만들어요.

구성 가능한 값의 전체 목록은 Amazon EKS Hybrid Nodes 게이트웨이 구성 참조를 참고하세요.

설치 확인

게이트웨이를 설치한 후 실행 중이고 정상인지 확인하세요.

Pod 상태 확인

두 개의 게이트웨이 Pod가 실행 중인지 확인하세요.

kubectl get pods -n eks-hybrid-nodes-gateway

다음과 유사한 출력이 보여야 해요.

NAME                                        READY   STATUS    RESTARTS   AGE
eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12   1/1     Running   0          2m
eks-hybrid-nodes-gateway-5d4f6a7b8c-def34   1/1     Running   0          2m

리더 선출 확인

한 Pod가 리더 선출 리스를 획득했는지 확인하세요.

kubectl get lease -n eks-hybrid-nodes-gateway

출력은 HOLDER 열에 현재 리더를 보여줘요.

NAME                     HOLDER                                      AGE
hybrid-gateway-leader    eks-hybrid-nodes-gateway-5d4f6a7b8c-abc12   2m

상태 엔드포인트 확인

포트 포워딩을 사용해 리더 Pod의 상태 엔드포인트가 응답하는지 확인하세요.

kubectl port-forward -n eks-hybrid-nodes-gateway LEADER_POD_NAME 8088:8088 &
curl -s http://localhost:8088/healthz

정상 게이트웨이는 HTTP 200 응답을 반환해요.

VPC 라우팅 테이블 항목 확인

Amazon VPC 콘솔 또는 AWS CLI에서 VPC 라우팅 테이블에 리더 게이트웨이 인스턴스의 ENI를 가리키는 하이브리드 Pod CIDR 항목이 있는지 확인하세요.

aws ec2 describe-route-tables \
  --route-table-ids ROUTE_TABLE_ID \
  --query "RouteTables[].Routes[?DestinationCidrBlock=='POD_CIDR']"

각 하이브리드 Pod CIDR에는 NetworkInterfaceId가 리더 인스턴스의 기본 ENI로 설정된 경로가 있어야 해요.

제거

Hybrid Nodes 게이트웨이를 제거하려면 다음을 실행하세요.

helm uninstall eks-hybrid-nodes-gateway --namespace eks-hybrid-nodes-gateway

참고

Helm 차트를 제거해도 게이트웨이가 만든 VPC 라우팅 테이블 항목은 자동으로 제거되지 않아요. 제거 후 더 이상 게이트웨이를 실행하지 않는 인스턴스로 트래픽이 라우팅되지 않도록 VPC 라우팅 테이블에서 하이브리드 Pod CIDR에 대한 경로를 수동으로 삭제하세요. AWS CLI로 경로를 제거할 수 있어요.

aws ec2 delete-route \
  --route-table-id ROUTE_TABLE_ID \
  --destination-cidr-block POD_CIDR

다음 단계

  • Amazon EKS Hybrid Nodes 게이트웨이 구성 참조 – Helm 값, CLI 플래그, 리더 선출 매개변수 커스터마이징.
  • Amazon EKS Hybrid Nodes 게이트웨이 운영 – 게이트웨이 모니터링, 장애 조치 동작 이해, 확장 계획.
  • Amazon EKS Hybrid Nodes 게이트웨이 문제 해결 – 일반적인 문제 진단 및 해결.

더 알아보기 (Learn more)