이 페이지에서는 Google Kubernetes Engine(GKE) 클러스터와 상호작용하도록 kubectl
명령줄 도구를 설치하고 구성하는 방법을 설명합니다.
개요
kubectl
은 GKE 클러스터와 상호작용하는 데 사용할 수 있는 명령줄 도구입니다. GKE에서 kubectl
를 사용하려면 도구를 설치하고 클러스터와 통신하도록 구성해야 합니다. Google Cloud에서 클러스터 여러 개를 실행하는 경우 추가로 kubectl
을 구성해야 합니다.
이 페이지에서는 다음을 보여줍니다.
kubectl
작동 방식kubectl
및 필수 종속 항목 설치 방법kubectl
의 기본 클러스터 설정 방법- 특정 클러스터에
kubectl
명령어를 실행하는 방법
시작하기 전에
시작하기 전에 다음 태스크를 수행했는지 확인합니다.
- Google Kubernetes Engine API를 사용 설정합니다. Google Kubernetes Engine API 사용 설정
- 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 initialize합니다. 이전에 gcloud CLI를 설치한 경우
gcloud components update
를 실행하여 최신 버전을 가져옵니다.
kubectl
를 설치합니다.
Google Cloud CLI나 apt
또는 yum
와 같은 외부 패키지 관리자를 사용하여 kubectl
을 설치할 수 있습니다.
gcloud
kubectl
구성요소를 설치합니다.gcloud components install kubectl
kubectl
최신 버전이 설치되어 있는지 확인합니다.kubectl version --client
apt
cloud-sdk
저장소가 있는지 확인합니다.grep -rhE ^deb /etc/apt/sources.list* | grep "cloud-sdk"
출력은 다음과 비슷합니다.
deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main
cloud-sdk
저장소가 나열되지 않으면 gcloud CLI를 설치합니다.kubectl
구성요소를 설치합니다.apt-get update apt-get install -y kubectl
kubectl
최신 버전이 설치되어 있는지 확인합니다.kubectl version --client
yum
cloud-sdk
저장소가 있는지 확인합니다.yum repolist | grep "google-cloud-sdk"
출력은 다음과 비슷합니다.
google-cloud-sdk Google Cloud SDK 2,205
kubectl
구성요소를 설치합니다.yum install -y kubectl
kubectl
최신 버전이 설치되어 있는지 확인합니다.kubectl version --client
필수 플러그인 설치
kubectl
및 기타 Kubernetes 클라이언트에는 인증 플러그인인 gke-gcloud-auth-plugin
이 필요합니다. 이 플러그인은 Client-go Credentials Plugins 프레임워크를 사용하여 GKE 클러스터와 통신하도록 인증 토큰을 제공합니다.
Kubernetes 버전 1.26이 출시되기 전에 gcloud CLI에 gke-gcloud-auth-plugin
바이너리를 설치해야 합니다. 설치하지 않으면 kubectl
또는 다른 커스텀 Kubernetes 클라이언트의 기존 설치 작동이 중지됩니다.
kubectl
및 다른 클라이언트를 사용하여 GKE와 상호작용하려면 이 플러그인을 설치해야 합니다.
플러그인이 설치되지 않으면 기존 클라이언트에 오류 메시지가 표시됩니다.
시작하기 전에 플러그인이 이미 설치되어 있는지 확인합니다.
gke-gcloud-auth-plugin --version
출력에 버전 정보가 표시되면 이 섹션을 건너뜁니다.
gcloud CLI나 apt
또는 yum
과 같은 외부 패키지 관리자를 사용하여 인증 플러그인을 설치할 수 있습니다.
gcloud
gke-gcloud-auth-plugin
바이너리를 설치합니다.
gcloud components install gke-gcloud-auth-plugin
apt
gke-gcloud-auth-plugin
바이너리를 설치합니다.
apt-get install google-cloud-sdk-gke-gcloud-auth-plugin
yum
gke-gcloud-auth-plugin
바이너리를 설치합니다.
yum install google-cloud-sdk-gke-gcloud-auth-plugin
gke-gcloud-auth-plugin
바이너리 설치를 확인합니다.
gke-gcloud-auth-plugin
바이너리 버전을 확인합니다.gke-gcloud-auth-plugin --version
플러그인을 사용하도록
kubectl
구성을 업데이트합니다.gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
다음을 바꿉니다.
CLUSTER_NAME
: 클러스터의 이름입니다.COMPUTE_REGION
: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우--zone=COMPUTE_ZONE
을 사용합니다.
구성 확인
kubectl get namespaces
출력은 다음과 비슷합니다.
NAME STATUS AGE default Active 51d kube-node-lease Active 51d kube-public Active 51d kube-system Active 51d
이 플러그인이 필요한 이유에 대한 자세한 내용은 Kubernetes KEP를 참조하세요.
kubectl
과 상호작용
Kubernetes는 kubeconfig
라는 YAML 파일을 사용하여 kubectl
의 클러스터 인증 정보를 저장합니다. 기본적으로 파일은 $HOME/.kube/config
에 저장됩니다.
kubeconfig
에는 컨텍스트라는 액세스 매개변수 그룹이 포함되어 있습니다. 각 컨텍스트에는 Kubernetes 클러스터, 사용자, 선택적 기본 네임스페이스가 포함되어 있습니다. kubectl
은 명령어를 실행할 때 컨텍스트를 참조합니다.
다음은 kubectl
을 구성하기 위해 완료할 수 있는 태스크입니다.
kubectl
에서 연결할 클러스터를 선택합니다.kubeconfig
파일에서 현재 컨텍스트를 설정하여kubectl
의 기본 클러스터를 설정합니다.--cluster
플래그를 사용하여 특정 클러스터에 대해kubectl
명령어를 실행합니다.
kubeconfig
보기
환경의 kubeconfig
를 보려면 다음 명령어를 실행하세요.
kubectl config view
이 명령어는 kubeconfig
항목이 생성된 모든 클러스터 목록을 반환합니다. GKE 클러스터가 나열된 경우 현재 환경에서 이 클러스터에 kubectl
명령어를 실행할 수 있습니다. 그렇지 않으면 kubectl의 클러스터 정보를 저장해야 합니다.
kubectl
의 현재 컨텍스트 보기
현재 컨텍스트는 현재 kubectl
의 기본 클러스터입니다. 모든 kubectl
명령어가 이 클러스터에 실행됩니다.
gcloud container clusters create-auto
를 사용하여 클러스터를 만들면 항목이 자동으로 환경의 kubeconfig
파일에 추가되고 현재 컨텍스트가 해당 클러스터로 변경됩니다. 예를 들면 다음과 같습니다.
gcloud container clusters create-auto my-cluster
Creating my-cluster...done
Fetching cluster endpoint and auth data.
kubeconfig entry generated for my-cluster
kubectl
의 현재 컨텍스트를 보려면 다음 명령어를 실행하세요.
kubectl config current-context
kubectl
의 클러스터 정보 저장
Google Cloud 콘솔을 사용하거나 다른 컴퓨터에서 gcloud CLI를 사용하여 클러스터를 만드는 경우 환경의 kubeconfig
파일이 업데이트되지 않습니다.
또한 프로젝트팀 구성원이 자신의 컴퓨터에서 클러스터를 만들기 위해 gcloud CLI를 사용할 경우에는 이 구성원의 kubeconfig
가 업데이트되지만, 내 구성은 업데이트되지 않습니다. kubeconfig
항목은 다음 중 하나를 포함합니다.
gcloud auth list
에 표시되는 사용자 인증 정보- 애플리케이션 기본 사용자 인증 정보(구성된 경우)
환경에서 kubeconfig
컨텍스트를 생성하려면 container.clusters.get
권한이 있는지 확인합니다. 이 권한을 제공하는 최소 권한의 IAM 역할은 container.clusterViewer
입니다.
특정 클러스터의 kubeconfig
컨텍스트를 생성하려면 다음 명령어를 실행합니다.
gcloud container clusters get-credentials CLUSTER_NAME \
--region=CLUSTER_REGION
다음을 바꿉니다.
CLUSTER_NAME
: 클러스터의 이름입니다.COMPUTE_REGION
: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우--zone=COMPUTE_ZONE
을 사용합니다.
비공개 클러스터의 내부 IP 주소를 사용하여 kubeconfig
항목 생성
모든 클러스터에는 표준 엔드포인트가 있습니다. 이 엔드포인트는 kubectl
및 다른 서비스가 클러스터 제어 영역과 통신하는 데 사용하는 Kubernetes API 서버를 노출합니다.
비공개 클러스터에는 내부 IP 주소인 privateEndpoint
와 외부 IP 주소인 publicEndpoint
등 엔드포인트 IP 주소 두 개가 포함되어 있습니다.
엔드포인트에 대한 공개 액세스가 중지된 경우를 제외하고 endpoint
필드는 외부 IP 주소를 참조하며, 이 경우 비공개 IP 주소가 사용됩니다.
비공개 클러스터에서 내부 IP 주소를 엔드포인트로 사용하려면 다음 명령어를 실행합니다.
gcloud container clusters get-credentials CLUSTER_NAME --internal-ip
CLUSTER_NAME
을 클러스터 이름으로 바꿉니다.
get-credentials
를 실행하면 기본적으로 endpoint
필드에 지정된 IP 주소가 사용됩니다.
kubectl
명령어의 기본 클러스터 설정
이전에 클러스터에서 kubeconfig 항목을 생성했으면 다음 명령어를 실행하여 kubectl
의 현재 컨텍스트를 해당 클러스터로 전환할 수 있습니다.
gcloud container clusters get-credentials CLUSTER_NAME \
--region=COMPUTE_REGION
다음을 바꿉니다.
CLUSTER_NAME
: 클러스터의 이름입니다.COMPUTE_REGION
: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우--zone=COMPUTE_ZONE
을 사용합니다.
예를 들어 프로젝트에 my-cluster
및 my-new-cluster
라는 2개의 클러스터가 있다고 가정해 보겠습니다. 현재 컨텍스트는 my-new-cluster
이지만 my-cluster
에 모든 kubectl
명령어를 실행하려고 합니다. 현재 컨텍스트를 my-new-cluster
에서 my-cluster
로 전환하려면 다음 명령어를 실행합니다.
gcloud container clusters get-credentials CLUSTER_NAME \
--region=COMPUTE_REGION
특정 클러스터에 개별 kubectl
명령어 실행
--cluster=CLUSTER_NAME
을 사용하여 특정 클러스터에 개별 kubectl
명령어를 실행할 수 있습니다.
예를 들어 환경에 my-cluster
및 my-new-cluster
라는 2개의 클러스터가 있고 현재 컨텍스트가 my-cluster
라고 가정해 보겠습니다. 애플리케이션을 my-new-cluster
에 배포하지만 현재 컨텍스트를 변경하지 않으려고 합니다. 현재 컨텍스트를 변경하지 않고 애플리케이션을 my-new-cluster
에 배포하려면 다음 명령어를 실행합니다.
kubectl run my-app --image us-docker.pkg.dev/my-project/my-repo/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-gcloud-auth-plugin을 찾을 수 없음
kubectl
또는 GKE와 상호작용하는 커스텀 클라이언트를 실행하려고 하는 동안 다음 오류가 발생하면 설치 안내의 설명대로 gke-gcloud-auth-plugin
을 설치합니다.
오류 메시지는 다음과 비슷합니다.
- 오류 샘플
Unable to connect to the server: getting credentials: exec: executable gke-gcloud-auth-plugin not found
It looks like you are trying to use a client-go credential plugin that is not installed.
To learn more about this feature, consult the documentation available at:
https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins
Visit cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin to install gke-gcloud-auth-plugin.
- 오류 샘플
Unable to connect to the server: getting credentials: exec: fork/exec /usr/lib/google-cloud-sdk/bin/gke-gcloud-auth-plugin: no such file or directory
오류: 패닉: 이름 GCP의 인증 제공업체를 찾을 수 없음
작동 방식의 설명대로 kubectl
또는 커스텀 Kubernetes 클라이언트가 Kubernetes client-go
버전 1.26 이상으로 빌드되면 no Auth Provider found for name "gcp"
오류가 발생합니다. 다음 단계를 수행하면 이 문제를 해결할 수 있습니다.
설치 안내의 설명대로
gke-gcloud-auth-plugin
를 설치합니다.gcloud components update
를 사용하여 최신 버전의 gcloud CLI로 업데이트합니다.kubeconfig
파일을 업데이트합니다.gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
다음을 바꿉니다.
CLUSTER_NAME
: 클러스터의 이름입니다.COMPUTE_REGION
: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우--zone=COMPUTE_ZONE
을 사용합니다.
경고: GCP 인증 플러그인은 지원 중단되었습니다. 대신 gcloud를 사용하세요.
gke-gcloud-auth-plugin
을 설치하고 GKE 클러스터에서 kubectl
명령어를 실행하면 이 경고 메시지가 표시될 수 있습니다. 이 메시지는 클라이언트 버전이 1.26 이전이면 나타납니다.
대신 gke-gcloud-auth-plugin
인증 플러그인을 사용하도록 클라이언트에 지시하려면 다음을 수행합니다.
텍스트 편집기에서 셸 로그인 스크립트를 엽니다.
Bash
vi ~/.bashrc
Zsh
vi ~/.zshrc
PowerShell을 사용하는 경우 이 단계를 건너뜁니다.
다음 환경 변수를 설정합니다.
Bash
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
Zsh
export USE_GKE_GCLOUD_AUTH_PLUGIN=True
PowerShell
[Environment]::SetEnvironmentVariable('USE_GKE_GCLOUD_AUTH_PLUGIN', True, 'Machine')
사용자 환경에서 변수를 적용합니다.
Bash
source ~/.bashrc
Zsh
source ~/.zshrc
PowerShell
터미널을 종료하고 새 터미널 세션을 엽니다.
gcloud CLI 업데이트
gcloud components update
클러스터를 인증합니다.
gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
다음을 바꿉니다.
CLUSTER_NAME
: 클러스터의 이름입니다.COMPUTE_REGION
: 클러스터의 Compute Engine 리전입니다. 영역 클러스터의 경우--zone=COMPUTE_ZONE
을 사용합니다.
다음 단계
직접 사용해 보기
Google Cloud를 처음 사용하는 경우 계정을 만들어 실제 시나리오에서 GKE의 성능을 평가할 수 있습니다. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
GKE 무료로 사용해 보기