Kubernetes API 서버에 인증

이 페이지에서는 Google Kubernetes Engine(GKE)에서 Kubernetes API 서버에 연결할 때 지원되는 인증 방법을 설명합니다.

Kubernetes 워크로드를 Google Cloud API에 인증하는 방법에 대한 자세한 내용은 워크로드 아이덴티티를 참조하세요.

개요

Kubernetes API 서버에 인증하는 방법은 몇 가지가 있습니다. GKE에서는 OAuth 인증이 클러스터 인증에 권장되며 자동으로 구성됩니다.

시작하기 전에

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

• 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 오류가 표시되면 이 섹션을 완료합니다.

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

   gcloud init

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

   gcloud init --console-only

2. 안내를 따라 gcloud에서 Google Cloud 계정을 사용하도록 승인합니다.
3. 새 구성을 만들거나 기존 구성을 선택합니다.
4. Google Cloud 프로젝트를 선택합니다.
5. 영역 클러스터의 기본 Compute Engine 영역이나 리전 또는 Autopilot 클러스터의 리전을 선택합니다.

참고: gcloud 명령어에서 --project, --zone, --region 플래그를 사용하여 이러한 기본 설정을 재정의할 수 있습니다.

gcloud config 사용

• 기본 프로젝트 ID를 설정합니다.

  gcloud config set project PROJECT_ID

• 영역 클러스터를 사용하는 경우 기본 컴퓨팅 영역을 설정합니다.

  gcloud config set compute/zone COMPUTE_ZONE

• Autopilot 또는 리전 클러스터를 사용하는 경우 기본 컴퓨팅 리전을 설정합니다.

  gcloud config set compute/region COMPUTE_REGION

• gcloud를 최신 버전으로 업데이트합니다.

  gcloud components update

참고: gcloud 명령어에서 --project, --zone, --region 플래그를 사용하여 이러한 기본 설정을 재정의할 수 있습니다.

사용자 인증

GKE는 gcloud 명령줄 도구를 통해 최종 사용자 인증을 관리합니다. gcloud 도구는 사용자를 Google Cloud에 인증하고, Kubernetes 구성을 설정하고, 클러스터의 OAuth 액세스 토큰을 가져오고, 액세스 토큰을 최신 상태로 유지합니다. Identity and Access Management(IAM) 또는 Kubernetes 역할 기반 액세스 제어(RBAC)를 사용하여 클러스터에 대한 액세스를 제어할 수 있습니다.

OAuth가 GKE와 통합되기 전 사전 프로비저닝된 X.509 인증서 또는 정적 비밀번호가 사용 가능한 유일한 인증 방법이었습니다. 이러한 방법은 더 이상 권장되지 않으며 GKE 버전 1.12 이상을 실행하는 새 클러스터에서 기본적으로 사용 중지됩니다. 기존 인증 방법을 사용할 경우 이러한 방법을 마이그레이션하는 것이 좋습니다.

OAuth를 사용하여 인증

OAuth 방법을 사용하여 클러스터에 인증하려면 다음을 수행합니다.

1. 사용자 인증 정보를 사용하여 gcloud 도구에 로그인합니다. 그러면 Google Cloud에 대한 인증 프로세스를 완료하기 위한 웹브라우저가 열립니다.

   gcloud auth login
   

   주의: Compute Engine VM에서는 이를 수행하지 마세요. 인증을 위해 서비스 계정을 사용합니다. 자세한 내용은 Google Cloud 내 서비스 섹션을 참조하세요.

2. 특정 클러스터의 Kubernetes 사용자 인증 정보를 검색합니다.

   gcloud container clusters get-credentials CLUSTER_NAME \
       --zone=COMPUTE_ZONE
   

3. 인증되었는지 확인합니다.

   kubectl cluster-info
   

서비스 인증

사용자 상호작용(예: CI/CD 파이프라인 스크립트) 없이 서비스에서 GKE 클러스터의 API 서버에 인증해야 하는 경우가 있습니다. 이를 수행하는 방법은 서비스가 실행되는 환경에 따라 다릅니다.

동일한 GKE 클러스터 내의 서비스

서비스가 연결할 GKE 클러스터 내부의 Pod에서 실행되는 경우 Kubernetes 서비스 계정을 사용하여 인증합니다.

1. Kubernetes 서비스 계정을 만들어 Pod에 연결합니다. Pod에 이미 Kubernetes 서비스 계정이 있는 경우 이 단계를 건너뛸 수 있습니다.

   이 예시에서는 cicd-ns 네임스페이스에 cicd라는 Kubernetes 서비스 계정을 사용합니다.

2. Kubernetes RBAC를 사용하여 Kubernetes 서비스 계정에 올바른 권한을 부여합니다.

   다음 예시에서는 prod 네임스페이스에서 edit 권한을 부여합니다.

   kubectl create rolebinding cicd \
       --clusterrole=edit \
       --serviceaccount=cicd-ns:cicd \
       --namespace=prod
   

3. 런타임 시 서비스가 kubectl을 호출하면 구성한 사용자 인증 정보가 자동으로 수신됩니다.

