자주 묻는 질문(FAQ) 및 문제 해결

Cloud 애셋 인벤토리는 글로벌 서비스인가요?

예. Cloud Asset API는 위치에 종속되지 않습니다. Cloud 애셋 인벤토리에서 지원되는 모든 지역 및 글로벌 애셋의 메타데이터를 제공하는 글로벌 엔드포인트가 있습니다. Cloud Asset API는 모든 영역에서 액세스할 수 있습니다.

Cloud 애셋 인벤토리는 어떤 종류의 데이터 일관성을 제공하나요?

Cloud 애셋 인벤토리는 현재 데이터에 대해서는 eventual consistency를, 이전 데이터에 대해서는 최선의 일관성을 제공합니다. 실제 가능성은 낮지만 Cloud 애셋 인벤토리에서 이전에 일부 애셋 업데이트가 누락되었을 수 있습니다.

Cloud Asset API 사용 권한이 없는 이유는 무엇인가요?

애셋을 내보내거나 조직, 프로젝트 또는 폴더에서 기록을 가져올 수 있는 권한이 없으면 오류가 반환됩니다.

예를 들어 권한이 없는 상태에서 다음 명령어를 실행할 경우

curl -X POST \
     -H "X-Goog-User-Project: BILLING_PROJECT_ID" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
          "outputConfig": {
            "gcsDestination": {
              "uri": "gs://BUCKET_NAME/FILENAME"
            }
          }
         }' \
         https://cloudasset.googleapis.com/v1/projects/PROJECT_ID:exportAssets

다음 오류를 반환합니다.

{
  "error": {
    "code": 403,
    "message": "The caller does not have permission",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::permission_denied: Request
        denied by Cloud IAM."
      }
    ]
  }
}

이 문제를 해결하려면 프로젝트, 폴더 또는 조직 관리자에게 액세스 권한을 요청하세요. 내보내거나 기록을 가져오려는 애셋에 따라 다음 역할 또는 필수 Cloud Asset API 권한이 포함된 다른 역할 중 하나가 필요합니다.

  • cloudasset.viewer

  • cloudasset.owner

역할 및 권한에 대한 자세한 내용은 역할 이해를 참조하세요.

Cloud Asset API의 액세스 제어 옵션에 대한 자세한 내용은 액세스 제어를 참조하세요.

내보내기에서 권한 거부됨 오류가 반환되는 이유는 무엇인가요?

달리 지정하지 않는 한 Cloud 애셋 인벤토리는 활성 프로젝트의 기본 Cloud 애셋 인벤토리 서비스 계정을 사용하여 Pub/Sub 주제, Cloud Storage 버킷, BigQuery 테이블과 같은 리소스를 관리합니다. 이 서비스 계정은 프로젝트에서 Cloud 애셋 인벤토리 API를 처음 호출할 때 생성되며 기본적으로 이러한 리소스가 동일한 프로젝트에 있는 한 해당 리소스를 관리할 수 있는 권한을 갖습니다.

다음과 같은 경우 권한이 거부되었다는 오류가 표시될 수 있습니다.

  • 활성 프로젝트를 설정하지 않고 REST 애셋을 사용할 때 Cloud 애셋 인벤토리는 사용할 서비스 계정을 알지 못하는 경우

  • Pub/Sub 주제, Cloud Storage 버킷 또는 BigQuery 테이블이 있는 프로젝트와 다른 프로젝트에서 gcloud CLI를 사용하는 경우. 이는 활성 프로젝트의 기본 Cloud 애셋 인벤토리 서비스 계정이 태스크(있는 경우) 수행에 사용되며 다른 프로젝트의 리소스에 쓸 수 있는 권한이 없을 수 있다는 의미입니다.

