kubeconfig 파일을 만들어 kubectl을 EKS 클러스터에 연결

클러스터의 kubeconfig 파일을 생성(또는 기존 파일을 업데이트)하여 kubectl을 Amazon EKS 클러스터에 연결하는 방법을 설명합니다.

출처: 문서

본문

팁: 예정된 Amazon EKS 워크숍에 등록하세요.

이 주제에서는 클러스터의 kubeconfig 파일을 생성합니다(또는 기존 파일을 업데이트합니다).

kubectl 명령줄 도구는 kubeconfig 파일의 구성 정보를 사용해 클러스터의 API 서버와 통신합니다. 자세한 내용은 Kubernetes 문서의 "kubeconfig 파일을 사용한 클러스터 액세스 구성"을 참고하세요.

Amazon EKS는 클러스터 인증에 kubectl과 함께 aws eks get-token 명령을 사용합니다. 기본적으로 AWS CLI는 다음 명령으로 반환되는 동일한 자격 증명을 사용합니다.

aws sts get-caller-identity

전제 조건

기존 Amazon EKS 클러스터. 배포하려면 "Amazon EKS 시작하기"를 참고하세요.
사용 기기나 AWS CloudShell에 kubectl 명령줄 도구가 설치되어 있어야 합니다. 버전은 클러스터의 Kubernetes 버전과 같거나 최대 한 개의 부 버전 앞뒤가 될 수 있습니다. 예를 들어 클러스터 버전이 1.29라면 kubectl 버전 1.28, 1.29, 1.30을 사용할 수 있습니다. kubectl 설치 또는 업그레이드 방법은 "kubectl 및 eksctl 설정"을 참고하세요.
사용 기기나 AWS CloudShell에 버전 2.12.3 이상 또는 버전 1.27.160 이상의 AWS Command Line Interface(AWS CLI)가 설치되어 구성되어 있어야 합니다. 현재 버전을 확인하려면 aws --version | cut -d / -f2 | cut -d ' ' -f1을 사용하세요. yum, apt-get, macOS용 Homebrew 같은 패키지 관리자는 AWS CLI 최신 버전보다 몇 버전 뒤처져 있는 경우가 많습니다. 최신 버전 설치 방법은 AWS Command Line Interface 사용 설명서의 "Installing" 및 "aws configure를 사용한 빠른 구성"을 참고하세요. AWS CloudShell에 설치된 AWS CLI 버전도 최신 버전보다 몇 버전 뒤처져 있을 수 있습니다. 업데이트 방법은 AWS CloudShell 사용 설명서의 "홈 디렉터리에 AWS CLI 설치"를 참고하세요.
지정한 클러스터에 대해 eks:DescribeCluster API 작업을 사용할 권한이 있는 IAM 사용자 또는 역할. 자세한 내용은 "Amazon EKS ID 기반 정책 예제"를 참고하세요. 자체 OpenID Connect 공급자의 ID로 클러스터에 액세스한다면, kubeconfig 파일을 생성하거나 업데이트하려면 Kubernetes 문서의 "kubectl 사용"을 참고하세요.

EKS 콘솔(CloudShell)로 연결

로컬 설정 없이 AWS CloudShell을 사용해 AWS Management Console에서 직접 클러스터에 연결할 수 있습니다.

https://console.aws.amazon.com/eks/home#/clusters에서 Amazon EKS 콘솔을 엽니다.
연결하려는 클러스터의 이름을 선택합니다.
클러스터 세부 정보 페이지에서 오른쪽 위 작업 표시줄의 Connect를 선택합니다.
클러스터용으로 사전 구성된 kubectl과 함께 AWS CloudShell이 열립니다.

연결되면 즉시 kubectl 명령을 실행할 수 있습니다.

kubectl get nodes
kubectl get pods -A

CloudShell 세션에는 kubectl, AWS CLI 및 표준 CloudShell 유틸리티가 포함됩니다. 이 기능은 공용 및 프라이빗 API 서버 엔드포인트를 모두 가진 클러스터를 지원합니다. 프라이빗 엔드포인트를 가진 클러스터의 경우 CloudShell이 자동으로 VPC 환경을 시작해 클러스터의 프라이빗 API 서버에 도달하며, 환경 이름을 입력하라는 메시지가 표시됩니다.

AWS CLI를 사용한 kubeconfig 파일 생성

사용 기기나 AWS CloudShell에 버전 2.12.3 이상 또는 버전 1.27.160 이상의 AWS Command Line Interface(AWS CLI)가 설치되어 구성되어 있어야 합니다. 현재 버전을 확인하려면 aws --version | cut -d / -f2 | cut -d ' ' -f1을 사용하세요. yum, apt-get, macOS용 Homebrew 같은 패키지 관리자는 AWS CLI 최신 버전보다 몇 버전 뒤처져 있는 경우가 많습니다. 최신 버전 설치 방법은 AWS Command Line Interface 사용 설명서의 "Installing" 및 "aws configure를 사용한 빠른 구성"을 참고하세요. AWS CloudShell에 설치된 AWS CLI 버전도 최신 버전보다 몇 버전 뒤처져 있을 수 있습니다. 업데이트 방법은 AWS CloudShell 사용 설명서의 "홈 디렉터리에 AWS CLI 설치"를 참고하세요.

지정한 클러스터에 대해 eks:DescribeCluster API 작업을 사용할 권한이 있어야 합니다. 자세한 내용은 "Amazon EKS ID 기반 정책 예제"를 참고하세요.

클러스터의 kubeconfig 파일을 생성하거나 업데이트합니다. region-code를 클러스터가 있는 AWS 리전으로, my-cluster를 클러스터 이름으로 바꾸세요.

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

기본적으로 생성되는 구성 파일은 홈 디렉터리의 기본 kubeconfig 경로(.kube)에 만들어지거나 해당 위치의 기존 config 파일과 병합됩니다. --kubeconfig 옵션으로 다른 경로를 지정할 수 있습니다.

kubectl 명령을 실행할 때 인증에 사용할 IAM 역할 ARN을 --role-arn 옵션으로 지정할 수 있습니다. 그렇지 않으면 기본 AWS CLI 또는 SDK 자격 증명 체인의 IAM 보안 주체가 사용됩니다. 기본 AWS CLI 또는 SDK ID는 aws sts get-caller-identity 명령으로 확인할 수 있습니다.

모든 사용 가능한 옵션은 aws eks update-kubeconfig help 명령을 실행하거나 AWS CLI Command Reference의 update-kubeconfig를 참고하세요.

구성을 테스트합니다.

kubectl get svc

예제 출력은 다음과 같습니다.

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

인증 또는 리소스 유형 오류가 발생하면 문제 해결 주제의 "Unauthorized or access denied (kubectl)"을 참고하세요.

더 알아보기 (Learn more)

공식 문서