공지사항 📌

마지막 업데이트 날짜: 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)하도록 변경되었으며, 계정 진단 시 선택한 인증 방식으로만 진행됩니다.

Guide-Account-Authentication-1

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

감사합니다.


GCP 진단 계정 등록 (Console)

개요

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

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

중요: 일부 단계는 Console에서 지원하지 않아 gcloud CLI 또는 직접 파일 수정이 필요합니다.


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 (아래에서 사용되므로 변경에 주의하시기 바랍니다.)
  1. IAM 및 관리자 > 서비스 계정으로 이동
  2. 상단의 + 서비스 계정 만들기 클릭
  3. 서비스 계정 세부정보 입력:
    • 서비스 계정 이름: cqi-check-sa
    • 서비스 계정 ID: cqi-check-sa (자동 생성됨)
    • 서비스 계정 설명: Service Account for CQI GCP diagnostics
  4. 만들고 계속하기 클릭
  5. 역할 부여는 나중에 진행하므로 완료 클릭
가이드 사진 접기 / 펼치기

Guide-GCP-Console-1


1-3. Custom Role 생성

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

  • 생성할 Custom Role: cqiGcpCheckSARole
  1. IAM 및 관리자 > 역할로 이동
  2. 상단의 + 역할 만들기 클릭
  3. 역할 정보 입력:
    • 제목: CQI GCP Check SA Role
    • 설명: Read-only permission for Service Account for CQI
    • ID: cqiGcpCheckSARole
    • 역할 출시 단계: 일반 안정화 버전
  4. + 권한 추가 클릭
  5. 필터에서 다음 권한을 검색하여 추가:
    • iam.serviceAccounts.get
    • iam.serviceAccounts.getAccessToken
    • storage.buckets.getIamPolicy
  6. 만들기 클릭
가이드 사진 접기 / 펼치기

Guide-GCP-Console-2


1-4. Service Account에 역할 부여

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

  1. IAM 및 관리자 > IAM으로 이동
  2. 액세스 권한 부여 클릭
  3. 새 주 구성원 필드에 서비스 계정 이메일 입력:
    • cqi-check-sa@<PROJECT_ID>.iam.gserviceaccount.com
  4. 역할 선택에서 다음 5개 역할을 추가 (역할당 + 다른 역할 추가 클릭):
역할 유형 역할 이름 검색어
기본 제공 역할 뷰어 (Viewer) roles/viewer
기본 제공 역할 추천자 뷰어 Recommender Viewer
기본 제공 역할 클라우드 애셋 뷰어 Cloud Asset Viewer
기본 제공 역할 Compute 추천자 뷰어 Compute Recommender
커스텀 역할 CQI GCP Check SA Role cqiGcpCheckSARole
  1. 저장 클릭
가이드 사진 접기 / 펼치기

Guide-GCP-Console-3


1-5. GCP API 활성화

  1. API 및 서비스 > 라이브러리로 이동
  2. 아래 12개 API를 각각 검색하여 사용 버튼 클릭:
API 이름 검색어 설명
Identity and Access Management (IAM) API IAM API IAM 관리
IAM Service Account Credentials API IAM Credentials Service Account 자격 증명
Security Token Service API Security Token Service 토큰 교환
Cloud Resource Manager API Resource Manager 리소스 관리
Cloud Key Management Service (KMS) API Cloud KMS 키 관리
Cloud DNS API Cloud DNS DNS 관리
Cloud SQL Admin API Cloud SQL Admin Cloud SQL 관리
Cloud Storage API Cloud Storage 스토리지 관리
Cloud Asset API Cloud Asset 애셋 인벤토리
Compute Engine API Compute Engine Compute 리소스
Kubernetes Engine API Kubernetes Engine GKE 관리
Recommender API Recommender 추천 API
가이드 사진 접기 / 펼치기

Guide-GCP-Console-4
Guide-GCP-Console-5

활성화되어있지 않은 API의 경우 사용 버튼이 표시됩니다. 클릭하여 API를 활성화합니다.

Guide-GCP-Console-6

팁: API 및 서비스 > 사용 설정된 API 및 서비스에서 활성화 상태를 확인할 수 있습니다.


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

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

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

2-1. 풀 생성

  1. IAM 및 관리자 > 워크로드 아이덴티티 풀로 이동
  2. + 풀 만들기 클릭
  3. 풀 정보 입력:
    • 이름: cqi-workload-identity-pool
    • 설명: Workload Identity Pool for CQI Service(AWS)
  4. 계속 클릭

2-2. AWS 공급업체 생성

  1. 공급업체 추가 화면에서:
    • 공급업체 선택: AWS 선택
  2. 공급업체 세부정보 입력:
    • 공급업체 이름: cqi-provider
    • AWS 계정 ID: 253477182359
  3. 계속 클릭
  4. 속성 매핑 구성:
Google 속성 (1) OIDC 속성 (2)
google.subject assertion.arn
attribute.aws_role assertion.arn.extract('assumed-role/{role}/')
attribute.account assertion.account
  1. 속성 조건 (선택사항이지만 보안을 위해 권장):
assertion.arn.startsWith('arn:aws:sts::253477182359:assumed-role/CQI_NODE/')
  1. 저장 클릭
가이드 사진 접기 / 펼치기

