AWS CLI로 EKS Auto Mode 클러스터 생성하기

EKS Auto Mode 클러스터는 컴퓨트·스토리지·네트워킹에 대한 일상적인 클러스터 관리 작업을 자동화합니다. 예를 들어 EKS Auto Mode 클러스터는 추가 노드가 필요할 때를 자동으로 감지하고 워크로드 수요를 충족하도록 새 EC2 인스턴스를 프로비저닝합니다.

이 주제에서는 AWS CLI로 새 EKS Auto Mode 클러스터를 만들고 선택적으로 샘플 워크로드를 배포하는 방법을 안내합니다.

출처: 문서

본문

사전 조건

시작하기 전에 다음을 준비하세요.

최신 버전의 AWS Command Line Interface(AWS CLI)가 기기에 설치·구성되어 있어야 합니다. 현재 버전을 확인하려면 aws --version을 실행하세요. AWS CLI 설치·업데이트 방법은 AWS Command Line Interface User Guide의 Installing과 Quick configuration을 참고하세요.
IAM 정책, IAM 역할, EKS 클러스터를 포함한 AWS 리소스를 만들 수 있는 충분한 IAM 권한.
기기에 kubectl 명령줄 도구가 설치되어 있어야 합니다. AWS는 EKS 클러스터의 Kubernetes 버전과 같은 kubectl 버전을 사용할 것을 권장합니다. kubectl 설치·업그레이드 방법은 Set up kubectl and eksctl을 참고하세요.

VPC 서브넷 지정

Amazon EKS Auto Mode는 VPC 서브넷에 노드를 배포합니다. EKS 클러스터를 만들 때 노드가 배포될 VPC 서브넷을 지정해야 해요. AWS 계정의 기본 VPC 서브넷을 사용하거나 크리티컬 워크로드용 전용 VPC를 만들 수 있습니다.

AWS는 클러스터용 전용 VPC 생성을 권장합니다. Create an Amazon VPC for your Amazon EKS cluster 방법을 배우세요.
EKS 콘솔은 새 VPC 생성을 지원합니다. Create an EKS Auto Mode Cluster with the AWS Management Console 방법을 배우세요.
대신 AWS 계정의 기본 VPC를 사용할 수도 있습니다. 다음 지침으로 Subnet ID를 찾으세요.

AWS CLI 사용:

다음 명령을 실행해 기본 VPC와 그 서브넷을 나열합니다.

aws ec2 describe-subnets --filters "Name=vpc-id,Values=$(aws ec2 describe-vpcs --query 'Vpcs[?IsDefault==`true`].VpcId' --output text)" --query 'Subnets[*].{ID:SubnetId,AZ:AvailabilityZone}' --output table

출력을 저장하고 Subnet ID를 기록하세요. 샘플 출력:

----------------------------------------
|             DescribeSubnets          |
----------------------------------------
|   SubnetId        |   AvailabilityZone  |
|--------------------|---------------------|
|   subnet-012345678 |   us-west-2a        |
|   subnet-234567890 |   us-west-2b        |
|   subnet-345678901 |   us-west-2c        |
----------------------------------------

EKS Auto Mode 클러스터용 IAM 역할

Cluster IAM Role

EKS Auto Mode는 AWS 계정에서 새 EC2 인스턴스 프로비저닝 같은 작업을 수행하려면 Cluster IAM Role이 필요합니다. EKS에 필요한 권한을 부여하려면 이 역할을 만들어야 해요. AWS는 Cluster IAM Role에 다음 AWS 관리형 정책을 연결할 것을 권장합니다.

AmazonEKSComputePolicy
AmazonEKSBlockStoragePolicyV2
AmazonEKSLoadBalancingPolicy
AmazonEKSNetworkingPolicy
AmazonEKSClusterPolicy

Node IAM Role

EKS Auto Mode 클러스터를 만들 때 Node IAM Role을 지정합니다. EKS Auto Mode가 대기 중인 워크로드를 처리할 노드를 만들 때 각 새 EC2 인스턴스 노드에 Node IAM Role이 할당됩니다. 이 역할은 노드가 EKS와 통신할 수 있게 하지만, 일반적으로 노드에서 실행되는 워크로드는 접근하지 않아요.

