Cloudflare Tunnel 클라이언트

Cloudflare Tunnel용 명령줄 클라이언트를 포함하고 있으며, Cloudflare 네트워크에서 오리진으로 트래픽을 프록시하는 터널링 데몬입니다. 이 데몬은 Cloudflare 네트워크와 오리진(예: 웹서버) 사이에 위치합니다. Cloudflare는 클라이언트 요청을 수신하여 이 데몬을 통해 사용자에게 전송하며, 방화벽에 구멍을 뚫을 필요가 없습니다 --- 오리진은 가능한 한 폐쇄된 상태로 유지할 수 있습니다. 자세한 문서는 Cloudflare Docs의 Cloudflare Tunnel 섹션에서 확인할 수 있습니다. 오리진으로의 프록시와 관련된 모든 사용법은 cloudflared tunnel help에서 확인할 수 있습니다.

cloudflared를 사용하여 Layer 4(즉, HTTP/websocket이 아닌)의 TCP 트래픽에 대해 (cloudflared tunnel로 보호되는) Tunnel 오리진에 접근할 수도 있으며, 이는 SSH, RDP 등의 사용 사례에 적합합니다. 이러한 사용법은 cloudflared access help에서 확인할 수 있습니다.

또는 WARP 클라이언트를 사용하여 클라이언트 측에서 cloudflared access 명령 없이도 Layer 4 트래픽에 대해 Tunnel 뒤의 프라이빗 오리진에 접근할 수 있습니다.

시작하기 전에

Cloudflare Tunnel을 사용하기 전에 Cloudflare 대시보드에서 몇 가지 단계를 완료해야 합니다. Cloudflare 계정에 웹사이트를 추가해야 합니다. 현재는 웹사이트 없이도 Tunnel을 사용할 수 있지만(예: 프라이빗 라우팅), 레거시 이유로 이 요구 사항은 여전히 필요합니다:

1. Cloudflare에 웹사이트 추가
2. 도메인 네임서버를 Cloudflare로 변경

cloudflared 설치

다운로드는 독립 실행형 바이너리, Docker 이미지, 그리고 Debian, RPM, Homebrew 패키지로 제공됩니다. cloudflared GitHub 저장소의 릴리스에서도 확인할 수 있습니다.

• Homebrew를 통해 또는 최신 Darwin amd64 릴리스를 다운로드하여 macOS에 설치할 수 있습니다
• Linux용 바이너리, Debian 및 RPM 패키지는 여기에서 확인할 수 있습니다
• cloudflared의 Docker 이미지는 DockerHub에서 사용 가능합니다
• Windows 머신에는 여기의 단계에 따라 설치할 수 있습니다
• 소스에서 빌드하려면 아래 개발 섹션에 언급된 필수 버전의 go를 설치하세요. 그런 다음 make cloudflared를 실행할 수 있습니다.

Cloudflare Tunnel에 대한 사용자 문서는 https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/ 에서 확인할 수 있습니다

Tunnel 생성 및 트래픽 라우팅

설치 후 cloudflared를 Cloudflare 계정으로 인증하고 오리진으로 트래픽을 제공할 Tunnel 생성을 시작할 수 있습니다.

• 다음 지침에 따라 Tunnel을 생성하세요
• 해당 Tunnel로 트래픽 라우팅:
  • Cloudflare의 공용 DNS 레코드를 통해
  • 또는 Cloudflare Load Balancer가 안내하는 공용 호스트명을 통해
  • 또는 WARP 클라이언트 프라이빗 트래픽을 통해

TryCloudflare

Cloudflare에 웹사이트를 추가하기 전에 Cloudflare Tunnel을 테스트하고 싶으신가요? 여기에서 제공되는 문서를 참고하여 TryCloudflare로 테스트할 수 있습니다.

주요 변경 사항 (Breaking Changes)

CLI 플래그, 환경 변수, 구성 키 또는 명령의 제거는 주요 변경 사항(breaking change)입니다. 이러한 제거는 해당 항목을 제거하는 릴리스 이전에 Cloudflare Tunnel 변경 로그에 공지되어야 합니다.

지원 중단된 버전

Cloudflare는 현재 가장 최근 릴리스로부터 1년 이내의 cloudflared 버전을 지원합니다. 기능 가용성과 무관한 주요 변경 사항이 도입되어 1년 이상 전에 릴리스된 버전에 영향을 미칠 수 있습니다. cloudflared 업그레이드에 대한 자세한 내용은 개발자 문서에서 확인할 수 있습니다.

예를 들어, 2023년 1월 기준으로 Cloudflare는 cloudflared 버전 2023.1.1부터 cloudflared 2022.1.1까지를 지원합니다.

개발

요구 사항

• GNU Make
• capnp
• go >= 1.27.3
• 선택적 도구:
  • capnpc-go
  • goimports
  • golangci-lint
  • gomocks

Go 업데이트

go.mod의 go 지시문은 전체 major.minor.patch 버전을 지정해야 합니다 (예: go 1.27.3). .0 릴리스를 포함하여 패치 버전을 생략하지 마십시오. 이는 cloudflared를 빌드하고 테스트하는 데 사용되는 정확한 Go 버전입니다. Makefile은 이로부터 GOTOOLCHAIN=go<version>을 내보내므로, make는 설치된 Go가 더 오래되었거나 더 새로운 경우 해당 툴체인을 다운로드합니다. make가 go run pkg@version으로 실행하는 도구들도 이 툴체인을 사용합니다. go.mod의 toolchain 지시문은 무시되므로 추가하지 마십시오. 대신 설치된 Go를 사용하려면 make <target> GOTOOLCHAIN=local을 실행하십시오.

Go를 업그레이드할 때는 go 지시문과 .gitlab-ci.yml, .ci/image/Dockerfile, .github/workflows/check.yaml 및 Dockerfile의 모든 해당 버전 참조를 업데이트하십시오. .ci/linux.gitlab-ci.yml의 Linux CI 빌더 이미지와 다이제스트를 일치하도록 업데이트하십시오. 해당 파일의 golangVersion이 major/minor 이미지 계열을 선택합니다. macOS와 Windows에서는 불일치가 툴체인 다운로드 비용만 발생시킵니다. GOTOOLCHAIN=local을 사용하는 빌드는 Go가 go.mod보다 오래된 경우 실패하고, 더 새로운 경우 자체 Go를 사용합니다.

빌드

로컬에서 cloudflared를 빌드하려면 make cloudflared를 실행하십시오.

테스트

로컬에서 테스트를 실행하려면 make test를 실행하십시오.

린팅

코드를 포맷하고 좋은 코드 품질을 유지하려면 make fmt와 make lint를 사용하십시오.

목(Mock)

인터페이스를 변경한 후에는 목을 다시 생성해야 할 수 있으므로 make mocks를 실행하십시오.

Git 훅

CI 오류를 방지하기 위해 각 푸시 전에 린팅과 테스트를 실행하는 pre-push 훅을 설치할 수 있습니다:

make install-hooks

이렇게 하면 각 push 전에 make fmt-check lint test를 실행하는 .githooks/의 훅을 사용하도록 git이 구성됩니다.