> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Pub/Sub IAM 권한

> 이 문서에서는 ClickPipes가 Google Cloud Pub/Sub에 인증하고 토픽에서 데이터를 수집하는 데 필요한 GCP IAM 권한을 설명합니다.

<Note>
  [여기](https://clickhouse.com/cloud/clickpipes#pubsub-private-preview)에서 비공개 프리뷰 대기자 명단에 등록할 수 있습니다.
</Note>

이 문서에서는 ClickPipes가 Google Cloud Pub/Sub에 인증하고 토픽에서 데이터를 수집하는 데 필요한 GCP IAM 권한과, 정확히 해당 권한만 부여하도록 서비스 계정을 설정하는 방법을 설명합니다.

<div id="prerequisite">
  ## 사전 요구 사항
</div>

이 가이드를 따르려면 다음이 필요합니다.

* 활성 상태의 ClickHouse Cloud 서비스
* 수집할 Pub/Sub 토픽이 포함된 GCP 프로젝트
* 해당 프로젝트에서 서비스 계정을 생성하고 역할을 부여할 수 있는 IAM 권한

<div id="authentication-model">
  ## 인증 모델
</div>

Pub/Sub용 ClickPipes는 [서비스 계정 JSON 키](https://cloud.google.com/iam/docs/keys-create-delete)를 사용해 GCP에 인증합니다. 파이프를 생성할 때 키 파일을 업로드하면, ClickPipes는 이를 저장 중 암호화하며 런타임에 다음 작업에 사용합니다.

* 프로젝트의 토픽을 나열하고 읽습니다.
* 메시지를 소비하기 위해 ClickPipes가 사용하는 [관리형 구독](/ko/integrations/clickpipes/pubsub/overview#managed-subscriptions)을 생성하고 삭제합니다.
* 해당 subscription에서 메시지를 소비합니다.
* (선택 사항) 스키마 레지스트리에서 네이티브 Pub/Sub 스키마를 읽습니다.

현재 Workload Identity 또는 인라인 자격 증명 붙여넣기 옵션은 지원되지 않으며, 서비스 계정 JSON 키가 현재 지원되는 유일한 인증 메서드입니다.

<div id="required-permissions">
  ## 필수 권한
</div>

ClickPipes를 사용하려면 토픽을 소유한 GCP 프로젝트에 다음 IAM 권한이 필요합니다. 이러한 권한은 검색(토픽 목록 조회, 검증, 샘플링), subscription 관리, 지속적인 수집, 정리까지 파이프의 전체 수명 주기를 포괄합니다.

<div id="topic-access">
  ### 토픽 액세스(검색 및 유효성 검사)
</div>

| Permission                         | Purpose                                 |
| ---------------------------------- | --------------------------------------- |
| `pubsub.topics.list`               | 검색 과정에서 프로젝트의 사용 가능한 토픽 목록을 확인합니다       |
| `pubsub.topics.get`                | 토픽이 존재하는지 확인하고 스키마 설정을 가져옵니다            |
| `pubsub.topics.attachSubscription` | 해당 **토픽**에 대한 subscription을 생성할 때 필요합니다 |

<div id="subscription-lifecycle">
  ### subscription 수명 주기(검색 및 수집)
</div>

| Permission                     | Purpose                                                         |
| ------------------------------ | --------------------------------------------------------------- |
| `pubsub.subscriptions.create`  | 관리형 subscription(`clickpipes-{pipeID}`) 및 임시 검색 subscription 생성 |
| `pubsub.subscriptions.get`     | 상태 점검(60초마다), 팔로워 폴링, subscription 유효성 검사                       |
| `pubsub.subscriptions.delete`  | 임시 검색 subscription 정리 및 파이프 삭제 시 관리형 subscription 삭제            |
| `pubsub.subscriptions.consume` | `Receive()`, `Ack()`, `Nack()`, 및 timestamp 기준 seek 작업          |

<div id="schema-access">
  ### 스키마 액세스(선택 사항 — 네이티브 Avro/Protobuf 토픽에만 해당)
</div>

| Permission           | Purpose                                |
| -------------------- | -------------------------------------- |
| `pubsub.schemas.get` | Pub/Sub 스키마 레지스트리에서 네이티브 스키마 정의를 조회합니다 |

<div id="predefined-roles">
  ## 사전 정의된 역할
</div>

| 역할                                                                                                   | 충분한가?   | 비고                                                                                                                  |
| ---------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| [`roles/pubsub.editor`](https://cloud.google.com/iam/docs/understanding-roles#pubsub.editor)         | 예       | 필요한 모든 권한을 포함합니다. 가장 포괄적인 옵션입니다.                                                                                    |
| [`roles/pubsub.subscriber`](https://cloud.google.com/iam/docs/understanding-roles#pubsub.subscriber) | **아니요** | `topics.list`, `topics.attachSubscription`, `subscriptions.create`, `subscriptions.delete`, `schemas.get` 권한이 없습니다. |
| [`roles/pubsub.viewer`](https://cloud.google.com/iam/docs/understanding-roles#pubsub.viewer)         | **아니요** | 읽기 전용 — subscription 관리나 활용은 할 수 없습니다.                                                                              |
| 사용자 지정 역할 *(권장)*                                                                                     | 예       | 최소 권한 원칙에 따라 위의 7가지 핵심 권한을 사용하십시오(`schemas.get`는 선택 사항).                                                            |

<div id="setup">
  ## 설정
</div>

<div id="create-custom-role">
  ### 사용자 지정 역할 생성(권장)
</div>

최소 권한 원칙에 따라 ClickPipes에 정확히 필요한 권한만 포함된 사용자 지정 역할을 생성하십시오.

다음과 같이 `gcloud` CLI를 사용해 수행할 수 있습니다:

```bash theme={null}
gcloud iam roles create clickpipes.pubsub.ingestion \
  --project=YOUR_PROJECT_ID \
  --title="ClickPipes Pub/Sub Ingestion" \
  --description="Permissions required by ClickHouse ClickPipes to ingest from Pub/Sub" \
  --permissions=pubsub.topics.list,pubsub.topics.get,pubsub.topics.attachSubscription,pubsub.subscriptions.create,pubsub.subscriptions.get,pubsub.subscriptions.delete,pubsub.subscriptions.consume \
  --stage=GA
```

또는 GCP Console에서 **IAM & Admin → Roles → Create role**로 이동한 뒤, [필요한 권한](#required-permissions)에 나열된 권한을 추가하세요.

<Info>
  **선택적 권한**

  네이티브 Pub/Sub Avro 또는 Protobuf 스키마를 사용하는 토픽에서 수집하는 경우 `--permissions` 목록에 `pubsub.schemas.get`을 추가하세요. 그렇지 않은 경우 역할을 최소 권한으로 유지할 수 있도록 추가하지 마세요.
</Info>

사용자 지정 역할을 생략하려는 경우에는 대신 `roles/pubsub.editor`를 부여할 수 있습니다.

<div id="create-service-account">
  ### 서비스 계정 생성
</div>

ClickPipe 전용 서비스 계정을 생성합니다:

```bash theme={null}
gcloud iam service-accounts create clickpipes-pubsub \
  --project=YOUR_PROJECT_ID \
  --display-name="ClickPipes Pub/Sub Ingestion"
```

<div id="grant-role">
  ### 서비스 계정에 역할 부여
</div>

프로젝트 수준에서 생성한 역할(또는 `roles/pubsub.editor`)을 서비스 계정에 바인딩하세요:

```bash theme={null}
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="projects/YOUR_PROJECT_ID/roles/clickpipes.pubsub.ingestion"
```

<div id="create-key">
  ### 서비스 계정 키 생성 및 다운로드
</div>

서비스 계정용 JSON 키를 생성한 다음 로컬로 다운로드합니다:

```bash theme={null}
gcloud iam service-accounts keys create clickpipes-pubsub-key.json \
  --iam-account=clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com
```

파이프를 생성할 때 이 `clickpipes-pubsub-key.json` 파일을 ClickPipes UI에 업로드하세요.

<Info>
  **키를 민감 정보로 취급하십시오**

  서비스 계정 키는 GCP 프로젝트에 대한 액세스 권한을 부여합니다. 이 파일은 안전하게 보관하고, 버전 관리 시스템에 커밋하지 말고, 정기적으로 교체하십시오. ClickPipes는 업로드 후 키를 저장 시 암호화합니다.
</Info>

<div id="notes">
  ## 참고 사항
</div>

* `pubsub.topics.attachSubscription` 권한은 subscription이 아니라 **토픽 리소스**에 필요합니다. subscription 수준의 권한만 부여할 때 이 점을 흔히 놓칩니다.
* 토픽이 네이티브 Pub/Sub 스키마(schema)(Avro 또는 Protobuf)를 사용하지 않는다면 `pubsub.schemas.get` 권한은 필요하지 않습니다.
* 관리형 구독의 이름은 `clickpipes-{pipeID}`이며, ack deadline은 60초, 메시지 보존 기간은 7일이고, 메시지 순서 지정이 활성화됩니다.
* 임시 검색 subscription의 이름은 `clickpipes-discovery-{uuid}`이며, ack deadline은 10초, 보존 기간은 10분이고, 24시간 후 자동 만료되는 TTL이 적용됩니다.
* ClickPipes는 `PermissionDenied` 및 `Unauthenticated` 오류를 재시도 불가로 처리합니다. 권한이 누락되면 파이프는 무기한 재시도하지 않고 즉시 실패합니다.