공지사항 📌

마지막 업데이트 날짜: 2026-03-01

공통 변경사항

보안 권고 사항에 따라, 진단 계정 등록 시 CSP사에서 자체적으로 발급받은 엑세스 키 사용을 중지하고 최소 권한만을 갖는 서비스 계정 생성 후 워크로드 인증 절차를 따를 것을 권고드립니다.

CSP별 진단 계정 등록 방법
- AWS: Access Key + Secret Key -> IAM Role ARN 등록 - 기존과 동일
- GCP: Service Account Key File 업로드 -> Credential Configuration File 업로드 (Workload Identity Federation 구성)
- Azure: Client Secret Key 미사용 (Workload Identity Federation 구성)

또한 진단 계정 등록 시 아래와 같이 인증 방식을 선택(택1)하도록 변경되었으며, 계정 진단 시 선택한 인증 방식으로만 진행됩니다.

미사용 엑세스 키는 추후 삭제될 예정이며, 기간은 별도 공지드리겠습니다.

감사합니다.

GCP 진단 계정 등록 (Cloud Shell)

개요

이 가이드는 GCP Cloud Shell(gcloud CLI)을 사용하여 CQI 진단을 위한 GCP Workload Identity Federation을 설정하는 방법을 단계별로 안내합니다.

참고 문서: GCP 공식 가이드 - 다른 클라우드에서 워크로드 아이덴티티 제휴

1. 사전 준비

1-1. CQI AWS 환경 정보

다음 정보는 CQI 서비스에서 제공하는 고정 값입니다:

항목	값
CQI AWS 계정 ID	`253477182359`
CQI AWS 역할 이름	`CQI_NODE`

1-2. Service Account 생성

CQI 진단에 사용할 Service Account를 생성합니다.

생성할 Service Account: cqi-check-sa (아래에서 사용되므로 변경에 주의하시기 바랍니다.)

# Service Account 생성
gcloud iam service-accounts create cqi-check-sa \
  --display-name="CQI Check Service Account" \
  --description="Service Account for CQI GCP diagnostics" \
  --project=<PROJECT_ID>

를 진단할 프로젝트 ID로 변경하세요.

1-3. Custom Role 생성

CQI 진단에 필요한 Custom Role을 생성합니다.

생성할 Custom Role: cqiGcpCheckSARole

# Custom Role 생성
gcloud iam roles create cqiGcpCheckSARole \
  --project=<PROJECT_ID> \
  --title="CQI GCP Check SA Role" \
  --description="Read-only permission for Service Account for CQI" \
  --permissions="iam.serviceAccounts.get,iam.serviceAccounts.getAccessToken,storage.buckets.getIamPolicy"

를 진단할 프로젝트 ID로 변경하세요.

1-4. Service Account에 역할 부여

생성한 Service Account에 필요한 역할을 부여합니다.

PROJECT_ID="<PROJECT_ID>"
SERVICE_ACCOUNT="cqi-check-sa@${PROJECT_ID}.iam.gserviceaccount.com"

# 1. 뷰어
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/viewer"

# 2. 추천자 뷰어
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/recommender.viewer"

# 3. 클라우드 애셋 뷰어
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/cloudasset.viewer"

# 4. Compute Recommender 뷰어
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="roles/recommender.computeViewer"

# 5. CQI GCP Check SA Role (Custom Role)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="projects/${PROJECT_ID}/roles/cqiGcpCheckSARole"

를 진단할 프로젝트 ID로 변경하세요($ 기호로 시작하는 ${PROJECT_ID} 등은 변경하지 않습니다).

1-5. GCP API 활성화

CQI 진단에 필요한 12개 API를 활성화합니다.

gcloud services enable \
  iam.googleapis.com \
  iamcredentials.googleapis.com \
  sts.googleapis.com \
  cloudresourcemanager.googleapis.com \
  cloudkms.googleapis.com \
  dns.googleapis.com \
  sqladmin.googleapis.com \
  storage.googleapis.com \
  cloudasset.googleapis.com \
  compute.googleapis.com \
  container.googleapis.com \
  recommender.googleapis.com \
  --project=PROJECT_ID

API 상세 설명 접기 / 펼치기

API	설명
Identity and Access Management (IAM) API	IAM 관리
IAM Service Account Credentials API	Service Account 자격 증명
Security Token Service (STS) API	토큰 교환
Cloud Resource Manager API	리소스 관리
Cloud Key Management Service (KMS) API	키 관리
Cloud DNS API	DNS 관리
Cloud SQL Admin API	Cloud SQL 관리
Cloud Storage API	스토리지 관리
Cloud Asset API	애셋 인벤토리
Compute Engine API	Compute 리소스
Kubernetes Engine API	GKE 관리
Recommender API	추천 API

