런치 템플릿(Launch Template)으로 관리형 노드 사용자 지정

런치 템플릿(Launch Template)으로 관리형 노드 사용자 지정

사용자 지정 런치 템플릿을 사용해 관리형 노드를 배포하는 방법을 설명합니다.

출처: 문서

본문

최고 수준의 사용자 지정을 위해 이 페이지의 단계를 기반으로 자체 런치 템플릿으로 관리형 노드를 배포할 수 있습니다. 런치 템플릿을 사용하면 노드 배포 시 부트스트랩 인수 제공(예: 추가 kubelet 인수), 노드에 할당된 IP 주소와 다른 CIDR 블록에서 Pod에 IP 주소 할당, 노드에 자체 사용자 지정 AMI 배포, 노드에 자체 사용자 지정 CNI 배포 같은 기능이 가능합니다.

관리형 노드 그룹을 처음 만들 때 자체 런치 템플릿을 제공하면 나중에 더 큰 유연성을 갖게 됩니다. 자체 런치 템플릿으로 관리형 노드 그룹을 배포하는 한, 같은 런치 템플릿의 다른 버전으로 반복적으로 업데이트할 수 있습니다. 노드 그룹을 다른 런치 템플릿 버전으로 업데이트하면 그룹의 모든 노드가 지정된 런치 템플릿 버전의 새 구성과 일치하도록 재활용됩니다.

관리형 노드 그룹은 항상 Amazon EC2 Auto Scaling 그룹과 함께 사용할 런치 템플릿으로 배포됩니다. 런치 템플릿을 제공하지 않으면 Amazon EKS API가 계정에 기본값으로 자동 생성합니다. 하지만 자동 생성된 런치 템플릿을 수정하지 않을 것을 권장합니다. 또한 사용자 지정 런치 템플릿을 사용하지 않는 기존 노드 그룹은 직접 업데이트할 수 없습니다. 대신 사용자 지정 런치 템플릿으로 새 노드 그룹을 만들어야 합니다.

런치 템플릿 구성 기본 사항

AWS Management Console, AWS CLI 또는 AWS SDK로 Amazon EC2 Auto Scaling 런치 템플릿을 만들 수 있습니다. 자세한 내용은 Amazon EC2 Auto Scaling 사용 설명서의 "Auto Scaling 그룹용 런치 템플릿 생성"을 참고하세요. 런치 템플릿의 일부 설정은 관리형 노드 구성에 사용되는 설정과 유사합니다. 런치 템플릿으로 노드 그룹을 배포하거나 업데이트할 때 일부 설정은 노드 그룹 구성이나 런치 템플릿 중 한 곳에서만 지정해야 합니다. 두 곳 모두에 설정을 지정하지 마세요. 설정이 있어서는 안 되는 곳에 존재하면 노드 그룹 생성이나 업데이트 같은 작업이 실패합니다.

다음 표는 런치 템플릿에서 금지된 설정을 나열합니다. 관리형 노드 그룹 구성에서 필요한 유사 설정(있는 경우)도 나열합니다. 나열된 설정은 콘솔에 표시되는 설정입니다. AWS CLI와 SDK에서는 유사하지만 다른 이름일 수 있습니다.

런치 템플릿 – 금지 Amazon EKS 노드 그룹 구성
Network interfaces 아래의 Subnet(Add network interface) Specify networking 페이지의 Node group network configuration 아래 Subnets
Advanced details 아래의 IAM instance profile Configure Node group 페이지의 Node group configuration 아래 Node IAM role
Advanced details 아래의 Shutdown behavior 및 Stop - Hibernate behavior. 두 설정 모두 런치 템플릿에서 기본값인 Don't include in launch template 설정을 유지하세요. 없음. Amazon EKS가 Auto Scaling 그룹이 아닌 인스턴스 라이프사이클을 제어해야 합니다.

다음 표는 관리형 노드 그룹 구성에서 금지된 설정을 나열합니다. 런치 템플릿에서 필요한 유사 설정(있는 경우)도 나열합니다. 나열된 설정은 콘솔에 표시되는 설정입니다. AWS CLI와 SDK에서는 유사한 이름일 수 있습니다.