노드에서 실행되는 워크로드에 권한을 부여하려면 EKS Pod Identity를 사용하세요. 자세한 내용은 Learn how EKS Pod Identity grants pods access to AWS services를 참고하세요. 이 역할을 만들고 다음 AWS 관리형 정책을 연결해야 합니다.

AmazonEKSWorkerNodeMinimalPolicy
AmazonEC2ContainerRegistryPullOnly

Service-Linked Role

EKS Auto Mode는 AWS가 자동으로 생성·구성하는 Service-Linked Role도 필요합니다. 자세한 내용은 AWSServiceRoleForAmazonEKS를 참고하세요.

EKS Auto Mode Cluster IAM Role 생성

1단계: Trust Policy 생성

Amazon EKS 서비스가 역할을 수임할 수 있게 하는 trust policy를 만듭니다. 정책을 trust-policy.json으로 저장하세요.

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "eks.amazonaws.com"
      },
      "Action": [
        "sts:AssumeRole",
        "sts:TagSession"
      ]
    }
  ]
}

2단계: IAM Role 생성

trust policy로 Cluster IAM Role을 만듭니다.

aws iam create-role \
    --role-name AmazonEKSAutoClusterRole \
    --assume-role-policy-document file://trust-policy.json

3단계: Role ARN 기록

새 역할의 ARN을 가져와 이후 단계에서 사용할 수 있게 저장합니다.

aws iam get-role --role-name AmazonEKSAutoClusterRole --query "Role.Arn" --output text

4단계: 필요한 정책 연결

필요한 권한을 부여하기 위해 Cluster IAM Role에 다음 AWS 관리형 정책을 연결합니다.

AmazonEKSClusterPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSClusterPolicy

AmazonEKSComputePolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSComputePolicy

AmazonEKSBlockStoragePolicyV2:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSBlockStoragePolicyV2

AmazonEKSLoadBalancingPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSLoadBalancingPolicy

AmazonEKSNetworkingPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoClusterRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSNetworkingPolicy

EKS Auto Mode Node IAM Role 생성

1단계: Trust Policy 생성

Amazon EKS 서비스가 역할을 수임할 수 있게 하는 trust policy를 만듭니다. 정책을 node-trust-policy.json으로 저장하세요.

