Amazon EKS 시작하기 – AWS Management Console 및 AWS CLI

Note: 이 주제는 EKS Auto Mode 없이 시작하는 내용을 다룹니다. 노드 배포에 Managed Node Groups를 사용합니다. EKS Auto Mode는 클러스터 컴퓨트·스토리지·네트워킹의 일상 작업을 자동화합니다. Amazon EKS Auto Mode 시작 방법을 배우려면 Amazon EKS Auto Mode를 참고하세요. EKS Auto Mode가 노드 배포의 선호 방법입니다.

이 가이드는 AWS Management Console과 AWS CLI로 Amazon Elastic Kubernetes Service(Amazon EKS)를 시작하는 데 필요한 모든 리소스를 만들도록 도와줍니다. 이 가이드에서는 각 리소스를 수동으로 만들 거예요. 튜토리얼이 끝나면 애플리케이션을 배포할 수 있는 실행 중인 Amazon EKS 클러스터가 생깁니다.

이 가이드의 절차는 각 리소스가 어떻게 생성되고 서로 어떻게 상호작용하는지 완전히 볼 수 있게 해 줍니다. 대부분의 리소스를 자동으로 만들어주는 것을 원한다면 eksctl CLI로 클러스터와 노드를 만드세요. 자세한 내용은 Get started with Amazon EKS – eksctl을 참고하세요.

출처: 문서

본문

사전 조건

이 튜토리얼을 시작하기 전에 Amazon EKS 클러스터를 생성·관리하는 데 필요한 다음 도구와 리소스를 설치·구성해야 합니다.

AWS CLI – Amazon EKS를 포함한 AWS 서비스 작업용 명령줄 도구입니다. 자세한 내용은 AWS Command Line Interface User Guide의 Installing을 참고하세요. AWS CLI를 설치한 뒤 구성하는 것도 권장합니다. 자세한 내용은 AWS Command Line Interface User Guide의 Quick configuration with aws configure 참고. 이 페이지에 표시된 update-kubeconfig 옵션을 사용하려면 AWS CLI v2가 필요합니다.
kubectl – Kubernetes 클러스터 작업용 명령줄 도구입니다. 자세한 내용은 Set up kubectl and eksctl을 참고하세요.
필수 IAM 권한 – 사용 중인 IAM 보안 주체는 Amazon EKS IAM 역할, 서비스 연결 역할, AWS CloudFormation, VPC 및 관련 리소스를 작업할 권한이 있어야 합니다. 자세한 내용은 IAM User Guide의 Actions와 Using service-linked roles를 참고하세요. 이 가이드의 모든 단계를 같은 사용자로 완료해야 합니다. 현재 사용자를 확인하려면 다음 명령을 실행하세요.

aws sts get-caller-identity

이 주제의 단계를 Bash 셸에서 완료할 것을 권장합니다. Bash 셸을 사용하지 않는다면 줄 연속 문자, 변수 설정·사용 방식 같은 일부 스크립트 명령을 셸에 맞게 조정해야 해요. 또한 셸의 따옴표·이스케이프 규칙이 다를 수 있습니다. 자세한 내용은 AWS Command Line Interface User Guide의 Using quotation marks with strings in the AWS CLI 참고.

1단계: Amazon EKS 클러스터 생성

Important: 가능한 한 간단하고 빠르게 시작하기 위해 이 주제에는 기본 설정으로 클러스터를 만드는 단계가 포함됩니다. 프로덕션용 클러스터를 만들기 전에 모든 설정을 숙지하고 요구사항을 충족하는 설정으로 배포하는 것을 권장합니다. 자세한 내용은 Create an Amazon EKS cluster를 참고하세요. 일부 설정은 클러스터를 만들 때만 활성화할 수 있습니다.

Amazon EKS 요구사항을 충족하는 공용·프라이빗 서브넷이 있는 Amazon VPC를 만듭니다. region-code를 Amazon EKS가 지원하는 AWS 리전으로 바꾸세요. AWS 리전 목록은 AWS General Reference 가이드의 Amazon EKS endpoints and quotas를 참고하세요. my-eks-vpc-stack은 원하는 이름으로 바꿀 수 있어요.