Guide-GCP-Console-7
Guide-GCP-Console-8
Guide-GCP-Console-9

  • 속성 매핑 구성
Google 속성 (1) OIDC 속성 (2)
google.subject assertion.arn
attribute.aws_role assertion.arn.extract('assumed-role/{role}/')
attribute.account assertion.account

매핑 추가 방법: + 매핑 추가 버튼을 클릭하여 attribute.account 매핑을 추가합니다.

  • 속성 조건
assertion.arn.startsWith('arn:aws:sts::253477182359:assumed-role/CQI_NODE/')

Guide-GCP-Console-10

속성 매핑 설명 접기 / 펼치기
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 역할 부여

  1. IAM 및 관리자 > 워크로드 아이덴티티 풀로 이동
  2. 생성한 풀 cqi-workload-identity-pool 클릭
  3. 상단의 액세스 권한 부여 클릭
  4. 서비스 계정 가장 기능을 사용하여 액세스 권한 부여 선택
  5. 서비스 계정 선택:
    • cqi-check-sa@<PROJECT_ID>.iam.gserviceaccount.com 선택
  6. 주 구성원 선택 섹션에서:
    • 속성 이름 필터 사용: aws_role 선택
    • 속성 값: CQI_NODE 입력
  7. 저장 클릭

참고: 이 설정은 principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/cqi-workload-identity-pool/attribute.aws_role/CQI_NODE 형태로 권한이 부여됩니다.

가이드 사진 접기 / 펼치기

Guide-GCP-Console-10
Guide-GCP-Console-11
Guide-GCP-Console-12

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. 인증 정보 구성 파일 다운로드

  1. IAM 및 관리자 > 워크로드 아이덴티티 풀로 이동
  2. 생성한 풀 cqi-workload-identity-pool 클릭
  3. 상단의 연결된 서비스 계정 탭 클릭
  4. 연결된 서비스 계정 cqi-check-sa 옆의 다운로드 아이콘 클릭
  5. 다운로드 옵션:
    • 형식: 구성 파일
    • 공급업체: cqi-provider 선택
  6. 다운로드 클릭

4-2. IMDSv2 설정 수동 추가 (필수)

중요 (Console 한계): Console에서 다운로드한 구성 파일에는 IMDSv2 설정이 포함되지 않습니다. AWS IMDSv2 환경(CQI 서비스)에서 사용하려면 다운로드한 JSON 파일을 수동으로 수정해야 합니다.

다운로드한 JSON 파일을 열어 credential_source 섹션에 다음 필드를 추가합니다:

  • 추가 필드: "imdsv2_session_token_url": "http://169.254.169.254/latest/api/token"

수정 전:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>",
  "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<SERVICE_ACCOUNT>:generateAccessToken",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "environment_id": "aws1",
    "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
    "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
    "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15"
  }
}

수정 후 (IMDSv2 추가):

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/providers/<PROVIDER_ID>",
  "subject_token_type": "urn:ietf:params:aws:token-type:aws4_request",
  "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/<SERVICE_ACCOUNT>:generateAccessToken",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "environment_id": "aws1",
    "region_url": "http://169.254.169.254/latest/meta-data/placement/availability-zone",
    "url": "http://169.254.169.254/latest/meta-data/iam/security-credentials",
    "regional_cred_verification_url": "https://sts.{region}.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
    "imdsv2_session_token_url": "http://169.254.169.254/latest/api/token"
  }
}

4-3. 대안: gcloud CLI 사용 (IMDSv2 자동 포함)

Console 대신 gcloud CLI를 사용하면 --enable-imdsv2 플래그가 자동으로 설정됩니다.

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

와 를 실제 값으로 변경하세요.


4-4. 생성된 파일 검증

파일이 올바르게 수정되었는지 확인합니다.

# imdsv2 필드 존재 확인 (Cloud Shell 또는 로컬 터미널에서)
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 서비스에 업로드합니다.

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

진단 계정 등록


참고

Console vs gcloud CLI 비교

단계 Console 지원 비고
Service Account 생성 ✅ 지원 -
Custom Role 생성 ✅ 지원 -
역할 부여 ✅ 지원 -
API 활성화 ✅ 지원 -
풀 생성 ✅ 지원 -
공급업체 생성 ✅ 지원 속성 매핑/조건 입력 가능
워크로드 인증 ✅ 지원 액세스 권한 부여 UI
인증 정보 다운로드 ⚠️ 부분 지원 IMDSv2 설정 수동 추가 필요

문제 해결

Console에서 워크로드 아이덴티티 풀이 보이지 않는 경우

  1. 올바른 프로젝트가 선택되었는지 확인
  2. 필요한 API (IAM, STS, IAM Credentials)가 활성화되었는지 확인
  3. 사용자에게 roles/iam.workloadIdentityPoolAdmin 권한이 있는지 확인

IMDSv2 관련 오류

CQI에서 인증 실패 시:

  1. CQI 관리자에게 EC2 인스턴스의 IMDSv2 설정 확인 요청
  2. 구성 파일에 imdsv2_session_token_url 필드가 있는지 확인(필수!)
  3. 없다면 사용자 인증 정보 구성 다운로드의 수정 절차 수행

참조


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

진단 계정 등록 가이드