본문 바로가기

직접 만든 소프트웨어, 두 가지 개발 기록

구현 구조와 적용 범위, 확인한 기능과 남은 한계를 함께 기록합니다.

소프트웨어개발

Cloudflare CLI 1.0 RC: 배포 스크립트를 바꾸기 전 확인할 차이

by 아빠띠띠뽀 2026. 11. 19.

Cloudflare CLI의 cf 1.0 RC를 기존 자동화에 넣으려면 명령 이름, 표준 출력, 대상 계정, 빌드 산출물의 차이를 함께 확인해 주세요. RC가 나왔다는 소식을 모든 API 명령이 더는 바뀌지 않는 최종 정식 버전으로 해석하면 안 됩니다.

Cloudflare는 2026년 11월 17일 cf 1.0.0-rc.1을 발표했습니다. 18일 공지와 현재 CLI 문서를 확인했어요. 이 글은 베타 cf 스크립트나 Wrangler 프로젝트를 운영하는 개발자가 변경 영향을 비교하도록 돕는 안내입니다. 실제 도구 설치·로그인·이전·배포를 실행한 결과는 아닙니다.

안정 범위와 아직 바뀔 수 있는 부분부터 나누세요

RC는 정식 출시를 앞두고 검토하는 출시 후보 버전입니다. 현재 공지는 cloudflare.config.ts 설정 형식, 빌드 결과를 쓰고 읽는 Build Output 형식, 프로젝트를 만들고 개발·빌드·배포하는 주요 명령이 1.0까지 안정적으로 유지될 것으로 예상한다고 설명합니다. 베타에서 쓰인 API 생성 명령의 대부분도 이 범위로 안내합니다.

그러나 덜 사용되는 일부 API 명령은 1.0 전에 호출 경로가 바뀔 수 있다고 남겨 두었습니다. 이 명령들은 Cloudflare API 스키마에서 생성돼요. 따라서 팀이 주로 쓰는 프로젝트 명령이 안정 범위라는 설명을 계정·보안·스토리지의 모든 API 명령 이름이 고정됐다는 뜻으로 확대하면 안 됩니다.

현재 공식 소개에서 cf는 Cloudflare 공개 API와 Workers 프로젝트를 다루는 하나의 명령줄 인터페이스입니다. DNS·스토리지·보안 자원을 관리하는 명령과 애플리케이션 개발·배포 명령을 한 도구에서 찾을 수 있어요. 범위가 넓은 만큼 자신의 스크립트가 어느 부분을 사용하는지 먼저 구분하는 것이 좋습니다.

새 도구 도입을 검토한다면 지금 사용하는 버전과 호출 명령의 목록을 남겨 주세요. 로컬 터미널, CI, 코딩 에이전트에서 같은 명령처럼 보여도 설치 위치·버전·인증 환경은 다를 수 있습니다. 이 차이를 확인하지 않고 전체 도구를 한꺼번에 교체하면 문제가 났을 때 원인을 좁히기 어렵습니다.

이 글은 RC의 안정성을 직접 측정하거나 운영 사용을 보증하지 않습니다. 공식 발표의 기대 범위와 남은 변경 가능성을 기준으로, 자신이 의존하는 입출력·설정·권한을 검토하는 것이 출발점입니다.

베타 업그레이드는 명령과 출력의 계약을 바꿀 수 있어요

1.0.0-rc.1에서는 일부 생성 API 명령의 이름이 별칭 없이 바뀝니다. 공지의 예는 cf workers secrets bulk가 cf workers secrets bulk-edit로 바뀐 경우예요. 예전 이름을 호출하는 스크립트가 새 이름으로 알아서 연결될 것이라고 가정하지 마세요. 실제 사용 명령은 공식 릴리스 노트와 현재 도움말에서 개별 확인해야 합니다.

