Documentation
¶
Overview ¶
Package cloudflare routes apps through a Cloudflare Tunnel (R-160, design 03 §4.5).
cloudflared runs beside Pando and dials out to Cloudflare, so nothing on this machine needs to be reachable from the internet and Cloudflare issues the certificates. Every ingress rule this adapter writes sends traffic to Pando's proxy — never to an app's container. R-023 has no exception for a tunnel: a rule pointing at a workload would be a way to an app that skips authorization, and it would work, which is why the instinct is dangerous.
Cloudflare Access is not configured here. It could only ever be a layer in front of Pando's proxy, never the only check; whether Pando should manage it at all is O-23.
Index ¶
- Constants
- func Info() api.KindInfo
- type Adapter
- func (a *Adapter) Capabilities(context.Context) (api.RoutingCapabilities, error)
- func (a *Adapter) Category() api.Category
- func (a *Adapter) Configure(_ context.Context, raw json.RawMessage) error
- func (a *Adapter) Edge(ctx context.Context, r api.EdgeRequest) (api.EdgePlan, bool, error)
- func (a *Adapter) Ensure(ctx context.Context, r api.RouteRequest) (api.RouteHandle, error)
- func (a *Adapter) HealthCheck(ctx context.Context) error
- func (a *Adapter) Kind() string
- func (a *Adapter) Observe(ctx context.Context, h api.RouteHandle) (api.RouteState, error)
- func (a *Adapter) Remove(ctx context.Context, h api.RouteHandle) error
- type Config
Constants ¶
const DefaultAPIBase = "https://api.cloudflare.com/client/v4"
DefaultAPIBase is Cloudflare's API.
const DefaultImage = "cloudflare/cloudflared:2025.1.0"
DefaultImage is the cloudflared this release of Pando runs.
const Kind = "cloudflare"
Kind is the adapter's kind string.
const ManagedComment = "Managed by Pando — changes are reset"
ManagedComment marks every DNS record Pando created. A record without it is not Pando's, and Pando never changes or removes one (design 03 §4.5).
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter writes a tunnel's ingress and DNS through Cloudflare's API.
func (*Adapter) Capabilities ¶
Capabilities: subdomain by default, path under the console hostname (R-164).
TLS is Cloudflare's: its included certificate covers the zone and one level below, which is exactly where apps are named.
func (*Adapter) Edge ¶
Edge makes sure the tunnel exists and routes the console, then describes the cloudflared that holds it open (R-174).
func (*Adapter) Ensure ¶
func (a *Adapter) Ensure(ctx context.Context, r api.RouteRequest) (api.RouteHandle, error)
Ensure writes an app's ingress rule and, for its own hostname, a DNS record.
Idempotent: the rule is found by hostname and path and replaced whole, so a change someone made to it in Cloudflare's dashboard is reset here — which is how the reconciler's next pass undoes drift.
func (*Adapter) HealthCheck ¶
HealthCheck asks Cloudflare whether the token can see the zone.
func (*Adapter) Observe ¶
func (a *Adapter) Observe(ctx context.Context, h api.RouteHandle) (api.RouteState, error)
Observe reads the rule back. It reports and never remediates (design 05): a rule changed in the dashboard shows here as pointing elsewhere, and the reconciler's next Ensure puts it back.
type Config ¶
type Config struct {
AccountID string `json:"account_id"`
// Zone is the Cloudflare zone apps are named in, such as example.com. An
// app is <app>.<zone>, never deeper: Cloudflare's included certificate
// covers *.zone and nothing below it, so a deeper name would have no
// HTTPS. There is deliberately no setting for one.
Zone string `json:"zone"`
// ConsoleHostname is where the console is served, and the host path-mode
// apps are served under. Empty is the zone itself.
ConsoleHostname string `json:"console_hostname,omitempty"`
// TunnelID attaches to an existing tunnel instead of creating one. Pando
// still writes its rules into that tunnel's ingress, and leaves the rules
// it did not write alone.
TunnelID string `json:"tunnel_id,omitempty"`
// Image is the cloudflared image. Pinned by Pando's release; set to
// override.
Image string `json:"image,omitempty"`
// APIBase is Cloudflare's API. Settable for tests, not offered in the form.
APIBase string `json:"api_base,omitempty"`
Credentials struct {
APIToken secret.Value `json:"api_token,omitzero"`
} `json:"credentials,omitzero"`
}
Config is the adapter's configuration.
Source Files