Amazon EKS 노드 그룹 구성 – 금지 런치 템플릿
(런치 템플릿에서 사용자 지정 AMI를 지정한 경우에만) Set compute and scaling configuration 페이지의 Node group compute configuration 아래 AMI type – 콘솔에 Specified in launch template 및 지정된 AMI ID가 표시됩니다. 런치 템플릿에서 Application and OS Images(Amazon Machine Image)를 지정하지 않았다면 노드 그룹 구성에서 AMI를 선택할 수 있습니다. Launch template contents 아래의 Application and OS Images(Amazon Machine Image) – 다음 요구 사항 중 하나에 해당한다면 ID를 지정해야 합니다.
Set compute and scaling configuration 페이지의 Node group compute configuration 아래 Disk size – 콘솔에 Specified in launch template이 표시됩니다. Storage(Volumes) 아래의 Size(Add new volume). 런치 템플릿에서 지정해야 합니다.
Specify Networking 페이지의 Node group configuration 아래 SSH key pair – 콘솔에 런치 템플릿에 지정된 키가 표시되거나 Not specified in launch template이 표시됩니다. Key pair(login) 아래의 Key pair name.
(없음) 런치 템플릿을 사용할 때 원격 액세스가 허용된 소스 보안 그룹을 지정할 수 없습니다. 인스턴스의 Network settings 아래 Security groups 또는 Network interfaces(Add network interface) 아래 Security groups 중 하나만, 둘 다는 안 됩니다. 자세한 내용은 "사용자 지정 보안 그룹 사용"을 참고하세요.

런치 템플릿으로 노드 그룹을 배포하는 경우(사용자 지정 AMI 지정 포함), Amazon EKS 노드 그룹 구성에서 금지된 설정과 관련해서는 다음을 참고하세요.

  • 사용자 지정 AMI를 지정하려면 Launch template contents 아래의 Application and OS Images(Amazon Machine Image) – 사용자 지정 AMI를 사용합니다. "AMI 지정"에 나열된 요구 사항을 충족하지 않는 AMI를 지정하면 노드 그룹 배포가 실패합니다.
  • Amazon EKS 최적화 AMI에 포함된 bootstrap.sh 파일에 인수를 제공하기 위해 사용자 데이터를 제공하려는 경우. 인스턴스가 Pod에 훨씬 더 많은 IP 주소를 할당하거나, 인스턴스와 다른 CIDR 블록에서 Pod에 IP 주소를 할당하거나, 아웃바운드 인터넷 액세스 없이 프라이빗 클러스터를 배포할 수 있게 합니다. 자세한 내용은 다음 주제를 참고하세요.
    • 접두사를 사용해 Amazon EKS 노드에 더 많은 IP 주소 할당
    • 사용자 지정 네트워킹으로 대체 서브넷에 Pod 배포
    • 인터넷 액세스가 제한된 프라이빗 클러스터 배포
    • AMI 지정

참고: 런치 템플릿을 사용해 노드 그룹을 배포한다면 Launch template contents 아래에 0개 또는 1개의 Instance type을 지정하세요. 또는 콘솔의 Set compute and scaling configuration 페이지에서 Instance types에 0-20개의 인스턴스 유형을 지정할 수 있습니다. 또는 Amazon EKS API를 사용하는 다른 도구로 할 수도 있습니다. 런치 템플릿에 인스턴스 유형을 지정하고 그 런치 템플릿으로 노드 그룹을 배포한다면 콘솔이나 Amazon EKS API를 사용하는 다른 도구에서 인스턴스 유형을 지정할 수 없습니다. 런치 템플릿, 콘솔 또는 Amazon EKS API를 사용하는 다른 도구에서 인스턴스 유형을 지정하지 않으면 t3.medium 인스턴스 유형이 사용됩니다. 노드 그룹이 Spot 용량 유형을 사용한다면 콘솔에서 여러 인스턴스 유형을 지정할 것을 권장합니다. 자세한 내용은 "관리형 노드 그룹 용량 유형"을 참고하세요.

노드 그룹에 배포하는 컨테이너가 Instance Metadata Service Version 2를 사용한다면 런치 템플릿에서 Metadata response hop limit을 2로 설정하세요. 자세한 내용은 Amazon EC2 사용 설명서의 "인스턴스 메타데이터 및 사용자 데이터"를 참고하세요.