{
  "Version":"2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

2단계: Node IAM Role 생성

이전 단계의 node-trust-policy.json 파일로 어떤 엔티티가 역할을 수임할 수 있는지 정의합니다. 다음 명령으로 Node IAM Role을 만듭니다.

aws iam create-role \
    --role-name AmazonEKSAutoNodeRole \
    --assume-role-policy-document file://node-trust-policy.json

3단계: Role ARN 기록

역할을 만든 뒤 Node IAM Role의 ARN을 가져와 저장합니다. 이후 단계에서 필요합니다. 다음 명령으로 ARN을 가져옵니다.

aws iam get-role --role-name AmazonEKSAutoNodeRole --query "Role.Arn" --output text

4단계: 필요한 정책 연결

Node IAM Role에 다음 AWS 관리형 정책을 연결해 필요한 권한을 제공합니다.

AmazonEKSWorkerNodeMinimalPolicy:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoNodeRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodeMinimalPolicy

AmazonEC2ContainerRegistryPullOnly:

aws iam attach-role-policy \
    --role-name AmazonEKSAutoNodeRole \
    --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPullOnly

EKS Auto Mode 클러스터 생성

개요

AWS CLI로 EKS Auto Mode 클러스터를 만들려면 다음 매개변수가 필요합니다.

cluster-name: 클러스터 이름
k8s-version: Kubernetes 버전(예: 1.31)
subnet-ids: 이전 단계에서 식별한 Subnet ID
cluster-role-arn: Cluster IAM Role의 ARN
node-role-arn: Node IAM Role의 ARN

기본 클러스터 구성

클러스터를 만들기 전에 다음 기본값과 기능을 검토하세요.

nodePools: EKS Auto Mode는 general-purpose와 system 기본 Node Pool을 포함합니다. Node Pools에 대해 자세히 알아보세요. Note: EKS Auto Mode의 Node Pools는 Amazon EKS Managed Node Groups와 다르지만 같은 클러스터에 공존할 수 있습니다.
computeConfig.enabled: EC2 인스턴스 생성·삭제 같은 일상적인 컴퓨트 작업을 자동화합니다.
kubernetesNetworkConfig.elasticLoadBalancing.enabled: Elastic Load Balancers 생성·삭제를 포함한 로드 밸런싱 작업을 자동화합니다.
storageConfig.blockStorage.enabled: Amazon EBS 볼륨 생성·삭제 같은 스토리지 작업을 자동화합니다.
accessConfig.authenticationMode: EKS access entries가 필요합니다. EKS 인증 모드에 대해 자세히 알아보세요.

환경 변수 설정

create-cluster 명령을 실행하기 전에 다음 환경 변수를 설정합니다. 플레이스홀더 값을 자신의 값으로 바꾸세요.

export AWS_REGION=us-east-1
export CLUSTER_NAME=my-auto-cluster
export K8S_VERSION=1.35
export CLUSTER_ROLE_ARN=arn:aws:iam::111122223333:role/AmazonEKSAutoClusterRole
export NODE_ROLE_ARN=arn:aws:iam::111122223333:role/AmazonEKSAutoNodeRole
export SUBNETS_JSON='["subnet-ExampleID1","subnet-ExampleID2","subnet-ExampleID3"]'

Note: SUBNETS_JSON 변수를 이전 단계의 subnet ID로 설정하세요. 셸이 대괄호와 따옴표를 특수 문자로 해석하지 않도록 값을 작은따옴표로 감싸야 합니다.

변수 확인(선택)

변수가 올바르게 설정되었는지 확인합니다.

echo "Region: ${AWS_REGION}"
echo "Cluster Name: ${CLUSTER_NAME}"
echo "K8s Version: ${K8S_VERSION}"
echo "Cluster Role ARN: ${CLUSTER_ROLE_ARN}"
echo "Node Role ARN: ${NODE_ROLE_ARN}"
echo "Subnets JSON: ${SUBNETS_JSON}"

명령 실행

다음 명령으로 클러스터를 만듭니다.

aws eks create-cluster \
  --region ${AWS_REGION} \
  --cli-input-json \
  "{
      \"name\": \"${CLUSTER_NAME}\",
      \"version\": \"${K8S_VERSION}\",
      \"roleArn\": \"${CLUSTER_ROLE_ARN}\",
      \"resourcesVpcConfig\": {
        \"subnetIds\": ${SUBNETS_JSON},
        \"endpointPublicAccess\": true,
        \"endpointPrivateAccess\": true
      },
      \"computeConfig\": {
        \"enabled\": true,
        \"nodeRoleArn\":\"${NODE_ROLE_ARN}\",
        \"nodePools\": [\"general-purpose\", \"system\"]
      },
      \"kubernetesNetworkConfig\": {
        \"elasticLoadBalancing\": {
          \"enabled\": true
        }
      },
      \"storageConfig\": {
        \"blockStorage\": {
          \"enabled\": true
        }
      },
      \"accessConfig\": {
        \"authenticationMode\": \"API\"
      }
    }"

클러스터 상태 확인

1단계: 클러스터 생성 확인 — 다음 명령으로 클러스터 상태를 확인합니다. 클러스터 생성은 보통 약 15분 걸립니다.

aws eks describe-cluster --name "${CLUSTER_NAME}" --output json

2단계: kubeconfig 업데이트 — 클러스터가 준비되면 로컬 kubeconfig 파일을 업데이트해 kubectl이 클러스터와 통신할 수 있게 합니다. 이 구성은 인증에 AWS CLI를 사용합니다.

aws eks update-kubeconfig --name "${CLUSTER_NAME}"

3단계: Node Pools 확인 — 다음 명령으로 클러스터의 Node Pools를 나열합니다.

kubectl get nodepools

다음 단계

새 EKS Auto Mode 클러스터에 샘플 워크로드를 배포하는 방법을 배워 보세요.

더 알아보기 (Learn more)

공식 문서