Pub/Sub 주제, Cloud Storage 버킷 또는 BigQuery 테이블로 요청을 보낼 때 올바른 서비스 계정이 사용되도록 하려면 올바른 기본 Cloud Asset 인벤토리 서비스 계정이 포함된 프로젝트 ID를 지정하면 됩니다. 한 프로젝트에서 다른 프로젝트로 내보내는 경우 서비스 계정에 특정 역할을 부여해야 합니다.

gcloud

gcloud CLI의 경우 명령어에 --billing-project 플래그를 추가하여 올바른 서비스 계정이 포함된 프로젝트 ID를 지정하세요.

--billing-project=BILLING_PROJECT_ID

또는 gcloud CLI로 명령어를 실행하기 전에 결제 프로젝트를 설정할 수 있습니다. 먼저 결제 프로젝트가 핵심 프로젝트와 다른지 확인합니다.

gcloud config list

필요한 경우 결제 프로젝트를 설정합니다.

gcloud config set billing/quota_project BILLING_PROJECT_ID

다음 값을 제공합니다.

  • BILLING_PROJECT_ID: Cloud 애셋 인벤토리 API가 사용 설정된 프로젝트 ID와 대상 Pub/Sub 주제, Cloud Storage 버킷 또는 BigQuery 테이블을 관리할 수 있는 권한이 있는 서비스 계정

REST

REST API의 경우 X-Goog-User-Project 헤더를 추가하여 올바른 서비스 계정이 포함된 프로젝트 ID를 지정합니다. curl을 사용할 때는 -H 플래그로 헤더를 설정합니다.

-H "X-Goog-User-Project: BILLING_PROJECT_ID"

다음 값을 제공합니다.

  • BILLING_PROJECT_ID: Cloud 애셋 인벤토리 API가 사용 설정된 프로젝트 ID와 대상 Pub/Sub 주제, Cloud Storage 버킷 또는 BigQuery 테이블을 관리할 수 있는 권한이 있는 서비스 계정

한 프로젝트에서 다른 프로젝트로 애셋 메타데이터 내보내기

한 프로젝트(PROJECT_A)에서 다른 프로젝트(PROJECT_B)로 애셋 메타데이터를 내보내려면 PROJECT_A의 기본 Cloud 애셋 인벤토리 서비스 계정에 PROJECT_B에 있는 리소스에 대한 액세스 권한을 부여해야 합니다. 이렇게 하면 두 가지 작업이 가능해집니다.

  • PROJECT_A에서 PROJECT_B에 있는 Pub/Sub 주제, Cloud Storage 버킷 또는 BigQuery 테이블로 애셋 메타데이터를 내보낼 수 있습니다.

  • PROJECT_A를 사용하여 PROJECT_B에서 PROJECT_B에 있는 Pub/Sub 주제, Cloud Storage 버킷 또는 BigQuery 테이블로 애셋 메타데이터를 내보낼 수 있습니다.

한 프로젝트에서 다른 프로젝트로 애셋 메타데이터를 내보내려면 다음 안내를 완료하세요.

  1. 요청을 실행하려는 프로젝트인 PROJECT_A에서 Cloud 애셋 인벤토리 API가 사용 설정되어 있는지 확인합니다.

  2. PROJECT_A에서 Cloud 애셋 인벤토리 API를 최소 한 개 이상 호출하여 기본 Cloud 애셋 인벤토리 서비스 계정을 만듭니다. 또는 수동으로 만들 수 있습니다.

    gcloud beta services identity create \
    --service=cloudasset.googleapis.com \
    --project=PROJECT_A_ID
