Kubernetes API 서버에 인증

Autopilot Standard

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

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

개요

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

시작하기 전에

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

Google Kubernetes Engine API를 사용 설정합니다.

Google Kubernetes Engine API 사용 설정

이 태스크에 Google Cloud CLI를 사용하려면 gcloud CLI를 설치한 후 초기화합니다. 이전에 gcloud CLI를 설치한 경우 gcloud components update를 실행하여 최신 버전을 가져옵니다.
참고: 기존 gcloud CLI 설치의 경우 compute/region 및 compute/zone 속성을 설정해야 합니다. 기본 위치를 설정하면 gcloud CLI에서 One of [--zone, --region] must be supplied: Please specify location과 같은 오류를 방지할 수 있습니다.

사용자 인증

GKE는 Google Cloud CLI를 통해 최종 사용자 인증을 관리합니다. gcloud CLI는 사용자를 Google Cloud에 인증하고, Kubernetes 구성을 설정하고, 클러스터의 OAuth 액세스 토큰을 가져오고, 액세스 토큰을 최신 상태로 유지합니다.

모든 GKE 클러스터는 kubectl이 제공한 사용자 인증 정보를 검증하고 사용자 또는 서비스 계정 ID에 연결된 이메일 주소를 검색하여 Google Cloud 사용자 및 서비스 계정 ID를 수락하도록 구성됩니다. 따라서 이러한 계정의 사용자 인증 정보에 userinfo.email OAuth 범위가 포함되어야 인증이 성공합니다.

gcloud를 사용하여 신규 또는 기존 클러스터에 환경의 kubeconfig를 설정하는 경우 gcloud는 gcloud 자체에서 사용하는 동일한 사용자 인증 정보를 kubectl에 제공합니다. 예를 들어 gcloud auth login을 사용하는 경우 userinfo.email 범위를 포함하여 개인 사용자 인증 정보가 kubectl에 제공됩니다. 따라서 GKE 클러스터에서 kubectl 클라이언트를 인증할 수 있습니다.

Compute Engine 인스턴스에서 실행되는 동안 kubectl이 Google Cloud 서비스 계정의 사용자 인증 정보를 사용하도록 구성할 수도 있습니다. 그러나 Compute Engine 인스턴스가 만든 사용자 인증 정보에는 기본적으로 userinfo.email 범위가 포함되지 않습니다. 따라서 이 범위를 반드시 명시적으로 추가해야 합니다. 예를 들어 Compute Engine 인스턴스를 만들 때 --scopes 플래그를 사용할 수 있습니다.

Identity and Access Management(IAM) 또는 Kubernetes 역할 기반 액세스 제어(RBAC)를 사용하여 클러스터의 작업을 승인할 수 있습니다.

OAuth를 사용하여 인증

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

사용자 인증 정보를 사용하여 gcloud CLI에 로그인합니다. 그러면 Google Cloud에 대한 인증 프로세스를 완료하기 위한 웹브라우저가 열립니다.
```
gcloud auth login
```
주의: 모든 사용자가 root에 액세스할 수 있는 Compute Engine VM에서는 이 작업을 수행하지 마세요. 인증을 위해 서비스 계정을 사용하세요. 자세한 내용은 Google Cloud 내 애플리케이션 섹션을 참조하세요.

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

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

인증되었는지 확인합니다.
```
kubectl cluster-info
```

인증된 사용자 또는 Google Cloud 서비스 계정은 승인 과정도 거쳐야 GKE 클러스터에서 작업을 수행할 수 있습니다. 승인을 구성하는 방법에 대한 자세한 내용은 역할 기반 액세스 제어를 참조하세요.

애플리케이션 인증

또한 CI/CD 파이프라인의 스크립트에서와 같이 사용자 상호작용 없이 포드의 애플리케이션에서 API 서버에 인증할 수 있습니다. 이를 수행하는 방법은 애플리케이션이 실행되는 환경에 따라 다릅니다.

동일한 클러스터의 애플리케이션

애플리케이션이 동일한 GKE 클러스터에서 실행되는 경우 Kubernetes 서비스 계정을 사용하여 인증합니다.

Kubernetes 서비스 계정을 만들어 포드에 연결합니다. 포드에 이미 Kubernetes 서비스 계정이 있거나 네임스페이스의 기본 서비스 계정을 사용하려면 이 단계를 건너뛰세요.
Kubernetes RBAC를 사용하여 애플리케이션에 필요한 권한을 Kubernetes 서비스 계정에 부여합니다.