런치 템플릿은 유연한 인스턴스 유형 선택을 허용하는 InstanceRequirements 기능을 지원하지 않습니다.

Amazon EC2 인스턴스 태그 지정

런치 템플릿의 TagSpecification 매개변수를 사용해 노드 그룹의 Amazon EC2 인스턴스에 적용할 태그를 지정할 수 있습니다. CreateNodegroup 또는 UpdateNodegroupVersion API를 호출하는 IAM 엔티티는 ec2:RunInstances와 ec2:CreateTags 권한이 있어야 하며, 태그는 런치 템플릿에 추가되어야 합니다.

사용자 지정 보안 그룹 사용

런치 템플릿을 사용해 노드 그룹의 인스턴스에 적용할 사용자 지정 Amazon EC2 보안 그룹을 지정할 수 있습니다. 이는 인스턴스 수준 보안 그룹 매개변수 또는 네트워크 인터페이스 구성 매개변수의 일부로 설정할 수 있습니다. 그러나 인스턴스 수준과 네트워크 인터페이스 보안 그룹을 모두 지정하는 런치 템플릿은 만들 수 없습니다. 관리형 노드 그룹에서 사용자 지정 보안 그룹을 사용할 때 적용되는 다음 조건을 고려하세요.

  • AWS Management Console을 사용할 때 Amazon EKS는 단일 네트워크 인터페이스 사양이 있는 런치 템플릿만 허용합니다.
  • 기본적으로 Amazon EKS는 노드와 컨트롤 플레인 간의 통신을 촉진하기 위해 클러스터 보안 그룹을 노드 그룹의 인스턴스에 적용합니다. 앞서 언급한 옵션 중 하나로 런치 템플릿에 사용자 지정 보안 그룹을 지정하면 Amazon EKS가 클러스터 보안 그룹을 추가하지 않습니다. 따라서 보안 그룹의 인바운드 및 아웃바운드 규칙이 클러스터 엔드포인트와 통신할 수 있게 해주는지 확인해야 합니다. 보안 그룹 규칙이 올바르지 않으면 워커 노드가 클러스터에 가입할 수 없습니다. 보안 그룹 규칙에 대한 자세한 내용은 "클러스터용 Amazon EKS 보안 그룹 요구 사항 보기"를 참고하세요.
  • 노드 그룹의 인스턴스에 SSH 액세스가 필요하면 그 액세스를 허용하는 보안 그룹을 포함하세요.

Amazon EC2 사용자 데이터

런치 템플릿에는 사용자 지정 사용자 데이터 섹션이 포함됩니다. 개별 사용자 지정 AMI를 수동으로 만들지 않고도 이 섹션에 노드 그룹의 구성 설정을 지정할 수 있습니다. Bottlerocket에 사용 가능한 설정에 대한 자세한 내용은 GitHub의 "Using user data"를 참고하세요.

인스턴스를 시작할 때 cloud-init를 사용해 런치 템플릿에 Amazon EC2 사용자 데이터를 제공할 수 있습니다. 자세한 내용은 cloud-init 문서를 참고하세요. 사용자 데이터는 일반적인 구성 작업을 수행하는 데 사용할 수 있습니다. 여기에는 다음 작업이 포함됩니다.

  • 사용자 또는 그룹 포함
  • 패키지 설치

관리형 노드 그룹과 함께 사용되는 런치 템플릿의 Amazon EC2 사용자 데이터는 Amazon Linux AMI의 경우 MIME 다중 파트 아카이브 형식, Bottlerocket AMI의 경우 TOML 형식이어야 합니다. 이는 사용자 데이터가 노드가 클러스터에 가입하는 데 필요한 Amazon EKS 사용자 데이터와 병합되기 때문입니다. kubelet을 시작하거나 수정하는 명령은 사용자 데이터에 지정하지 마세요. 이는 Amazon EKS가 병합한 사용자 데이터의 일부로 수행됩니다. 노드에 라벨 설정 같은 특정 kubelet 매개변수는 관리형 노드 그룹 API로 직접 구성할 수 있습니다.

참고: 수동 시작이나 사용자 지정 구성 매개변수 전달을 포함한 고급 kubelet 사용자 지정에 대한 자세한 내용은 "AMI 지정"을 참고하세요. 런치 템플릿에 사용자 지정 AMI ID가 지정되면 Amazon EKS는 사용자 데이터를 병합하지 않습니다.