2. 워크로드 아이덴티티 풀 및 공급업체 생성

워크로드 아이덴티티 풀 및 AWS 공급업체를 생성합니다. 이 단계에서는 값을 변경하지 않고 복사 후 그대로 실행합니다.

생성할 Workload Identity Pool: cqi-workload-identity-pool
생성할 AWS 공급업체: cqi-provider

2-1. 풀 생성

gcloud iam workload-identity-pools create cqi-workload-identity-pool \
    --location="global" \
    --description="Workload Identity Pool for CQI Service(AWS)" \
    --display-name="cqi-workload-identity-pool"

2-2. AWS 공급업체 생성

gcloud iam workload-identity-pools providers create-aws cqi-provider \
  --location="global" \
  --workload-identity-pool="cqi-workload-identity-pool" \
  --account-id="253477182359" \
  --attribute-mapping="google.subject=assertion.arn,attribute.aws_role=assertion.arn.extract('assumed-role/{role}/'),attribute.account=assertion.account" \
  --attribute-condition="assertion.arn.startsWith('arn:aws:sts::253477182359:assumed-role/CQI_NODE/')"

속성 매핑 설명 접기 / 펼치기

GCP 속성	AWS 속성	설명
`google.subject`	`assertion.arn`	주체 식별자 (필수)
`attribute.aws_role`	Role 이름 추출	`CQI_NODE` 부분만 추출
`attribute.account`	`assertion.account`	AWS 계정 ID

이렇게 설정하면:
- attribute.aws_role = CQI_NODE (ARN에서 role 이름만 추출)
- 조건: CQI_NODE Role로 assume된 요청만 허용

3. 워크로드 인증

외부 워크로드가 Google Cloud 리소스에 액세스하도록 허용합니다.

3-1. Workload Identity User 역할 부여

gcloud iam service-accounts add-iam-policy-binding cqi-check-sa@<PROJECT_ID>.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/cqi-workload-identity-pool/attribute.aws_role/CQI_NODE"

와 를 실제 값으로 변경하세요. 는 gcloud projects describe <PROJECT_ID> --format='value(projectNumber)'로 확인할 수 있습니다.

principalSet 사용 이유 접기 / 펼치기