초기 베타에서 오랫동안 갱신하지 않았다면 이전 변경도 함께 확인해야 합니다. camelCase나 snake_case의 API 이름에서 만들어진 명령은 kebab-case를 사용합니다. 예를 들어 cf accounts billing getCredits와 cf accounts billing get-credits의 차이가 있습니다. 철자 하나의 차이도 자동화에서는 다른 호출이 됩니다.

프리뷰 배포 이름을 넘기는 방식도 확인 대상입니다. 현재 공지는 cf previews deploy에서 이름을 위치 인자 대신 --preview-name으로 전달한다고 설명합니다. 이 예시는 새 배포를 실행하라는 지시가 아니라 기존 스크립트가 기대하는 인자 형태를 비교할 항목입니다.

출력 흐름도 중요합니다. 프롬프트·진행률·상태 메시지는 stderr에 쓰고 stdout에는 명령 결과만 남깁니다. stdout은 다른 프로그램이 받아 처리하는 기본 출력, stderr는 진단·진행 정보를 보내는 별도 통로라고 생각하면 편해요. 과거에 stdout에서 진행 문구를 찾아 완료를 판단했다면 같은 방식이 계속 작동하는지 검토해야 합니다.

그렇다고 두 흐름을 무조건 합치는 것이 답은 아닙니다. JSON을 읽는 단계에 진행 문구가 섞이면 파싱 조건이 달라질 수 있어요. 어떤 출력이 실제 데이터이고 어떤 출력이 사람이 읽는 안내인지 구분한 뒤, 스크립트의 정상·실패 판단과 로그 보존을 점검하는 편이 좋습니다. 이 부분은 자동화 설계 제안이며 실제 팀의 파이프라인에서 시험하지 않았습니다.

버전 확인의 출력도 변경 목록에 있습니다. cf --version은 버전 번호만 출력합니다. 문자열 전체를 기대하던 비교 코드가 있다면 버전 값의 확인 방식까지 살펴보세요.

새 산출물과 의존성은 프로젝트 조건으로 비교하세요

이번 RC는 Build Output을 버전 1로 옮기며 경로는 .cloudflare/output/v1/입니다. cf build가 쓰고 cf deploy가 읽는 빌드 산출물의 형식·위치예요. 공지는 배포 명령이 처음 실행될 때 이 위치에 새 빌드를 자동으로 만든다고 안내합니다. 예전 산출물 경로를 직접 다루는 CI라면 그 참조도 확인해야 합니다.

의존성에는 캐럿, 즉 ^ 버전 범위를 사용하며 Vite 빌드 프로젝트에는 @cloudflare/vite-plugin 2.0.0-rc.0 이상을 요구합니다. Wrangler로 빌드하는 기존 프로젝트에는 Wrangler 4.163.0 이상이 요구됩니다. 두 수치를 모든 프로젝트가 똑같이 설치해야 하는 한 묶음으로 읽지 말고 자신의 빌드 경로와 연결해 주세요.

cf가 지원하는 Node.js 범위는 LTS 릴리스의 최신 버전들과 최신 활성 릴리스입니다. 이 표현은 오래된 모든 Node 버전의 지원을 뜻하지 않습니다. 실제 런타임은 개발자 PC와 CI에서 따로 확인하고, 잠금 파일과 패키지 관리 방식도 함께 보존해 변경의 원인을 추적할 수 있게 하는 것이 좋습니다.

Wrangler 프로젝트를 곧바로 새 프로젝트 명령으로 돌리는 일과, 기존 프로젝트 옆에서 자원 관리 API 명령을 쓰는 일도 구분됩니다. 현재 소개는 Wrangler 프로젝트를 바꾸지 않고 cf 자원 명령을 함께 쓸 수 있다고 설명합니다. 반면 해당 프로젝트에서 cf dev, cf build, cf deploy를 쓰기 전에는 cf migrate로 전환하도록 안내합니다.

그러므로 자원 조회에 새 도구를 써 보는 검토와 프로젝트 설정을 이전하는 결정을 한 단계로 묶을 필요는 없습니다. 실제 이전을 결정할 때는 저장소의 변경분·설정·빌드 경로를 검토하고 기존의 정상 결과와 비교할 계획이 있어야 합니다. 이 글은 migrate를 실행하거나 변환 결과가 그대로 동작하는지 확인하지 않았어요.