다음 세부 정보는 사용자 데이터 섹션에 대한 더 많은 정보를 제공합니다.

Amazon Linux 2 사용자 데이터 – 여러 사용자 데이터 블록을 단일 MIME 다중 파트 파일로 결합할 수 있습니다. 예를 들어 Docker 데몬을 구성하는 cloud boothook을 사용자 지정 패키지를 설치하는 사용자 데이터 셸 스크립트와 결합할 수 있습니다. MIME 다중 파트 파일은 다음 구성 요소로 구성됩니다.

  • 콘텐츠 유형 및 파트 경계 선언 – Content-Type: multipart/mixed; boundary="==MYBOUNDARY=="
  • MIME 버전 선언 – MIME-Version: 1.0
  • 다음 구성 요소를 포함하는 하나 이상의 사용자 데이터 블록:
    • 사용자 데이터 블록의 시작을 알리는 여는 경계 – --==MYBOUNDARY==
    • 블록의 콘텐츠 유형 선언: Content-Type: text/cloud-config; charset="us-ascii". 콘텐츠 유형에 대한 자세한 내용은 cloud-init 문서를 참고하세요.
    • 사용자 데이터의 내용(예: 셸 명령 목록 또는 cloud-init 지시문).
    • MIME 다중 파트 파일의 끝을 알리는 닫는 경계: --==MYBOUNDARY==--

다음은 직접 만들 수 있는 MIME 다중 파트 파일의 예제입니다.

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

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

#!/bin/bash
echo "Running custom user data script"

--==MYBOUNDARY==--

Amazon Linux 2023 사용자 데이터 – Amazon Linux 2023(AL2023)은 YAML 구성 스키마를 사용하는 새 노드 초기화 프로세스 nodeadm을 도입합니다. 자체 관리형 노드 그룹이나 런치 템플릿이 있는 AMI를 사용한다면 이제 새 노드 그룹을 만들 때 추가 클러스터 메타데이터를 명시적으로 제공해야 합니다. 최소 요구 매개변수의 예는 다음과 같습니다. 여기서 apiServerEndpoint, certificateAuthority, service cidr은 이제 필수입니다.

---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig
spec:
  cluster:
    name: my-cluster
    apiServerEndpoint: https://example.com
    certificateAuthority: Y2VydGlmaWNhdGVBdXRob3JpdHk=
    cidr: 10.100.0.0/16

일반적으로 이 구성은 있는 그대로 또는 MIME 다중 파트 문서에 포함해 사용자 데이터에 설정합니다.

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

--BOUNDARY
Content-Type: application/node.eks.aws

---
apiVersion: node.eks.aws/v1alpha1
kind: NodeConfig spec: [...]

--BOUNDARY--

AL2에서는 이러한 매개변수의 메타데이터가 Amazon EKS DescribeCluster API 호출에서 검색되었습니다. AL2023에서는 대규모 노드 확장 중에 추가 API 호출이 제한(throttling)될 위험이 있으므로 이 동작이 변경되었습니다. 런치 템플릿 없이 관리형 노드 그룹을 사용하거나 Karpenter를 사용한다면 이 변경의 영향을 받지 않습니다. certificateAuthority와 service cidr에 대한 자세한 내용은 Amazon EKS API Reference의 DescribeCluster를 참고하세요.

다음은 노드 사용자 지정을 위한 셸 스크립트(패키지 설치나 컨테이너 이미지 사전 캐싱 같은)를 필수 nodeadm 구성과 결합한 AL2023 사용자 데이터의 완전한 예제입니다. 이 예제는 다음을 포함한 일반적인 사용자 지정을 보여줍니다.

  • 추가 시스템 패키지 설치
  • Pod 시작 시간을 개선하기 위한 컨테이너 이미지 사전 캐싱
  • HTTP 프록시 구성 설정
  • 노드 라벨링을 위한 kubelet 플래그 구성
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="BOUNDARY"

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

#!/bin/bash
set -o errexit
set -o pipefail
set -o nounset

# Install additional packages
yum install -y htop jq iptables-services

# Pre-cache commonly used container images
nohup docker pull public.ecr.aws/eks-distro/kubernetes/pause:3.2 &