방식	Principal 형식	적합한 경우
주체별 (principal://)	`subject/arn:aws:sts::253...assumed-role/CQI_NODE/i-xxxxx`	특정 인스턴스만 허용
속성별 (principalSet://)	`attribute.aws_role/CQI_NODE`	같은 Role의 모든 요청 허용

이렇게 설정하면:
- google.subject는 전체 ARN (세션 이름 포함)으로 매핑됨 → 매번 달라질 수 있음
- attribute.aws_role은 Role 이름만 추출 → CQI_NODE로 고정

4. 사용자 인증 정보 구성 다운로드

CQI 서비스에 전달할 사용자 인증 정보 구성 파일을 생성합니다.

4-1. 인증 정보 구성 파일 생성

gcloud iam workload-identity-pools create-cred-config \
    projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/cqi-workload-identity-pool/providers/cqi-provider \
    --service-account=cqi-check-sa@<PROJECT_ID>.iam.gserviceaccount.com \
    --aws \
    --enable-imdsv2 \
    --output-file=cqi-check-sa-wif-config.json

와 를 실제 값으로 변경하세요. 중요: CQI 서비스는 "AWS IMDSv2 Required" 옵션을 사용하므로 반드시 --enable-imdsv2 플래그를 포함해야 합니다.

4-2. 생성된 파일 검증

# JSON 형식 확인
cat cqi-check-sa-wif-config.json | jq .

# imdsv2 필드 존재 확인
cat cqi-check-sa-wif-config.json | jq .credential_source.imdsv2_session_token_url

예상 출력:

"http://169.254.169.254/latest/api/token"

CQI 진단 계정 등록

다운로드 받은 사용자 인증 정보 구성 파일(.json)을 CQI 서비스에 업로드합니다.

CQI에 로그인
진단 계정 목록(Account List) 페이지로 이동
진단 계정 추가(Add Account) 버튼 클릭
CSP로 GCP 선택
인증 방식에서 Workload Identity Federation 선택
앞서 생성한 .json 파일 업로드
필요한 정보 입력 후 등록

참고: 전체 스크립트 (One-Shot)

아래 스크립트를 사용하면 전체 설정을 한 번에 수행할 수 있습니다.

#!/bin/bash
# GCP Workload Identity Federation 설정 스크립트

set -e

# === 변수 설정 (환경에 맞게 수정) ===
PROJECT_ID="<YOUR_PROJECT_ID>"
SERVICE_ACCOUNT_NAME="cqi-check-sa"
SERVICE_ACCOUNT="${SERVICE_ACCOUNT_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

# CQI 서비스 제공 정보 (고정 값)
CQI_AWS_ACCOUNT_ID="253477182359"
CQI_AWS_ROLE="CQI_NODE"

# === 1. Service Account 생성 ===
echo "Creating Service Account..."
gcloud iam service-accounts create $SERVICE_ACCOUNT_NAME \
  --display-name="CQI Check Service Account" \
  --description="Service Account for CQI GCP diagnostics" \
  --project=$PROJECT_ID

# === 2. Custom Role 생성 ===
echo "Creating Custom Role..."
gcloud iam roles create cqiGcpCheckSARole \
  --project=$PROJECT_ID \
  --title="CQI GCP Check SA Role" \
  --description="Read-only permission for Service Account for CQI" \
  --permissions="iam.serviceAccounts.get,iam.serviceAccounts.getAccessToken,storage.buckets.getIamPolicy"

# === 3. 역할 부여 ===
echo "Assigning roles..."
for ROLE in "roles/viewer" "roles/recommender.viewer" "roles/cloudasset.viewer" "roles/recommender.computeViewer"; do
  gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role="$ROLE"
done

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SERVICE_ACCOUNT}" \
  --role="projects/${PROJECT_ID}/roles/cqiGcpCheckSARole"

# === 4. API 활성화 ===
echo "Enabling APIs..."
gcloud services enable \
  iam.googleapis.com iamcredentials.googleapis.com sts.googleapis.com \
  cloudresourcemanager.googleapis.com cloudkms.googleapis.com dns.googleapis.com \
  sqladmin.googleapis.com storage.googleapis.com cloudasset.googleapis.com \
  compute.googleapis.com container.googleapis.com recommender.googleapis.com \
  --project=$PROJECT_ID

# === 5. Workload Identity Pool 생성 ===
echo "Creating Workload Identity Pool..."
gcloud iam workload-identity-pools create cqi-workload-identity-pool \
  --location="global" \
  --description="Workload Identity Pool for CQI Service(AWS)" \
  --display-name="cqi-workload-identity-pool" \
  --project=$PROJECT_ID

# === 6. AWS Provider 생성 ===
echo "Creating AWS Provider..."
gcloud iam workload-identity-pools providers create-aws cqi-provider \
  --location="global" \
  --workload-identity-pool="cqi-workload-identity-pool" \
  --account-id="$CQI_AWS_ACCOUNT_ID" \
  --attribute-mapping="google.subject=assertion.arn,attribute.aws_role=assertion.arn.extract('assumed-role/{role}/'),attribute.account=assertion.account" \
  --attribute-condition="assertion.arn.startsWith('arn:aws:sts::${CQI_AWS_ACCOUNT_ID}:assumed-role/${CQI_AWS_ROLE}/')" \
  --project=$PROJECT_ID

# === 7. Workload Identity User 역할 부여 ===
echo "Granting Workload Identity User role..."
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
gcloud iam service-accounts add-iam-policy-binding $SERVICE_ACCOUNT \
  --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/cqi-workload-identity-pool/attribute.aws_role/${CQI_AWS_ROLE}"

# === 8. 인증 정보 구성 파일 생성 ===
echo "Creating credential config file..."
gcloud iam workload-identity-pools create-cred-config \
  projects/${PROJECT_NUMBER}/locations/global/workloadIdentityPools/cqi-workload-identity-pool/providers/cqi-provider \
  --service-account=$SERVICE_ACCOUNT \
  --aws \
  --enable-imdsv2 \
  --output-file=cqi-check-sa-wif-config.json

echo ""
echo "=== 설정 완료 ==="
echo "인증 정보 파일: cqi-check-sa-wif-config.json"
echo "이 파일을 CQI 서비스에 업로드하세요."

참조

문서 버전: 1.1 최종 수정일: 2026-03-01 담당자: CQI AX운영최적화팀(cloud-tech@lgcns.com)