하이브리드 노드용 운영 체제 준비

하이브리드 노드의 노드 운영 체제로 지원되는 OS와 nodeadm을 포함한 운영 체제 이미지 구축 방법을 설명합니다.

출처: 문서

본문

Bottlerocket, Amazon Linux 2023(AL2023), Ubuntu, RHEL이 하이브리드 노드의 노드 운영 체제로 지속적으로 검증됩니다. Bottlerocket은 VMware vSphere 환경에서만 AWS에서 지원됩니다. AL2023은 Amazon EC2 외부에서 실행될 때 AWS Support 요금제로 포함되지 않습니다. AL2023은 온프레미스 가상화 환경에서만 사용할 수 있으며 자세한 내용은 Amazon Linux 2023 사용자 가이드를 참조하세요. AWS는 Ubuntu 및 RHEL 운영 체제와의 하이브리드 노드 통합을 지원하지만 운영 체제 자체에 대한 지원은 제공하지 않습니다.

운영 체제 프로비저닝과 관리는 사용자 책임입니다. 하이브리드 노드를 처음 테스트할 때는 이미 프로비저닝된 호스트에서 Amazon EKS Hybrid Nodes CLI(nodeadm)를 실행하는 것이 가장 쉽습니다. 프로덕션 배포의 경우 nodeadm을 운영 체제 이미지에 포함하고 호스트 시작 시 호스트가 Amazon EKS 클러스터에 자동으로 조인하도록 systemd 서비스로 실행하도록 구성할 것을 권장합니다. vSphere에서 Bottlerocket을 노드 운영 체제로 사용한다면 Bottlerocket이 이미 하이브리드 노드에 필요한 의존성을 포함하고 호스트 시작 시 구성한 클러스터에 자동으로 연결되므로 nodeadm을 사용할 필요가 없습니다.

SSM 자격 증명 공급자에 필요한 nodeadm 버전

AWS Systems Manager(SSM)를 하이브리드 노드의 자격 증명 공급자로 사용한다면 새 설치와 업그레이드에 nodeadm 버전 1.0.19 이상을 사용해야 합니다. 이전 버전의 nodeadm은 오래된 SSM 서명 키를 포함하고 있으며 nodeadm install 및 nodeadm upgrade 중 다음 서명 검증 오류로 실패합니다.

{"msg":"Command failed","error":"failed to install ssm installer: validating ssm-setup-cli signature: Signature Verification Error: No matching signature"}

이 오류를 해결하려면 nodeadm install 또는 nodeadm upgrade를 실행하기 전에 최신 버전의 nodeadm을 다운로드하세요.

버전 호환성

아래 표는 하이브리드 노드의 노드 운영 체제로 호환되고 검증된 운영 체제 버전을 나타냅니다. 이 표에 포함되지 않은 다른 운영 체제 변형 또는 버전을 사용한다면 AWS Support가 하이브리드 노드와 해당 운영 체제 변형 또는 버전의 호환성을 다루지 않습니다. 하이브리드 노드는 기본 인프라에 대해 애그노스틱하며 x86 및 ARM 아키텍처를 지원합니다.

운영 체제	버전
Amazon Linux	Amazon Linux 2023 (AL2023)
Bottlerocket	v1.37.0 이상, Kubernetes v1.28 이상을 실행하는 VMware 변형
Ubuntu	Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04
Red Hat Enterprise Linux	RHEL 8, RHEL 9

운영 체제 고려 사항

일반

Amazon EKS Hybrid Nodes CLI(nodeadm)를 사용하여 하이브리드 노드 구성 요소와 의존성의 설치 및 구성을 간소화할 수 있습니다. 운영 체제 이미지 빌드 파이프라인 중이나 각 온프레미스 호스트에서 런타임에 nodeadm install 프로세스를 실행할 수 있습니다. nodeadm이 설치하는 구성 요소에 대한 자세한 내용은 Hybrid nodes nodeadm reference를 참조하세요.

온프레미스 환경에서 인터넷에 도달하기 위해 프록시를 사용한다면 설치 및 업그레이드 프로세스가 패키지 관리자를 프록시로 구성하도록 추가 운영 체제 구성이 필요합니다. 지침은 하이브리드 노드용 프록시 구성을 참조하세요.

Bottlerocket