# Configure HTTP proxy if needed
cat > /etc/profile.d/http-proxy.sh

Bottlerocket 사용자 데이터 – Bottlerocket은 TOML 형식으로 사용자 데이터를 구성합니다. Amazon EKS가 제공하는 사용자 데이터와 병합할 사용자 데이터를 제공할 수 있습니다. 예를 들어 추가 kubelet 설정을 제공할 수 있습니다.

[settings.kubernetes.system-reserved]
cpu = "10m"
memory = "100Mi"
ephemeral-storage= "1Gi"

지원되는 설정에 대한 자세한 내용은 Bottlerocket 문서를 참고하세요. 사용자 데이터에서 노드 라벨과 taint를 구성할 수 있습니다. 하지만 이는 노드 그룹 내에서 구성할 것을 권장합니다. 그렇게 하면 Amazon EKS가 이 구성을 적용합니다.

사용자 데이터가 병합될 때 형식은 유지되지 않지만 내용은 동일하게 유지됩니다. 사용자 데이터에 제공한 구성은 Amazon EKS가 구성한 모든 설정을 재정의합니다. 따라서 settings.kubernetes.max-pods나 settings.kubernetes.cluster-dns-ip를 설정하면 사용자 데이터의 이 값이 노드에 적용됩니다.

Amazon EKS는 모든 유효한 TOML을 지원하지 않습니다. 알려진 지원되지 않는 형식 목록은 다음과 같습니다.

  • 따옴표로 묶인 키 안의 따옴표: 'quoted "value"' = "value"
  • 값의 이스케이프된 따옴표: str = "I'm a string. \"You can quote me\""
  • 혼합 부동 소수점과 정수: numbers = [ 0.1, 0.2, 0.5, 1, 2, 5 ]
  • 배열의 혼합 유형: contributors = ["[email protected]", { name = "Baz", email = "[email protected]" }]
  • 따옴표 키가 있는 대괄호 헤더: [foo."bar.baz"]

Windows 사용자 데이터 – Windows 사용자 데이터는 PowerShell 명령을 사용합니다. 관리형 노드 그룹을 만들 때 사용자 지정 사용자 데이터는 Amazon EKS 관리 사용자 데이터와 결합됩니다. PowerShell 명령이 먼저 오고, 그다음 관리 사용자 데이터 명령이 오며, 모두 하나의 `` 태그 안에 있습니다.

중요: Windows 노드 그룹을 만들 때 Amazon EKS는 Linux 기반 노드가 클러스터에 가입하도록 aws-auth ConfigMap을 업데이트합니다. 서비스는 Windows AMI에 대한 권한을 자동으로 구성하지 않습니다. Windows 노드를 사용한다면 access entry API를 통해 또는 aws-auth ConfigMap을 직접 업데이트해 액세스를 관리해야 합니다. 자세한 내용은 "EKS 클러스터에 Windows 노드 배포"를 참고하세요.

참고: 런치 템플릿에 AMI ID가 지정되지 않으면 Amazon EKS를 구성하기 위해 사용자 데이터에 Windows Amazon EKS Bootstrap 스크립트를 사용하지 마세요.

예제 사용자 데이터는 다음과 같습니다.


Write-Host "Running custom user data script"

AMI 지정

다음 요구 사항 중 하나에 해당하면 런치 템플릿의 ImageId 필드에 AMI ID를 지정하세요. 추가 정보가 필요한 요구 사항을 선택하세요.

예제: Amazon EKS 최적화 Linux/Bottlerocket AMI에 포함된 bootstrap.sh 파일에 인수를 전달할 사용자 데이터 제공

부트스트래핑은 인스턴스가 시작될 때 실행할 수 있는 명령을 추가하는 것을 설명하는 용어입니다. 예를 들어 부트스트래핑을 사용하면 추가 kubelet 인수를 사용할 수 있습니다. 런치 템플릿을 지정하지 않고 eksctl을 사용하거나, 런치 템플릿의 사용자 데이터 섹션에 정보를 지정해 bootstrap.sh 스크립트에 인수를 전달할 수 있습니다.

eksctl로 런치 템플릿을 지정하지 않음:

my-nodegroup.yaml이라는 파일을 다음 내용으로 생성합니다. 모든 example value를 자신의 값으로 바꾸세요. --apiserver-endpoint, --b64-cluster-ca, --dns-cluster-ip 인수는 선택 사항입니다. 그러나 정의하면 bootstrap.sh 스크립트가 describeCluster 호출을 피할 수 있습니다. 이는 프라이빗 클러스터 설정이나 노드를 자주 확장·축소하는 클러스터에서 유용합니다. bootstrap.sh 스크립트에 대한 자세한 내용은 GitHub의 bootstrap.sh 파일을 참고하세요.

필수 인수는 클러스터 이름(my-cluster)뿐입니다.

ami-1234567890abcdef0의 최적화 AMI ID를 검색하려면 다음 섹션을 참고하세요.

  • 권장 Amazon Linux AMI ID 검색
  • 권장 Bottlerocket AMI ID 검색
  • 권장 Microsoft Windows AMI ID 검색

클러스터의 certificate-authority를 검색하려면 다음 명령을 실행하세요.

aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code

클러스터의 api-server-endpoint를 검색하려면 다음 명령을 실행하세요.

aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code

--dns-cluster-ip의 값은 서비스 CIDR 끝에 .10을 붙인 것입니다. 클러스터의 service-cidr을 검색하려면 다음 명령을 실행하세요. 예를 들어 반환된 값이 ipv4 10.100.0.0/16이라면 값은 10.100.0.10입니다.

aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code

이 예제는 Amazon EKS 최적화 AMI에 포함된 bootstrap.sh 스크립트를 사용해 사용자 지정 max-pods 값을 설정하는 kubelet 인수를 제공합니다. 노드 그룹 이름은 63자를 넘을 수 없습니다. 문자나 숫자로 시작해야 하며, 나머지 문자에는 하이픈과 밑줄을 포함할 수 있습니다. my-max-pods-value 선택에 대한 도움말은 "How maxPods is determined"를 참고하세요. 관리형 노드 그룹을 사용할 때 maxPods가 결정되는 방법에 대한 자세한 내용은 "How maxPods is determined"를 참고하세요.

---
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig

metadata:
  name: my-cluster
  region: region-code

managedNodeGroups:
  - name: my-nodegroup
    ami: ami-1234567890abcdef0
    instanceType: m5.large
    privateNetworking: true
    disableIMDSv1: true
    labels: { x86-al2-specified-mng }
    overrideBootstrapCommand: |
      #!/bin/bash
      /etc/eks/bootstrap.sh my-cluster \
        --b64-cluster-ca certificate-authority \
        --apiserver-endpoint api-server-endpoint \
        --dns-cluster-ip service-cidr.10 \
        --kubelet-extra-args '--max-pods=my-max-pods-value' \
        --use-max-pods false

모든 사용 가능한 eksctl config 파일 옵션은 eksctl 문서의 "Config file schema"를 참고하세요. eksctl 유틸리티는 여전히 사용자를 위해 런치 템플릿을 만들고 config 파일에서 제공한 데이터로 사용자 데이터를 채웁니다.

다음 명령으로 노드 그룹을 생성합니다.

eksctl create nodegroup --config-file=my-nodegroup.yaml

런치 템플릿의 사용자 데이터:

런치 템플릿의 사용자 데이터 섹션에 다음 정보를 지정합니다. 모든 example value를 자신의 값으로 바꾸세요. --apiserver-endpoint, --b64-cluster-ca, --dns-cluster-ip 인수는 선택 사항입니다. 그러나 정의하면 bootstrap.sh 스크립트가 describeCluster 호출을 피할 수 있습니다. 이는 프라이빗 클러스터 설정이나 노드를 자주 확장·축소하는 클러스터에서 유용합니다. bootstrap.sh 스크립트에 대한 자세한 내용은 GitHub의 bootstrap.sh 파일을 참고하세요.

필수 인수는 클러스터 이름(my-cluster)뿐입니다.

클러스터의 certificate-authority를 검색하려면 다음 명령을 실행하세요.

aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code

클러스터의 api-server-endpoint를 검색하려면 다음 명령을 실행하세요.

aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code

--dns-cluster-ip의 값은 서비스 CIDR 끝에 .10을 붙인 것입니다. 클러스터의 service-cidr을 검색하려면 다음 명령을 실행하세요. 예를 들어 반환된 값이 ipv4 10.100.0.0/16이라면 값은 10.100.0.10입니다.

aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code

이 예제는 Amazon EKS 최적화 AMI에 포함된 bootstrap.sh 스크립트를 사용해 사용자 지정 max-pods 값을 설정하는 kubelet 인수를 제공합니다. my-max-pods-value 선택에 대한 도움말은 "How maxPods is determined"를 참고하세요. 관리형 노드 그룹을 사용할 때 maxPods가 결정되는 방법에 대한 자세한 내용은 "How maxPods is determined"를 참고하세요.

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

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

#!/bin/bash
set -ex
/etc/eks/bootstrap.sh my-cluster \
  --b64-cluster-ca certificate-authority \
  --apiserver-endpoint api-server-endpoint \
  --dns-cluster-ip service-cidr.10 \
  --kubelet-extra-args '--max-pods=my-max-pods-value' \
  --use-max-pods false

--==MYBOUNDARY==--

예제: Amazon EKS 최적화 Windows AMI에 포함된 Start-EKSBootstrap.ps1 파일에 인수를 전달할 사용자 데이터 제공

부트스트래핑은 인스턴스가 시작될 때 실행할 수 있는 명령을 추가하는 것을 설명하는 용어입니다. 런치 템플릿을 지정하지 않고 eksctl을 사용하거나, 런치 템플릿의 사용자 데이터 섹션에 정보를 지정해 Start-EKSBootstrap.ps1 스크립트에 인수를 전달할 수 있습니다.

사용자 지정 Windows AMI ID를 지정하려면 다음 고려 사항을 명심하세요.

  • 런치 템플릿을 사용하고 사용자 데이터 섹션에 필요한 부트스트랩 명령을 제공해야 합니다. 원하는 Windows ID를 검색하려면 "최적화된 Windows AMI로 노드 생성"의 표를 사용할 수 있습니다.
  • 몇 가지 한도와 조건이 있습니다. 예를 들어 AWS IAM Authenticator 구성 맵에 eks:kube-proxy-windows를 추가해야 합니다. 자세한 내용은 "AMI ID 지정 시 한도와 조건"을 참고하세요.

런치 템플릿의 사용자 데이터 섹션에 다음 정보를 지정합니다. 모든 example value를 자신의 값으로 바꾸세요. -APIServerEndpoint, -Base64ClusterCA, -DNSClusterIP 인수는 선택 사항입니다. 그러나 정의하면 Start-EKSBootstrap.ps1 스크립트가 describeCluster 호출을 피할 수 있습니다.

필수 인수는 클러스터 이름(my-cluster)뿐입니다.

클러스터의 certificate-authority를 검색하려면 다음 명령을 실행하세요.

aws eks describe-cluster --query "cluster.certificateAuthority.data" --output text --name my-cluster --region region-code

클러스터의 api-server-endpoint를 검색하려면 다음 명령을 실행하세요.

aws eks describe-cluster --query "cluster.endpoint" --output text --name my-cluster --region region-code

--dns-cluster-ip의 값은 서비스 CIDR 끝에 .10을 붙인 것입니다. 클러스터의 service-cidr을 검색하려면 다음 명령을 실행하세요. 예를 들어 반환된 값이 ipv4 10.100.0.0/16이라면 값은 10.100.0.10입니다.

aws eks describe-cluster --query "cluster.kubernetesNetworkConfig.serviceIpv4Cidr" --output text --name my-cluster --region region-code

추가 인수는 "Bootstrap script configuration parameters"를 참고하세요.

참고: 사용자 지정 서비스 CIDR을 사용한다면 -ServiceCIDR 매개변수로 지정해야 합니다. 그렇지 않으면 클러스터의 Pod에 대한 DNS 확인이 실패합니다.