gcloud projects add-iam-policy-binding PROJECT_A_ID \
    --member=serviceAccount:service-PROJECT_A_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com \
    --role=roles/cloudasset.serviceAgent

    Google Cloud 프로젝트 번호를 찾는 방법

    콘솔

    Google Cloud 프로젝트 번호를 찾으려면 다음 단계를 완료합니다.

    1. Google Cloud 콘솔의 대시보드 페이지로 이동합니다.

      대시보드로 이동

    2. 메뉴 바에서 전환 상자를 클릭합니다.
    3. 다음 조직에서 선택 상자에서 조직을 선택한 후 프로젝트 이름을 검색합니다.
    4. 프로젝트 이름을 클릭하여 해당 프로젝트로 전환합니다. 프로젝트 번호가 프로젝트 정보 카드에 표시됩니다.

    gcloud CLI

    다음 명령어를 사용하여 Google Cloud 프로젝트 번호를 검색할 수 있습니다.

    gcloud projects describe PROJECT_ID --format="value(projectNumber)"

  3. 서비스 계정에 올바른 권한을 부여합니다.

    • Pub/Sub을 통해 피드에 게시하려면 주제의 서비스 계정에 roles/pubsub.publisher 역할을 부여합니다.

      gcloud pubsub topics add-iam-policy-binding projects/PROJECT_B_ID/topics/TOPIC_ID \
    --member=serviceAccount:service-PROJECT_A_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com \
    --role=roles/pubsub.publisher

    • Cloud Storage 버킷에 쓰려면 버킷의 서비스 계정에 roles/storage.objectCreator 역할을 부여합니다.

      gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
  --member=serviceAccount:service-PROJECT_A_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com \
  --role=roles/storage.objectCreator

    • BigQuery 테이블에 쓰려면 프로젝트의 서비스 계정에 roles/bigquery.dataEditor 및 roles/bigquery.user 역할을 부여합니다.

      gcloud projects add-iam-policy-binding PROJECT_B_ID \
    --member=serviceAccount:service-PROJECT_A_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com \
    --role=roles/bigquery.user
gcloud projects add-iam-policy-binding PROJECT_B_ID \
    --member=serviceAccount:service-PROJECT_A_NUMBER@gcp-sa-cloudasset.iam.gserviceaccount.com \
    --role=roles/bigquery.dataEditor

Cloud 애셋 인벤토리 요청을 수행할 때는 사용할 프로젝트로 PROJECT_A를 지정해야 합니다. gcloud CLI의 경우 --billing-project 플래그를 PROJECT_A_ID로 설정합니다. REST의 경우 X-Goog-User-Project 헤더를 PROJECT_A_ID로 설정합니다.

Cloud Asset API 결과가 비활성화된 이유는 무엇인가요?

Cloud Asset API의 데이터는 최선의 노력을 통해 최신 상태로 유지됩니다. 거의 모든 애셋 업데이트가 몇 분 안에 클라이언트에 제공되지만 간혹 Cloud 애셋 API 메서드의 결과에 최신 애셋 업데이트가 포함되지 않을 수 있습니다.

ExportAssets 실행 후 임시 파일이 출력되는 이유는 무엇인가요?

ExportAssets 작업은 출력 폴더에 임시 파일을 만들 수 있습니다. 작업이 진행되는 동안 이 임시 파일을 삭제하지 마세요. 작업이 완료된 후에 임시 파일이 자동으로 삭제됩니다.

임시 파일이 그대로 남아 있는 경우 ExportAssets 작업이 완료된 후에 안전하게 삭제할 수 있습니다.

Google Cloud CLI 또는 Cloud Shell 사용자 인증 정보가 거부된 이유는 무엇인가요?

요청에서 사용자 프로젝트가 Google Cloud CLI 또는 Cloud Shell에서 cloudasset.googleapis.com으로 전송되는 경우 다음과 같은 오류 메시지를 받게 됩니다.

Your application has authenticated using end user credentials from the
Google Cloud CLI or Cloud Shell which are not supported by the
cloudasset.googleapis.com. We recommend that most server applications
use service accounts instead. For more information about service accounts
and how to use them in your application, see
https://cloud.google.com/docs/authentication/.

이 문제를 해결하려면 사용자 프로젝트를 Cloud Asset API가 사용 설정된 사용자의 프로젝트 ID로 설정하세요. HTTP 요청에서 HTTP 헤더 X-Goog-User-Project를 지정하면 됩니다.

