Controller Options¶

This document describes all configuration options for the controller binary. For Helm chart values, see Helm Values.

Command Line Flags¶

For full distributed-tracing setup, see Distributed Tracing.

Proxy Endpoints¶

Each --proxy-endpoints URL names the Service the controller pushes proxy config to. The chart passes its own headless proxy Service, and the controller renders one per Gateway data plane; both meet the requirements below. A Service you bring yourself must meet them too.

• It is headless (clusterIP: None), so its name resolves to every proxy pod. A ClusterIP Service name resolves to one virtual IP, so each push reaches a single pod and the other replicas never get a config.
• It sets publishNotReadyAddresses: true, so DNS also returns NotReady pods. A joining proxy stays NotReady until it has its first config, so without the setting DNS never returns it and it never receives that config.
• Its name resolves through the controller's own DNS. A name that only an egress proxy set in HTTP_PROXY/HTTPS_PROXY can resolve fails the push instead of being sent through that proxy.

Environment Variables¶

All flags can be set via environment variables with the CF_ prefix. Dashes in flag names are replaced with underscores.

Examples:

• --controller-name → CF_CONTROLLER_NAME
• --log-level → CF_LOG_LEVEL
• --leader-elect → CF_LEADER_ELECT

Cluster Domain Auto-Detection¶

The controller automatically detects the Kubernetes cluster domain from /etc/resolv.conf search domains. If detection fails, it falls back to cluster.local.

To override auto-detection:

--cluster-domain=my-cluster.local

Or via environment variable:

CF_CLUSTER_DOMAIN=my-cluster.local

Leader Election¶

For high availability deployments with multiple controller replicas, enable leader election:

--leader-elect=true
--leader-election-namespace=cloudflare-tunnel-system

Only the leader processes events; other replicas remain on standby for automatic failover.

flowchart LR
    subgraph Replicas
        R1[Replica 1<br/>Leader]
        R2[Replica 2<br/>Standby]
        R3[Replica 3<br/>Standby]
    end

    LEASE[(Lease)]

    R1 -->|holds| LEASE
    R2 -.->|watches| LEASE
    R3 -.->|watches| LEASE

Logging¶

Log Levels¶

Log Formats¶

Example JSON log:

{
  "level": "info",
  "ts": "2024-01-15T10:30:00Z",
  "msg": "HTTPRoute reconciled",
  "route": "default/my-app",
  "hostnames": ["app.example.com"]
}

Health Endpoints¶

The controller exposes health endpoints for Kubernetes probes:

These are used by Kubernetes to determine pod health:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8081
readinessProbe:
  httpGet:
    path: /readyz
    port: 8081

Metrics Endpoint¶

The controller exposes Prometheus metrics on the metrics port:

See Metrics & Alerting for available metrics.