---
title: "Google Cloud Service Extensions 연동 가이드"
description: "본 문서에서는 Google Cloud Service Extensions와 Cloud CDN을 사용하여 도브러너의 CDN 임베더를 구성하고 배포하는 방법을 설명합니다."
---
> For the complete documentation index, see [llms.txt](https://docs.doverunner.com/llms.txt).

CDN 임베더는 Google Cloud Service Extensions를 활용하여 Cloud CDN을 통해 포렌식 워터마크가 적용된 콘텐츠를 제공합니다. 
이 가이드는 도브러너 포렌식 워터마킹 구현을 위한 임베더 구성 및 배포 과정을 안내합니다.

샘플 코드는 GitHub에서 확인할 수 있습니다.
[Google Cloud Embedder 샘플](https://github.com/doverunner/fwm-cdn-embedder-gcp-service-extensions)

임베더는 Go로 작성된 Proxy-Wasm 플러그인입니다. Global external Application Load Balancer에 edge extension으로 연결되며, Cloud CDN 캐시를 조회하기 전에 실행됩니다. 임베더는 콘텐츠를 저장하거나 제공하지 않으며, 재작성된 경로의 파일은 Cloud CDN이 origin에서 가져옵니다.

:::caution[AES 토큰 사용 권장]
이 가이드는 AES 워터마크 토큰만 다룹니다. 세션 URL은 `wmt_type: aes`(기본값)로 요청하세요. 이 임베더에서는 JWT 토큰(`wmt_type: jwt`)을 권장하지 않습니다. JWT 토큰의 RS256 서명 검증은 Service Extensions 플러그인의 [실행 시간 한도](https://docs.cloud.google.com/service-extensions/docs/quotas?hl=ko)(요청당 1ms)를 넘을 수 있으며, 한도를 넘은 플러그인은 종료되고 해당 요청에는 `500`이 반환됩니다.
:::

```mermaid
sequenceDiagram
    box 최종 사용자
    participant A as 최종 사용자
    end
    box 콘텐츠 서비스
    participant W as 서비스 사이트
    end
    box 도브러너
    participant S as Doverunner Session Manager
    end
    box 콘텐츠 서비스
    participant B as Load balancer (edge extension)
    participant C as Cloud CDN
    participant D as Origin
    end
    A ->> W: 재생 요청
    W ->> S: 세션 URL API 요청 (콘텐츠 경로, 세션 데이터)
    S ->> W: 워터마크 토큰이 담긴 세션 URL
    W ->> A: 세션 URL 전달
    A ->> B: 세션 URL 재생 시작 (세그먼트 요청)
    Note right of B: Doverunner CDN-Embedder
    B -->> B: 토큰 검증 후 0/1 세그먼트 경로로 재작성
    alt 토큰 거부
        B ->> A: 403
    else 토큰 유효
        B ->> C: 재작성된 경로 요청
        opt Cache miss
            C ->> D: 세그먼트 요청
            D ->> C: 세그먼트 반환
        end
        C ->> A: 조합된 세그먼트 전달
    end
    Note right of A: 조합된 콘텐츠 재생
```

CDN 임베더의 역할은 다음과 같습니다:
- **세션 관리자**가 발급한 워터마크 토큰 검증  
- 올바른 **워터마크 파일 경로** 확인 (사용자/세션/변형 기반)  
- Cloud CDN이 확인된 파일을 제공하도록 요청 경로를 재작성하고, 토큰이 거부되면 `403` 응답  

주요 구성은 다음을 통해 수행됩니다:
- `config.json` – 워터마크 토큰 및 폴더 구조 구성. 플러그인 구성으로 플러그인에 전달됨  
- `edge-extension.yaml` – 플러그인을 load balancer에 연결하는 edge extension  

## 구성

#### 플러그인 구성 (`config.json`)

플러그인은 플러그인 버전을 만들 때 전달한 플러그인 구성에서 설정을 읽습니다. 모듈에 설정이 컴파일되어 들어가지 않으므로, 한 번 빌드한 모듈을 모든 배포에 사용할 수 있습니다. 배포에 맞는 값으로 `config.json` 파일을 업데이트하세요:

```json
{
  "aesKey": "YOUR_DOVERUNER_SITE_KEY",
  "type": "unlabeled_a_variant",
  "availableInterval": 60,
  "prefixFolder": ["wm-contents"],
  "wmtPublicKey": "YOUR_PUBLIC_KEY",
  "wmtPassword": "YOUR_PASSWORD"
}
```

`wmtPublicKey`와 `wmtPassword`는 이 가이드에서 다루지 않는 JWT 토큰에서만 사용합니다. 값을 바꾸지 말고 그대로 두세요.

:::caution
`config.json`에는 비밀 값이 들어 있습니다. 사이트 키가 있으면 누구나 유효한 워터마크 토큰을 만들 수 있으므로, 값을 채운 파일을 저장소에 커밋하지 마세요. 플러그인 버전마다 구성이 저장되므로 프로젝트에서 플러그인을 조회할 수 있는 사용자를 제한하세요.
:::

#### 구성 매개변수

| 매개변수                | 설명                                                                                              |
|---------------------|-------------------------------------------------------------------------------------------------|
| `aesKey`            | 도브러너 콘텐츠 보안 서비스에서 발급한 사이트 키                                                                     |
| `type`              | 워터마크 파일의 폴더 구조. `unlabeled_a_variant` 또는 `directory_prefix`. [워터마크 파일 폴더 구조](#워터마크-파일-폴더-구조) 참고 |
| `availableInterval` | 토큰 유효 기간(분 단위, 무제한 유효성을 위해 `0`으로 설정)                                                            |
| `prefixFolder`      | 워터마크된 파일이 포함된 최상위 폴더 배열. 워터마크 토큰 요청 사양의 `prefix_folder`에 해당                                     |
| ~~`wmtPublicKey`~~  | ~~JWT 토큰용 PEM 형식 공개 키~~. 이 가이드에서는 사용하지 않음                                                       |
| ~~`wmtPassword`~~   | ~~JWT 토큰에 담긴 워터마크 패턴을 복호화하는 비밀번호~~. 이 가이드에서는 사용하지 않음                                          |

## 워터마크 파일 폴더 구조

`prefixFolder` 구성 매개변수에 지정된 폴더 구조에 따라 origin에 워터마크가 적용된 콘텐츠를 구성하세요. 최상위 폴더는 워터마크 토큰 요청 사양에 정의된 `prefix_folder` 값과 일치해야 합니다.

`type`은 origin에 A/B 버전이 저장된 방식에 맞춰 설정합니다:

- `unlabeled_a_variant`: A/B 버전 세그먼트가 한 폴더에 함께 저장되고, B 버전 파일에는 `b.` 접두사가 붙습니다.
- `directory_prefix`: A/B 버전이 `0`, `1` 폴더에 나뉘어 저장됩니다. T&P 서비스로 전처리한 콘텐츠는 이 구조로 저장됩니다.

## 임베더의 요청 처리 방식

플러그인은 edge extension의 일치 조건에 맞는 모든 요청의 요청 헤더를 처리합니다:

1. 경로의 첫 번째 세그먼트가 `prefixFolder` 항목 중 하나이면 토큰을 복호화하고, 제공할 변형 파일의 경로로 재작성합니다.
2. 그 밖의 경로는 바꾸지 않고 그대로 통과시킵니다.

edge extension은 URL map과 Cloud CDN 캐시 조회보다 먼저 실행되므로, 플러그인이 재작성한 경로로 Cloud CDN이 캐시를 조회하고 origin에서 파일을 가져옵니다. 재작성된 경로에는 토큰이 없으므로, 같은 세그먼트의 같은 변형을 받는 시청자는 캐시 항목 하나를 함께 사용합니다. 토큰은 요청마다 검증하므로, 세그먼트가 캐시되어 있어도 만료된 토큰은 거부됩니다.

거부된 요청에는 플러그인이 `403`으로 응답하며, 이 요청은 Cloud CDN이나 origin에 도달하지 않습니다. 응답 본문에는 `Invalid watermark token`처럼 짧은 사유가 들어갑니다.

:::caution
무엇을 보호할지는 일치 조건이 정합니다. 일치 조건에 포함되지 않는 요청은 플러그인을 거치지 않고 Cloud CDN으로 전달되어 그대로 제공됩니다. 시청자가 load balancer를 거치지 않고 origin에 직접 접근하지 못하게 하세요. 이런 요청도 플러그인을 거치지 않습니다.
:::

## 배포

### 사전 요구사항

배포를 진행하기 전에 다음 사항을 확인하세요:

- Network Services API와 Artifact Registry API가 사용 설정된 Google Cloud 프로젝트
- Global external Application Load Balancer(load balancing scheme `EXTERNAL_MANAGED`). Classic Application Load Balancer는 extension을 지원하지 않습니다.
- 워터마크된 콘텐츠를 저장한 origin. Cloud CDN을 사용 설정한 백엔드 버킷 또는 백엔드 서비스로 load balancer에 연결되어 있어야 합니다. [Cloud CDN 설정](https://docs.cloud.google.com/cdn/docs/using-cdn?hl=ko)을 참고하세요.
- `us` multi-region 위치의 Artifact Registry Docker 저장소. global load balancer에서 사용하는 플러그인은 이 위치에 저장해야 합니다. 저장소가 다른 프로젝트에 있다면 [플러그인 만들기](https://docs.cloud.google.com/service-extensions/docs/create-plugin?hl=ko)에 따라 Service Extensions service agent에 저장소 접근 권한을 부여하세요.
- gcloud CLI와 Docker
- 플러그인을 직접 빌드하는 경우 Go 1.24 이상과 binaryen(`wasm-opt`). GitHub 릴리스의 미리 빌드된 플러그인을 배포한다면 필요하지 않습니다.

API를 사용 설정합니다:

```bash
gcloud services enable networkservices.googleapis.com artifactregistry.googleapis.com
```

### 1단계: 플러그인 빌드 또는 다운로드

샘플 디렉터리에서 플러그인을 빌드합니다:

```bash
./packaging/build.sh
```

이 스크립트는 `GOOS=wasip1 GOARCH=wasm`, `-buildmode=c-shared`로 모듈을 컴파일하고 `wasm-opt`로 최적화한 뒤 `dist/plugin.wasm`에 저장합니다. 모듈과 `config.json`을 합친 크기가 플러그인 크기 한도인 5MiB를 넘으면 실패합니다.

각 [GitHub 릴리스](https://github.com/doverunner/fwm-cdn-embedder-gcp-service-extensions/releases/latest)에는 미리 빌드된 `plugin.wasm`과 `config.json`, `Dockerfile`, `LICENSE`가 담긴 `doverunner_fwm_embedder_gcp.<version>.zip`도 첨부되어 있습니다. 이 파일을 사용하는 경우에는 압축을 푼 폴더에서 2단계와 3단계를 진행하세요.

### 2단계: Artifact Registry에 플러그인 푸시

`packaging/Dockerfile`은 모듈을 컨테이너 이미지로 패키징합니다(`FROM scratch`, `COPY plugin.wasm plugin.wasm`). 저장소가 아직 없다면 먼저 만듭니다:

```bash
gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=us
```

이미지를 빌드하고 푸시합니다:

```bash
gcloud auth configure-docker us-docker.pkg.dev
docker build --no-cache --platform wasm -f packaging/Dockerfile -t fwm-embedder dist/
docker tag fwm-embedder us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0
docker push us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0
```

압축을 푼 릴리스 폴더에서는 `docker build --no-cache --platform wasm -t fwm-embedder .`로 이미지를 빌드합니다.

### 3단계: 플러그인 생성

`config.json`을 플러그인 구성으로 지정해 플러그인을 만듭니다:

```bash
gcloud service-extensions wasm-plugins create fwm-embedder \
    --location=global \
    --image=us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0 \
    --main-version=v3-0-0 \
    --plugin-config-file=config.json \
    --log-config=enable=true,sample-rate=1,min-log-level=INFO
```

### 4단계: Edge extension으로 플러그인 연결

다음 내용을 `edge-extension.yaml`로 저장합니다:

```yaml
name: fwm-embedder
forwardingRules:
- https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules/HTTPS_FORWARDING_RULE
- https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/forwardingRules/HTTP_FORWARDING_RULE
loadBalancingScheme: EXTERNAL_MANAGED
extensionChains:
- name: watermark
  matchCondition:
    celExpression: 'request.path.startsWith("/wm-contents/")'
  extensions:
  - name: fwm-embedder
    service: projects/PROJECT_ID/locations/global/wasmPlugins/fwm-embedder
    failOpen: false
    supportedEvents:
    - REQUEST_HEADERS
```

- `celExpression`: `config.json`의 `prefixFolder` 항목**마다** `request.path.startsWith("/<folder>/")` 조건을 하나씩 작성하고 `||`로 연결합니다. 식은 최대 500자까지 작성할 수 있습니다.
- `forwardingRules`: URL map이 워터마크된 콘텐츠의 origin으로 이어지는 전달 규칙을 모두 나열합니다. 보통 HTTPS 규칙이며, HTTP 규칙이 HTTPS로 redirect만 하는 것이 아니라면 HTTP 규칙도 포함합니다. 나열하지 않은 전달 규칙으로 들어온 요청은 플러그인을 거치지 않습니다. 전달 규칙 하나에는 edge extension을 하나만 연결할 수 있습니다. 전달 규칙의 참조 값은 `gcloud compute forwarding-rules describe FORWARDING_RULE --global --format='value(selfLink)'`로 확인합니다.
- `failOpen`: `false`(기본값)이면 플러그인이 실패했을 때 플러그인 없이 처리를 이어가지 않고 load balancer가 오류를 반환합니다.

edge extension을 가져옵니다:

```bash
gcloud service-extensions lb-edge-extensions import fwm-embedder \
    --source=edge-extension.yaml \
    --location=global
```

플러그인이 모든 위치에 배포되기까지 몇 분 걸립니다. 그 후 [세션 URL API](https://docs.doverunner.com/ko/content-security/forensic-watermarking/embedding/session-manager/#%EC%84%B8%EC%85%98-url-api)에 `domain`을 load balancer의 도메인으로, `prefix_folder`를 `prefixFolder` 항목 중 하나로 지정해 세션 URL을 발급받고, load balancer를 통해 재생하면서 같은 변형을 다시 요청했을 때 캐시에서 제공되는지 확인합니다. 응답에 `Age` 헤더가 있고, load balancer 요청 로그(`resource.type="http_load_balancer"`)에 `httpRequest.cacheHit: true`가 표시되면 됩니다.

### 플러그인 업데이트 및 롤백

새 빌드나 변경한 `config.json`을 배포하려면 새 플러그인 버전을 만듭니다. `--image`, 새 `--main-version`, 구성 파일을 함께 지정합니다. 구성만 바뀐 경우에는 같은 이미지 태그를 지정해도 됩니다. `--plugin-config-file`은 `--image`와 함께 지정할 때만 사용할 수 있습니다:

```bash
gcloud service-extensions wasm-plugins update fwm-embedder \
    --location=global \
    --image=us-docker.pkg.dev/PROJECT_ID/REPOSITORY/fwm-embedder:3.0.0 \
    --main-version=v3-0-0-r2 \
    --plugin-config-file=config.json
```

롤백하려면 `--image` 없이 기존 버전을 기본 버전으로 지정합니다:

```bash
gcloud service-extensions wasm-plugins update fwm-embedder \
    --location=global \
    --main-version=v3-0-0
```

플러그인 하나에는 버전을 최대 100개까지 만들 수 있습니다. 오래된 버전은 `gcloud service-extensions wasm-plugin-versions delete VERSION --wasm-plugin=fwm-embedder --location=global`로 삭제합니다.

## 문제 해결

| 응답 | 원인 | 조치 |
|:---|:---|:---|
| `403` `Invalid watermark token` | 토큰을 복호화하지 못했습니다. 보통 `aesKey`가 토큰을 발급한 사이트의 사이트 키와 다를 때 발생합니다. | `aesKey`를 확인하고 새 플러그인 버전을 만듭니다. |
| `403` `The watermark token usage period has expired` | 토큰이 발급된 지 `availableInterval`분이 지났습니다. | 세션 URL을 새로 요청하거나 `availableInterval`을 조정합니다. |
| `403` `Unsafe file path request detected.` | 세션 URL에서 변형 파일(예: `b.` 파일)을 직접 지정했습니다. | 정상 동작입니다. 세션 URL 매니페스트에 있는 경로로 재생하세요. |
| 세그먼트 요청이 실패하고, 플러그인 로그의 재작성 경로가 origin에 없음 | 보통 `type` 값이 폴더 구조와 맞지 않을 때 발생합니다. | 폴더 구조를 확인하고 `type`을 다시 설정한 뒤 새 플러그인 버전을 만듭니다. |
| 세션 URL 요청이 실패하고, 플러그인 로그에 해당 요청이 없음 | 요청이 플러그인에 도달하지 않았습니다. 경로가 `celExpression`에 포함되지 않았거나, 전달 규칙이 `forwardingRules`에 없습니다. | 빠진 `prefixFolder` 조건이나 전달 규칙을 추가하고 edge extension을 다시 가져옵니다. |

## 추가 리소스

- [Service Extensions 플러그인 개요](https://docs.cloud.google.com/service-extensions/docs/plugins-overview?hl=ko)
- [플러그인 코드 준비](https://docs.cloud.google.com/service-extensions/docs/prepare-plugin-code?hl=ko)
- [플러그인 만들기](https://docs.cloud.google.com/service-extensions/docs/create-plugin?hl=ko)
- [Edge extension 구성](https://docs.cloud.google.com/service-extensions/docs/configure-edge-extensions?hl=ko)
- [Cloud CDN 설정](https://docs.cloud.google.com/cdn/docs/using-cdn?hl=ko)
- [도브러너 포렌식 워터마킹 임베딩 문서](https://docs.doverunner.com/ko/content-security/forensic-watermarking/embedding/)

## 지원

CDN 임베더 구성 또는 배포에 대한 추가 지원이 필요한 경우 [도브러너 지원팀에 문의](https://support.doverunner.com/)하거나 포렌식 워터마킹 임베딩 문서를 참조하세요.