[string]$EKSBootstrapScriptFile = "$env:ProgramFiles\Amazon\EKS\Start-EKSBootstrap.ps1"
& $EKSBootstrapScriptFile -EKSClusterName my-cluster `
	 -Base64ClusterCA certificate-authority `
	 -APIServerEndpoint api-server-endpoint `
	 -DNSClusterIP service-cidr.10

예제: 특정 보안, 규정 준수 또는 내부 정책 요구 사항으로 인한 사용자 지정 AMI 실행

자세한 내용은 Amazon EC2 사용 설명서의 "Amazon Machine Images (AMI)"를 참고하세요. Amazon EKS AMI 빌드 사양에는 Amazon Linux 기반 사용자 지정 Amazon EKS AMI를 빌드하기 위한 리소스와 구성 스크립트가 포함되어 있습니다. 자세한 내용은 GitHub의 "Amazon EKS AMI Build Specification"을 참고하세요. 다른 운영 체제가 설치된 사용자 지정 AMI를 빌드하려면 GitHub의 "Amazon EKS Sample Custom AMIs"를 참고하세요.

관리형 노드 그룹과 함께 사용되는 런치 템플릿에서는 AMI ID에 동적 매개변수 참조를 사용할 수 없습니다.

중요: AMI를 지정할 때 Amazon EKS는 AMI에 내장된 Kubernetes 버전을 클러스터의 컨트롤 플레인 버전과 비교해 검증하지 않습니다. 사용자 지정 AMI의 Kubernetes 버전이 Kubernetes 버전 불일치 정책을 준수하는지 확인하는 것은 사용자의 책임입니다.

  • 노드의 kubelet 버전은 클러스터 버전보다 새로우면 안 됩니다.
  • 노드의 kubelet 버전은 클러스터 버전보다 최대 3개의 부 버전 뒤이거나 같아야 합니다(Kubernetes 버전 1.28 이상의 경우), 또는 클러스터 버전보다 최대 2개의 부 버전 뒤이거나 같아야 합니다(버전 1.27 이하의 경우).

버전 불일치 위반으로 관리형 노드 그룹을 만들면 다음이 발생할 수 있습니다.

  • 노드가 클러스터에 가입하지 못함
  • 정의되지 않은 동작 또는 API 비호환성
  • 클러스터 불안정성 또는 워크로드 실패

AMI를 지정할 때 Amazon EKS는 사용자 데이터를 병합하지 않습니다. 대신 노드가 클러스터에 가입하는 데 필요한 bootstrap 명령을 제공할 책임이 있습니다. 노드가 클러스터에 가입하지 못하면 Amazon EKS CreateNodegroup 및 UpdateNodegroupVersion 작업도 실패합니다.

AMI ID 지정 시 한도와 조건

관리형 노드 그룹에서 AMI ID를 지정할 때 관련된 한도와 조건은 다음과 같습니다.

  • 런치 템플릿에서 AMI ID를 지정하는 것과 지정하지 않는 것 사이를 전환하려면 새 노드 그룹을 만들어야 합니다.
  • 콘솔에서 더 새로운 AMI 버전이 제공될 때 알림을 받지 않습니다. 노드 그룹을 더 새로운 AMI 버전으로 업데이트하려면 업데이트된 AMI ID로 런치 템플릿의 새 버전을 만들어야 합니다. 그런 다음 노드 그룹을 새 런치 템플릿 버전으로 업데이트해야 합니다.
  • AMI ID를 지정하면 API에서 다음 필드를 설정할 수 없습니다.
    • amiType
    • releaseVersion
    • version
  • AMI ID를 지정하면 API에 설정된 모든 taints가 비동기적으로 적용됩니다. taint를 노드가 클러스터에 가입하기 전에 적용하려면 --register-with-taints 명령줄 플래그를 사용해 사용자 데이터의 kubelet에 taint를 전달해야 합니다. 자세한 내용은 Kubernetes 문서의 kubelet을 참고하세요.
  • Windows 관리형 노드 그룹에 사용자 지정 AMI ID를 지정할 때 AWS IAM Authenticator 구성 맵에 eks:kube-proxy-windows를 추가하세요. DNS가 제대로 작동하려면 이 작업이 필요합니다.

AWS IAM Authenticator 구성 맵을 편집을 위해 엽니다.

kubectl edit -n kube-system cm aws-auth

Windows 노드와 연결된 각 rolearn 아래의 groups 목록에 이 항목을 추가합니다. 구성 맵은 aws-auth-cm-windows.yaml과 유사해야 합니다.

- eks:kube-proxy-windows

파일을 저장하고 텍스트 편집기를 종료합니다.

사용자 지정 런치 템플릿을 사용하는 모든 AMI의 경우 관리형 노드 그룹의 기본 HttpPutResponseHopLimit은 2로 설정됩니다.

더 알아보기 (Learn more)