Bottlerocket 노드를 연결하는 단계와 도구는 다른 운영 체제의 단계와 다르며 Connect hybrid nodes의 단계 대신 Connect hybrid nodes with Bottlerocket에서 별도로 다룹니다.
Bottlerocket 단계는 하이브리드 노드 CLI 도구 nodeadm을 사용하지 않습니다.
EKS Hybrid Nodes에서 지원되는 것은 Bottlerocket 버전 v1.37.0 이상의 VMware 변형뿐입니다. Bottlerocket의 VMware 변형은 Kubernetes 버전 v1.28 이상에서 사용할 수 있습니다. 다른 Bottlerocket 변형은 하이브리드 노드 운영 체제로 지원되지 않습니다. 참고: Bottlerocket의 VMware 변형은 x86_64 아키텍처에서만 사용할 수 있습니다.

Containerd

Containerd는 표준 Kubernetes 컨테이너 런타임이며 모든 Amazon EKS 노드 컴퓨팅 유형뿐 아니라 하이브리드 노드의 의존성입니다. Amazon EKS Hybrid Nodes CLI(nodeadm)는 nodeadm install 프로세스 중 containerd 설치를 시도합니다. --containerd-source 명령줄 옵션으로 nodeadm install 런타임에 containerd 설치를 구성할 수 있습니다. 유효한 옵션은 none, distro, docker입니다. RHEL을 사용한다면 distro는 유효한 옵션이 아니며, Docker 저장소에서 containerd 빌드 설치를 구성하거나 containerd를 수동으로 설치할 수 있습니다. AL2023 또는 Ubuntu를 사용할 때 nodeadm은 기본적으로 운영 체제 배포판에서 containerd를 설치합니다. nodeadm이 containerd를 설치하지 않게 하려면 --containerd-source none 옵션을 사용하세요.

Ubuntu

Ubuntu 24.04를 사용한다면 Pod가 제대로 종료되도록 하는 수정을 채택하기 위해 containerd 버전을 업데이트하거나 AppArmor 구성을 변경해야 할 수 있습니다. 자세한 내용은 Ubuntu #2065423을 참조하세요. AppArmor 프로필 변경을 적용하려면 재부팅이 필요합니다. 최신 Ubuntu 24.04 버전은 패키지 관리자에 수정 사항이 포함된 업데이트된 containerd 버전(containerd 버전 1.7.19+)이 있습니다.

ARM

ARM 하드웨어를 사용한다면 EKS kube-proxy 애드온 버전 1.31 이상을 실행하려면 Cryptography Extension(ARMv8.2+crypto)을 갖춘 ARMv8.2 호환 프로세서가 필요합니다. Raspberry Pi 5 이전의 모든 Raspberry Pi 시스템과 Cortex-A72 기반 프로세서는 이 요구 사항을 충족하지 않습니다. 해결 방법으로 2026년 7월 확장 지원 종료까지 EKS kube-proxy 애드온 버전 1.30을 계속 사용하거나(Kubernetes release calendar 참조), 업스트림의 사용자 지정 kube-proxy 이미지를 사용할 수 있습니다.

kube-proxy 로그의 다음 오류 메시지는 이 비호환성을 나타냅니다.

Fatal glibc error: This version of Amazon Linux requires a newer ARM64 processor compliant with at least ARM architecture 8.2-a with Cryptographic extensions. On EC2 this is Graviton 2 or later.

운영 체제 이미지 구축

Amazon EKS는 nodeadm을 포함하고 호스트 시작 시 실행되도록 구성하는 운영 체제 이미지를 만드는 데 사용할 수 있는 예시 Packer 템플릿을 제공합니다. 이 프로세스는 각 호스트에서 하이브리드 노드 의존성을 개별적으로 가져오는 것을 피하고 하이브리드 노드 부트스트랩 프로세스를 자동화하는 데 권장됩니다. Ubuntu 22.04, Ubuntu 24.04, RHEL 8 또는 RHEL 9 ISO 이미지와 함께 예시 Packer 템플릿을 사용할 수 있으며 OVA, Qcow2 또는 raw 형식으로 이미지를 출력할 수 있습니다.

사전 요구 사항

예시 Packer 템플릿을 사용하기 전에 Packer를 실행하는 머신에 다음이 설치되어 있어야 합니다.

Packer 버전 1.11.0 이상. Packer 설치 지침은 Packer 문서의 Install Packer를 참조하세요.
OVA를 구축한다면 VMware vSphere 플러그인 1.4.0 이상
Qcow2 또는 raw 이미지를 구축한다면 QEMU 플러그인 버전 1.x

환경 변수 설정

Packer 빌드를 실행하기 전에 Packer를 실행하는 머신에 다음 환경 변수를 설정하세요.

일반

