이 페이지에서는 Google Kubernetes Engine에서 kubectl
명령줄 도구에 클러스터 액세스를 구성하는 방법을 설명합니다.
개요
Google Cloud 프로젝트에서 여러 개의 클러스터를 실행하는 경우 kubectl
에 연결할 클러스터를 선택해야 합니다. Kubernetes의 kubeconfig
파일에서 현재 컨텍스트를 설정하여 kubectl
의 기본 클러스터를 설정할 수 있습니다. 또한 --cluster
플래그를 사용하여 특정 클러스터에 대해 kubectl
명령어를 실행할 수 있습니다.
다음 섹션에서는 kubeconfig
작동 방법, kubectl
의 기본 클러스터 설정 방법, 특정 클러스터에 대해 개별 kubectl
명령어를 실행하는 방법을 설명합니다.
시작하기 전에
시작하기 전에 다음 태스크를 수행했는지 확인합니다.
- Google Kubernetes Engine API가 사용 설정되었는지 확인합니다. Google Kubernetes Engine API 사용 설정
- Cloud SDK가 설치되었는지 확인합니다.
다음 방법 중 하나를 사용하여 기본 gcloud
설정을 진행합니다.
gcloud init
를 사용하여 기본값 설정 과정을 진행합니다.gcloud config
를 사용하여 프로젝트 ID, 영역, 리전을 개별적으로 설정합니다.
gcloud init 사용
One of [--zone, --region] must be supplied: Please specify
location
오류가 표시되면 이 섹션을 완료합니다.
-
gcloud init
를 실행하고 다음 안내를 따르세요.gcloud init
원격 서버에서 SSH를 사용하는 경우
--console-only
플래그를 사용하여 다음 명령어로 브라우저를 실행하지 못하게 할 수 있습니다.gcloud init --console-only
- 안내를 따라
gcloud
에서 Google Cloud 계정을 사용하도록 승인합니다. - 새 구성을 만들거나 기존 구성을 선택합니다.
- Google Cloud 프로젝트를 선택합니다.
- 기본 Compute Engine 영역을 선택합니다.
gcloud config 사용
Kubernetes 구성 파일
Kubernetes는 kubeconfig
라는 YAML 파일을 사용하여 kubectl
의 클러스터 인증 정보를 저장합니다. kubeconfig
에는 명령어를 실행할 때 kubectl
이 참조하는 컨텍스트 목록이 포함됩니다. 기본적으로 파일은 $HOME/.kube/config
에 저장됩니다.
컨텍스트는 액세스 매개변수의 그룹입니다. 각 컨텍스트에는 Kubernetes 클러스터, 사용자, 네임스페이스가 포함되어 있습니다. 현재 컨텍스트는 현재 kubectl
의 기본값인 클러스터입니다. 모든 kubectl
명령어가 이 클러스터를 대상으로 실행됩니다.
gcloud container clusters create
를 사용하여 클러스터를 만들면 환경의 kubeconfig
에 항목이 자동으로 추가되고 현재 컨텍스트가 해당 클러스터로 변경됩니다.
gcloud container clusters create my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster
Google Cloud Console을 사용하거나 다른 컴퓨터에서 gcloud
를 사용하여 클러스터를 만들 때는 환경의 kubeconfig
가 업데이트되지 않습니다.
또한 프로젝트팀 구성원이 자신의 컴퓨터에서 클러스터를 만들기 위해 gcloud
를 사용할 경우에는 이 구성원의 kubeconfig
가 업데이트되지만, 내 구성은 업데이트되지 않습니다. 로컬 kubeconfig
에 클러스터를 추가하려면 아래의 안내를 따르세요.
클러스터 엔드포인트 정보
모든 클러스터에는 표준 엔드포인트가 있습니다. 이 엔드포인트는 kubectl
및 다른 서비스가 클러스터 제어 영역(마스터)과 통신하는 데 사용하는 Kubernetes API 서버를 노출합니다. 엔드포인트 IP는 Cloud Console에서 클러스터 세부정보 탭의 엔드포인트 필드 및 endpoint
필드의 gcloud container clusters describe
출력에 표시됩니다.
gcloud container clusters get-credentials
를 실행할 때는 이 명령어가 클러스터 엔드포인트를 kubeconfig
업데이트 중에 가져오는 것을 확인할 수 있습니다.
비공개 클러스터에는 내부 IP 주소인 privateEndpoint
와 외부 IP 주소인 publicEndpoint
라는 서로 다른 엔드포인트 IP 주소 2개가 포함됩니다.
엔드포인트의 공개 액세스가 사용 중지된 경우를 제외하고 endpoint
필드는 외부 IP를 참조하며, 이 경우 비공개 IP가 사용됩니다.
get-credentials
를 실행하면 기본적으로 endpoint
필드에 지정된 IP가 사용됩니다.
비공개 클러스터의 경우, 내부 IP를 엔드포인트로 사용하려면 비공개 클러스터의 내부 IP 주소를 사용하여 kubeconfig
항목 생성을 참조하세요.
kubectl
인증 정보
모든 GKE 클러스터는 kubectl
이 제공한 사용자 인증 정보를 검증하고 사용자 또는 서비스 계정 ID에 연결된 이메일 주소를 검색하여 Google Cloud 사용자 및 서비스 계정 ID를 수락하도록 구성됩니다. 따라서 이러한 계정의 사용자 인증 정보에 userinfo.email
OAuth 범위가 포함되어야 인증이 성공합니다.
gcloud
를 사용하여 신규 또는 기존 클러스터에서 환경의 kubeconfig
를 설정하는 경우 gcloud
는 gcloud
자체에서 사용하는 사용자 인증 정보를 kubectl
에 제공합니다. 예를 들어 gcloud auth login
을 사용하는 경우 개인의 사용자 인증 정보가 kubectl
에 제공되며 userinfo.email
범위가 포함됩니다. 따라서 GKE 클러스터가 kubectl
클라이언트를 인증할 수 있습니다.
Compute Engine 인스턴스에서 실행되는 동안 kubectl
이 Google Cloud 서비스 계정의 사용자 인증 정보를 사용하도록 구성할 수도 있습니다. 그러나 Compute Engine 인스턴스가 만든 사용자 인증 정보에는 기본적으로 userinfo.email
범위가 포함되지 않습니다. 따라서 이 범위를 반드시 명시적으로 추가해야 합니다. 예를 들어 Compute Engine 인스턴스를 만들 때 --scopes
플래그를 사용할 수 있습니다.
인증된 사용자 또는 Google Cloud 서비스 계정은 승인 과정도 거쳐야 GKE 클러스터에서 작업을 수행할 수 있습니다. 승인을 구성하는 방법에 대한 자세한 내용은 역할 기반 액세스 제어를 참조하세요.
Kubernetes API 서버에 연결할 때 지원되는 인증 방법에 대한 자세한 내용은 Kubernetes API 서버에 인증을 참조하세요.
kubectl
의 현재 컨텍스트 보기
kubectl
의 현재 컨텍스트를 보려면 다음 명령어를 실행하세요.
kubectl config current-context
kubeconfig
보기
환경의 kubeconfig
를 보려면 다음 명령어를 실행하세요.
kubectl config view
이 명령어는 kubeconfig
항목이 생성된 모든 클러스터 목록을 반환합니다. GKE 클러스터가 나열된 경우 현재 환경에서 이 클러스터에 kubectl
명령어를 실행할 수 있습니다. 그렇지 않은 경우 클러스터에 kubeconfig
항목을 생성해야 합니다.
kubeconfig
항목 생성
Cloud Console이나 다른 컴퓨터에서 또는 프로젝트의 다른 구성원에 의해 생성된 클러스터에 kubectl
명령어를 실행하려면 환경에서 kubeconfig
항목을 생성해야 합니다.
다음 명령어를 실행하여 kubeconfig
항목을 생성합니다.
gcloud container clusters get-credentials cluster-name
여기서 cluster-name은 클러스터 이름입니다.
이 명령어를 사용하려면 container.clusters.get
권한이 있어야 합니다. 이 권한을 제공하는 최소 권한의 IAM 역할은 container.clusterViewer
입니다.
kubeconfig
항목은 다음 중 하나를 포함합니다.
gcloud auth list
에 표시되는 사용자 인증 정보- 애플리케이션 기본 사용자 인증 정보(구성된 경우)
비공개 클러스터의 내부 IP 주소를 사용하여 kubeconfig
항목 생성
get-credentials
를 실행할 때 비공개 클러스터의 내부 IP 주소를 kubeconfig
에 기록하도록 --internal-ip
를 지정할 수 있습니다.
gcloud container clusters get-credentials --internal-ip cluster-name
kubectl
명령어의 기본 클러스터 설정
이전에 클러스터에 kubeconfig
항목을 생성한 경우 다음을 실행하여 kubectl
의 현재 컨텍스트를 이 클러스터로 전환할 수 있습니다.
gcloud container clusters get-credentials
예를 들어 프로젝트에 클러스터 두 개(my-cluster
및 my-new-cluster
)가 있다고 가정해 보겠습니다. 현재 컨텍스트는 my-new-cluster
이지만 my-cluster
에 모든 kubectl
명령어를 실행하려 합니다. 현재 컨텍스트를 my-new-cluster
에서 my-cluster
로 전환하려면 다음 명령어를 실행합니다.
gcloud container clusters get-credentials my-cluster
특정 클러스터에 개별 kubectl
명령어 실행
특정 클러스터를 대상으로 개별 kubectl
명령어를 실행하려면 kubeconfig
에 표시되는 클러스터 이름을 --cluster
플래그의 인수로 전달합니다.
예를 들어 환경에 클러스터 두 개(my-cluster
및 my-new-cluster
)가 있고 현재 컨텍스트는 my-cluster
라고 가정해 보겠습니다. 애플리케이션을 my-new-cluster
에 배포하지만 현재 컨텍스트를 변경하지 않으려고 합니다. 현재 컨텍스트를 변경하지 않고 애플리케이션을 my-new-cluster
에 배포하려면 다음 명령어를 실행합니다.
kubectl run my-app --image gcr.io/my-bucket/my-app:1.0 --cluster my-new-cluster
문제 해결
부족한 인증 범위
gcloud container clusters get-credentials
를 실행하면 다음 오류가 발생합니다.
ERROR: (gcloud.container.clusters.get-credentials) ResponseError: code=403, message=Request had insufficient authentication scopes.
이 오류는 cloud-platform
범위가 없는 Compute Engine VM에서 Kubernetes Engine API에 액세스하려고 했으므로 발생합니다. Compute Engine VM 인스턴스의 범위를 변경하는 방법에 대한 자세한 내용은 인스턴스의 서비스 계정 만들기 및 사용 설정을 참조하세요.
다음 단계
- GKE 클러스터의 리소스에 대한 액세스를 승인하는 방법 알아보기
- Google Cloud 서비스 계정으로 Kubernetes 워크로드에서 Google Cloud 서비스를 인증하는 방법 알아보기
kubectl
요약본 읽기