EKS 노드의 Hostname을 Instance ID 기반으로 변경하기

이번 블로그에서는 Amazon EKS에서 EC2 노드의 기본 Hostname 대신 Instance ID를 기반으로 Hostname을 설정하는 방법에 대해 정리해 보겠습니다.

 

들어가며

Amazon EKS에서 Managed Node Group을 생성하면 EC2 인스턴스가 자동으로 생성되고 Kubernetes 클러스터에 Worker Node로 등록됩니다.

 

이때 노드의 이름은 기본적으로 EC2 Private DNS 이름을 기반으로 설정됩니다. 하지만 노드를 구분하거나 모니터링할 때 EC2 Instance ID를 기반으로 노드를 식별하고 싶을 수 있습니다.

 

이번 글에서는 Amazon Linux 2023(AL2023) 환경을 기준으로 nodeadm의 실행 구조를 살펴보고, Launch Template의 User Data와 aws-auth ConfigMap을 활용해 Kubernetes 노드의 Hostname을 Instance ID 기반으로 변경하는 방법을 알아보겠습니다.

 

사전 지식: nodeadm은 어떻게 실행될까?

Amazon Linux 2023 기반의 EKS 노드는 기존 Amazon Linux 2에서 사용하던 bootstrap.sh 대신 nodeadm을 사용하여 노드 초기화를 진행합니다.

 

nodeadm은 NodeConfig YAML을 읽어 Kubernetes 노드에 필요한 설정을 적용하는 도구입니다.

 

노드 부팅 과정에서 관련 서비스는 다음과 같은 순서로 실행됩니다.

nodeadm-config.service
                    ↓
             cloud-init
                    ↓
nodeadm-run.service
                    ↓
               kubelet

 

여기서 중요한 부분은 cloud-init 이후에 nodeadm-run.service가 실행된다는 점입니다.

 

실제로 nodeadm-run.service의 설정을 확인해 보겠습니다.

sudo systemctl cat nodeadm-run

 

실행 결과는 다음과 같습니다.

[Unit]
Description=EKS Nodeadm Run
Documentation=https://github.com/awslabs/amazon-eks-ami

After=nodeadm-config.service cloud-final.service
Requires=nodeadm-config.service

[Service]
Type=oneshot
ExecStart=/usr/bin/nodeadm init --skip config \
  --config-source imds://user-data \
  --config-source file:///etc/eks/nodeadm.d/ \
  --config-cache /run/eks/nodeadm/config.json

StandardError=journal+console

[Install]
WantedBy=multi-user.target

 

여기서 주목해야 할 부분은 다음 옵션입니다.

--config-source file:///etc/eks/nodeadm.d/

 

해당 옵션은 /etc/eks/nodeadm.d/ 디렉토리에 존재하는 NodeConfig 파일을 설정 소스로 사용한다는 의미입니다.

 

또한 After=nodeadm-config.service cloud-final.service 설정을 통해 cloud-init의 최종 단계가 완료된 이후 실행되도록 구성되어 있습니다.

 

따라서 cloud-init 단계에서 Bash 스크립트를 이용해 /etc/eks/nodeadm.d/ 디렉토리에 NodeConfig YAML 파일을 미리 생성해 두면, 이후 실행되는 nodeadm-run.service가 해당 설정을 읽어 적용할 수 있습니다.

 

이러한 실행 순서를 활용하면 별도의 AMI를 생성하지 않고도 Launch Template의 User Data만으로 노드 설정을 변경할 수 있습니다.

 

실습: Instance ID 기반 Hostname 설정하기

1. Launch Template User Data 수정

먼저 EKS Managed Node Group에서 사용하는 Launch Template의 User Data를 수정합니다.

 

Amazon Linux 2023 환경에서는 MIME 형식의 User Data를 사용하여 Bash 스크립트를 실행할 수 있습니다.

 

아래 스크립트는 IMDSv2를 통해 현재 EC2 인스턴스의 Instance ID를 가져온 다음, 해당 값을 이용해 NodeConfig YAML 파일을 생성합니다.

MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="

--==MYBOUNDARY==
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: 21600")

INSTANCE_ID=$(curl -s \
  -H "X-aws-ec2-metadata-token: $TOKEN" \
  "http://169.254.169.254/latest/meta-data/instance-id")