Google Cloud 내 서비스

서비스가 Google Cloud(예: Compute Engine VM 또는 다른 GKE 클러스터) 내에서 실행되는 경우 환경에서 사용할 수 있는 Google 서비스 계정 사용자 인증 정보를 사용하여 API 서버에 인증해야 합니다.

1. Compute Engine 환경에 Google 서비스 계정을 할당합니다. 서비스가 Compute Engine VM 내에서 실행되는 경우 인스턴스에 Google 서비스 계정을 할당합니다. 서비스가 GKE 클러스터 내에서 실행되는 경우 워크로드 아이덴티티를 사용하여 Pod가 Google 서비스 계정으로 실행되도록 구성합니다.

   이 예시에서는 ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com을 Google 서비스 계정으로 사용합니다.

2. Google 서비스 계정에 클러스터에 대한 액세스 권한을 부여합니다.

   이 예시에서는 클러스터 내의 Kubernetes API 객체에 대한 액세스 권한을 제공하는 roles/container.developer IAM 역할을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
       --role=roles/container.developer
   

3. 클러스터 사용자 인증 정보를 검색합니다.

   gcloud container clusters get-credentials CLUSTER_NAME \
       --zone=COMPUTE_ZONE
   

   서비스는 환경에 설정된 Google 서비스 계정을 사용하여 자동으로 인증됩니다.

다른 환경의 서비스

Google Cloud 외부 환경에서 서비스를 인증하면 관리되는 Google 서비스 계정 사용자 인증 정보에 서비스가 액세스할 수 없습니다. 클러스터 사용자 인증 정보를 검색하려면 Google 서비스 계정을 만들고, 해당 키를 다운로드하고, 서비스에서 런타임에 이 키를 사용하여 gcloud 도구로 클러스터 사용자 인증 정보를 검색해야 합니다.

1. 서비스의 Google 서비스 계정을 만듭니다. 이미 Google 서비스 계정이 있다면 이 단계를 건너뛰어도 됩니다.

   이 예시에서는 이름이 ci-cd-pipeline인 서비스 계정을 만듭니다.

   gcloud iam service-accounts create ci-cd-pipeline
   

2. Google 서비스 계정에 클러스터 액세스 권한을 부여합니다.

   이 예시에서는 ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com을 Google 서비스 계정으로 사용하고, 클러스터 내 Kubernetes API 객체에 대한 액세스 권한을 제공하는 roles/container.developer IAM 역할을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
       --role=roles/container.developer
   

   또한 Kubernetes RBAC를 사용하여 이 액세스 권한을 부여하면 보다 세밀하게 액세스를 제어할 수 있습니다.

3. Google 서비스 계정의 키를 만들고 다운로드합니다. 런타임에 이 키를 서비스에 제공합니다.

   gcloud iam service-accounts keys create gsa-key.json \
       --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
   

4. 런타임에 서비스를 실행하는 환경에서 Google 서비스 계정 키를 사용하여 gcloud 도구에 인증합니다.

   gcloud auth activate-service-account ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
       --key-file=gsa-key.json
   

5. gcloud 도구를 사용하여 클러스터 사용자 인증 정보를 검색합니다.

   gcloud config set project PROJECT_ID
   gcloud container clusters get-credentials CLUSTER_NAME \
       --zone=COMPUTE_ZONE
   

gcloud가 없는 환경

gcloud 도구를 사용하여 클러스터 사용자 인증 정보를 검색하는 것이 좋습니다. 이 방법은 제어 영역 IP 순환 또는 사용자 인증 정보 순환 같은 클러스터 이벤트에 대한 복원력이 우수하기 때문입니다. 그러나 환경에 gcloud 도구를 설치할 수 없다면 정적 kubeconfig 파일을 만들어 클러스터에 인증할 수 있습니다.

1. 서비스의 Google 서비스 계정을 만듭니다. 이미 Google 서비스 계정이 있다면 이 단계를 건너뛰어도 됩니다.

   이 예시에서는 이름이 ci-cd-pipeline인 서비스 계정을 만듭니다.

   gcloud iam service-accounts create ci-cd-pipeline
   

2. Google 서비스 계정에 클러스터 액세스 권한을 부여합니다.

   이 예시에서는 ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com을 Google 서비스 계정으로 사용하고, 클러스터 내 Kubernetes API 객체에 대한 액세스 권한을 제공하는 roles/container.developer IAM 역할을 부여합니다.

   gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
       --role=roles/container.developer
   

   또한 Kubernetes RBAC를 사용하여 이 액세스 권한을 부여하면 보다 세밀하게 액세스를 제어할 수 있습니다.

3. Google 서비스 계정의 키를 만들고 다운로드합니다.

   이 예시에서 키 파일의 이름은 gsa-key.json입니다.

   gcloud iam service-accounts keys create gsa-key.json \
       --iam-account=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com
   

4. 클러스터의 endpoint 및 clusterCaCertificate 값을 가져옵니다.

   gcloud container clusters describe CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
        --format="value(endpoint)"
   
   gcloud container clusters describe CLUSTER_NAME \
       --zone=COMPUTE_ZONE \
       --format="value(masterAuth.clusterCaCertificate)"
   

