# Terraform을 사용한 Google Cloud Storage (GCS) 로그 소스 관리 (Beta)

## 개요

{% hint style="info" %}
Terraform를 사용한 Google Cloud Storage(GCS) 로그 소스 관리는 Panther 버전 1.121부터 오픈 베타이며, 모든 고객에게 제공됩니다. 버그 보고와 기능 요청은 Panther 지원 팀에 공유해 주세요.
{% endhint %}

Panther를 사용하여 Terraform에서 Google Cloud Storage(GCS) 로그 소스를 정의할 수 있습니다. [Terraform provider](https://registry.terraform.io/providers/panther-labs/panther/latest)이렇게 하면 GCS 로그 소스를 코드형 인프라로 관리할 수 있어 버전 관리와 자동화된 배포가 가능해집니다.

GCS 로그 소스를 생성하는 다른 방법으로는 [Panther API](/ko/panther/api/rest/log-sources/gcs-sources.md) 직접적으로 사용하거나 [Panther Console에서 수동으로 생성하는 방법](/ko/data-onboarding/data-transports/google/cloud-storage.md).

## Terraform에서 Panther GCS 로그 소스를 정의하는 방법

다음 섹션에서는 HashiCorp Configuration Language(HCL)에서 GCS 로그 소스를 정의하는 방법을 설명합니다.

### 사전 요구 사항

* 시작하기 전에, 다음 권한이 있는 API URL과 토큰이 있는지 확인하세요: `Manage Log Sources` 권한. 이는 3단계를 완료하는 데 필요합니다.
  * 필요한 경우, 다음을 따르세요 [Panther Console에서 API 토큰을 생성하는 방법에 대한 이 지침](/ko/panther/api.md#how-to-create-a-panther-api-token).
* 다음을 따라 Google Cloud Platform(GCP) 인프라를 설정하세요. [GCS 소스 설정 가이드](/ko/data-onboarding/data-transports/google/cloud-storage.md#step-2-create-required-google-cloud-platform-gcp-infrastructure).

### 1단계: 인증 방법 선택

GCS 버킷에 접근할 인증 방법을 선택하세요:

* **서비스 계정**: JSON 키 파일을 사용하는 Google Cloud 서비스 계정
* **워크로드 아이덴티티 페더레이션**: AWS와 함께 Google Cloud Workload Identity Federation을 사용합니다.

선택한 인증 방법에 따라 아래 2단계에서 정의할 변수가 결정됩니다.

### 2단계: 변수 정의

다음을 정의하세요 `variables.tf` 아래 코드 블록에 표시된 변수로 파일을 만드세요.

```hcl
variable "panther_api_token" {
  description = "Panther API 토큰"
  type        = string
  sensitive   = true
}

variable "panther_api_url" {
  description = "Panther API URL"
  type        = string
}

variable "integration_label" {
  description = "GCS 로그 소스 통합의 이름"
  type        = string
}

variable "gcs_bucket" {
  description = "로그를 가져올 GCS 버킷의 이름"
  type        = string
}

variable "subscription_id" {
  description = "GCS 버킷 알림을 위한 Pub/Sub 구독 ID"
  type        = string
}

variable "credentials_type" {
  description = "자격 증명 유형(service_account 또는 wif)"
  type        = string
  validation {
    condition     = contains(["service_account", "wif"], var.credentials_type)
    error_message = "자격 증명 유형은 'service_account' 또는 'wif' 중 하나여야 합니다."
  }
}

// 인증 변수는 credentials_type에 따라 다릅니다. 아래 표를 참조하세요
variable "credentials" {
  description = "서비스 계정 JSON 키 또는 WIF 자격 증명 구성 파일 내용"
  type        = string
  sensitive   = true
}

variable "project_id" {
  description = "Google Cloud 프로젝트 ID(WIF에는 필요, 서비스 계정에는 선택 사항)"
  type        = string
  default     = ""
}

// (선택 사항) log_stream_type = "JsonArray"인 경우에만 관련 있음
variable "json_array_envelope_field" {
  description = "json array 스트림의 envelope 필드"
  type        = string
  default     = ""
}

// (선택 사항) log_stream_type = "XML"인 경우에만 관련됨
variable "xml_root_element" {
  description = "XML 로그 스트림의 루트 요소 이름"
  type        = string
  default     = ""
}
```

### 3단계: 정의한 변수에 대한 값 제공

다음을 추가하세요 `*.tfvars` 2단계에서 정의한 변수에 값을 할당하는 파일입니다. 이 섹션을 완료하려면 필수 구성 요소 섹션에 설명된 API URL과 토큰이 필요합니다.

* 당신의 `panther_api_url` 값은 루트 API URL이어야 합니다. 이는 다음 중 하나입니다:
  * 하나의 [GraphQL API URL](/ko/panther/api/graphql.md#step-1-identify-your-panther-graphql-api-url) 다음 없이 `/public/graphql` 접미사
  * 하나의 [REST API URL](/ko/panther/api/rest.md#step-1-identify-your-panther-rest-api-url) 원본 그대로 (REST URL에는 루트 URL 뒤에 접미사가 없습니다)

```hcl
panther_api_token         = "XXXXXXXXXX"
panther_api_url           = "https://your-panther-url/v1"
integration_label         = "my-gcs-logs"
gcs_bucket                = "my-log-bucket"
subscription_id           = "my-panther-subscription"
credentials_type          = "service_account" // service_account 또는 wif
credentials               = "{ ... }" // JSON 키 파일 또는 자격 증명 구성 내용
project_id                = "my-gcp-project" // WIF에는 필요, service_account에는 선택 사항
json_array_envelope_field = "" // 선택 사항, log_stream_type = "JsonArray"인 경우에만 관련됨
xml_root_element          = "" // 선택 사항, log_stream_type = "XML"인 경우에만 관련됨
```

#### **인증 방법별 변수**

다음의 `variables.tf` 파일에서, 1단계에서 선택한 인증 방법에 대한 아래 **추가 변수** 열의 값을 포함하세요.

해당 `credentials_type` 필드는 `credentials` 필드에 제공된 자격 증명 유형과 일치해야 합니다.

<table><thead><tr><th width="243">인증 방법</th><th width="204">credentials_type 값</th><th>추가 변수</th></tr></thead><tbody><tr><td>서비스 계정 인증</td><td><code>service_account</code></td><td><code>credentials</code> (JSON 키 파일 내용)</td></tr><tr><td>워크로드 아이덴티티 페더레이션 인증</td><td><code>wif</code></td><td><code>credentials</code> (자격 증명 구성 파일 내용), <code>project_id</code></td></tr></tbody></table>

### 4단계: Terraform provider 정의

다음을 추가하세요 [Panther](https://registry.terraform.io/providers/panther-labs/panther/latest) Terraform provider.

```hcl
terraform {
  required_providers {
    panther = {
      source  = "panther-labs/panther"
      version = "~> 0.2.10"
    }
  }
}
```

### 5단계: Panther GCS 로그 소스 정의

다음 HCL 구성은 Panther에서 GCS 로그 소스를 정의합니다.

```hcl
provider "panther" {
  token = var.panther_api_token
  url   = var.panther_api_url
}

resource "panther_gcssource" "demo_gcs_source" {
  integration_label = var.integration_label
  log_stream_type   = "JSON" // 옵션: Auto, JSON, JsonArray, Lines, XML
  gcs_bucket        = var.gcs_bucket
  subscription_id   = var.subscription_id
  credentials_type  = var.credentials_type
  credentials       = var.credentials
  project_id        = var.project_id // WIF에는 필요, service_account에는 선택 사항

  prefix_log_types = [{
    prefix            = "audit-logs/"
    excluded_prefixes = ["audit-logs/exclude/"]
    log_types         = ["GCP.AuditLog"]
  }, {
    prefix            = "cloudtrail/"
    excluded_prefixes = []
    log_types         = ["AWS.CloudTrail"]
  }]

  // (선택 사항) log_stream_type에 따라 구성
  log_stream_type_options = {
    json_array_envelope_field = var.json_array_envelope_field // "JsonArray"에 해당
    xml_root_element          = var.xml_root_element          // "XML"에 해당
  }
}
```

#### 접두사 기반 로그 유형 매핑

단순한 로그 유형 배열을 사용하는 HTTP 또는 S3 소스와 달리, GCS 소스는 `prefix_log_types` 를 사용하여 버킷 내의 서로 다른 접두사를 특정 로그 유형에 매핑합니다:

* **`prefix`**: 일치시킬 GCS 객체 접두사(예: "audit-logs/", "application-logs/")
* **`excluded_prefixes`**: 주요 접두사 내에서 제외할 접두사의 선택적 배열
* **`log_types`**: 이 접두사와 일치하는 객체에 적용할 로그 유형 스키마 배열

이렇게 하면 하나의 GCS 버킷에 접두사별로 구성된 여러 유형의 로그를 포함할 수 있으며, 각기 다른 스키마를 적용할 수 있습니다.

### 6단계: 중단 알러트 구성(선택 사항)

로그 소스가 데이터 수신을 중지할 때 알러트를 트리거하려면, 다음을 추가하세요 `panther_log_source_alarm` 위에서 생성한 GCS 소스를 가리키는 리소스:

```hcl
resource "panther_log_source_alarm" "demo_alarm" {
  source_id         = panther_gcssource.demo_gcs_source.id
  type              = "SOURCE_NO_DATA"
  minutes_threshold = 60
}
```

전체 인수 참조 및 import 구문은 다음을 참조하세요 [Terraform을 사용한 Log Source Alarm 관리](/ko/panther/terraform/log-source-alarms.md).

## 전체 예제

GCP 인프라 설정이 포함된 완전한 작동 예제를 보려면 다음을 참조하세요. [Panther 보조 저장소](https://github.com/panther-labs/panther-auxiliary/tree/main/terraform/panther_gcs_transport_type_infra).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.panther.com/ko/panther/terraform/gcs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.