**이 페이지 개선에 도움 주기** 

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

# EKS Hybrid Nodes 게이트웨이 시작하기
<a name="hybrid-nodes-gateway-getting-started"></a>

이 페이지에서는 Amazon EKS Hybrid Nodes 게이트웨이의 사전 조건, 환경 준비, 설치, 확인 및 제거를 안내합니다. 게이트웨이 및 해당 아키텍처에 대한 소개는 [Amazon EKS Hybrid Nodes 게이트웨이](hybrid-nodes-gateway-overview.md) 섹션을 참조하세요.

## 사전 조건
<a name="hybrid-nodes-gateway-prerequisites"></a>

Hybrid Nodes 게이트웨이를 설치하기 전에 환경이 다음 요구 사항을 충족하는지 확인합니다.
+  **Cilium CNI 및 VTEP 지원을 포함하는 EKS 클러스터** - EKS 클러스터는 하이브리드 노드의 CNI로 Cilium의 EKS 버전을 사용해야 하며, Cilium VTEP를 활성화해야 합니다. 자세한 내용은 [하이브리드 노드 게이트웨이에 대해 CNI 구성](hybrid-nodes-gateway-cni.md) 섹션을 참조하세요.
+  **클라우드 노드의 AWS VPC CNI** - 클러스터의 게이트웨이 노드 및 기타 클라우드 노드는 AWS VPC CNI를 사용해야 합니다. 게이트웨이는 VPC 네이티브 라우팅을 사용하여 VPC 및 VXLAN 터널 간 트래픽을 전달합니다.
+  **하이브리드 연결** - VPC 및 온프레미스 환경 간 프라이빗 연결이 필요합니다. AWS Direct Connect, AWS Site-to-Site VPN 또는 자체 VPN 솔루션을 사용할 수 있습니다. 자세한 내용은 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md) 섹션을 참조하세요.
+  **VXLAN 트래픽 허용됨** - 게이트웨이 EC2 인스턴스에 연결된 보안 그룹은 포트 8472에서 인바운드 및 아웃바운드 UDP 트래픽을 허용해야 합니다. 하이브리드 노드 측에서 온프레미스 방화벽 규칙은 게이트웨이 노드 IP 주소에서 송수신되는 UDP 포트 8472 트래픽도 허용해야 합니다.
+  **라우팅 테이블 관리에 대한 IAM 권한** - VPC 라우팅 테이블을 관리하려면 게이트웨이에 다음과 같은 EC2 작업이 필요합니다.
  +  `ec2:DescribeRouteTables` 
  +  `ec2:CreateRoute` 
  +  `ec2:ReplaceRoute` 
  +  `ec2:DescribeInstances` 

    다음 접근 방식 중 하나를 사용하여 이러한 권한을 부여할 수 있습니다.

------
#### [ EKS Pod Identity (recommended) ]

    [EKS Pod Identity](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html)를 사용하여 게이트웨이 포드의 서비스 계정에만 권한을 부여합니다.

    1. 아직 설치하지 않은 경우 클러스터에 EKS Pod Identity Agent 추가 기능을 설치하세요.

       ```
       aws eks create-addon \
         --cluster-name {{CLUSTER_NAME}} \
         --addon-name eks-pod-identity-agent
       ```

    1. 필요한 EC2 권한 및 EKS Pod Identity에 대한 신뢰 정책을 사용하여 IAM 역할을 생성하세요.

       ```
       cat > gateway-trust-policy.json << 'EOF'
       {
         "Version": "2012-10-17" 		 	 	 ,
         "Statement": [
           {
             "Effect": "Allow",
             "Principal": { "Service": "pods.eks.amazonaws.com" },
             "Action": ["sts:AssumeRole", "sts:TagSession"]
           }
         ]
       }
       EOF
       
       aws iam create-role \
         --role-name EKSHybridNodesGatewayRole \
         --assume-role-policy-document file://gateway-trust-policy.json
       
       aws iam put-role-policy \
         --role-name EKSHybridNodesGatewayRole \
         --policy-name HybridNodesGatewayRouteTable \
         --policy-document '{
           "Version": "2012-10-17" 		 	 	 ,
           "Statement": [{
             "Effect": "Allow",
             "Action": [
               "ec2:DescribeRouteTables",
               "ec2:CreateRoute",
               "ec2:ReplaceRoute",
               "ec2:DescribeInstances"
             ],
             "Resource": "*"
           }]
         }'
       ```

    1. IAM 역할을 게이트웨이 서비스 계정에 연결하는 Pod Identity 연결을 생성하세요.

       ```
       aws eks create-pod-identity-association \
         --cluster-name {{CLUSTER_NAME}} \
         --namespace eks-hybrid-nodes-gateway \
         --service-account eks-hybrid-nodes-gateway \
         --role-arn {{arn:aws:iam::ACCOUNT_ID:role/EKSHybridNodesGatewayRole}}
       ```