모든 운영 체제 및 출력 형식으로 이미지를 구축하려면 다음 환경 변수를 설정해야 합니다.

환경 변수	유형	설명
PKR_SSH_PASSWORD	String	Packer는 프로비저닝 시 생성된 머신에 SSH로 접속하기 위해 `ssh_username` 및 `ssh_password` 변수를 사용합니다. 이 값은 해당 OS의 kickstart 또는 user-data 파일에서 초기 사용자를 만들 때 사용한 비밀번호와 일치해야 합니다. 기본값은 OS에 따라 "builder" 또는 "ubuntu"로 설정됩니다. 비밀번호를 설정할 때 해당 `ks.cfg` 또는 `user-data` 파일에서도 일치하도록 변경해야 합니다.
ISO_URL	String	사용할 ISO의 URL입니다. 서버에서 다운로드할 웹 링크 또는 로컬 파일의 절대 경로일 수 있습니다.
ISO_CHECKSUM	String	제공된 ISO에 대한 관련 체크섬입니다.
CREDENTIAL_PROVIDER	String	하이브리드 노드용 자격 증명 공급자입니다. 유효한 값은 SSM 하이브리드 활성화용 `ssm`(기본값)과 IAM Roles Anywhere용 `iam`입니다.
K8S_VERSION	String	하이브리드 노드용 Kubernetes 버전(예: `1.31`). 지원되는 Kubernetes 버전은 Amazon EKS supported versions를 참조하세요.
NODEADM_ARCH	String	`nodeadm install`용 아키텍처입니다. `amd` 또는 `arm`을 선택하세요.

RHEL

RHEL을 사용한다면 다음 환경 변수를 설정해야 합니다.

환경 변수	유형	설명
RH_USERNAME	String	RHEL subscription manager 사용자 이름
RH_PASSWORD	String	RHEL subscription manager 비밀번호
RHEL_VERSION	String	사용 중인 RHEL ISO 버전입니다. 유효한 값은 `8` 또는 `9`입니다.

Ubuntu

Ubuntu 전용 환경 변수는 필요하지 않습니다.

vSphere

VMware vSphere OVA를 구축한다면 다음 환경 변수를 설정해야 합니다.

환경 변수	유형	설명
VSPHERE_SERVER	String	vSphere 서버 주소
VSPHERE_USER	String	vSphere 사용자 이름
VSPHERE_PASSWORD	String	vSphere 비밀번호
VSPHERE_DATACENTER	String	vSphere 데이터센터 이름
VSPHERE_CLUSTER	String	vSphere 클러스터 이름
VSPHERE_DATASTORE	String	vSphere 데이터스토어 이름
VSPHERE_NETWORK	String	vSphere 네트워크 이름
VSPHERE_OUTPUT_FOLDER	String	템플릿용 vSphere 출력 폴더

QEMU

환경 변수	유형	설명
PACKER_OUTPUT_FORMAT	String	QEMU 빌더의 출력 형식입니다. 유효한 값은 `qcow2`와 `raw`입니다.

템플릿 검증

빌드를 실행하기 전에 환경 변수를 설정한 후 다음 명령으로 템플릿을 검증합니다. 다른 이름의 템플릿을 사용한다면 template.pkr.hcl을 바꾸세요.

packer validate template.pkr.hcl

이미지 빌드

다음 명령으로 이미지를 빌드하고 -only 플래그를 사용하여 이미지의 대상과 운영 체제를 지정합니다. 다른 이름의 템플릿을 사용한다면 template.pkr.hcl을 바꾸세요.

vSphere OVA

참고

vSphere에서 RHEL을 사용한다면 kickstart 파일을 OEMDRV 이미지로 변환하고 부팅할 ISO로 전달해야 합니다. 자세한 내용은 EKS Hybrid Nodes GitHub 저장소의 Packer Readme를 참조하세요.

Ubuntu 22.04 OVA

packer build -only=general-build.vsphere-iso.ubuntu22 template.pkr.hcl

Ubuntu 24.04 OVA

packer build -only=general-build.vsphere-iso.ubuntu24 template.pkr.hcl

RHEL 8 OVA

packer build -only=general-build.vsphere-iso.rhel8 template.pkr.hcl

RHEL 9 OVA

packer build -only=general-build.vsphere-iso.rhel9 template.pkr.hcl

QEMU

참고

빌더 호스트와 일치하지 않는 특정 호스트 CPU용 이미지를 구축한다면 QEMU 문서에서 호스트 CPU와 일치하는 이름을 확인하고 다음 명령을 실행할 때 -cpu 플래그와 함께 호스트 CPU 이름을 사용하세요.

