kubectl 설치 및 클러스터 액세스 구성

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 페이지에서는 Google Kubernetes Engine(GKE) 클러스터를 관리하고 액세스하는 데 사용되는 kubectl 명령줄 도구를 설치하는 방법을 안내합니다. Google Cloud에서 여러 클러스터를 실행할 경우에는 kubectl 구성이 필요합니다.

다음 방법을 알아봅니다.

• kubectl 작동 방식
• kubectl 및 필수 종속 항목 설치 방법
• kubectl의 기본 클러스터 설정 방법
• 특정 클러스터에 kubectl 명령어를 실행하는 방법

이 페이지는 클라우드 리소스 프로비저닝 및 구성을 포함하여 클라우드 인프라를 설정, 모니터링, 관리하는 IT 관리자, 운영자, 개발자를 대상으로 합니다. Google Cloud 문서에 참조된 일반적인 역할 및 예시 태스크에 대해 자세히 알아보려면 일반 GKE Enterprise 사용자 역할 및 태스크를 참조하세요.

이 페이지를 읽기 전에 Kubernetes kubectl을 미리 숙지해야 합니다.

시작하기 전에

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

• Google Kubernetes Engine API를 사용 설정합니다.
Google Kubernetes Engine API 사용 설정
• 이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화하세요. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.

kubectl 설치

Google Cloud CLI나 apt 또는 yum와 같은 외부 패키지 관리자를 사용하여 kubectl을 설치할 수 있습니다.

필수 플러그인 설치

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 components install gke-gcloud-auth-plugin

  apt-get install google-cloud-sdk-gke-gcloud-auth-plugin

  yum install google-cloud-sdk-gke-gcloud-auth-plugin

gke-gcloud-auth-plugin 바이너리 설치를 확인합니다.

1. gke-gcloud-auth-plugin 바이너리 버전을 확인합니다.

   gke-gcloud-auth-plugin --version
   

2. 플러그인을 사용하도록 kubectl 구성을 업데이트합니다.

   gcloud container clusters get-credentials CLUSTER_NAME \
       --location=CONTROL_PLANE_LOCATION
   

   다음을 바꿉니다.

   • CLUSTER_NAME: 클러스터 이름입니다.
   • CONTROL_PLANE_LOCATION: 클러스터의 컨트롤 플레인에 대한 Compute Engine 위치입니다. 리전 클러스터의 경우 리전 또는 영역 클러스터의 경우 영역을 제공합니다.

3. 다음 명령어를 실행하여 구성을 확인합니다.

   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 \
    --location=CONTROL_PLANE_LOCATION

다음을 바꿉니다.

• CLUSTER_NAME: 클러스터 이름입니다.
• CONTROL_PLANE_LOCATION: 클러스터의 컨트롤 플레인에 대한 Compute Engine 위치입니다. 리전 클러스터의 경우 리전 또는 영역 클러스터의 경우 영역을 제공합니다.

클러스터의 내부 IP 주소를 사용하여 kubeconfig 항목 생성

모든 클러스터에는 각기 서로 다른 특성의 여러 엔드포인트 주소가 포함됩니다. 이러한 엔드포인트 중 하나는 클러스터 컨트롤 플레인과 통신하기 위해 kubectl 및 다른 서비스에서 사용되는 표준 엔드포인트로 작동합니다. GKE는 다음 순서를 기준으로 엔드포인트를 자동으로 선택합니다.

• 외부 IP 주소(외부 엔드포인트를 사용 설정한 경우)
• 내부 IP 주소
• DNS 주소(IP 액세스가 사용 중지된 경우). 기본적으로 표준 엔드포인트를 사용하려면 get-credentials 명령어를 실행합니다. kubectl에 사용되는 엔드포인트를 추가로 제어하려면 --internal-ip 또는 --dns-endpoint 플래그를 사용합니다. 내부 IP 주소를 사용하도록 kubeconfig 파일을 업데이트하려면 다음 명령어를 실행합니다.

gcloud container clusters get-credentials CLUSTER_NAME --internal-ip

DNS 주소를 사용하도록 kubeconfig 파일을 업데이트하려면 다음 명령어를 실행합니다.

gcloud container clusters get-credentials CLUSTER_NAME --dns-endpoint

CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

기본적으로 get-credentials를 실행하면 endpoint 필드에 지정된 IP 주소가 사용됩니다.

kubectl 명령어의 기본 클러스터 설정

이전에 클러스터에서 kubeconfig 항목을 생성했으면 다음 명령어를 실행하여 kubectl의 현재 컨텍스트를 해당 클러스터로 전환할 수 있습니다.

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION

다음을 바꿉니다.

• CLUSTER_NAME: 클러스터 이름입니다.
• CONTROL_PLANE_LOCATION: 클러스터의 컨트롤 플레인에 대한 Compute Engine 위치입니다. 리전 클러스터의 경우 리전 또는 영역 클러스터의 경우 영역을 제공합니다.

예를 들어 프로젝트에 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

다음 단계

• GKE 클러스터의 리소스에 대한 액세스를 승인하는 방법 알아보기
• GKE 워크로드에서 Google Cloud 서비스에 인증
• kubectl 요약본 읽기
• kubectl 명령줄 도구 문제 해결