curl을 사용하는 경우 다음 매개변수를 추가하면 됩니다.

-H "X-Goog-User-Project: PROJECT_ID"

gcloud CLI를 사용하는 경우 gcloud asset 명령어와 함께 --billing-project PROJECT_ID 플래그를 지정하거나 다음 명령어를 사용하세요.

gcloud config set billing/quota_project PROJECT_ID

동일한 애셋에 대해 다른 상위 항목이 표시되는 이유는 무엇인가요?

Cloud Asset API를 호출하여 동일한 애셋의 RESOURCE 메타데이터 및 IAM POLICY 메타데이터와 같은 서로 다른 메타데이터 유형을 가져올 때 ancestors 필드가 콘텐츠 유형 간에 일관되지 않을 수 있습니다. 이는 콘텐츠 유형마다 데이터 수집 일정이 다르므로 수집 프로세스가 완료될 때까지 일관되지 않을 수 있기 때문입니다. update_time 필드를 확인하여 애셋에 가장 최신 정보가 있는지 확인하세요.

불일치가 24시간 이상 계속되면 Google에 문의하세요.

ExportAssets API를 얼마나 자주 호출해야 하나요?

동일한 프로젝트, 폴더, 조직에 대해 ExportAssets API를 순차적으로 호출하는 것이 좋습니다. 예를 들어 이전 호출이 완료된 후에 두 번째 호출을 실행합니다. 애셋 업데이트를 실시간으로 캡처하려면 실시간 알림을 사용하는 것이 좋습니다.

중복 애셋 업데이트 받기

실시간 알림을 설정한 후 Pub/Sub 주제에서 중복 애셋 업데이트를 받을 수 있습니다. Pub/Sub는 최소 1회 전송을 보장하지 않으므로 전송 시도가 자동으로 재시도됩니다.

프로젝트 삭제 알림을 받지 못한 이유는 무엇인가요?

프로젝트를 종료하면 30일 내에 작업을 실행취소할 수 있습니다. 알림의 deleted 필드는 프로젝트가 영구적으로 삭제될 때까지 설정되지 않습니다. 삭제 대기 중인 프로젝트를 모니터링하려면 프로젝트의 lifecycleState에서 조건(예: temporal_asset.asset.resource.data.lifecycleState == "DELETE_REQUESTED")으로 피드를 설정할 수 있습니다.

SearchAllResources API를 사용하여 리소스의 JSON 표현을 검색하려면 어떻게 해야 하나요?

read_mask가 지정되지 않은 경우 기본적으로 SearchAllResources는 다음 표준 필드를 반환합니다.

  • name

  • assetType

  • project

  • folders

  • organization

  • displayName

  • description

  • location

  • labels

  • networkTags

  • kmsKeys

  • createTime

  • updateTime

  • state

  • additionalAttributes

  • parentFullResourceName

  • parentAssetType

위에 나열된 필드 외에 리소스 메타데이터의 모든 필드를 검색하려면 검색 요청에 read_mask 플래그(gcloud의 --read-mask)를 지정하면 됩니다.

read_mask는 결과에 반환하려는 필드 목록이며 쉼표로 구분됩니다. versionedResources 및 attachedResources와 같은 일부 필드는 너무 커서 기본적으로 결과에 포함되지 않습니다. 이러한 필드를 포함하려면 read_mask에서 지정하면 됩니다. 또는 "*"를 사용하여 모든 사용 가능한 필드를 포함합니다. read_mask 값의 예로는 "name,location", "name,versionedResources", "*"가 있습니다.

gcloud 예시는 다음과 같습니다.

gcloud asset search-all-resources \
    --scope=organizations/123456 \
    --query="state=RUNNING" \
    --asset-types=compute.googleapis.com/Instance \
    --read-mask="name,versionedResources"