Cloudflare Worker Previews 격리 진단: 자동 분리와 수동 분리 기준
Durable Objects·Containers의 자동 격리와 KV·D1·R2·Queue·Workflow의 수동 분리를 구분하고, 운영 오염을 배포 전후에 확인하는 진단표입니다.
읽기 전에 핵심만
- 자동 격리되는 핵심 상태 리소스는 Durable Objects와 Containers이며 나머지 계정 리소스는 별도 바인딩을 점검해야 합니다.
- Service binding·Workflow·Queue·Cron은 production 연결 또는 프리뷰 제한이 있으므로 URL 분리와 실행 경로 격리를 따로 검증합니다.
- canary read-back과 접근 차단, 삭제 후 container 목록까지 통과한 기록을 남긴 뒤 브랜치 자동화를 확대합니다.
Cloudflare Worker Previews에서 자동으로 격리되는 핵심 상태 리소스는 Durable Objects와 Containers입니다. KV·D1·R2·Queue producer·Workflow처럼 계정에 이미 존재하는 리소스는 같은 ID나 이름을 바인딩하면 프리뷰끼리 또는 운영과 데이터를 공유하므로, 별도의 비운영 리소스로 직접 분리해야 합니다. Service binding은 연결된 Worker의 production deployment를 호출하고 Queue consumer·Cron Trigger·production route는 프리뷰 실행 대상이 아니어서 URL이 달라졌다는 사실만으로는 격리가 끝났다고 볼 수 없습니다.
확인된 사실: Cloudflare는 2026년 9월 22일 Worker Previews를 공개하며 Git 브랜치마다 별도 코드, 구성, URL, 관측성과 상태를 제공한다고 설명했습니다. 현재 공식 문서는 Wrangler 4.135.0 이상을 요구하며, 프로젝트 의존성을 갱신해야 프로젝트 명령이 새 버전을 사용한다고 명시합니다.
직접 대조: 공식 문서의 리소스 표와 제한 절을 대조하면 자동 격리, 별도 바인딩 필요, production 연결 또는 프리뷰 미지원이 서로 다른 범주입니다. 아래 진단은 이 세 범주를 섞지 않는 데 목적이 있습니다.
POEMORA의 해석: 프리뷰 격리의 증거는 URL 하나가 아니라 설정, 상태 저장소, 다른 Worker 호출, 비동기 실행, 접근 제어, 삭제 후 잔여물까지 각각 확인한 기록입니다.
증상: 프리뷰 URL은 다른데 운영 흔적이 바뀐다
다음 현상은 격리 실패를 의심할 예시 증상입니다. 하나만으로 원인이 확정되지는 않으므로 원본 데이터나 운영 설정을 지우지 말고 확인 순서대로 범위를 좁힙니다.
- 프리뷰에서 만든 테스트 값이 운영 KV 키, D1 행 또는 R2 객체 목록에 나타납니다.
- 프리뷰가 보낸 Queue 메시지를 운영 consumer가 처리합니다.
- 프리뷰 Worker A의 Service binding 호출이 프리뷰 B가 아니라 운영 Worker B의 응답을 돌려줍니다.
- HTTP 요청은 프리뷰에서 정상인데 Cron Trigger나 Queue consumer 경로는 실행되지 않습니다.
- 프리뷰를 삭제했는데 생성됐던 container app이 목록에 남아 있습니다.
- 내부 검증용 Preview URL을 로그인 없이 외부에서 열 수 있습니다.
안전 원칙: 증상을 재현할 때는 운영 데이터와 구별되는 canary 값, 읽기 전용 조회, 별도 비운영 리소스를 사용합니다. 운영 행 삭제, Queue 비우기, bucket 정리처럼 원인을 숨길 수 있는 조치는 진단 전에 하지 않습니다.
가능한 원인: 코드 격리와 리소스 격리를 같은 것으로 봤다
가능한 원인은 다섯 갈래입니다.
- 리소스 식별자 공유:
previews설정에 운영과 같은 KV namespace ID, D1 database ID, R2 bucket name 또는 Queue name을 넣었습니다. - 비동기 경로 오해: 프리뷰는 Queue에 메시지를 생산할 수 있지만 현재 Queue consumer가 될 수 없고, Cron Trigger도 production을 대상으로 합니다.
- 다른 Worker·Workflow 연결: Service binding은 bound Worker의 production deployment를 호출합니다. Workflow binding은 프리뷰 전용 Workflow를 만들지 않고 기존 Workflow의 배포 코드·바인딩·인스턴스를 사용합니다.
- 설정·접근 제어 누락: Previews는 production 설정을 상속하지 않으며
previewsblock을 사용합니다. Preview URL은 기본적으로 공개이므로 비공개 검증에는 Cloudflare Access 같은 접근 정책이 필요합니다. - 삭제를 정리 완료로 간주: Preview 삭제 뒤 URL과 Durable Object namespace는 제거되더라도 생성된 container app은 목록에 남을 수 있습니다.
확인 순서: 운영 오염 가능성을 여섯 단계로 좁힌다
1. Wrangler와 대상 URL을 고정한다
프로젝트 의존성의 Wrangler가 4.135.0 이상인지 확인하고 현재 브랜치에서 npx wrangler preview를 실행합니다. Preview URL은 해당 프리뷰의 최신 배포를 가리키고 Deployment URL은 특정 배포를 가리키므로, 진단 기록에는 어느 URL과 배포를 확인했는지 함께 남깁니다.
2. production과 previews 설정을 나란히 비교한다
wrangler.jsonc 또는 wrangler.toml의 top level과 previews block을 펼쳐 변수, secret 적용 범위, binding의 ID·이름을 한 줄씩 비교합니다. 같은 이름을 써도 실제 대상 ID가 다를 수 있고, 반대로 binding 이름이 달라도 같은 계정 리소스를 가리킬 수 있으므로 표시 이름이 아니라 실제 식별자를 봅니다.
3. 리소스 격리 매트릭스를 채운다
| 분류 | 리소스 | 판정 기준 |
|---|---|---|
| 자동 격리 | Durable Objects, Containers | 프리뷰별 namespace·container app·instance가 생성되는지 확인 |
| 별도 바인딩 필요 | KV, D1, R2, Queue producer, Vectorize, Hyperdrive, Analytics Engine, Pipelines | 운영과 다른 ID·이름·데이터베이스 또는 schema를 가리키는지 확인 |
| 별도 비운영 대상 필요 | Workflows | 기존 Workflow가 아니라 전용 비운영 Workflow에 바인딩했는지 확인 |
| production 연결 주의 | Service bindings | 호출 대상이 bound Worker의 production deployment임을 전제로 테스트 |
| 프리뷰 미지원 경로 | Queue consumers, Cron Triggers, production routes | 프리뷰에서 실행될 것이라고 가정하지 않고 별도 테스트 경로 사용 |
4. 상태 저장소에 canary를 쓰고 양쪽에서 읽는다
프리뷰 전용으로 만든 KV·D1·R2 등에 운영 값과 충돌하지 않는 canary를 한 건 기록합니다. 프리뷰에서는 보이고 운영 리소스에서는 보이지 않아야 통과입니다. 양쪽에 보이면 쓰기를 중단하고 binding ID·이름부터 교정합니다. 자동 격리 대상인 Durable Objects와 Containers도 프리뷰별 namespace와 app이 실제로 생성됐는지 read-back합니다.
5. 호출·비동기·접근 경로를 따로 검사한다
Service binding 응답에는 테스트용 식별 표식을 두어 production Worker 호출 여부를 확인합니다. Queue는 프리뷰 producer가 production Queue를 가리킬 경우 운영 consumer가 메시지를 처리할 수 있으므로 전용 비운영 Queue를 사용하거나 발행을 중단합니다. scheduled 로직은 scheduled()와 테스트 전용 route가 함께 호출할 수 있는 함수로 분리해 Preview URL에서 검증합니다. 외부 공개가 허용되지 않은 프리뷰는 Cloudflare Access 정책을 적용한 뒤 비인증 요청이 차단되는지 확인합니다.
6. 삭제 뒤 잔여물을 확인한다
npx wrangler preview delete --name 실행 뒤 npx wrangler containers list로 container app 잔여물을 확인합니다. 남은 app을 삭제할 때는 이름만으로 넓게 지우지 말고 Worker·Preview·class 조합과 application ID를 대조합니다.
조치: 자동 격리 대상만 남기고 공유 바인딩을 끊는다
- Durable Objects와 Containers는 자동 격리를 사용하되 필요한 binding과 migration이
previews설정에서 유효한지 확인합니다. - KV·D1·R2와 데이터 파이프라인 계열은 프리뷰 전용 이름 규칙과 리소스 생명주기를 정하고 운영 식별자를 허용 목록에서 제외합니다.
- Workflow는 먼저 전용 비운영 Workflow를 배포한 뒤 바인딩합니다. Service binding으로 다른 Worker를 호출하는 경로는 자동으로 같은 이름의 Preview에 연결되지 않는다는 전제에서 테스트합니다. 같은 Worker 내부 호출을 유지해야 하는 경우 공식 문서가 안내하는
ctx.exports적용 가능성을 검토합니다. - Queue consumer와 Cron Trigger가 필요한 시나리오는 운영 trigger를 프리뷰에 복제하려 하지 말고, 핵심 로직을 직접 호출할 수 있는 안전한 테스트 경로로 분리합니다.
- Preview URL은 public default를 받아들이지 말고 조직의 접근 정책을 기본값으로 둡니다.
한계와 중단 조건: 확인이 끝나기 전 운영을 건드리지 않는다
Worker Previews가 모든 Cloudflare 리소스를 자동 복제하는 것은 아닙니다. 특히 Hyperdrive는 별도 configuration만으로 데이터가 완전히 분리되지 않으며, 별도 데이터베이스나 schema까지 가리켜야 실질적인 격리가 됩니다. Containers의 Preview 지원도 부분적이므로 process가 시작되고 응답하는지 직접 확인해야 합니다.
다음 중 하나라도 불명확하면 프리뷰 배포를 운영 검증 완료로 승격하지 말고 플랫폼 담당자에게 에스컬레이션합니다.
- binding이 어느 account resource를 가리키는지 확인할 권한이 없습니다.
- production Queue·Workflow·Service binding 호출을 안전하게 차단할 방법이 없습니다.
- canary가 운영 데이터에서 발견됐지만 원본과 테스트 값을 구분할 수 없습니다.
- 삭제 대상 container application ID를 정확히 식별할 수 없습니다.
- 접근 정책 적용 전 내부 데이터나 인증 흐름이 노출될 수 있습니다.
다음 행동: 한 브랜치의 격리 증거를 템플릿으로 남긴다
먼저 실제 브랜치 하나를 골라 Wrangler 버전, Preview·Deployment URL, previews binding 식별자, canary read-back, Service·Queue·Cron 판정, Access 차단, 삭제 후 목록을 한 장의 진단표에 기록합니다. 이 기록이 모두 통과한 뒤에만 같은 리소스 규칙을 다른 브랜치 자동화에 확대합니다.
자주 묻는 질문
Worker Preview를 만들면 KV·D1·R2도 자동으로 복제되나요?
아니요. KV는 namespace ID, D1은 database ID, R2는 bucket name을 기준으로 기존 리소스에 바인딩됩니다. 운영과 다른 프리뷰 전용 리소스를 만들고 previews block에서 별도 식별자를 지정해야 합니다.
자동으로 격리되는 Cloudflare 리소스는 무엇인가요?
현재 공식 리소스 표에서 프리뷰별 자동 격리가 명시된 핵심 리소스는 Durable Objects와 Containers입니다. 실제 namespace·container app·instance 생성과 응답은 배포 뒤 다시 확인해야 합니다.
Preview에서 Queue와 Cron을 그대로 테스트할 수 있나요?
Preview는 Queue producer가 될 수 있지만 현재 consumer가 될 수 없고, Cron Trigger는 production을 대상으로 합니다. 전용 비운영 Queue와 직접 호출 가능한 테스트 route로 핵심 로직을 분리하는 편이 안전합니다.
Preview를 삭제하면 Containers도 모두 정리되나요?
Preview record와 Durable Object namespace가 제거돼도 생성된 container app이 목록에 남을 수 있습니다. preview delete 뒤 containers list로 application ID를 대조하고 잔여물만 제한적으로 정리해야 합니다.