aws cloudformation create-stack \
  --region region-code \
  --stack-name my-eks-vpc-stack \
  --template-url https://s3.us-west-2.amazonaws.com/amazon-eks/cloudformation/2020-10-29/amazon-eks-vpc-private-subnets.yaml

Tip: 이전 명령이 만드는 모든 리소스 목록은 AWS CloudFormation 콘솔(https://console.aws.amazon.com/cloudformation/)을 열어 확인하세요. my-eks-vpc-stack 스택을 선택한 다음 Resources 탭을 선택합니다.

클러스터 IAM 역할을 만들고 필요한 Amazon EKS IAM 관리형 정책을 연결합니다. Amazon EKS가 관리하는 Kubernetes 클러스터는 사용자를 대신해 다른 AWS 서비스에 요청하여 서비스와 함께 사용하는 리소스를 관리합니다. 다음 내용을 eks-cluster-role-trust-policy.json 파일에 복사합니다.

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

역할을 만듭니다.

aws iam create-role \
  --role-name myAmazonEKSClusterRole \
  --assume-role-policy-document file://"eks-cluster-role-trust-policy.json"

필요한 Amazon EKS 관리형 IAM 정책을 역할에 연결합니다.

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

Amazon EKS 콘솔(https://console.aws.amazon.com/eks/home#/clusters)을 엽니다.
콘솔 오른쪽 위에 표시된 AWS 리전이 클러스터를 만들 리전인지 확인합니다. 아니라면 AWS 리전 이름 옆 드롭다운을 선택해 원하는 리전을 고릅니다.
Create cluster를 선택합니다. 이 옵션이 보이지 않으면 왼쪽 탐색 창에서 Clusters를 먼저 선택하세요.
Configure cluster 페이지에서 다음을 수행합니다.
- Custom configuration을 선택하고 Use EKS Auto Mode를 비활성화합니다. (EKS Auto Mode 클러스터를 원한다면 대신 Create an EKS Auto Mode Cluster with the AWS Management Console을 참고하세요.)
- 클러스터의 Name을 입력합니다(예: my-cluster). 이름은 영숫자 문자(대소문자 구분)와 하이픈만 포함할 수 있고, 영숫자 문자로 시작해야 하며 100자를 초과할 수 없습니다. 이름은 클러스터를 만드는 AWS 리전과 계정 내에서 고유해야 합니다.
- Cluster Service Role에서 myAmazonEKSClusterRole을 선택합니다.
- 나머지 설정은 기본값으로 두고 Next를 선택합니다.
Specify networking 페이지에서 다음을 수행합니다.
- VPC 드롭다운에서 이전 단계에서 만든 VPC의 ID를 선택합니다. * | my-eks-vpc-stack-VPC 같은 형태입니다.
- Subnets 드롭다운에서 이전 단계에서 만든 서브넷을 선택합니다. * | my-eks-vpc-stack-* 같은 형태입니다.
- Additional security groups 드롭다운에서 이전 단계에서 만든 보안 그룹을 선택합니다. * | my-eks-vpc-stack-ControlPlaneSecurityGroup-* 같은 형태입니다.
- 나머지 설정은 기본값으로 두고 Next를 선택합니다.
Configure observability 페이지에서 Next를 선택합니다.
Select add-ons 페이지에서 Next를 선택합니다. 애드온에 대한 자세한 내용은 Amazon EKS add-ons를 참고하세요.
Configure selected add-ons settings 페이지에서 Next를 선택합니다.
Review and create 페이지에서 Create를 선택합니다.
클러스터 이름 오른쪽에서 클러스터 프로비저닝 과정이 완료될 때까지 몇 분간 상태가 Creating으로 표시됩니다. 상태가 Active가 될 때까지 다음 단계로 진행하지 마세요.

Note: 요청의 Availability Zone 중 하나가 Amazon EKS 클러스터를 만들 충분한 용량이 없다는 오류가 발생할 수 있어요. 이 경우 오류 출력에 새 클러스터를 지원할 수 있는 Availability Zones가 포함됩니다. 계정의 지원 Availability Zones에 있는 서브넷 최소 2개로 클러스터 생성을 다시 시도하세요. 자세한 내용은 Insufficient capacity를 참고하세요.

2단계: 클러스터에 연결

이 섹션에서는 kubectl을 클러스터에 연결해 Kubernetes 리소스를 관리할 수 있게 합니다. 진행하기 전에 1단계에서 클러스터 생성이 성공적으로 완료되었는지 확인하세요.

옵션 1: AWS CLI로 연결 — 클러스터용 kubeconfig 파일을 만들거나 업데이트합니다. region-code를 클러스터를 만든 AWS 리전으로, my-cluster를 클러스터 이름으로 바꾸세요.

aws eks update-kubeconfig --region region-code --name my-cluster

기본적으로 config 파일은 ~/.kube에 생성되거나 새 클러스터 구성이 ~/.kube의 기존 config 파일에 추가됩니다. 구성을 테스트합니다.

kubectl get svc

Note: 권한 부여나 리소스 유형 오류가 발생하면 트러블슈팅 주제의 Unauthorized or access denied (kubectl)를 참고하세요. 예시 출력:

NAME             TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
svc/kubernetes   ClusterIP   10.100.0.1           443/TCP   1m

옵션 2: EKS 콘솔로 연결 — 로컬 설정 없이 콘솔에서 직접 연결할 수도 있어요. 1단계에서 만든 클러스터의 클러스터 세부 정보 페이지에서 Connect를 선택하면 클러스터용 kubectl이 미리 구성된 AWS CloudShell이 열립니다. 연결을 테스트합니다.

kubectl get svc

자세한 내용은 Connect kubectl to an EKS cluster by creating a kubeconfig file를 참고하세요.

3단계: 노드 생성

Important: 가능한 한 간단하고 빠르게 시작하기 위해 이 주제에는 대부분 기본 설정으로 노드를 만드는 단계가 포함됩니다. 프로덕션용 노드를 만들기 전에 모든 설정을 숙지하고 요구사항을 충족하는 설정으로 배포하는 것을 권장합니다. 자세한 내용은 Manage compute resources by using nodes를 참고하세요. 일부 설정은 노드를 만들 때만 활성화할 수 있습니다.

이 절차는 이전 단계에서 만든 서브넷과 노드 IAM 역할을 지정하여 Managed node groups로 노드를 만들도록 클러스터를 구성합니다. Amazon EC2 인스턴스에서 Amazon Linux 애플리케이션을 실행할 수 있게 해 줍니다.

EKS에서 노드를 구성하는 다양한 방법은 Manage compute resources by using nodes를 참고하세요. 클러스터 배포 후 다른 노드 유형을 추가할 수 있습니다. 이 가이드에서 다루지는 않지만 Windows 자체 관리형 노드와 Bottlerocket 노드도 클러스터에 추가할 수 있어요.

EC2 Linux 관리형 노드 그룹 생성

노드 IAM 역할을 만들고 필요한 Amazon EKS IAM 관리형 정책을 연결합니다. Amazon EKS 노드 kubelet 데몬은 사용자를 대신해 AWS API에 요청합니다. 노드는 IAM 인스턴스 프로필과 관련 정책을 통해 이러한 API 호출 권한을 받습니다. 다음 내용을 node-role-trust-policy.json 파일에 복사합니다.

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

노드 IAM 역할을 만듭니다.

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

필요한 관리형 IAM 정책을 역할에 연결합니다.

aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKSWorkerNodePolicy \
  --role-name myAmazonEKSNodeRole
aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly \
  --role-name myAmazonEKSNodeRole
aws iam attach-role-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonEKS_CNI_Policy \
  --role-name myAmazonEKSNodeRole

Amazon EKS 콘솔(https://console.aws.amazon.com/eks/home#/clusters)을 엽니다.
1단계에서 만든 클러스터 이름(예: my-cluster)을 선택합니다.
my-cluster 페이지에서 다음을 수행합니다.
- Compute 탭을 선택합니다.
- Add Node Group을 선택합니다.
Configure Node Group 페이지에서 다음을 수행합니다.
- Name에 관리형 노드 그룹의 고유 이름을 입력합니다(예: my-nodegroup). 노드 그룹 이름은 63자를 초과할 수 없습니다. 문자나 숫자로 시작해야 하며, 나머지 문자에는 하이픈과 밑줄을 포함할 수 있어요.
- Node IAM role name에서 이전 단계에서 만든 myAmazonEKSNodeRole 역할을 선택합니다. 각 노드 그룹이 고유한 IAM 역할을 사용하는 것을 권장합니다.
- Next를 선택합니다.
Set compute and scaling configuration 페이지에서 기본값을 수락하고 Next를 선택합니다.
Specify networking 페이지에서 기본값을 수락하고 Next를 선택합니다.
Review and create 페이지에서 관리형 노드 그룹 구성을 검토하고 Create를 선택합니다.
몇 분 후 Node Group 구성 섹션의 Status가 Creating에서 Active로 변경됩니다. 상태가 Active가 될 때까지 다음 단계로 진행하지 마세요.

4단계: 리소스 보기

노드와 Kubernetes 워크로드를 볼 수 있어요. 왼쪽 탐색 창에서 Clusters를 선택하고, 클러스터 목록에서 만든 클러스터 이름(예: my-cluster)을 선택합니다. my-cluster 페이지에서 다음을 선택합니다.

Compute 탭 – 클러스터에 배포된 Nodes 목록이 보입니다. 노드 이름을 선택해 자세한 정보를 볼 수 있어요.
Resources 탭 – Amazon EKS 클러스터에 기본적으로 배포되는 모든 Kubernetes 리소스가 보입니다. 콘솔에서 리소스 유형을 선택해 더 알아보세요.

5단계: 리소스 삭제

이 튜토리얼에서 만든 클러스터·노드 사용이 끝나면 만든 리소스를 삭제해야 합니다. 리소스를 삭제하기 전에 이 클러스터로 더 하고 싶은 것이 있다면 다음 단계(Next steps)를 참고하세요.

만든 노드 그룹이나 Fargate 프로필을 삭제합니다. Amazon EKS 콘솔(https://console.aws.amazon.com/eks/home#/clusters)을 엽니다. 왼쪽 탐색 창에서 Clusters를 선택하고, 클러스터 목록에서 my-cluster를 선택합니다. Compute 탭을 선택합니다. 노드 그룹을 만들었다면 my-nodegroup 노드 그룹을 선택하고 Delete를 선택한 뒤 my-nodegroup을 입력하고 Delete를 선택합니다. 노드 그룹 프로필이 삭제될 때까지 계속하지 마세요.
클러스터를 삭제합니다. 왼쪽 탐색 창에서 Clusters를 선택하고, 클러스터 목록에서 my-cluster를 선택합니다. Delete cluster를 선택합니다. my-cluster를 입력하고 Delete를 선택합니다. 클러스터가 삭제될 때까지 계속하지 마세요.
만든 VPC AWS CloudFormation 스택을 삭제합니다. CloudFormation 콘솔(https://console.aws.amazon.com/cloudformation/)을 엽니다. my-eks-vpc-stack 스택을 선택하고 Delete를 선택합니다. Delete my-eks-vpc-stack 확인 대화 상자에서 Delete stack을 선택합니다.
만든 IAM 역할을 삭제합니다. IAM 콘솔(https://console.aws.amazon.com/iam/)을 엽니다. 왼쪽 탐색 창에서 Roles를 선택합니다. 만든 각 역할(myAmazonEKSClusterRole, myAmazonEKSNodeRole)을 목록에서 선택합니다. Delete를 선택하고 요청된 확인 텍스트를 입력한 다음 Delete를 선택합니다.

다음 단계

다음 문서 주제는 클러스터의 기능을 확장하는 데 도움을 줍니다.

클러스터를 만든 IAM 보안 주체만 kubectl이나 AWS Management Console로 Kubernetes API server에 요청할 수 있습니다. 다른 IAM 보안 주체가 클러스터에 접근하게 하려면 추가해야 해요. 자세한 내용은 Grant IAM users and roles access to Kubernetes APIs와 Required permissions를 참고하세요.
클러스터에 샘플 애플리케이션을 배포합니다.
프로덕션용 클러스터를 배포하기 전에 클러스터·노드의 모든 설정을 숙지하는 것을 권장합니다. 일부 설정(예: Amazon EC2 노드에 대한 SSH 접근 활성화)은 클러스터를 만들 때 해야 합니다.
클러스터 보안을 강화하려면 Amazon VPC Container Networking Interface 플러그인이 서비스 계정용 IAM 역할을 사용하도록 구성하세요.

더 알아보기 (Learn more)

공식 문서