Google 클라우드 GKE 리소스 동기화

Overview

QueryPie에서는 쿠버네티스 클러스터 등록 및 관리를 위한 GCP 연동을 지원합니다. GCP Project 내의 GKE 클러스터를 동기화하여 QueryPie에서 관리하는 클러스터로 등록하고, 사용자 및 그룹에 동기화해 온 클러스터에 대한 Kubernetes API 접근 권한을 부여하고 정책을 설정할 수 있습니다.

이 문서는 GCP Service Account Key JSON을 QueryPie에 직접 등록하여 GKE Standard 또는 Autopilot 클러스터를 동기화하는 절차를 안내합니다.

GCP의 GKE 리소스 동기화 기능은 11.5.4 이상, 11.6.1 이상에서 제공됩니다.

사전 준비사항

대상 GCP Project ID를 확인합니다.
동기화 대상 GKE 클러스터가 GKE Standard 또는 Autopilot으로 생성되어 있는지 확인합니다.
GCP에서 Service Account 생성, IAM 역할 부여, Service Account Key 생성이 가능한 관리자 권한을 준비합니다.
QueryPie에서 KAC Cloud Provider를 생성하고 동기화할 수 있는 관리자 권한을 준비합니다.
GCP Project에서 다음 API가 활성화되어 있는지 확인합니다.

API	사용 목적
`container.googleapis.com`	GKE 클러스터 목록, Endpoint, CA 조회 및 Kubernetes API 접속
`iam.googleapis.com`	Service Account 및 Key 생성
`cloudresourcemanager.googleapis.com`	Project IAM Binding 설정

API가 활성화되어 있지 않다면 GCP Console의 APIs & Services > Enabled APIs & services 메뉴에서 활성화하거나, 아래 명령을 실행합니다.


gcloud services enable \
  container.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  --project=<PROJECT_ID>

GCP Service Account 생성 및 권한 부여

QueryPie가 GCP와 GKE에 인증할 수 있도록 QueryPie 전용 Service Account를 생성합니다.


gcloud iam service-accounts create querypie-kac-gke \
  --display-name="QueryPie KAC GKE" \
  --project=<PROJECT_ID>
export QUERYPIE_GKE_SA="querypie-kac-gke@<PROJECT_ID>.iam.gserviceaccount.com"

생성한 Service Account에 GKE 클러스터 동기화 및 Kubernetes API 접속에 필요한 IAM 역할을 부여합니다.


gcloud projects add-iam-policy-binding <PROJECT_ID> \
  --member="serviceAccount:${QUERYPIE_GKE_SA}" \
  --role="roles/container.admin"

roles/container.admin에는 QueryPie KAC의 클러스터 동기화와 사용자 및 그룹 impersonation에 필요한 container.clusters.impersonate 권한이 포함됩니다.

Service Account Key JSON 생성

QueryPie Cloud Provider Credential에 등록할 Service Account Key JSON 파일을 생성합니다.


gcloud iam service-accounts keys create querypie-kac-gke-key.json \
  --iam-account="${QUERYPIE_GKE_SA}" \
  --project=<PROJECT_ID>

생성된 JSON 파일은 Base64로 변환하지 않고, 파일의 전체 JSON 내용을 QueryPie에 입력합니다.

보안 주의: Service Account Key JSON의 private_key는 장기 자격증명입니다. Git, Wiki, 메신저, 티켓 등에 원문을 업로드하지 말고, QueryPie 등록에 사용한 뒤에는 조직의 Key 보관 및 삭제 정책에 따라 원본 파일을 관리합니다. QueryPie에 Cloud Provider를 저장한 뒤에는 Service Account JSON을 수정하거나 다른 Service Account로 교체할 수 없으므로, Credential을 변경해야 하는 경우 새 Cloud Provider를 등록합니다.

QueryPie에서 GCP 연동 정보 등록하기

Administrator > Kubernetes > Connection Management > Cloud Providers 메뉴로 이동합니다.
우측 상단의 + Create Provider 버튼을 클릭합니다.
Name 항목에 해당 프로바이더를 구분할 수 있는 이름을 입력합니다.
Cloud Provider 항목에서 GCP를 선택합니다.
Project ID 항목에 GKE 클러스터가 있는 GCP Project ID를 입력합니다.
Credential 항목에서 Service Account를 선택합니다.
Service Account JSON 항목에 querypie-kac-gke-key.json 파일의 전체 JSON 내용을 입력합니다.
필요 시 Search Filter 또는 Auto Configuration Upon Synchronization > Tag를 설정합니다.
Replication Frequency 항목에서 동기화 방식을 선택합니다.
- Manual: 동기화를 실행하는 시점에만 수동으로 리소스를 동기화합니다.
- Scheduling: Cron Expression 기반의 주기적인 스케줄링으로 리소스를 동기화합니다.
Dry Run 버튼을 클릭하여 Credential과 클러스터 조회 결과를 미리 확인합니다.
Save 버튼을 클릭하여 Cloud Provider를 저장합니다.

등록된 GCP Cloud Provider 동기화 및 관리

Administrator > Kubernetes > Connection Management > Cloud Providers 메뉴로 이동합니다.
등록한 GCP Cloud Provider를 클릭하여 상세 화면으로 이동합니다.
우측 상단의 Synchronize 버튼을 클릭하여 GCP에서 GKE 클러스터를 동기화합니다.
표시되는 Synchronization Log에서 동기화 진행 상황을 확인합니다.
Settings > Systems > Jobs 메뉴에서도 동기화 히스토리를 확인할 수 있습니다.
Administrator > Kubernetes > Connection Management > Clusters 목록에서 GKE 클러스터가 등록되었는지 확인합니다.