------
#### [ Node IAM role ]

    게이트웨이 노드의 인스턴스 프로파일과 연결된 IAM 역할에 필요한 권한을 사용하여 인라인 또는 관리형 정책을 연결합니다.

    ```
    aws iam put-role-policy \
      --role-name {{NODE_ROLE_NAME}} \
      --policy-name HybridNodesGatewayRouteTable \
      --policy-document '{
        "Version": "2012-10-17" 		 	 	 ,
        "Statement": [{
          "Effect": "Allow",
          "Action": [
            "ec2:DescribeRouteTables",
            "ec2:CreateRoute",
            "ec2:ReplaceRoute",
            "ec2:DescribeInstances"
          ],
          "Resource": "*"
        }]
      }'
    ```

    게이트웨이 노드의 모든 포드에는 이러한 권한이 있습니다.

------
+  **EKS 자율 모드(게이트웨이 노드에 자율 모드를 사용하는 경우)** - EKS 자율 모드를 사용하여 게이트웨이 노드를 프로비저닝하려는 경우 EKS 클러스터에서 자율 모드를 활성화해야 합니다. 자세한 내용은 [EKS 자율 모드 활성화](https://docs.aws.amazon.com/eks/latest/userguide/migrate-auto.html)를 참조하세요.

## 게이트웨이 노드 준비
<a name="hybrid-nodes-gateway-prepare-nodes"></a>

게이트웨이에는 고가용성을 위해 2개 이상의 EC2 노드가 필요합니다. 다음과 같이 게이트웨이에 대해 지원되는 두 가지 노드 구성 옵션이 있습니다.
+  [EKS 자율 모드(권장)](#hybrid-nodes-gateway-auto-mode-nodes) - 노드는 `NodePool` 및 `NodeClass`를 사용하여 자동으로 프로비저닝됩니다. 소스/대상 확인, 레이블 및 테인트는 모두 선언 방식으로 구성됩니다.
+  [관리형 노드 그룹](#hybrid-nodes-gateway-mng-nodes) - 사용자가 관리형 노드 그룹 또는 자체 관리형 노드를 사용하여 노드를 프로비저닝합니다. 관리형 노드 그룹 API를 통해 레이블을 구성할 수 있으며, 사용자 데이터가 포함된 사용자 지정 시작 템플릿을 사용하여 소스/대상 확인을 비활성화할 수 있습니다.

### EKS 자율 모드(권장)
<a name="hybrid-nodes-gateway-auto-mode-nodes"></a>

EKS 자율 모드를 사용하는 경우 헬름 차트를 설치하기 전에 `NodePool` 및 `NodeClass`를 생성해야 합니다. NodePool은 올바른 레이블, 테인트 및 소스/대상 확인 구성을 통해 EC2 인스턴스를 프로비저닝합니다. 노드를 수동으로 프로비저닝하거나 구성할 필요가 없습니다.

다음 리소스를 클러스터에 적용하여 자리 표시자 값을 대체합니다.
+  {{YOUR\_NODE\_ROLE}} - EKS 자율 모드에서 노드를 프로비저닝하는 데 사용하는 노드 IAM 역할의 이름입니다. 클러스터에서 자율 모드를 활성화할 때 사용자가 구성하거나 EKS에서 생성하는 역할입니다. 자세한 내용은 [EKS 자율 모드에 대한 노드 IAM 역할 생성](https://docs.aws.amazon.com/eks/latest/userguide/auto-create-node-role.html)을 참조하세요.
+  {{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` 테인트는 이러한 노드에서 허용 일정이 일치하는 게이트웨이 포드만 보장합니다.
+  `labels` - `hybrid-gateway-node: "true"` 레이블은 헬름 차트 노드 선택기에서 이러한 노드로 게이트웨이 포드를 대상으로 지정하는 데 사용됩니다.
+  `nodeClassRef` - 소스/대상 확인 구성을 사용하여 NodePool을 NodeClass에 연결합니다.

### 관리형 노드 그룹
<a name="hybrid-nodes-gateway-mng-nodes"></a>

관리형 노드 그룹을 사용하는 경우 필수 레이블, 테인트 및 시작 시 소스/대상 확인을 비활성화하는 사용자 지정 시작 템플릿을 사용하여 게이트웨이에 대한 전용 노드 그룹을 생성합니다.

#### 1단계: 시작 템플릿 생성
<a name="_step_1_create_a_launch_template"></a>

인스턴스가 부팅될 때 프라이머리 ENI에서 소스/대상 확인을 비활성화하는 사용자 데이터가 포함된 시작 템플릿을 생성합니다.

```
# Create the launch template with user data to disable source/dest check
USERDATA=$(cat <<'SCRIPT' | base64 -w 0
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==BOUNDARY=="

--==BOUNDARY==
Content-Type: text/x-shellscript; charset="us-ascii"

#!/bin/bash
TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" \
  -H "X-aws-ec2-metadata-token-ttl-seconds: 60")
MAC=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/mac)
ENI_ID=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  "http://169.254.169.254/latest/meta-data/network/interfaces/macs/${MAC}/interface-id")
REGION=$(curl -s -H "X-aws-ec2-metadata-token: $TOKEN" \
  http://169.254.169.254/latest/meta-data/placement/region)

aws ec2 modify-network-interface-attribute \
  --network-interface-id "$ENI_ID" \
  --no-source-dest-check \
  --region "$REGION"

--==BOUNDARY==--
SCRIPT
)

aws ec2 create-launch-template \
  --launch-template-name {{YOUR_CLUSTER_NAME}}-gateway-lt \
  --launch-template-data "{\"UserData\":\"${USERDATA}\",\"MetadataOptions\":{\"HttpTokens\":\"required\",\"HttpPutResponseHopLimit\":2}}"
```

**참고**  
사용자 데이터 스크립트에 성공하려면 노드의 IAM 역할에 `ec2:ModifyNetworkInterfaceAttribute` 권한이 있어야 합니다. MIME 멀티파트 형식은 사용자 데이터가 EKS 부트스트랩 스크립트와 함께 실행되도록 보장합니다.

#### 2단계: 관리형 노드 그룹 생성
<a name="_step_2_create_the_managed_node_group"></a>

1단계의 게이트웨이 레이블, 테인트 및 시작 템플릿을 사용하여 전용 관리형 노드 그룹을 생성합니다.

```
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`를 설정합니다.
+  `--taints`는 이러한 노드에서 허용 일정이 일치하는 게이트웨이 포드만 보장하도록 `NoSchedule` 테인트를 추가합니다.
+  `--launch-template`는 부팅 시 소스/대상 확인을 비활성화하는 시작 템플릿을 연결합니다.

고가용성을 위해 서로 다른 가용 영역의 서브넷을 사용합니다.

## Helm을 사용하여 설치
<a name="hybrid-nodes-gateway-install"></a>

### EKS Auto Mode
<a name="hybrid-nodes-gateway-install-auto"></a>

다음 명령을 실행하여 EKS 자율 모드로 게이트웨이를 설치합니다.

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

### 관리형 노드 그룹 또는 자체 관리형 노드
<a name="hybrid-nodes-gateway-install-mng"></a>

관리형 노드 그룹 또는 자체 관리형 노드의 경우 `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}}
```

### 필수 헬름 값
<a name="hybrid-nodes-gateway-required-values"></a>

다음 값은 모든 설치에 필요합니다.


| 값 | 설명 | 
| --- | --- | 
|  `vpcCIDR`  | EKS 클러스터 VPC의 CIDR 블록(예: `10.0.0.0/16`). 하이브리드 노드가 게이트웨이를 통해 VPC 바운드 트래픽을 라우팅하도록 Cilium VTEP 구성에 사용됩니다. | 
|  `podCIDRs`  | Cilium이 하이브리드 노드에서 사용하는 포드 CIDR의 쉼표로 구분된 목록(예: `10.100.0.0/16,10.101.0.0/16`)입니다. 게이트웨이는 이러한 CIDR에 대한 VPC 라우팅 테이블 항목 및 VXLAN 경로를 생성합니다. | 
|  `routeTableIDs`  | 프로그래밍할 VPC 라우팅 테이블 ID의 쉼표로 구분된 목록(예: `rtb-0abc1234def567890,rtb-0fed9876cba543210`)입니다. 게이트웨이는 하이브리드 포드 CIDR에서 활성 게이트웨이 인스턴스를 가리키는 경로를 이러한 테이블에서 생성합니다. | 

구성 가능한 값의 전체 목록은 [Amazon EKS Hybrid Nodes 게이트웨이 구성 참조](hybrid-nodes-gateway-configuration.md) 섹션을 참조하세요.

## 설치 확인
<a name="hybrid-nodes-gateway-verify"></a>

게이트웨이를 설치한 후 실행 중이고 정상 상태인지 확인합니다.

### 포드 상태 확인
<a name="hybrid-nodes-gateway-verify-pods"></a>

두 게이트웨이 포드가 실행 중인지 확인합니다.

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

### 리더 선정 확인
<a name="hybrid-nodes-gateway-verify-leader"></a>

한 포드가 리더 선정 리스를 획득했는지 확인합니다.

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

출력에는 `HOLDER` 열의 현재 리더가 표시됩니다.

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

### 상태 엔드포인트 확인
<a name="hybrid-nodes-gateway-verify-health"></a>

포트 전달을 사용하여 리더 포드에서 상태 엔드포인트가 응답하는지 확인합니다.

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

정상 상태의 게이트웨이는 HTTP 200 응답을 반환합니다.

### VPC 라우팅 테이블 항목 확인
<a name="hybrid-nodes-gateway-verify-routes"></a>

Amazon VPC 콘솔에서 또는 AWS CLI를 사용하여 VPC 라우팅 테이블에 리더 게이트웨이 인스턴스의 ENI를 가리키는 하이브리드 포드 CIDR에 대한 항목이 포함되어 있는지 확인합니다.

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

각 하이브리드 포드 CIDR에는 `NetworkInterfaceId`가 리더 인스턴스의 프라이머리 ENI로 설정된 경로가 있어야 합니다.

## 제거
<a name="hybrid-nodes-gateway-uninstall"></a>

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

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

**참고**  
헬름 차트를 제거해도 게이트웨이에서 생성한 VPC 라우팅 테이블 항목은 자동으로 제거되지 않습니다. 제거 후 더 이상 게이트웨이를 실행하지 않는 인스턴스로 트래픽을 라우팅하지 않도록 VPC 라우팅 테이블에서 하이브리드 포드 CIDR의 경로를 수동으로 삭제합니다. AWS CLI를 사용하여 경로를 제거할 수 있습니다.  

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

## 다음 단계
<a name="hybrid-nodes-gateway-getting-started-next"></a>
+  [Amazon EKS Hybrid Nodes 게이트웨이 구성 참조](hybrid-nodes-gateway-configuration.md) - 헬름 값, CLI 플래그 및 리더 선정 파라미터를 사용자 지정합니다.
+  [Amazon EKS Hybrid Nodes 게이트웨이 작업](hybrid-nodes-gateway-operations.md) - 게이트웨이를 모니터링하고, 장애 조치 동작을 이해하며, 규모 조정을 계획합니다.
+  [Amazon EKS Hybrid Nodes 게이트웨이 문제 해결](hybrid-nodes-gateway-troubleshooting.md) - 일반적인 문제를 진단하고 해결합니다.