**이 페이지 개선에 도움 주기**
이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다.
# 하이브리드 노드 연결
**참고**
다음 단계는 Bottlerocket을 제외한 호환 운영 체제를 실행하는 하이브리드 노드에 적용됩니다. Bottlerocket을 실행하는 하이브리드 노드를 연결하는 단계는 [Bottlerocket을 실행하는 하이브리드 노드 연결](hybrid-nodes-bottlerocket.md) 섹션을 참조하세요.
이 주제에서는 하이브리드 노드를 Amazon EKS 클러스터에 연결하는 방법을 설명합니다. 하이브리드 노드가 클러스터에 조인되면 Amazon EKS 콘솔이나 kubectl과 같은 Kubernetes 호환 도구에 준비되지 않음 상태로 표시됩니다. 이 페이지의 단계를 완료한 후 [하이브리드 노드에 대한 CNI 구성](hybrid-nodes-cni.md)로 이동하여 하이브리드 노드가 애플리케이션을 실행할 준비가 되게 합니다.
## 사전 조건
하이브리드 노드를 Amazon EKS 클러스터에 연결하기 전에 사전 조건 단계를 완료했는지 확인합니다.
+ 온프레미스 환경에서 Amazon EKS 클러스터를 호스팅하는 AWS 리전으로 네트워크 연결이 가능합니다. 자세한 정보는 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md)을 참조하세요.
+ 온프레미스 호스트에 하이브리드 노드용 호환 운영 체제가 설치되어 있습니다. 자세한 정보는 [하이브리드 노드용 운영 체제 준비](hybrid-nodes-os.md)을 참조하세요.
+ 하이브리드 노드 IAM 역할을 생성하고 온프레미스 자격 증명 공급자(AWS Systems Manager 하이브리드 활성화 또는 AWS IAM Roles Anywhere)를 설정했습니다. 자세한 정보는 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md)을 참조하세요.
+ 하이브리드 노드가 활성화된 Amazon EKS 클러스터를 생성했습니다. 자세한 정보는 [하이브리드 노드를 사용하여 Amazon EKS 클러스터 생성](hybrid-nodes-cluster-create.md)을 참조하세요.
+ 하이브리드 노드 IAM 역할을 Kubernetes 역할 기반 액세스 제어(RBAC) 권한과 연결했습니다. 자세한 정보는 [하이브리드 노드에 대한 클러스터 액세스 준비](hybrid-nodes-cluster-prep.md)을 참조하세요.
## 1단계: 각 온프레미스 호스트에 하이브리드 노드 CLI(`nodeadm`) 설치
사전 구축된 운영 체제 이미지에 Amazon EKS Hybrid Nodes CLI(`nodeadm`)를 포함하는 경우 이 단계를 건너뛸 수 있습니다. 하이브리드 노드 버전 `nodeadm`에 대한 자세한 내용은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요.
하이브리드 노드 버전 `nodeadm`은 Amazon CloudFront가 제공하는 Amazon S3에서 호스팅됩니다. 각 온프레미스 호스트에 `nodeadm`을 설치하려면 온프레미스 호스트에서 다음 명령을 실행할 수 있습니다.
**x86\$164 호스트의 경우:**
```
curl -OL 'https://hybrid-assets.eks.amazonaws.com/releases/latest/bin/linux/amd64/nodeadm'
```
**ARM 호스트의 경우**
```
curl -OL 'https://hybrid-assets.eks.amazonaws.com/releases/latest/bin/linux/arm64/nodeadm'
```
각 호스트에서 다운로드한 바이너리에 실행 파일 권한을 추가합니다.
```
chmod +x nodeadm
```
## 2단계: `nodeadm`을 사용하여 하이브리드 노드 종속성 설치
사전 구축된 운영 체제 이미지에 하이브리드 노드 종속성을 설치하는 경우 이 단계를 건너뛸 수 있습니다. `nodeadm install` 명령을 사용하여 하이브리드 노드에 필요한 모든 종속성을 설치할 수 있습니다. 하이브리드 노드 종속성에는 Containered, kubelet, kubectl 및 AWS SSM 또는 AWS IAM Roles Anywhere 구성 요소가 포함됩니다. `nodeadm install`에서 설치한 구성 요소 및 파일 위치에 대한 자세한 내용은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요. `nodeadm install` 프로세스를 위해 온프레미스 방화벽에서 허용해야 하는 도메인에 대한 자세한 내용은 하이브리드 노드용 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.md)를 참조하세요.
아래 명령을 실행하여 온프레미스 호스트에 하이브리드 노드 종속성을 설치합니다. 아래 명령은 호스트에서 sudo/root 액세스 권한이 있는 사용자와 함께 실행해야 합니다.
**중요**
하이브리드 노드 CLI(`nodeadm`)는 호스트에서 sudo/root 액세스 권한이 있는 사용자와 함께 실행해야 합니다.
+ 예를 들어 `K8S_VERSION`을 Amazon EKS 클러스터의 Kubernetes 마이너 버전(예: `1.31`)으로 바꿉니다. 지원되는 Kubernetes 버전 목록은 [Amazon EKS 지원 버전](https://docs.aws.amazon.com/eks/latest/userguide/kubernetes-versions.html)을 참조하세요.
+ `CREDS_PROVIDER`를 사용 중인 온프레미스 자격 증명 공급자로 바꿉니다. 유효한 값은 `ssm`(AWS SSM) 및 `iam-ra`(AWS IAM Roles Anywhere)입니다.
```
nodeadm install K8S_VERSION --credential-provider CREDS_PROVIDER
```
## 3단계: 클러스터에 하이브리드 노드 연결
하이브리드 노드를 클러스터에 연결하기 전에 Amazon EKS 컨트롤 플레인과 하이브리드 노드 간 통신을 주고받기 위해 클러스터의 온프레미스 방화벽 및 보안 그룹에서 필요한 액세스를 허용했는지 확인합니다. 이 단계에서 발생하는 대부분의 문제는 방화벽 구성, 보안 그룹 구성 또는 하이브리드 노드 IAM 역할 구성과 관련이 있습니다.
**중요**
하이브리드 노드 CLI(`nodeadm`)는 호스트에서 sudo/root 액세스 권한이 있는 사용자와 함께 실행해야 합니다.
1. 각 호스트에 배포 값을 포함하는 `nodeConfig.yaml` 파일을 생성합니다. 사용 가능한 구성 설정에 대한 전체 설명은 [하이브리드 노드 `nodeadm` 참조](hybrid-nodes-nodeadm.md) 섹션을 참조하세요. 하이브리드 노드 IAM 역할에 `eks:DescribeCluster` 작업에 대한 권한이 없는 경우 `nodeConfig.yaml`의 클러스터 섹션에서 Kubernetes API 엔드포인트, 클러스터 CA 번들, Kubernetes 서비스 IPv4 CIDR을 전달해야 합니다.
1. 온프레미스 자격 증명 공급자에 대해 AWS SSM 하이브리드 활성화를 사용하는 경우 아래 `nodeConfig.yaml` 예제를 사용합니다.
1. `CLUSTER_NAME`를 클러스터 이름으로 바꿉니다.
1. `AWS_REGION`을 클러스터를 호스팅하는 AWS 리전으로 바꿉니다. 예를 들어 `us-west-2`입니다.
1. `ACTIVATION_CODE`를 AWS SSM 하이브리드 활성화를 생성할 때 받은 활성화 코드로 바꿉니다. 자세한 정보는 [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md)을 참조하세요.
1. `ACTIVATION_ID`를 AWS SSM 하이브리드 활성화를 생성할 때 받은 활성화 ID로 바꿉니다. AWS Systems Manager 콘솔 또는 AWS CLI `aws ssm describe-activations` 명령에서 이 정보를 검색할 수 있습니다.
```
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
cluster:
name: CLUSTER_NAME
region: AWS_REGION
hybrid:
ssm:
activationCode: ACTIVATION_CODE
activationId: ACTIVATION_ID
```
1. 온프레미스 자격 증명 공급자에 AWS IAM Roles Anywhere를 사용하는 경우 아래 `nodeConfig.yaml` 예제를 사용합니다.
1. `CLUSTER_NAME`를 클러스터 이름으로 바꿉니다.
1. `AWS_REGION`을 클러스터를 호스팅하는 AWS 리전으로 바꿉니다. 예를 들어 `us-west-2`입니다.
1. `NODE_NAME`을 노드의 이름으로 바꿉니다. 하이브리드 노드 IAM 역할의 신뢰 정책을 `"sts:RoleSessionName": "${aws:PrincipalTag/x509Subject/CN}"` 리소스 조건으로 구성한 경우 노드 이름은 호스트에서 인증서의 CN과 일치해야 합니다. 사용하는 `nodeName`은 64자를 초과할 수 없습니다.
1. 하이브리드 노드에 대한 자격 증명 준비 단계에서 구성한 트러스트 앵커의 ARN으로 `TRUST_ANCHOR_ARN`을 바꿉니다.
1. [하이브리드 노드에 대한 자격 증명 준비](hybrid-nodes-creds.md) 단계에서 구성한 트러스트 앵커의 ARN으로 `PROFILE_ARN`을 바꿉니다.
1. `ROLE_ARN`을 하이브리드 노드 IAM 역할의 ARN으로 바꿉니다.
1. `CERTIFICATE_PATH`를 노드 인증서의 디스크 경로로 바꿉니다. 지정하지 않으면 기본값은 `/etc/iam/pki/server.pem`입니다.
1. `KEY_PATH`를 인증서 프라이빗 키의 디스크 경로로 바꿉니다. 지정하지 않으면 기본값은 `/etc/iam/pki/server.key`입니다.
```
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
cluster:
name: CLUSTER_NAME
region: AWS_REGION
hybrid:
iamRolesAnywhere:
nodeName: NODE_NAME
trustAnchorArn: TRUST_ANCHOR_ARN
profileArn: PROFILE_ARN
roleArn: ROLE_ARN
certificatePath: CERTIFICATE_PATH
privateKeyPath: KEY_PATH
```
1. `nodeConfig.yaml`로 `nodeadm init` 명령을 실행하여 하이브리드 노드를 Amazon EKS 클러스터에 연결합니다.
```
nodeadm init -c file://nodeConfig.yaml
```
위 명령이 성공적으로 완료되면 하이브리드 노드가 Amazon EKS 클러스터에 조인된 것입니다. 클러스터의 컴퓨팅 탭으로 이동하거나([IAM 보안 주체가 볼 수 있는 권한이 있는지 확인](view-kubernetes-resources.md#view-kubernetes-resources-permissions)) `kubectl get nodes`를 사용하여 Amazon EKS 콘솔에서 이를 확인할 수 있습니다.
**중요**
노드의 상태는 `Not Ready`이며, 이는 하이브리드 노드에서 실행되는 CNI가 없기 때문에 이러한 상태가 예상됩니다. 노드가 클러스터에 조인하지 않은 경우 [하이브리드 노드 문제 해결](hybrid-nodes-troubleshooting.md) 섹션을 참조하세요.
## 4단계: 하이브리드 노드에 대한 CNI 구성
하이브리드 노드가 애플리케이션을 실행할 수 있게 하려면 [하이브리드 노드에 대한 CNI 구성](hybrid-nodes-cni.md)의 단계를 계속합니다.