> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasource-credentials/gcs.md).

# Google Cloud Storage 자격 증명

GCS 데이터 소스를 위한 Google Cloud 자격 증명을 안전하게 생성합니다.

Roboflow가 Google Cloud Storage 버킷을 다음을 통해 미러링하도록 하려면 이 페이지를 사용하세요 [데이터 소스](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md).

{% hint style="warning" %}
Google Cloud Storage의 경우, 지속적인 동기화, 반복 가져오기, 또는 메타데이터 사이드카 지원이 필요할 때는 언제나 Datasources와 Bucket Mirror를 사용하세요. 이 사용 사례에서는 서명된 URL이나 로컬 다운로드 워크플로를 만들지 마세요.
{% endhint %}

## 자격 증명 유형 선택

Roboflow는 GCS Datasources에 대해 세 가지 Google Cloud 액세스 패턴을 지원합니다:

1. [**가장**](#use-service-account-impersonation): 권장: 키 없음, Roboflow가 단기 토큰을 사용
2. [**직접 부여**](#use-a-direct-bucket-grant): 버킷에 대해 Roboflow의 서비스 계정에 읽기 권한을 직접 부여합니다
3. [**JSON 키**](#use-a-service-account-json-key): 레거시: 내보낸 서비스 계정 키로, 하위 호환성을 위해 유지됩니다

[가장](#use-service-account-impersonation) 및 [직접 부여](#use-a-direct-bucket-grant) 은 키가 없습니다: 비밀은 절대 Google Cloud 프로젝트를 벗어나지 않습니다. Google [는 내보낼 수 있는 키를 권장하지 않습니다](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys) (그리고 많은 조직은 정책으로 이를 차단합니다), 따라서 키 없는 옵션을 선호하세요.

### 보안 지침

자격 증명을 만들기 전에:

1. Roboflow 전용 서비스 계정을 사용하세요.
2. 다음만 부여하세요 **Storage Object Viewer** (`roles/storage.objectViewer`), 특정 버킷에만 범위를 지정합니다.
3. 를 선호하세요 [가장](#use-service-account-impersonation) 또는 [직접 부여](#use-a-direct-bucket-grant) 다음을 통해 [내보낸 JSON 키](#use-a-service-account-json-key).
4. 자격 증명은 Roboflow Workspace [자격 증명](https://app.roboflow.com/settings/thirdpartykeys) 또는 자체 비밀 관리자를 사용합니다.
5. IAM 권한 부여를 제거하여 언제든지 Roboflow의 액세스를 취소할 수 있습니다.

두 키 없는 모드는 다음을 사용해 권한을 워크스페이스에 연결합니다: **워크스페이스 토큰** 은 자격 증명 생성 모달에 표시됩니다( Google Cloud에는 AWS 스타일의 External ID가 없습니다). 토큰을 생성 중인 자격 증명과 함께 보관하세요.

### 서비스 계정 가장 사용

**권장됩니다. 키는 교환되지 않습니다.** Roboflow는 [서비스 계정 가장](https://cloud.google.com/iam/docs/service-account-impersonation) 을 사용하여 단기 토큰으로 버킷을 읽습니다.

1. Roboflow에서 [Google Cloud(가장) 자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create/gcsImpersonation). 모달에는 다음이 표시됩니다 **필수 서비스 계정 이름** (`rf-datasource-<token>`) 및 **Roboflow 서비스 계정**. 닫지 말고 열어 두세요. 두 값이 모두 필요합니다.
2. 해당 정확한 이름으로 프로젝트에 서비스 계정을 만드세요(이 이름에는 워크스페이스 토큰이 포함되며, 이 토큰이 권한을 워크스페이스에 연결합니다):

   * 여세요 [서비스 계정 콘솔](https://console.cloud.google.com/iam-admin/serviceaccounts/create).
   * 다음을 설정하세요 **서비스 계정 ID** (다음 앞부분 `@`)을 모달에 표시된 값과 정확히 일치하도록 설정한 다음 `rf-datasource-<token>` 모달에서 **만들기 및 계속** → **완료**.

   CLI를 선호하시나요?

   ```sh
   gcloud iam service-accounts create rf-datasource-<token> --project YOUR_PROJECT
   ```
3. 부여하세요 **해당 새 서비스 계정에** 버킷에 대한 읽기 액세스 권한을:

   * 여세요 [Cloud Storage 브라우저](https://console.cloud.google.com/storage/browser) → 버킷 → **권한** → **액세스 권한 부여**.
   * 새 주체 = `rf-datasource-<token>@…` 서비스 계정, 역할 = **Storage Object Viewer** → **저장**.

   CLI를 선호하시나요?

   ```sh
   gsutil iam ch "serviceAccount:rf-datasource-<token>@YOUR_PROJECT.iam.gserviceaccount.com:roles/storage.objectViewer" gs://YOUR_BUCKET
   ```
4. 다음 권한을 부여하세요 **Roboflow 서비스 계정** 해당 **서비스 계정 토큰 생성자** 역할 **방금 만든 서비스 계정에**. 이 권한이 있어야 Roboflow가 이를 가장할 수 있습니다:

   * 다음에서 [서비스 계정](https://console.cloud.google.com/iam-admin/serviceaccounts), 해당 `rf-datasource-<token>` 서비스 계정 → **권한** 탭 → **액세스 권한 부여**.
   * 새 주체 = 모달에 표시된 Roboflow 서비스 계정, 역할 = **서비스 계정 토큰 생성자** → **저장**.

   CLI를 선호하시나요?

   ```sh
   gcloud iam service-accounts add-iam-policy-binding rf-datasource-<token>@YOUR_PROJECT.iam.gserviceaccount.com \\
     --member="serviceAccount:ROBOFLOW_SERVICE_ACCOUNT" \\
     --role="roles/iam.serviceAccountTokenCreator" --project YOUR_PROJECT
   ```
5. 모달로 돌아가 서비스 계정 이메일을 입력하고 저장하세요. 다음을 계속 진행하세요 [Roboflow에서 자격 증명 만들기](#create-the-credential-in-roboflow).

워크스페이스 토큰은 워크스페이스와 자격 증명 유형에 연결되어 있으므로, 모달을 다시 열어도 동일한 필수 서비스 계정 이름이 표시됩니다.

### 직접 버킷 권한 부여 사용

**키는 교환되지 않습니다.** 버킷에 Roboflow의 서비스 계정에 대한 읽기 액세스 권한을 직접 부여한 다음, 마커 객체로 해당 버킷이 워크스페이스에 속함을 증명합니다.

1. Roboflow에서 [Google Cloud(직접 부여) 자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create/gcsDirectAccess). 모달에는 다음이 표시됩니다 **Roboflow 서비스 계정** 및 귀하의 **워크스페이스 토큰**.
2. Roboflow 서비스 계정에 버킷에 대한 읽기 액세스 권한을 부여하세요:

   * 여세요 [Cloud Storage 브라우저](https://console.cloud.google.com/storage/browser) → 버킷 → **권한** → **액세스 권한 부여**.
   * 새 주체 = 모달의 Roboflow 서비스 계정, 역할 = **Storage Object Viewer** → **저장**.

   CLI를 선호하시나요?

   ```sh
   gsutil iam ch "serviceAccount:ROBOFLOW_SERVICE_ACCOUNT:roles/storage.objectViewer" gs://YOUR_BUCKET
   ```
3. 다음에 마커 객체를 업로드하세요 **`.roboflow/workspace-token`** 그 내용에 워크스페이스 토큰이 포함되어야 합니다(이는 버킷을 워크스페이스에 연결합니다):

   * 다음에서 [Cloud Storage 브라우저](https://console.cloud.google.com/storage/browser), 버킷을 열고 **폴더 만들기** `.roboflow`, 그런 다음 **업로드** 이름이 다음인 작은 파일 `workspace-token` 그 내용이 토큰인 파일.

   CLI를 선호하시나요?

   ```sh
   printf 'YOUR_WORKSPACE_TOKEN' | gsutil cp - gs://YOUR_BUCKET/.roboflow/workspace-token
   ```
4. Roboflow에 자격 증명을 저장한 다음 [Roboflow에서 자격 증명 만들기](#create-the-credential-in-roboflow).

Roboflow는 다음을 읽습니다 `.roboflow/workspace-token` Datasource 검증 중 마커를 읽으며, 없으면 실패합니다.

### 서비스 계정 JSON 키 사용

**레거시입니다. 키 없는 옵션이 불가능할 때만 사용하세요.** Google [는 내보낼 수 있는 키를 권장하지 않습니다](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys), 그리고 많은 조직이 정책으로 그 생성을 차단합니다. 키 없는 [가장](#use-service-account-impersonation) 또는 [직접 부여](#use-a-direct-bucket-grant) 옵션을 선호하세요.

1. 전용 서비스 계정을 만들고 다음 권한을 부여하세요 **Storage Object Viewer** 버킷에 대해 (다음의 2\~3단계와 동일 [가장](#use-service-account-impersonation)이지만, 이름은 무엇이든 가능합니다).
2. JSON 키를 만드세요:

   * 다음에서 [서비스 계정](https://console.cloud.google.com/iam-admin/serviceaccounts), 서비스 계정 → **키** 탭 → **키 추가** → **새 키 만들기** → **JSON** → **만들기**. 브라우저가 키 파일을 다운로드합니다.
   * 만약 **새 키 만들기** 가 비활성화되어 있으면, 조직 정책이 키 내보내기를 차단하고 있는 것입니다.  [가장](#use-service-account-impersonation) 또는 [직접 부여](#use-a-direct-bucket-grant) 를 대신 사용하세요.

   CLI를 선호하시나요?

   ```sh
   gcloud iam service-accounts keys create key.json --iam-account SA_EMAIL
   ```
3. Roboflow에서 [Google Cloud Storage(JSON 키) 자격 증명 추가](https://app.roboflow.com/settings/thirdpartykeys#create/gcs), 프로젝트 ID를 입력하고 JSON 키를 붙여넣은 다음 저장하세요.

## Roboflow에서 자격 증명 만들기

Google Cloud 측 액세스를 설정한 후:

1. 로 이동하세요 [자격 증명](https://app.roboflow.com/settings/thirdpartykeys#create) 워크스페이스 설정에서.
2. 클릭하세요 **자격 증명 추가** (또는 유형별 링크를 사용하세요: [가장](https://app.roboflow.com/settings/thirdpartykeys#create/gcsImpersonation), [직접 부여](https://app.roboflow.com/settings/thirdpartykeys#create/gcsDirectAccess), [JSON 키](https://app.roboflow.com/settings/thirdpartykeys#create/gcs)).
3. 설정한 Google Cloud Storage 자격 증명 유형을 선택하세요.
4. 서비스 계정 이메일을 입력하고([가장](#use-service-account-impersonation)), 워크스페이스 토큰 마커([직접 부여](#use-a-direct-bucket-grant)), 또는 프로젝트 ID + JSON 키([JSON 키](#use-a-service-account-json-key)).
5. 자격 증명을 저장하세요.
6. 다음을 만들 때 해당 자격 증명을 선택하세요 [데이터 소스](https://app.roboflow.com/settings/datasources#create).

## 다음 단계

자격 증명이 저장되면 다음으로 진행하세요 [데이터 소스](https://docs.roboflow.com/datasets/ko/create-and-upload/adding-data/datasources.md) 버킷 미러링을 구성하려면