검토 항목 기존 환경과 비교할 내용
프로젝트 종류 Wrangler 유지 여부와 cf 프로젝트 명령 사용 계획
빌드 결과 v1 산출물 경로와 CI의 보관·배포 참조
의존성 Vite 플러그인 또는 Wrangler의 요구 버전
실행 환경 지원 Node.js와 개발·CI의 실제 설치 버전

계정 선택·로컬 상태·배포 자원을 함께 보존하세요

이전 베타와 달리 cf는 실행 사이의 계정 선택을 저장하지 않습니다. 프롬프트를 생략하려면 설정 파일의 accountId 또는 CLOUDFLARE_ACCOUNT_ID를 사용한다고 공지는 안내합니다. 이름이 익숙한 프로젝트라고 해도 현재 어느 계정을 대상으로 하는지 명시적으로 확인하는 습관이 필요합니다.

계정을 지정하는 것과 충분한 권한으로 인증됐다는 것은 다릅니다. CI에서는 실제로 허용된 자원과 작업 범위를 확인해야 해요. 블로그의 예시를 따라 새 토큰을 만들거나 권한을 넓히기보다 조직의 기존 승인 절차와 보안 정책을 우선해 주세요. 이 글에서는 인증 정보나 실제 계정 값을 조회하지 않았습니다.

로컬 실행 상태는 프로젝트의 .cloudflare/state에 저장된다는 변경도 있습니다. 이 경로를 빌드 출력 폴더와 같은 것으로 보고 정리하면 안 돼요. 로컬에 남겨야 할 시험 데이터가 있는지와 팀의 백업·삭제 정책을 확인하고, 버전 문제를 해결한다는 이유로 상태 폴더를 먼저 지우지 않는 편이 좋습니다.

배포 변경 목록에는 설정 파일 밖에서 추가한 secrets가 재배포로 제거되지 않는다는 항목이 있습니다. 그렇다고 모든 자원이 자동 보존되거나 잘못된 대상 배포가 무해해지는 것은 아닙니다. 실제 자원·바인딩·원격 설정을 확인하고 로컬 설정과 다른 부분은 담당자의 의도인지 구분해야 해요.

cf deploy --no-provision은 바인딩에 자원 ID가 없을 때 새 자원을 만드는 대신 실패하도록 하는 동작입니다. cf deploy --dry-run은 만들 프로젝트 설정 변경을 실제 변경 없이 보여 줍니다. API 명령도 dry-run으로 요청을 미리 볼 수 있지만, 미리보기 결과를 실제 배포·연결·서비스 검증의 성공으로 기록해서는 안 됩니다.

특히 --force는 기본 복구 옵션으로 붙이지 마세요. 공지는 원격 설정과 로컬 Build Output 충돌 등에서 강제 배포하는 동작을 설명하며, 터미널 없이 실행되는 파괴적 명령은 force가 없으면 오류로 종료한다고 안내합니다. 보호 장치를 없애 오류를 지나가는 일과 원인을 해결하는 일은 다릅니다. 영향과 권한을 이해한 담당자가 필요한 경우를 판단해야 합니다.

로그 수집도 명령 실행과 결과 해석을 나누세요

이번 공지에는 cf observability tail이 실시간 로그와 관찰 이벤트를 줄 단위 JSON으로 스트리밍한다는 내용이 있습니다. 대상은 Worker, zone과 하위 도메인, 계정 전체 등으로 구분할 수 있어요. 넓은 대상을 고르면 더 많은 운영 정보가 포함될 수 있으므로 실제 업무에 필요한 범위를 먼저 정하는 것이 좋습니다.

아래는 공식 발표에 있는 명령 형태를 설명하기 위한 예시입니다. my-worker는 실제 서비스 이름이 아니며 filters.json은 필요한 필터를 담은 파일을 가정합니다. 이 글을 작성하면서 두 명령을 실행하거나 로그를 수집하지 않았습니다.