Ubuntu 22.04 Qcow2 / Raw

packer build -only=general-build.qemu.ubuntu22 template.pkr.hcl

Ubuntu 24.04 Qcow2 / Raw

packer build -only=general-build.qemu.ubuntu24 template.pkr.hcl

RHEL 8 Qcow2 / Raw

packer build -only=general-build.qemu.rhel8 template.pkr.hcl

RHEL 9 Qcow2 / Raw

packer build -only=general-build.qemu.rhel9 template.pkr.hcl

user-data를 통해 nodeadm 구성 전달

cloud-init을 통해 user-data에서 nodeadm 구성을 전달하여 호스트 시작 시 하이브리드 노드를 구성하고 EKS 클러스터에 자동으로 연결할 수 있습니다. 하이브리드 노드의 인프라로 VMware vSphere를 사용할 때 이 작업을 수행하는 방법의 예시는 아래와 같습니다.

GitHub의 govc readme 지침에 따라 govc CLI를 설치합니다.
이전 섹션에서 Packer 빌드를 실행하고 템플릿을 프로비저닝한 후, 다음을 사용하여 템플릿을 복제해 여러 다른 노드를 만들 수 있습니다. 하이브리드 노드로 사용할 각 새 VM마다 템플릿을 복제해야 합니다. 아래 명령의 변수를 환경의 값으로 바꾸세요. 아래 명령의 VM_NAME은 metadata.yaml 파일을 통해 VM 이름을 주입할 때 NODE_NAME으로 사용됩니다.

govc vm.clone -vm "/PATH/TO/TEMPLATE" -ds="YOUR_DATASTORE" \
    -on=false -template=false -folder=/FOLDER/TO/SAVE/VM "VM_NAME"

각 새 VM에 대해 템플릿을 복제한 후 VM용 userdata.yaml과 metadata.yaml을 만듭니다. VM들이 같은 userdata.yaml과 metadata.yaml을 공유할 수 있으며, 다음 단계에서 이를 VM별로 채웁니다. nodeadm 구성은 userdata.yaml의 write_files 섹션에서 만들고 정의합니다. 아래 예시는 하이브리드 노드의 온프레미스 자격 증명 공급자로 AWS SSM 하이브리드 활성화를 사용합니다. nodeadm 구성에 대한 자세한 내용은 Hybrid nodes nodeadm reference를 참조하세요.

userdata.yaml:

#cloud-config
users:
  - name: <username> # username for login. Use 'builder' for RHEL or 'ubuntu' for Ubuntu.
    passwd: <password> # password to login. Default is 'builder' for RHEL.
    groups: [adm, cdrom, dip, plugdev, lxd, sudo]
    lock-passwd: false
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash

write_files:
  - path: /usr/local/bin/nodeConfig.yaml
    permissions: '0644'
    content: |
      apiVersion: node.eks.aws/v1alpha1
      kind: NodeConfig
      spec:
          cluster:
              name: <Cluster-Name>
              region: <AWS-region>
          hybrid:
              ssm:
                  activationCode: <Your-SSM-activation-code>
                  activationId: <Your-SSM-activation-id>

runcmd:
  - /usr/local/bin/nodeadm init -c file:///usr/local/bin/nodeConfig.yaml >> /var/log/nodeadm-init.log 2>&1

metadata.yaml:

환경용 metadata.yaml을 만듭니다. 파일에 "$NODE_NAME" 변수 형식을 유지하세요. 이 값은 이후 단계에서 값으로 채워집니다.

instance-id: "$NODE_NAME"
local-hostname: "$NODE_NAME"
network:
  version: 2
  ethernets:
    nics:
      match:
        name: ens*
      dhcp4: yes

다음 명령으로 userdata.yaml과 metadata.yaml 파일을 gzip+base64 문자열로 추가합니다. 다음 명령은 만드는 각 VM에 대해 실행해야 합니다. VM_NAME을 업데이트하는 VM의 이름으로 바꾸세요.

export NODE_NAME="VM_NAME"
export USER_DATA=$(gzip -c9 userdata.yaml | base64 -w0)
export METADATA=$(gzip -c9 metadata.yaml | base64 -w0)
govc vm.change -vm="$VM_NAME" -e "guestinfo.userdata=$USER_DATA"
govc vm.change -vm="$VM_NAME" -e "guestinfo.metadata=$METADATA"

더 알아보기 (Learn more)

공식 문서