> 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 버킷을 미러링하도록 하려는 경우 이 페이지를 사용하세요 [데이터 소스](/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. 다음만 부여하세요 **저장소 객체 뷰어** (`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>@…` 서비스 계정, 역할 = **저장소 객체 뷰어** → **저장**.

   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 서비스 계정, 역할 = **저장소 객체 뷰어** → **저장**.

   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` 데이터 소스 검증 중 마커를 읽으며, 없으면 실패합니다.

### 서비스 계정 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. 전용 서비스 계정을 만들고 그 계정에 권한을 부여하세요 **저장소 객체 뷰어** 버킷에서(다음의 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) Workspace 설정의
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).

## 다음 단계

자격 증명이 저장된 후, 다음을 계속하세요: [데이터 소스](/datasets/ko/create-and-upload/adding-data/datasources.md) 버킷 미러링을 구성합니다.