mkdir -p /etc/eks/nodeadm.d/

cat > /etc/eks/nodeadm.d/hostname-override.yaml << EOF
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  kubelet:
    flags:
    - "--hostname-override=${INSTANCE_ID}.ec2.internal"
EOF

--==MYBOUNDARY==--

 

스크립트의 동작 과정은 다음과 같습니다.

1. IMDSv2를 통해 Metadata Token을 발급받습니다.
2. 발급받은 Token을 이용해 현재 EC2의 Instance ID를 조회합니다.
3. /etc/eks/nodeadm.d/ 디렉토리를 생성합니다.
4. Instance ID를 포함한 NodeConfig YAML 파일을 생성합니다.

생성되는 YAML 파일은 다음과 같은 형태입니다.

apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  kubelet:
    flags:
    - "--hostname-override=i-0123456789abcdef0.ec2.internal"

 

이렇게 생성된 설정은 이후 nodeadm-run.service가 실행될 때 읽히며, kubelet의 Hostname 설정에 반영됩니다.

 

2. EKS Access Entry 확인 및 삭제

다음으로 확인해야 할 부분은 EKS Access Entry입니다.

 

EKS Managed Node Group을 생성하면 환경의 인증 모드와 구성에 따라 EKS가 노드 IAM Role에 대한 EC2_LINUX Access Entry를 자동으로 생성할 수 있습니다.

 

이 Access Entry는 Kubernetes 노드 인증에 사용되는 Username을 다음과 같은 형태로 지정합니다.

system:node:{{EC2PrivateDNSName}}

 

그런데 이번에는 Instance ID를 기반으로 Hostname을 변경했기 때문에 기존 Private DNS 이름을 사용하는 인증 설정과 충돌할 수 있습니다.

 

따라서 Access Entry를 사용하는 인증 구성이라면 해당 Entry를 확인하고, 기존 설정을 제거한 뒤 aws-auth ConfigMap을 통해 Username을 관리하도록 구성해야 합니다.

 

먼저 Access Entry를 확인합니다.

aws eks list-access-entries \
  --cluster-name <CLUSTER_NAME>

 

이후 해당 Node IAM Role에 연결된 Access Entry를 확인합니다.

aws eks describe-access-entry \
  --cluster-name <CLUSTER_NAME> \
  --principal-arn arn:aws:iam::<ACCOUNT_ID>:role/nodegroup-role

 

기존 EC2_LINUX Access Entry를 제거하려면 다음 명령어를 실행합니다.

aws eks delete-access-entry \
  --cluster-name <CLUSTER_NAME> \
  --principal-arn arn:aws:iam::<ACCOUNT_ID>:role/nodegroup-role

 

단, Access Entry를 삭제하면 해당 Entry를 통한 인증도 제거됩니다. 클러스터의 인증 모드와 다른 인증 경로가 정상적으로 구성되어 있는지 먼저 확인해야 합니다.

3. aws-auth ConfigMap 수정

이제 Kubernetes의 aws-auth ConfigMap을 수정합니다.

kubectl edit configmap aws-auth -n kube-system

 

기존 Node IAM Role의 Username 설정을 다음과 같이 변경합니다.

apiVersion: v1
data:
  mapRoles: |
    - rolearn: arn:aws:iam::<ACCOUNT_ID>:role/nodegroup-role
      groups:
      - system:bootstrappers
      - system:nodes
      username: system:node:{{SessionName}}.ec2.internal
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system

 

여기서 중요한 부분은 다음 설정입니다.

username: system:node:{{SessionName}}.ec2.internal

 

{{SessionName}}은 IAM Role 세션 이름을 의미합니다. EC2 Instance Profile을 사용하는 일반적인 환경에서는 Instance ID가 세션 이름으로 사용되므로, 최종적으로 다음과 같은 Username이 만들어집니다.

system:node:i-0123456789abcdef0.ec2.internal

 

앞서 NodeConfig에서 설정한 kubelet의 Hostname과 인증 Username이 일치하도록 구성하는 것이 핵심입니다.

 

4. 기존 노드에 설정 적용하기