다음 예시에서는 prod 네임스페이스의 리소스에 대한 view 권한을 cicd-ns 네임스페이스의 cicd라는 서비스 계정에 부여합니다.
```
kubectl create rolebinding cicd-secret-viewer \
    --namespace=prod \
    --clusterrole=view \
    --serviceaccount=cicd-ns:cicd
```
런타임에서 애플리케이션이 Kubernetes API 요청을 전송하면 API 서버는 서비스 계정 사용자 인증 정보를 인증합니다.

Google Cloud 내 애플리케이션

애플리케이션이 Google Cloud 내부에서 실행되지만 대상 클러스터의 외부인 경우(예: Compute Engine VM 또는 다른 GKE 클러스터) 환경에서 사용 가능한 IAM 서비스 계정 사용자 인증 정보를 사용하여 API 서버에 인증해야 합니다.

사용자 환경에 IAM 서비스 계정을 할당합니다. 애플리케이션이 Compute Engine VM 내에서 실행되는 경우 인스턴스에 IAM 서비스 계정을 할당합니다. 애플리케이션이 다른 GKE 클러스터에서 실행되는 경우 GKE용 워크로드 아이덴티티 제휴를 사용하여 포드가 IAM 서비스 계정으로 실행되도록 구성합니다.

다음 예시에서는 ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com을 IAM 서비스 계정으로 사용합니다.
IAM 서비스 계정에 클러스터에 대한 액세스 권한을 부여합니다.

다음 예시에서는 클러스터 내에서 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
```
또는 RBAC를 사용하여 IAM 서비스 계정에 클러스터에 대한 액세스 권한을 부여할 수 있습니다. 동일한 클러스터의 애플리케이션에서 kubectl create rolebinding 명령어를 실행하고 --service-account 플래그 대신 --user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com을 사용합니다.
클러스터 사용자 인증 정보를 검색합니다.
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --zone=COMPUTE_ZONE
```
애플리케이션은 환경에 설정된 IAM 서비스 계정을 사용하여 자동으로 인증됩니다.

다른 환경의 애플리케이션

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

애플리케이션의 IAM 서비스 계정을 만듭니다. 이미 IAM 서비스 계정이 있는 경우 이 단계를 건너뜁니다.

다음 명령어는 ci-cd-pipeline이라는 IAM 서비스 계정을 만듭니다.
```
gcloud iam service-accounts create ci-cd-pipeline
```
IAM 서비스 계정에 클러스터 액세스 권한을 부여합니다.

다음 명령어는 ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com IAM 서비스 계정에 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
```
RBAC를 사용하여 IAM 서비스 계정에 클러스터에 대한 액세스 권한을 부여할 수도 있습니다. 동일한 클러스터의 애플리케이션에서 kubectl create rolebinding 명령어를 실행하고 --service-account 플래그 대신 --user=ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com을 사용합니다.

IAM 서비스 계정의 키를 만들고 다운로드합니다. 런타임에서 애플리케이션에 제공합니다.

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

런타임에서 애플리케이션을 실행하는 환경에서 IAM 서비스 계정 키를 사용하여 gcloud CLI에 인증합니다.
```
gcloud auth activate-service-account ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com \
    --key-file=gsa-key.json
```

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

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

gcloud가 없는 환경

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

애플리케이션의 IAM 서비스 계정을 만듭니다. 이미 IAM 서비스 계정이 있는 경우 이 단계를 건너뜁니다.

다음 명령어는 ci-cd-pipeline이라는 IAM 서비스 계정을 만듭니다.
```
gcloud iam service-accounts create ci-cd-pipeline
```
IAM 서비스 계정에 클러스터 액세스 권한을 부여합니다.

다음 명령어는 ci-cd-pipeline@PROJECT_ID.iam.gserviceaccount.com IAM 서비스 계정에 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
```
커스텀 IAM 역할을 만들어 부여하는 권한을 세밀하게 제어할 수도 있습니다.

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

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

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

클러스터의 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)"

다음이 포함된 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:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - --use_application_default_credentials
      command: gke-gcloud-auth-plugin
      installHint: Install gke-gcloud-auth-plugin for kubectl by following
        https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#install_plugin
      provideClusterInfo: true
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 인코딩 인증서를 디코딩할 필요가 없음).

사용자 환경의 애플리케이션과 함께 kubeconfig.yaml 및 gsa-key.json을 배포합니다. 런타임에 애플리케이션을 실행하는 환경에서 다음 환경 변수를 설정합니다.
```
export KUBECONFIG=path/to/kubeconfig.yaml
export GOOGLE_APPLICATION_CREDENTIALS=path/to/gsa-key.json
```
이제 애플리케이션이 Kubernetes API에 요청을 전송할 수 있으며 IAM 서비스 계정으로 인증됩니다.

기존 인증 방법

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

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

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

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

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

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

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

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

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

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

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

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