Doveva essere un rapido progetto del weekend. Sapete il tipo: "Creo una VM di egress, ci instrado del traffico, sorseggio il mio caffè e ho finito per pranzo." Lettore, non avevo finito per pranzo.

La Configurazione

Stavo costruendo un piccolo access tier per alcuni ambienti di sviluppo: una VM di egress con Cloudflare Zero Trust davanti, routing basato su hostname per due domini di sviluppo specifici e AWS WAF dall'altra parte che controllava l'IP sorgente. Roba piuttosto standard del tipo "dai al mio team accesso sicuro senza esporre cose a internet pubblico".

Tutto è andato liscio finché non sono arrivato alla parte in cui devi abilitare la decrittazione TLS. Questa è la magia che permette al gateway di Cloudflare di ispezionare effettivamente il traffico e instradarlo in base all'hostname anziché solo all'IP. Senza, le tue bellissime regole hostname se ne stanno lì belle e non fanno assolutamente nulla.

Il Percorso dei Tutorial

Ho seguito il percorso di apprendimento ufficiale di Cloudflare. Ho seguito tre diversi blog post. Ho seguito il tutorial di YouTube di qualcuno la cui voce sembrava volesse davvero che mi iscrivessi. Dicevano tutti la stessa cosa:

Vai su Zero Trust > Settings > Network > Firewall > TLS decryption e attiva l'interruttore.

Così ci sono andato. L'interruttore è scattato. Poi è apparso un banner rosso nella parte superiore dello schermo che diceva semplicemente:

Error configuring TLS setting.

Tutto qui. Nessun codice. Nessun indizio. Nessun link "clicca qui per i dettagli". Solo una sensazione di "qualcosa è andato storto, buona fortuna."

Ho riprovato. Stesso errore. Ho aggiornato. Stesso errore. Ho provato con Firefox. Stesso errore. Ho svuotato la cache. Stesso errore. Ho considerato di fare il caffè. Fatto il caffè. Stesso errore.

Il Lavoro Investigativo

Ecco dove entra in gioco il mio strumento preferito. Quando l'UI si rifiuta di dirti cosa non va, la scheda network e curl lo faranno. Ho aperto gli strumenti di sviluppo, osservato la richiesta che l'interruttore stava inviando, l'ho copiata come curl e l'ho eseguita localmente:

{
  "result": null,
  "success": false,
  "errors": [
    {
      "code": 2211,
      "message": "TLS decryption cannot be enabled without a certificate. Please disable TLS encryption or configure a certificate using the 'certificate' setting."
    }
  ],
  "messages": []
}

Eccolo lì. Un messaggio di errore chiaro, utile e attuabile. Il tipo di messaggio che, se mostrato nell'UI, mi avrebbe risparmiato circa novanta minuti della mia vita. Invece era nascosto nella risposta JSON, inghiottito da qualche parte tra l'API e lo schermo.

Il messaggio diceva sostanzialmente: "ti serve prima un certificato, patata assoluta." (Sto parafrasando.)

La Vera Soluzione

Ecco la cosa che nessuno su internet sembra menzionare: la gestione dei certificati si è spostata.

Ogni guida che ho letto indicava la vecchia posizione. La posizione attuale effettiva è sepolta in una sezione completamente diversa. Nello specifico:

Zero Trust > Traffic policies > Traffic settings > Certificates (scheda in alto)

Non Network. Non Firewall. Traffic policies > Traffic settings.

Generi un certificato gestito da Cloudflare lì. Poi lo contrassegni come Available e In-Use. Poi aspetti da cinque a dieci minuti (anche questa parte nessuno la menziona, guardi solo un campo di stato e metti in discussione silenziosamente le tue scelte di vita). Una volta che il certificato è completamente attivo, puoi finalmente tornare indietro e abilitare la decrittazione TLS.

Funziona e basta. L'interruttore scatta. Il banner rosso sta lontano. Il mondo ha di nuovo senso.

La Morale

Due cose mi sono rimaste impresse da questa piccola avventura.

Primo: la documentazione non era sbagliata, era solo datata. Cloudflare si muove velocemente e riorganizza spesso la dashboard. Non è una lamentela, solo una realtà. Quando segui una guida per qualsiasi prodotto in rapida evoluzione, aspettati che i percorsi dei menu possano essere cambiati. I concetti sono gli stessi, i pulsanti non sono sempre dove dicono gli screenshot.

Secondo: la scheda network è la tua migliore amica. Quando un'UI ti dà un errore inutile, l'API ne sa quasi sempre di più. Gli strumenti di sviluppo del browser, curl o anche solo leggere la risposta raw fanno la differenza tra debuggare in cinque minuti e debuggare in cinque ore. La gestione degli errori dell'UI è un sottile strato dipinto sopra un sistema molto più dettagliato, e quel sistema è proprio lì che aspetta che tu glielo chieda gentilmente.

Il Bonus

L'ho segnalato a Cloudflare. Il codice di errore 2211 ha un messaggio perfettamente valido allegato. Semplicemente non arriva allo schermo. Speriamo che qualcuno lo noti e un futuro guerriero del weekend riceva un banner utile invece di uno vago.

Fino ad allora, se mai vedrai "Error configuring TLS setting" senza ulteriori dettagli, la risposta è probabilmente:

  1. Genera prima un certificato (sotto Traffic policies > Traffic settings)
  2. Contrassegnalo come Available e In-Use
  3. Aspetta
  4. Poi abilita la decrittazione TLS

Ora, se mi scusate, ho una VM di egress che finalmente funziona, e un caffè che si è raffreddato due volte.

Saluti dalla scrivania di debugging di mezzanotte di domenica (02:42 AM).