새로운 노드를 생성하는 경우에는 Launch Template의 User Data가 부팅 과정에서 실행되므로 별도의 작업 없이 설정이 적용됩니다.

 

하지만 이미 실행 중인 노드에 변경 사항을 적용하려면 추가 작업이 필요합니다.

 

기존 노드에서 kubelet을 재시작하려면 다음 명령어를 실행합니다.

sudo systemctl restart kubelet

 

다만 기존 노드의 Hostname 변경은 단순한 서비스 재시작만으로 항상 정상 반영되는 것은 아닙니다. 기존 Node 객체와의 이름 불일치도 고려해야 합니다.

 

따라서 운영 환경에서는 기존 노드의 Pod를 안전하게 Drain한 뒤 노드를 제거하고, Auto Scaling Group을 통해 새로운 노드가 생성되도록 하는 방법을 권장합니다.

kubectl drain <NODE_NAME> \
  --ignore-daemonsets \
  --delete-emptydir-data

kubectl delete node <NODE_NAME>

 

이후 Auto Scaling Group에서 새로운 EC2 인스턴스가 생성되면 수정된 Launch Template의 User Data가 실행됩니다.

 

결과 확인

모든 설정이 완료되었다면 Kubernetes에 등록된 노드 이름을 확인합니다.

kubectl get nodes -o wide

 

정상적으로 적용되었다면 다음과 같이 Instance ID를 기반으로 노드 이름이 표시됩니다.

NAME                                      STATUS   ROLES    AGE
i-0123456789abcdef0.ec2.internal          Ready    <none>   5m
i-0987654321abcdef0.ec2.internal          Ready    <none>   5m

 

이처럼 기존 EC2 Private DNS 기반의 노드 이름이 아닌 Instance ID 기반의 노드 이름으로 등록된 것을 확인할 수 있습니다.

주의할 점

• 실행 순서가 중요합니다. NodeConfig 파일은 nodeadm-run.service가 실행되기 전에 생성되어야 합니다. 따라서 cloud-init을 활용하는 것이 중요합니다.
• Access Entry를 확인해야 합니다. EC2_LINUX Access Entry가 존재하면 해당 인증 설정이 노드 Username에 영향을 줄 수 있으므로 인증 모드를 확인해야 합니다.
• Username과 Hostname이 일치해야 합니다. kubelet에서 설정한 Hostname과 Kubernetes 인증 과정에서 사용하는 Username이 일치하지 않으면 노드 인증 및 등록에 문제가 발생할 수 있습니다.
• SessionName을 확인해야 합니다. {{SessionName}}이 실제 Instance ID로 치환되는지 IAM Role 세션 정보를 확인해야 합니다.
• 기존 노드 적용 시 주의해야 합니다. 운영 중인 노드에서 kubelet을 재시작하기보다는 Pod를 안전하게 이동한 후 노드를 교체하는 방법이 더 안전합니다.

마무리

이번 글에서는 Amazon Linux 2023 기반의 EKS 노드에서 nodeadm의 실행 순서를 활용해 Instance ID 기반으로 Hostname을 변경하는 방법을 알아보았습니다.

 

핵심은 cloud-init이 nodeadm-run.service보다 먼저 실행된다는 점입니다. 이를 활용하면 Launch Template의 User Data에서 NodeConfig 파일을 미리 생성하고, 이후 nodeadm이 해당 설정을 읽도록 구성할 수 있습니다.

 

또한 EKS Access Entry와 aws-auth ConfigMap의 인증 설정을 함께 고려해야 정상적으로 Kubernetes 노드에 등록할 수 있습니다.

이번 과정을 통해 EKS의 노드 초기화 구조와 Kubernetes 인증 과정이 서로 어떻게 연결되는지 이해할 수 있었습니다.

 

이것으로 EKS 노드의 Hostname을 Instance ID 기반으로 변경하는 방법에 대한 글을 마치겠습니다. 감사합니다!

 

참고 문서

https://docs.aws.amazon.com/ko_kr/eks/latest/userguide/launch-templates.html

시작 템플릿을 사용한 관리형 노드 사용자 지정 - Amazon EKS

https://docs.aws.amazon.com/eks/latest/userguide/access-entries.html

Grant IAM users access to Kubernetes with EKS access entries - Amazon EKS