cf observability tail --worker my-worker
cf observability tail --worker my-worker --filters @filters.json

Worker 이벤트를 보려면 해당 Worker의 Workers Logs가 켜져 있어야 합니다. 명령이 연결됐는데 기대한 이벤트가 보이지 않는다면 이 전제와 대상·필터를 구분해 봐야 해요. 필터의 실제 형식은 현재 도움말을 확인하고, 예시 파일이 있는 것처럼 임의로 실행하지 않는 편이 정확합니다.

자동화에서 이 로그를 읽는다면 스트림 시작, 개별 JSON 처리, 연결 종료·오류를 다른 상태로 남기는 것이 좋습니다. 프로세스가 잠시 살아 있었다는 사실만으로 필요한 이벤트를 확보했다고 볼 수는 없어요. 로그를 저장·공유할 때도 서비스 정보와 민감한 내용이 포함되는지 조직의 규칙에 따라 확인해야 합니다.

도입 검토 메모에는 실행할 명령, 대상 계정과 자원, 예상하는 결과 형식, 실패 시 중단 조건을 적어 두세요. 실제 시험을 수행했다면 그때의 버전·시각·원문 로그로 문서 확인과 구분해야 합니다. 여기서는 그러한 실행 증거가 없으므로 로그 수집의 성공이나 안정성을 주장하지 않습니다.

업그레이드 전후 비교에서도 원래 스크립트와 설정·잠금 파일·정상 배포 이력을 보존해 주세요. 도구 버전을 되돌리는 일만으로 원격에서 이미 변경한 자원까지 되돌아가는 것은 아닙니다. 운영 복구는 실제 변경 자원과 배포 기록을 별도로 확인하는 계획이 필요합니다.

자주 묻는 질문과 변경 범위 결정

RC이면 모든 명령을 바로 고정해도 되나요? 주요 프로젝트 명령과 설정·Build Output의 안정 범위를 안내하지만 일부 API 생성 명령은 1.0 전에 바뀔 수 있습니다. 실제 스크립트에서 사용하는 호출을 기준으로 확인해 주세요.

Wrangler를 당장 전부 바꿔야 하나요? 현재 공식 안내는 자원 명령을 기존 프로젝트 옆에서 사용하는 경로와 프로젝트를 이전하는 경로를 나눕니다. 이 글이 모든 기존 프로젝트의 즉시 이전을 요구하거나 새 도구가 더 빠르다고 시험한 것은 아닙니다.

dry-run이 통과하면 배포도 완료된 건가요? 미리보기와 실제 실행은 다른 단계입니다. 실제 배포 이후에는 저장된 설정과 대상 자원·서비스 동작을 따로 확인해야 합니다. 이 글에서는 어느 배포도 수행하지 않았습니다.

팀에서 먼저 볼 것은 무엇인가요? 현재 버전, 사용하는 명령 이름과 인자, stdout/stderr 파싱, 대상 계정, 빌드 경로를 모아 보세요. 공식 변경에 해당하는 부분을 찾고 비운영 환경의 검증 계획을 세운 뒤, 권한과 복구 근거가 준비된 범위부터 결정하는 것이 이 글의 제안입니다.

자료 확인일은 2026년 11월 18일입니다. 공식 발표와 현재 문서로 확인한 범위이며, 실제 계정 설정 변경·명령 실행·성능 시험은 하지 않았어요. 적용 시점의 계정·버전·환경과 승인 범위는 담당자가 다시 확인해 주세요.

함께 읽어 볼 글: 로컬 자원과 배포 자원의 경계를 구분하는 Artifacts 안내.

명령 도구를 나타내는 빈 판과 분리된 두 출력 트레이·설정 노트를 작업대에 놓은 개념 그림
도구 업그레이드 때 명령·출력·설정을 나누어 살피는 개념 이미지입니다. 실제 배포 성공이나 명령 실행 결과를 보여 주는 화면은 아닙니다.