5. 다음이 포함된 kubeconfig.yaml 파일을 만듭니다.

   apiVersion: v1
   kind: Config
   clusters:
   - name: CLUSTER_NAME
     cluster:
       server: https://endpoint
       certificate-authority-data: masterAuth.clusterCaCertificate
   users:
   - name: ci-cd-pipeline-gsa
     user:
       auth-provider:
         name: gcp
   contexts:
   - context:
       cluster: CLUSTER_NAME
       user: ci-cd-pipeline-gsa
     name: CLUSTER_NAME-ci-cd
   current-context: CLUSTER_NAME-ci-cd
   

   다음을 바꿉니다.

   • CLUSTER_NAME: 클러스터 이름입니다.
   • endpoint: 이전 단계에서 가져온 endpoint 값입니다.
   • masterAuth.clusterCaCertificate: 이전 단계에서 가져온 clusterCaCertificate 값입니다(base64 인코딩 인증서를 디코딩할 필요가 없음).

6. 사용자 환경의 서비스와 함께 kubeconfig.yaml 및 gsa-key.json을 배포합니다. 런타임에 서비스를 실행하는 환경에서 다음 환경 변수를 설정합니다.

   export KUBECONFIG=path/to/kubeconfig.yaml
   export GOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json
   

7. 이제 서비스가 kubectl을 호출할 수 있으며 Google 서비스 계정으로 인증됩니다.

기존 인증 방법

참고: GKE Autopilot 클러스터의 경우 기존 인증 방법을 사용할 수 없습니다.

참고: 기존 인증은 지원 중단되었으며 GKE 1.19 이상에서 삭제되었습니다.

OAuth가 GKE와 통합되기 전에는 사전 프로비저닝된 X.509 인증서 또는 정적 비밀번호가 유일하게 사용 가능한 인증 방법이었지만, 이제는 더 이상 권장되지 않으며 사용 중지되어야 합니다. 이러한 방법은 클러스터를 손상시킬 수 있는 공격 범위가 넓으며 GKE 버전 1.12 이상을 실행하는 클러스터에서 기본적으로 사용 중지됩니다. 기존 인증 방법을 사용하는 경우 이를 해제하는 것이 좋습니다.

사용 설정되었으면 container.clusters.getCredentials 권한이 있는 사용자가 클라이언트 인증서 및 정적 비밀번호를 검색할 수 있습니다. roles/container.admin, roles/owner, roles/editor 역할은 모두 이 권한을 포함하므로, 이러한 역할을 현명하게 사용해야 합니다. GKE의 Cloud IAM 역할에 대해 자세히 알아보세요.

정적 비밀번호를 사용한 인증 사용 중지

정적 비밀번호는 API 서버가 검증하는 사용자 이름과 비밀번호의 조합입니다. GKE에서는 이 인증 방법이 기본 인증입니다.

참고: 기본 인증은 지원 중단되었으며 GKE 1.19 이상에서 삭제되었습니다.

기존 클러스터를 업데이트하고 정적 암호를 삭제하려면 다음을 사용하세요.

gcloud container clusters update CLUSTER_NAME --no-enable-basic-auth

클라이언트 인증서를 사용한 인증 사용 중지

인증서 인증의 경우 클라이언트는 API 서버가 지정된 인증 기관에 확인하는 인증서를 제공합니다. GKE에서는 클러스터 루트 인증 기관(CA)이 클라이언트 인증서를 서명합니다.

클라이언트 인증서 인증은 Kubernetes API 서버에 대한 승인에 영향을 미칩니다. 클러스터에서 기존 속성 기반 액세스 제어(ABAC) 승인이 사용 설정된 경우 클라이언트 인증서는 기본적으로 API 서버에서 인증 및 모든 작업을 수행할 수 있습니다. 반면 역할 기반 액세스 제어(RBAC)가 사용 설정된 경우 클라이언트 인증서에 Kubernetes 리소스에 대한 특정 승인이 부여되어야 합니다.

참고: GKE 1.8 이상에서는 ABAC가 기본적으로 사용 중지되고 이 클라이언트 인증서에 권한이 부여되지 않습니다.

클라이언트 인증서를 생성하지 않고 클러스터를 만들려면 --no-issue-client-certificate 플래그를 사용하세요.

gcloud container clusters create CLUSTER_NAME \
    --no-issue-client-certificate

현재까지는 기존 클러스터에서 클라이언트 인증서를 삭제할 수 있는 방법이 없습니다. 기존 클러스터에서 클라이언트 인증서 인증 사용을 중지하려면 클러스터에서 RBAC가 사용 설정되어 있고 클라이언트 인증서에 클러스터에 대한 승인이 없어야 합니다.

다음 단계

• Google Cloud 인증 알아보기
• GKE의 액세스 제어 알아보기
• Google 서비스 계정 알아보기
• 워크로드 아이덴티티 알아보기
• 클러스터 보안 강화 알아보기