QueryPie는 projects/<PROJECT_ID>/locations/-/clusters API를 사용하여 Project 내 모든 location의 GKE 클러스터를 조회합니다. Standard와 Autopilot GKE 클러스터를 모두 동기화할 수 있습니다.

Cloud Provider를 한 번 등록하고 나면 Provider 일부 정보는 변경할 수 없습니다.

항목	변경 가능 여부
Name	변경 가능
Cloud Provider	변경 불가
Project ID	변경 불가
Credential	변경 불가
Service Account JSON	변경 불가
Vault Secret Store (Credential 을 “Vault(GCP)”로 선택한 경우만 해당됨.)	변경 불가
Roleset Path (Credential 을 “Vault(GCP)”로 선택한 경우만 해당됨.)	변경 불가
Search Filter	변경 가능
Auto Configuration Upon Synchronization > Tag	변경 불가
Use Regular Expression Search	변경 가능
Use Case-sensitive Search	변경 가능
Replication Frequency	변경 가능

GKE Standard와 Autopilot 차이

항목	Standard	Autopilot
클러스터 동기화	지원	지원
사용자 정의 사용자 및 그룹 impersonation	지원	지원
`system:*` 사용자 및 그룹 impersonation	지원	미지원

Autopilot에서는 KAC Policy의 impersonation 그룹으로 system:masters 같은 system:* 그룹을 사용할 수 없습니다. 사용자 정의 그룹을 사용하는 경우 Standard와 Autopilot 모두 해당 그룹을 필요한 Kubernetes ClusterRole에 연결하는 ClusterRoleBinding을 대상 GKE 클러스터에 생성해야 합니다.

예를 들어 QueryPie에서 querypie:kac-admins 그룹을 impersonation 그룹으로 사용하는 경우, 대상 GKE 클러스터에 다음과 같은 ClusterRoleBinding을 구성할 수 있습니다.


apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: querypie-kac-admins
subjects:
  - kind: Group
    name: querypie:kac-admins
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io

운영 환경에서는 cluster-admin 대신 조직 정책에 맞는 최소 권한 ClusterRole을 사용하는 것을 권장합니다.

보다 자세한 내용은 아래 링크 참고 바랍니다.

Dry Run/Synchronization Log 표기 문구

발생 시점	문구
Dry Run 또는 Synchronize 동기화 시작	`Cluster synchronize started.`
신규 클러스터 추가 완료	`New Cluster is added: {Cluster Name} (https://{Endpoint}).`
기존 클러스터 정보 업데이트 완료	`Cluster {Cluster Name} is updated.`
기존 클러스터 제거 완료	`Cluster {Cluster Name} is removed.`
Dry Run 또는 Synchronize 동기화 성공 종료	`Cluster synchronize succeeded.`
이미 중복된 클러스터명이 확인되어 동기화 실패	`Cluster synchronization failed. The cluster name “{Cluster Name}” is already in use by another cluster. To synchronize it, delete the existing cluster.`
Dry Run 또는 Synchronize 동기화 실패 종료	`Cluster synchronize failed. {additional statement}`
클러스터 Endpoint를 조회할 수 없어 동기화 스킵	`Skipping cluster {Cluster Name}: endpoint not available (cluster may be provisioning).`
클러스터 CA 인증서를 조회할 수 없어 동기화 스킵	`Skipping cluster {Cluster Name}: CA certificate not available.`
신규 클러스터 추가 실패	`Failed to add cluster {Cluster Name}: {additional statement}`
기존 클러스터 업데이트 실패	`Failed to update cluster {Cluster Name}: {additional statement}`
기존 클러스터 삭제 실패	`Failed to delete cluster {Cluster Name}: {additional statement}`

자주 묻는 질문

Q. Service Account JSON은 Base64로 인코딩해서 입력해야 하나요?

A. 아닙니다. querypie-kac-gke-key.json 파일의 전체 JSON 내용을 그대로 입력합니다.

Q. GKE Autopilot 클러스터도 동기화할 수 있나요?

A. 네. GKE Standard와 Autopilot 클러스터 모두 동기화할 수 있습니다. 다만 Autopilot에서는 system:masters 같은 system:* 사용자 및 그룹 impersonation을 사용할 수 없으므로, 사용자 정의 그룹과 필요한 Kubernetes RBAC Binding을 사용하는 것을 권장합니다.

Q. Cloud Provider 저장 후 Project ID나 Credential을 수정할 수 있나요?

A. 아니요. Provider를 저장한 뒤에는 Cloud Provider, Project ID, Credential, Service Account JSON과 같은 핵심 연결 정보는 변경할 수 없습니다. 다른 Project나 Credential을 사용해야 한다면 Cloud Provider를 새로 등록합니다.

Q. 동기화는 성공했지만 사용자가 클러스터에 접속하지 못합니다.

A. QueryPie에 클러스터가 등록된 뒤에도 사용자 또는 그룹에 대한 KAC 접근 권한과 정책이 별도로 필요합니다. 또한 사용자 정의 impersonation 그룹을 사용하는 경우 대상 GKE 클러스터에 해당 그룹을 Kubernetes RoleBinding 또는 ClusterRoleBinding으로 연결했는지 확인합니다.