kubectl의 클러스터 액세스 구성

이 페이지에서는 Google Kubernetes Engine에서 kubectl 명령줄 도구에 클러스터 액세스를 구성하는 방법을 설명합니다.

개요

Google Cloud 프로젝트에서 여러 개의 클러스터를 실행하는 경우 kubectl에 연결할 클러스터를 선택해야 합니다. Kubernetes의 kubeconfig 파일에서 현재 컨텍스트를 설정하여 kubectl의 기본 클러스터를 설정할 수 있습니다. 또한 --cluster 플래그를 사용하여 특정 클러스터에 대해 kubectl 명령어를 실행할 수 있습니다.

다음 섹션에서는 kubeconfig 작동 방법, kubectl의 기본 클러스터 설정 방법, 특정 클러스터에 대해 개별 kubectl 명령어를 실행하는 방법을 설명합니다.

시작하기 전에

시작하기 전에 다음 태스크를 수행했는지 확인합니다.

다음 방법 중 하나를 사용하여 기본 gcloud 설정을 진행합니다.

  • gcloud init를 사용하여 기본값 설정 과정을 진행합니다.
  • gcloud config를 사용하여 프로젝트 ID, 영역, 리전을 개별적으로 설정합니다.

gcloud init 사용

One of [--zone, --region] must be supplied: Please specify location 오류가 표시되면 이 섹션을 완료합니다.

  1. gcloud init를 실행하고 다음 안내를 따르세요.

    gcloud init

    원격 서버에서 SSH를 사용하는 경우 --console-only 플래그를 사용하여 다음 명령어로 브라우저를 실행하지 못하게 할 수 있습니다.

    gcloud init --console-only
  2. 안내를 따라 gcloud에서 Google Cloud 계정을 사용하도록 승인합니다.
  3. 새 구성을 만들거나 기존 구성을 선택합니다.
  4. Google Cloud 프로젝트를 선택합니다.
  5. 기본 Compute Engine 영역을 선택합니다.

gcloud config 사용

  • 기본 프로젝트 ID를 설정합니다.
    gcloud config set project project-id
  • 영역 클러스터를 사용하는 경우 기본 컴퓨팅 영역을 설정합니다. 
    gcloud config set compute/zone compute-zone
  • 리전 클러스터를 사용하는 경우 기본 컴퓨팅 리전을 설정합니다.
    gcloud config set compute/region compute-region
  • gcloud를 최신 버전으로 업데이트합니다. 
    gcloud components update

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 항목은 다음 중 하나를 포함합니다.

비공개 클러스터의 내부 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 인스턴스의 범위를 변경하는 방법에 대한 자세한 내용은 인스턴스의 서비스 계정 만들기 및 사용 설정을 참조하세요.

다음 단계