**이 페이지 개선에 도움 주기** 이 사용자 가이드에 기여하려면 모든 페이지의 오른쪽 창에 있는 **GitHub에서 이 페이지 편집** 링크를 선택합니다. # Bottlerocket을 실행하는 하이브리드 노드 연결 이 주제에서는 Bottlerocket을 실행하는 하이브리드 노드를 Amazon EKS 클러스터에 연결하는 방법을 설명합니다. [Bottlerocket](https://aws.amazon.com/bottlerocket/)은 AWS에서 후원하고 지원하는 오픈 소스 Linux 배포판입니다. Bottlerocket은 컨테이너 워크로드 호스팅용으로 특별히 설계되었습니다. Bottlerocket을 사용하면 컨테이너 인프라 업데이트를 자동화하여 컨테이너화된 배포의 가용성을 개선하고 운영 비용을 절감할 수 있습니다. Bottlerocket에는 컨테이너를 실행하는 데 필수적인 소프트웨어만 포함되어 있어 리소스 사용량이 개선되고 보안 위협과 관리 오버헤드가 감소합니다. Bottlerocket 버전 v1.37.0 이상의 VMware 변형만 EKS Hybrid Nodes에서 지원됩니다. Bottlerocket의 VMware 변형은 Kubernetes 버전 v1.28 이상에서 사용할 수 있습니다. 이러한 변형의 OS 이미지에는 kubelet, containerd, aws-iam-authenticator 및 기타 EKS Hybrid Nodes용 소프트웨어 사전 조건이 포함됩니다. Bottlerocket 부트스트랩 및 관리자 컨테이너에 대한 base64 인코딩된 사용자 데이터가 포함된 Bottlerocket [설정](https://github.com/bottlerocket-os/bottlerocket#settings) 파일을 사용하여 이러한 구성 요소를 구성할 수 있습니다. 이러한 설정을 구성하면 Bottlerocket이 하이브리드 노드 자격 증명 공급자를 사용하여 하이브리드 노드를 클러스터에 인증할 수 있습니다. 하이브리드 노드가 클러스터에 조인되면 Amazon EKS 콘솔이나 `kubectl`과 같은 Kubernetes 호환 도구에 `Not Ready` 상태로 표시됩니다. 이 페이지의 단계를 완료한 후 [하이브리드 노드에 대한 CNI 구성](hybrid-nodes-cni.md)로 이동하여 하이브리드 노드가 애플리케이션을 실행할 준비가 되게 합니다. ## 사전 조건 하이브리드 노드를 Amazon EKS 클러스터에 연결하기 전에 사전 조건 단계를 완료했는지 확인합니다. + 온프레미스 환경에서 Amazon EKS 클러스터를 호스팅하는 AWS 리전으로 네트워크 연결이 가능합니다. 자세한 정보는 [하이브리드 노드용 네트워킹 준비](hybrid-nodes-networking.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단계: Bottlerocket 설정 TOML 파일 생성 하이브리드 노드에 대해 Bottlerocket을 구성하려면 필요한 구성으로 `settings.toml` 파일을 생성해야 합니다. TOML 파일의 내용은 사용 중인 자격 증명 공급자(SSM 또는 IAM Roles Anywhere)에 따라 달라집니다. 이 파일은 Bottlerocket 인스턴스를 프로비저닝할 때 사용자 데이터로 전달됩니다. **참고** 아래에 제공된 TOML 파일은 EKS 클러스터에서 Bottlerocket VMWare 시스템을 노드로 초기화하는 데 필요한 최소 설정만 나타냅니다. Bottlerocket은 여러 사용 사례를 해결하기 위해 다양한 설정을 제공하므로, 하이브리드 노드 초기화 이후 추가 구성 옵션의 경우 [Bottlerocket 설명서](https://bottlerocket.dev/en)에서 사용 중인 Bottlerocket 버전에 대해 문서화된 모든 설정의 전체 목록을 참조하세요(예를 들어 Bottlerocket 1.51.x에 대해 사용할 수 있는 모든 설정은 [여기](https://bottlerocket.dev/en/os/1.51.x/api/settings-index)를 참조). ### SSM AWS Systems Manager를 자격 증명 공급자로 사용하는 경우 다음 내용이 포함된 `settings.toml` 파일을 생성합니다. ``` [settings.kubernetes] cluster-name = "" api-server = "" cluster-certificate = "" hostname-override = "" provider-id = "eks-hybrid://///" authentication-mode = "aws" cloud-provider = "" server-tls-bootstrap = true [settings.network] hostname = "" [settings.aws] region = "" [settings.kubernetes.credential-providers.ecr-credential-provider] enabled = true cache-duration = "12h" image-patterns = [ "*.dkr.ecr.*.amazonaws.com", "*.dkr.ecr.*.amazonaws.com.rproxy.govskope.ca.cn", "*.dkr.ecr.*.amazonaws.eu", "*.dkr.ecr-fips.*.amazonaws.com", "*.dkr.ecr-fips.*.amazonaws.eu", "public.ecr.aws" ] [settings.kubernetes.node-labels] "eks.amazonaws.com/compute-type" = "hybrid" "eks.amazonaws.com/hybrid-credential-provider" = "ssm" [settings.host-containers.admin] enabled = true user-data = "" [settings.bootstrap-containers.eks-hybrid-setup] mode = "always" user-data = "" [settings.host-containers.control] enabled = true ``` 자리 표시자를 다음 값으로 바꿉니다. + ``: Amazon ECS 클러스터의 이름입니다. + ``: 클러스터의 API 서버 엔드포인트입니다. + ``: 클러스터의 base64로 인코딩된 CA 번들입니다. + ``: 클러스터를 호스팅하는 AWS 리전입니다(예: "us-east-1"). + ``: Bottlerocket 인스턴스의 호스트 이름으로, 노드 이름으로도 구성됩니다. 이 이름은 임의의 고유한 값일 수 있지만 [Kubernetes 객체 이름 지정 규칙](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names)을 따라야 합니다. 또한 사용하는 호스트 이름은 64자를 초과할 수 없습니다. 참고: SSM 공급자를 사용하는 경우 인스턴스가 SSM에 등록된 후 이 호스트 이름 및 노드 이름이 관리형 인스턴스 ID(예: `mi-*` ID)로 바뀝니다. + ``: Bottlerocket 관리자 컨테이너 구성의 base64로 인코딩된 내용입니다. 관리자 컨테이너를 활성화하면 시스템 탐색 및 디버깅을 위해 SSH를 사용하여 Bottlerocket 인스턴스에 연결할 수 있습니다. 필수 설정은 아니지만 용이한 문제 해결을 위해 활성화하는 것이 좋습니다. 관리자 컨테이너를 사용한 인증에 대한 자세한 내용은 [Bottlerocket 관리자 컨테이너 설명서](https://github.com/bottlerocket-os/bottlerocket-admin-container#authenticating-with-the-admin-container)를 참조하세요. 관리자 컨테이너는 예를 들어 SSH 사용자 및 키 입력을 JSON 형식으로 사용합니다. ``` { "user": "", "ssh": { "authorized-keys": [ "" ] } } ``` + ``: Bottlerocket 부트스트랩 컨테이너 구성의 base64로 인코딩된 내용입니다. 구성에 대한 자세한 내용은 [Bottlerocket 부트스트랩 컨테이너 설명서](https://github.com/bottlerocket-os/bottlerocket-bootstrap-container)를 참조하세요. 부트스트랩 컨테이너는 인스턴스를 AWS SSM 관리형 인스턴스로 등록하고 Amazon EKS 클러스터에서 Kubernetes 노드로 조인하는 역할을 합니다. 부트스트랩 컨테이너로 전달되는 사용자 데이터는 이전에 생성한 SSM 하이브리드 활성화 코드 및 ID를 입력으로 수락하는 명령 간접 호출의 형태를 취합니다. ``` eks-hybrid-ssm-setup --activation-id= --activation-code= --region= ``` ### IAM Roles Anywhere AWS IAM Roles Anywhere를 자격 증명 공급자로 사용하는 경우 다음 내용이 포함된 `settings.toml` 파일을 생성합니다. ``` [settings.kubernetes] cluster-name = "" api-server = "" cluster-certificate = "" hostname-override = "" provider-id = "eks-hybrid://///" authentication-mode = "aws" cloud-provider = "" server-tls-bootstrap = true [settings.network] hostname = "" [settings.aws] region = "" config = "" [settings.kubernetes.credential-providers.ecr-credential-provider] enabled = true cache-duration = "12h" image-patterns = [ "*.dkr.ecr.*.amazonaws.com", "*.dkr.ecr.*.amazonaws.com.rproxy.govskope.ca.cn", "*.dkr.ecr.*.amazonaws.eu", "*.dkr.ecr-fips.*.amazonaws.com", "*.dkr.ecr-fips.*.amazonaws.eu", "public.ecr.aws" ] [settings.kubernetes.node-labels] "eks.amazonaws.com/compute-type" = "hybrid" "eks.amazonaws.com/hybrid-credential-provider" = "iam-ra" [settings.host-containers.admin] enabled = true user-data = "" [settings.bootstrap-containers.eks-hybrid-setup] mode = "always" user-data = "" ``` 자리 표시자를 다음 값으로 바꿉니다. + ``: Amazon ECS 클러스터의 이름입니다. + ``: 클러스터의 API 서버 엔드포인트입니다. + ``: 클러스터의 base64로 인코딩된 CA 번들입니다. + ``: 클러스터를 호스팅하는 AWS 리전입니다(예: "us-east-1") + ``: Bottlerocket 인스턴스의 호스트 이름으로, 노드 이름으로도 구성됩니다. 이 이름은 임의의 고유한 값일 수 있지만 [Kubernetes 객체 이름 지정 규칙](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names)을 따라야 합니다. 또한 사용하는 호스트 이름은 64자를 초과할 수 없습니다. 참고: IAM-RA 공급자를 사용하는 경우 하이브리드 노드 IAM 역할의 신뢰 정책을 `"sts:RoleSessionName": "${aws:PrincipalTag/x509Subject/CN}"` 리소스 조건으로 구성했으면 노드 이름은 호스트에서 인증서의 CN과 일치해야 합니다. + ``: AWS config 파일의 base64로 인코딩된 내용입니다. 파일의 내용은 다음과 같습니다. ``` [default] credential_process = aws_signing_helper credential-process --certificate /root/.aws/node.crt --private-key /root/.aws/node.key --profile-arn --role-arn --trust-anchor-arn --role-session-name ``` + ``: Bottlerocket 관리자 컨테이너 구성의 base64로 인코딩된 내용입니다. 관리자 컨테이너를 활성화하면 시스템 탐색 및 디버깅을 위해 SSH를 사용하여 Bottlerocket 인스턴스에 연결할 수 있습니다. 필수 설정은 아니지만 용이한 문제 해결을 위해 활성화하는 것이 좋습니다. 관리자 컨테이너를 사용한 인증에 대한 자세한 내용은 [Bottlerocket 관리자 컨테이너 설명서](https://github.com/bottlerocket-os/bottlerocket-admin-container#authenticating-with-the-admin-container)를 참조하세요. 관리자 컨테이너는 예를 들어 SSH 사용자 및 키 입력을 JSON 형식으로 사용합니다. ``` { "user": "", "ssh": { "authorized-keys": [ "" ] } } ``` + ``: Bottlerocket 부트스트랩 컨테이너 구성의 base64로 인코딩된 내용입니다. 구성에 대한 자세한 내용은 [Bottlerocket 부트스트랩 컨테이너 설명서](https://github.com/bottlerocket-os/bottlerocket-bootstrap-container)를 참조하세요. 부트스트랩 컨테이너는 인스턴스에서 IAM Roles Anywhere 호스트 인증서 및 인증서 프라이빗 키 파일을 생성하는 역할을 합니다. 그런 다음 `aws_signing_helper`가 Amazon EKS 클러스터로 인증하기 위한 임시 자격 증명을 얻기 위해 사용합니다. 부트스트랩 컨테이너로 전달되는 사용자 데이터는 이전에 생성한 인증서 및 프라이빗 키의 내용을 입력으로 수락하는 명령 간접 호출의 형태를 취합니다. ``` eks-hybrid-iam-ra-setup --certificate= --key= ``` ## 2단계: 사용자 데이터로 Bottlerocket vSphere VM 프로비저닝 TOML 파일을 구성했으면 vSphere VM 생성 중에 이 파일을 사용자 데이터로 전달합니다. VM이 처음 켜지기 전에 사용자 데이터가 구성되어 있어야 합니다. 따라서 인스턴스를 생성할 때 사용자 데이트를 제공해야 합니다. VM을 미리 생성하려는 경우에는 사용자 데이터를 구성할 때까지 VM이 poweredOff 상태여야 합니다. 예를 들어 `govc` CLI를 사용하는 경우: ### 처음으로 VM 생성 ``` govc vm.create \ -on=true \ -c=2 \ -m=4096 \ -net.adapter= \ -net= \ -e guestinfo.userdata.encoding="base64" \ -e guestinfo.userdata="$(base64 -w0 settings.toml)" \ -template= \ ``` ### 기존 VM의 사용자 데이터 업데이트 ``` govc vm.create \ -on=false \ -c=2 \ -m=4096 \ -net.adapter= \ -net= \ -template= \ govc vm.change -vm \ -e guestinfo.userdata="$(base64 -w0 settings.toml)" \ -e guestinfo.userdata.encoding="base64" govc vm.power -on ``` 위 섹션에서 `-e guestinfo.userdata.encoding="base64"` 옵션은 사용자 데이터가 base64로 인코딩되도록 지정합니다. `-e guestinfo.userdata` 옵션은 `settings.toml` 파일의 base64로 인코딩된 내용을 사용자 데이터로 Bottlerocket 인스턴스에 전달합니다. 자리 표시자를 Bottlerocket OVA 템플릿 및 네트워킹 세부 정보와 같은 특정 값으로 바꿉니다. ## 3단계: 하이브리드 노드 연결 확인 Bottlerocket 인스턴스가 시작되면 Amazon EKS 클러스터에 조인을 시도합니다. 클러스터의 컴퓨팅 탭으로 이동하거나 다음 명령을 실행하여 Amazon EKS 콘솔에서 연결을 확인할 수 있습니다. ``` kubectl get nodes ``` **중요** 노드의 상태는 `Not Ready`이며, 이는 하이브리드 노드에서 실행되는 CNI가 없기 때문에 이러한 상태가 예상됩니다. 노드가 클러스터에 조인하지 않은 경우 [하이브리드 노드 문제 해결](hybrid-nodes-troubleshooting.md) 섹션을 참조하세요. ## 4단계: 하이브리드 노드에 대한 CNI 구성 하이브리드 노드가 애플리케이션을 실행할 수 있게 하려면 [하이브리드 노드에 대한 CNI 구성](hybrid-nodes-cni.md)의 단계를 계속합니다.