Client Cloudflare Tunnel

Contiene il client a riga di comando per Cloudflare Tunnel, un daemon di tunneling che inoltra il traffico dalla rete Cloudflare alle tue origini. Questo daemon si colloca tra la rete Cloudflare e la tua origine (ad es. un webserver). Cloudflare intercetta le richieste dei client e le invia a te tramite questo daemon, senza richiedere di aprire varchi nel firewall --- la tua origine può rimanere il più chiusa possibile. Un'ampia documentazione è disponibile nella sezione Cloudflare Tunnel della documentazione Cloudflare. Tutti gli utilizzi relativi all'inoltro verso le tue origini sono disponibili in cloudflared tunnel help.

Puoi anche usare cloudflared per accedere alle origini dei Tunnel (protette con cloudflared tunnel) per il traffico TCP a livello 4 (cioè non HTTP/websocket), il che è rilevante per casi d'uso come SSH, RDP, ecc. Tali utilizzi sono disponibili in cloudflared access help.

In alternativa puoi usare il client WARP per accedere alle origini private dietro i Tunnel per il traffico di livello 4 senza richiedere i comandi cloudflared access sul lato client.

Prima di iniziare

Prima di usare Cloudflare Tunnel, dovrai completare alcuni passaggi nella dashboard Cloudflare: devi aggiungere un sito web al tuo account Cloudflare. Nota che oggi è possibile usare Tunnel senza un sito web (ad es. per il routing privato), ma per ragioni storiche questo requisito è ancora necessario:

1. Aggiungi un sito web a Cloudflare
2. Cambia i nameserver del tuo dominio in Cloudflare

Installazione di cloudflared

I download sono disponibili come binari standalone, immagine Docker e pacchetti Debian, RPM e Homebrew. Puoi anche trovare le release qui nel repository GitHub cloudflared.

• Puoi installare su macOS tramite Homebrew o scaricando l'ultima release Darwin amd64
• Binari e pacchetti Debian e RPM per Linux sono disponibili qui
• Un'immagine Docker di cloudflared è disponibile su DockerHub
• Puoi installare su macchine Windows con i passaggi qui
• Per compilare dai sorgenti, installa la versione richiesta di go, indicata nella sezione Sviluppo qui sotto. Poi puoi eseguire make cloudflared.

La documentazione utente per Cloudflare Tunnel è disponibile su https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/

Creazione di Tunnel e instradamento del traffico

Una volta installato, puoi autenticare cloudflared nel tuo account Cloudflare e iniziare a creare Tunnel per servire traffico alle tue origini.

• Crea un Tunnel con queste istruzioni
• Instrada il traffico verso quel Tunnel:
  • Tramite record DNS pubblici in Cloudflare
  • Oppure tramite un hostname pubblico guidato da un Cloudflare Load Balancer
  • Oppure dal traffico privato del client WARP

TryCloudflare

Vuoi testare Cloudflare Tunnel prima di aggiungere un sito web a Cloudflare? Puoi farlo con TryCloudflare usando la documentazione disponibile qui.

Modifiche incompatibili

La rimozione di flag CLI, variabili d'ambiente, chiavi di configurazione o comandi è una modifica incompatibile. Tali rimozioni devono essere annunciate nel changelog di Cloudflare Tunnel prima della release che le rimuove.

Versioni deprecate

Cloudflare attualmente supporta le versioni di cloudflared che rientrano entro un anno dalla release più recente. Potrebbero essere introdotte modifiche incompatibili non legate alla disponibilità delle funzionalità che avranno impatto sulle versioni rilasciate più di un anno fa. Puoi leggere di più sull'aggiornamento di cloudflared nella nostra documentazione per sviluppatori.

Ad esempio, a partire da gennaio 2023 Cloudflare supporterà cloudflared dalla versione 2023.1.1 alla versione 2022.1.1.

Sviluppo

Requisiti

• GNU Make
• capnp
• go >= 1.27.3
• Strumenti opzionali:
  • capnpc-go
  • goimports
  • golangci-lint
  • gomocks

Aggiornamento di Go

La direttiva go in go.mod deve specificare la versione completa major.minor.patch (ad esempio, go 1.27.3). Non omettere la versione patch, incluse le release .0. Questa è la versione esatta di Go usata per compilare e testare cloudflared: il Makefile esporta GOTOOLCHAIN=go<version> da essa, così make scarica quella toolchain ogni volta che il Go installato è più vecchio o più nuovo. Anche gli strumenti che make esegue con go run pkg@version usano questa toolchain. Una direttiva toolchain in go.mod viene ignorata; non aggiungerne una. Per usare invece il Go installato, esegui make <target> GOTOOLCHAIN=local.

Quando aggiorni Go, aggiorna la direttiva go e tutti i riferimenti di versione corrispondenti in .gitlab-ci.yml, .ci/image/Dockerfile, .github/workflows/check.yaml e nei Dockerfile. Aggiorna l'immagine del builder CI Linux e il digest in .ci/linux.gitlab-ci.yml per allinearli; il suo golangVersion seleziona la famiglia di immagini major/minor. Su macOS e Windows una discrepanza comporta solo il download di una toolchain. Le build che usano GOTOOLCHAIN=local falliscono se il loro Go è più vecchio di quello in go.mod e usano il proprio Go se è più nuovo.

Build

Per compilare cloudflared localmente esegui make cloudflared

Test

Per eseguire localmente i test esegui make test

Linting

Per formattare il codice e mantenere una buona qualità del codice usa make fmt e make lint

Mock

Dopo modifiche alle interfacce potresti dover rigenerare i mock, quindi esegui make mocks

Git Hooks

Per evitare errori in CI, puoi installare hook pre-push che eseguono linting e test prima di ogni push:

make install-hooks

Questo configurerà git per utilizzare gli hook in .githooks/ che eseguono make fmt-check lint test prima di ogni push.